Skip to content

feat(bla): start a beamline coding agent as the agent service account - #38

Merged
Thomas A Caswell (tacaswell) merged 19 commits into
NSLS2:mainfrom
gwbischof:feat/bl-agent
Nov 13, 2026
Merged

Thomas A Caswell (tacaswell) merged 19 commits into
NSLS2:mainfrom
gwbischof:feat/bl-agent

Conversation

@gwbischof

@gwbischof Garrett Bischof (gwbischof) commented Nov 5, 2026 •

Copy link
Copy Markdown
Contributor

bla starts a beamline coding agent as the agent service account, so beamline
staff do not run the bw* wrappers as that account themselves.

bla            # opencode, the default
bla opencode2  # a named one

The launcher decides everything the agent sees — the AI gateway key, the
NSLS-II API tokens, the writable directories and which agent starts. Only the
agent name is taken from the command line, from a fixed list, and no option is
passed through, so a caller cannot widen the sandbox with --exec,
--rw-path, --ro-path or --n2c-token.

What a session gets

~/agent the agent's writable directory, created as the caller
profile collection mounted read-write when present; the agent commits, a human pushes
$HOME per session, under /run/nsls2/agent/home/<caller>/ on tmpfs
git identity <caller> (beamline agent) / noreply@bnl.gov, plus safe.directory
npm cache shared per caller, so a session does not refetch

An audit line goes to the journal at every start, naming the caller, host,
agent and directory.

Resolved since the first draft

  • Install path is /opt/nsls2/scripts/bin/bla, matching this repo rather
    than the /usr/local/bin in the deck. The sudo rule in NSLS2/ansible#5025
    names that exact path.
  • Tokens: --n2c-token all. The minter is the thing that decides what the
    agent should hold; naming them here would mean a change in two repos every
    time the set moves.

Testing

Run against an AlmaLinux 8.10 container (bwrap 0.4.0, the version on the
workstations), as a non-privileged caller through the real sudo rule:

  • The sandbox starts, cwd=~/agent, and the re-exec passes the resolved
    agent so the caller and agent phases cannot disagree.
  • bwrap masking holds on 0.4.0, and the agent cannot mount anything of its own
    (CapEff=0).
  • Other beamlines' paths are not visible inside the sandbox.
  • Skills and /etc/opencode/AGENTS.md reach the sandbox.
  • Failure paths: unknown agent, options after the agent name, missing
    SUDO_USER, caller is root.
  • shellcheck and shfmt clean.

Known gap: masking a binary does not stop a library. npm install ssh2 and
pyNfsClient both reach the network without the masked client. The sandbox is
a boundary for what the agent can write, not a guarantee about what it can
reach; the nftables allow-list in NSLS2/ansible#5025 is what constrains that.

Draft until it has run on a real beamline workstation, which needs xfagent in
n2sn-service-accounts.

@gwbischof
Garrett Bischof (gwbischof) force-pushed the feat/bl-agent branch 2 times, most recently from 1e68686 to a9ad778 Compare November 5, 2026 19:47
Beamline staff do not run the bw* launchers as the agent account
themselves. They run bl-agent through sudo, and it decides everything the
agent sees: the AI gateway key, the NSLS-II API tokens, the writable
directory and the agent to start.

Only the agent name is taken from the command line, and only from a fixed
list; no option is passed through, so a caller cannot widen the sandbox
with --exec, --rw-path, --ro-path or --n2c-token. The calling user, the
host and the agent go to syslog before the agent starts, so an action can
be traced to a person even though the agent runs as a shared account.

The gateway key is read from the file the n2c_agent role installs and
passed as AIFAPIM_API_KEY, which every bw* wrapper already understands;
bwclaude turns it into ANTHROPIC_FOUNDRY_API_KEY itself. N2SN_CREDS_DIR
points at the tokens the root minter keeps, so the account needs no
n2c-token session of its own.

Assisted-by: opencode:claude-opus-4-8
Three things found by running it on AlmaLinux 8.

sudo replaces PATH with its secure_path, which holds neither
/opt/nsls2/scripts/bin nor /usr/local/bin, and the profile.d snippet that
adds them is only read by a login shell, so exec'ing the wrapper by name
always failed. Run it by absolute path, next to this script.

hostname is not installed everywhere and the failure was swallowed, so the
audit line said host= with nothing after it. Use HOSTNAME, and let a logger
failure stop the run: no log line, no agent.

The BL_AGENT_* path overrides were there to test on macOS. A launcher whose
point is that the caller decides nothing should not read caller-controlled
variables for credential paths, even though sudo scrubs them today.

Assisted-by: opencode:claude-opus-4-8
Every other script in bin/ has a page in docs/ and a row in the README
table; bl-agent had neither. Also write the account check the way
bwrap_check_account does in the shared library, instead of a one-line
short-circuit that says the same thing less clearly.

Assisted-by: opencode:claude-opus-4-8
Found running the real wrappers on AlmaLinux 8.

sudo's secure_path is /sbin:/bin:/usr/sbin:/usr/bin, so the wrapper could
not find opencode, which npm installs in /usr/local/bin.

The wrappers create their authoring directories under $HOME on the host
before bind-mounting them in, and xfagent has no home: every run died on
'mkdir: cannot create directory /home/xfagent'. Point HOME at the tmpfs
the host setup role mounts, and check it is writable first.

HOME cannot be the caller's agent directory: a wrapper refuses to run
where the working directory is $HOME or an ancestor of it, since that
would mount the whole home tree.

Assisted-by: opencode:claude-opus-4-8
Slide 10 of the plan: the agent reads the live profile collection and
works on a clone in the agent directory. $HOME is a tmpfs in the sandbox,
so the rest of the operator's home stays hidden and only this directory is
mounted back, read-only.

A host without one starts with a warning rather than failing: not every
host that runs an agent has a profile collection, and the queue servers
keep theirs somewhere else.

Assisted-by: opencode:claude-opus-4-8
The agent directory, its ACLs and a home for the agent account were
going to be an ansible role. They do not need to be: the caller owns
their home, so bl-agent creates the agent directory and sets the ACLs as
them, before re-running as the agent account.

Both accounts get default entries on the agent directory. Without them a
file the agent creates is owned by the agent account and unreadable to
the person who has to review it, which is the whole hand-off in the plan.

$HOME for the agent account is /tmp/bl-agent-<caller>: that account has
no home and no XDG runtime directory, nothing kept there needs to outlive
a reboot, and per-caller means two people sharing the account do not
share a cache.

Assisted-by: opencode:claude-opus-4-8
shfmt is configured with keep_padding, which indents a multi-line array
one space further every time it runs, so the file never settles and the
lint job cannot pass. One line avoids the construct entirely.

The map is still the allow-list the usage text and the unknown-agent
check read, both unchanged.

Assisted-by: opencode:claude-opus-5
Found by exercising the launcher in a container:

--help and a bare run created the agent directory, set ACLs and needed
the sudo rule before they would print. Asking what the command is now
answers anyone and changes nothing.

An option in the agent's place was reported as a stray argument ('got:
bash' for --exec bash), and a typo still created a directory, because
the name was only checked after the re-run as the agent account. All
argument checking now happens first.

A symlinked agent directory was refused, but blamed the filesystem for
not supporting ACLs. It is now named for what it is, and checked again
as the agent account, which also closes the window where the caller
could swap the directory after the ACLs were set.

An unreadable gateway key printed bash's own error about the path before
ours.

Assisted-by: opencode:claude-opus-5
…ction

A $HOME per session, under the directory the n2c_agent role makes on the
tmpfs. Two agents started at once no longer race to create the same
database, and two people sharing an operator account do not read each
other's conversations. The cache stays per caller: it is most of the
size and holds nothing personal.

The profile collection is mounted read-write, so the agent edits and
commits in the real repository. That needs an identity, which it had
none of, and safe.directory, because the repository belongs to the
caller and git refuses to work in someone else's. Both go in a gitconfig
in $HOME, which the wrappers mount. The same ACLs the agent directory
gets are applied to the profile collection, or the person is locked out
of committing after the agent has.

The agent cannot push: the sandbox has no GitHub credentials. It says so
at startup and gives the command to publish afterwards.

check_profile_collection refuses a link the caller cannot write. It
catches a mistake, not a determined caller, who owns the link and can
repoint it after the check; scoping the agent account per beamline is
what would make that pointless.

Assisted-by: opencode:claude-opus-5
The page still said HOME was /tmp/bl-agent-<caller> and that the profile
collection was mounted read-only, both of which changed when the agent
started committing.

Adds what it gained since: the shared cache and why npm needs an .npmrc
to use it, the ACLs on the profile collection and what goes wrong
without them, the check on a caller-pointed symlink and what it does not
cover, and the git identity the agent commits with.

Assisted-by: opencode:claude-opus-5
Typing 'bla' is the whole command for the common case. An agent can
still be named, and --help lists them with the default called out.

The resolved agent is passed to the re-run as the agent account rather
than the original arguments, so the two phases cannot disagree about
which one was meant.

Fixes a bug the default exposed: write_git_config ended its group with a
test that is false when there is no profile collection, so the group's
exit status looked like a write failure and the launcher died saying it
could not write a file it had just written. Every earlier test had a
profile collection.

Assisted-by: opencode:claude-opus-5
The page is about the tool, so it is named for it; bla appears where
a command is meant.

Assisted-by: opencode:claude-opus-5
@gwbischof Garrett Bischof (gwbischof) changed the title feat(bl-agent): start a beamline agent as the agent account feat(bla): start a beamline coding agent as the agent service account Nov 9, 2026
Drops the git identity, keeping safe.directory. git refuses every
command in a repository owned by someone else, so that entry is still
needed for the agent to run git status at all.

Leaving the identity out makes a commit fail with "please tell me who
you are" rather than succeed quietly. A guard against a mistake, not a
boundary: anyone can pass git -c user.name.

The startup message now says to review with git diff rather than to push
commits that will not be there.

Assisted-by: opencode:claude-opus-5
A profile collection usually lives on shared storage, where setfacl
fails. The recursive attempt walked every file to achieve nothing --
7845 of them on the SMI collection -- and left the caller none the
wiser about why the agent could not change anything.

It now checks the filesystem first and says what it found. The list
matches the ansible compliance role's compliance_agent_acls_fstypes, so
there is one definition of which filesystems take ACLs.

Assisted-by: opencode:claude-opus-5
The base role already puts base_aifapim_host in /etc/profile.d for
everyone else, and n2c_agent now writes the same value next to the key.
When the gateway moved to aifapim.nsls2.bnl.gov, a baseline run fixed
every other caller; a hardcoded constant here would have needed its own
release and left the agent 404ing in the meantime.

The constant stays as the fallback for a host the role has not reached.

Assisted-by: opencode:claude-opus-5
@gwbischof
Garrett Bischof (gwbischof) marked this pull request as ready for review November 12, 2026 17:26
Copilot AI balanced review requested due to automatic review settings November 12, 2026 17:26

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Binary masking is disabled on the stated bwrap 0.4.0 target, leaving SSH, sudo, and other intended-to-be-masked binaries executable.

No open issues 🎉

What changed in this PR

Adds bla as a controlled entry point for beamline staff to launch existing sandboxed coding agents under the xfagent service account.

Changes:

  • Selects an allowlisted agent, defaulting to opencode2, without forwarding caller options.
  • Configures credentials, shared workspace permissions, session homes, caches, and startup auditing.
  • Documents usage, sandbox access, and the human review-and-commit workflow.
File Description
README.md Adds bla to the script index with a documentation link.
docs/​beamline-agent.md Describes launcher usage, configuration, permissions, and auditing.
bin/​bla Implements account switching, session setup, and sandbox-wrapper launch.

Review effort: Balanced

A tmpfs inside the sandbox would give the same isolation and the same
reboot behaviour. The state is on the host so a session outlives the
sandbox that wrote it and can be reopened later, which is a change to
the launcher rather than to where every agent stores its data.

Notes that each run still makes a new directory, so nothing reopens one
yet.

Assisted-by: opencode:claude-opus-5
Copilot AI balanced review requested due to automatic review settings November 13, 2026 18:10

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Unresolved permission, cache-persistence, and authentication defects can block intended workflows, while the promised no-commit safeguard does not reliably prevent commits.

No open issues 🎉

Review effort: Balanced

Comment thread bin/bla Resolved
The comments said staff run this as themselves. They do not: the sudoers
rule names the beamline operator account, so that is who invokes it, and
a session on ws2 confirms it -- the caller directory is xf12id and the
agent directory is /home/xf12id/agent. A sysadmin running it as
themselves works too, but it is not the normal path, and introduction.md
tells people to use this instead of running an agent as themselves.

The error for an empty SUDO_USER said 'run it as yourself', which asked
for the wrong thing on a shared operator account. It now says to run it
from the account they logged in with.

Assisted-by: opencode:claude-opus-5
Copilot AI balanced review requested due to automatic review settings November 13, 2026 22:09
SCRIPT_DIR followed symlinks (readlink -f) but PROGRAM_NAME did not
(basename of $0), so composing them gave a path that does not exist as
soon as the two differ. Reproduced: a symlink at /usr/local/bin/
beamline-agent pointing at /opt/nsls2/scripts/bin/bla made the re-exec
ask sudo for /opt/nsls2/scripts/bin/beamline-agent.

Everything now comes from one readlink -f, so the re-exec asks for the
path the sudoers rule actually names. It also fixes the audit line:
logger -t used PROGRAM_NAME, so a symlink would have renamed the audit
trail too.

Assisted-by: opencode:claude-opus-5
Comment thread bin/bla Resolved
The check read as fussiness because nothing said what it was for. It is
not a permission check -- the agent account is already past sudo by then.
SUDO_USER is the only thing that says whose home holds ~/agent and the
profile collection, whose session directory to use, and whose name goes
in the audit line, and the agent account's own home holds none of that.

The message said 'cannot tell who you are', which sounds like an
identity check. It now names the consequence instead.

Assisted-by: opencode:claude-opus-5

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

On the stated workstation’s bwrap 0.4.0, the launch path skips binary masking, leaving SSH and other intended-to-be-masked binaries available.

No open issues 🎉

Review effort: Balanced

Copilot AI balanced review requested due to automatic review settings November 13, 2026 22:16
@tacaswell
Thomas A Caswell (tacaswell) merged commit 8a6b989 into NSLS2:main Nov 13, 2026
1 check passed

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🔵 Needs a closer look

Human assessment is needed because unpublished findings show that the target bwrap version leaves SSH and other intended-to-be-masked clients available, undermining the claimed sandbox restrictions.

No open issues 🎉

Review effort: Balanced

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants