From e26b4be8a19fed05b705b337ab43a16480cf46d2 Mon Sep 17 00:00:00 2001 From: Garrett Bischof Date: Thu, 5 Nov 2026 14:15:56 -0500 Subject: [PATCH 01/19] feat(bl-agent): start a beamline agent as the agent account 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 --- bin/bl-agent | 145 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 145 insertions(+) create mode 100755 bin/bl-agent diff --git a/bin/bl-agent b/bin/bl-agent new file mode 100755 index 0000000..29ee385 --- /dev/null +++ b/bin/bl-agent @@ -0,0 +1,145 @@ +#!/usr/bin/env bash +# +# bl-agent — start a beamline coding agent as the agent service account. +# +# Beamline staff do not run the bw* launchers as the agent account directly. +# They run +# +# sudo -u xfagent /opt/nsls2/scripts/bin/bl-agent opencode2 +# +# and this script decides everything the agent sees: the AI gateway key, the +# NSLS-II API tokens, the writable directory and the instructions. Nothing is +# passed through from the caller, so a caller cannot widen the sandbox with +# --exec, --rw-path, --ro-path or --n2c-token. Only the agent name is taken +# from the command line, and only from a fixed list. +# +# The calling user, the host and the agent are logged to syslog before the +# agent starts, so an action can be traced back to a person even though the +# agent runs as a shared account. +# +# Requires: the n2c_agent ansible role (the gateway key and the token minter), +# and the base role (the bw* launchers and the account check). + +set -o errexit +set -o nounset +set -o pipefail + +readonly PROGRAM_NAME="${0##*/}" + +# Agents this launcher knows, and the wrapper each one runs. Adding a name +# here is the only way to make it available. +declare -A AGENT_WRAPPERS=( + [opencode]=bwopencode + [opencode2]=bwopencode2 + [claude]=bwclaude +) + +# Where the n2c_agent role puts the gateway key and the minted tokens. The +# defaults match roles/n2c_agent/defaults/main.yml in NSLS2/ansible. +readonly AIFAPIM_KEY_PATH="${BL_AGENT_AIFAPIM_KEY_PATH:-/etc/nsls2/agent/aifapim/key}" +readonly AGENT_CREDS_DIR="${BL_AGENT_CREDS_DIR:-/run/nsls2/agent/creds}" +readonly AIFAPIM_GATEWAY_HOST="${BL_AGENT_AIFAPIM_HOST:-aifapim.nsls2.bnl.gov}" # gitleaks:allow + +readonly ACCOUNT_CHECK=/opt/nsls2/libexec/agent-account-check + +die() { + echo "${PROGRAM_NAME}: $*" >&2 + exit 1 +} + +usage() { + cat < ${PROGRAM_NAME} + +Start a beamline coding agent in its sandbox. The agent runs as the account +this is invoked as, reads the beamline's AI gateway key and the NSLS-II API +tokens kept by the host, and may write only in the calling user's agent +directory. + +Agents: +$(printf ' %s\n' "${!AGENT_WRAPPERS[@]}" | sort) + +No other options are accepted: this launcher, not the caller, decides what +the agent can reach. +EOF +} + +# calling_user +# The person who invoked sudo. SUDO_USER is set by sudo and is the name of +# the user who ran it, which is what the audit line and the writable +# directory are based on. +calling_user() { + local user="${SUDO_USER:-}" + [[ -n "${user}" ]] || die "SUDO_USER is not set; run this with sudo -u ${PROGRAM_NAME} " + [[ "${user}" != "root" ]] || die "refusing to run for root" + printf '%s\n' "${user}" +} + +# agent_home_dir USER +# The writable directory for USER, created by the host setup role. The agent +# works in a clone here and a person moves changes into the live profile. +agent_home_dir() { + local user="$1" home + home="$(getent passwd "${user}" | cut -d: -f6)" + [[ -n "${home}" ]] || die "cannot find the home directory of '${user}'" + printf '%s/agent\n' "${home}" +} + +main() { + [[ $# -ge 1 ]] || { + usage >&2 + exit 1 + } + + case "$1" in + -h | --help) + usage + exit 0 + ;; + esac + + local agent="$1" + shift + [[ $# -eq 0 ]] || die "no options are accepted after the agent name (got: $*)" + + local wrapper="${AGENT_WRAPPERS[${agent}]:-}" + [[ -n "${wrapper}" ]] || die "unknown agent '${agent}'. Known agents: $(printf '%s ' "${!AGENT_WRAPPERS[@]}" | sort | tr -d '\n')" + + # The same check the bw* launchers run. It is advisory there; running it + # here as well means a refusal is reported before anything is set up. + if [[ -x "${ACCOUNT_CHECK}" ]]; then + "${ACCOUNT_CHECK}" || exit $? + fi + + local user agent_dir + user="$(calling_user)" + agent_dir="$(agent_home_dir "${user}")" + [[ -d "${agent_dir}" ]] || die "'${agent_dir}' does not exist; the host setup role creates it" + [[ -w "${agent_dir}" ]] || die "'${agent_dir}' is not writable by this account; check its ACL" + + [[ -r "${AIFAPIM_KEY_PATH}" ]] || die "cannot read the AI gateway key '${AIFAPIM_KEY_PATH}'; is this a beamline host with the n2c_agent role?" + + # The key is read here and passed in the environment, because the wrappers + # take it as AIFAPIM_API_KEY. The file itself is never mounted. + local aifapim_key + aifapim_key="$(< "${AIFAPIM_KEY_PATH}")" + [[ -n "${aifapim_key}" ]] || die "the AI gateway key '${AIFAPIM_KEY_PATH}' is empty" + + logger -t "${PROGRAM_NAME}" -p auth.notice \ + "agent start: user=${user} host=$(hostname -s) agent=${agent} wrapper=${wrapper} dir=${agent_dir}" || + true + + # N2SN_CREDS_DIR points the wrapper at the tokens the root minter keeps, + # instead of a per-user n2c-token session this account does not have. + export N2SN_CREDS_DIR="${AGENT_CREDS_DIR}" + export AIFAPIM_HOST="${AIFAPIM_GATEWAY_HOST}" + export AIFAPIM_API_KEY="${aifapim_key}" + + cd "${agent_dir}" || die "cannot enter '${agent_dir}'" + + # --n2c-token all mounts every token the minter keeps, read-only, one file + # each; a token the account cannot read is skipped by the wrapper. + exec "${wrapper}" --n2c-token all +} + +main "$@" From 55c06f0925f8c68a7144f8627783c4d2572e856f Mon Sep 17 00:00:00 2001 From: Garrett Bischof Date: Thu, 5 Nov 2026 14:40:17 -0500 Subject: [PATCH 02/19] fix(bl-agent): run the wrapper by path, log the host, drop the overrides 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 --- bin/bl-agent | 134 ++++++++++++++++++++------------------------------- 1 file changed, 52 insertions(+), 82 deletions(-) diff --git a/bin/bl-agent b/bin/bl-agent index 29ee385..024f75d 100755 --- a/bin/bl-agent +++ b/bin/bl-agent @@ -1,24 +1,15 @@ #!/usr/bin/env bash -# # bl-agent — start a beamline coding agent as the agent service account. # -# Beamline staff do not run the bw* launchers as the agent account directly. -# They run -# # sudo -u xfagent /opt/nsls2/scripts/bin/bl-agent opencode2 # -# and this script decides everything the agent sees: the AI gateway key, the -# NSLS-II API tokens, the writable directory and the instructions. Nothing is -# passed through from the caller, so a caller cannot widen the sandbox with -# --exec, --rw-path, --ro-path or --n2c-token. Only the agent name is taken -# from the command line, and only from a fixed list. -# -# The calling user, the host and the agent are logged to syslog before the -# agent starts, so an action can be traced back to a person even though the -# agent runs as a shared account. +# This launcher, not the caller, decides what the agent can reach: only the +# agent name is taken from the command line, from a fixed list, and no option +# is passed through. The calling user is logged to syslog first, so an action +# can be traced to a person even though the agent runs as a shared account. # -# Requires: the n2c_agent ansible role (the gateway key and the token minter), -# and the base role (the bw* launchers and the account check). +# Requires the n2c_agent ansible role (gateway key, token minter) and the base +# role (the bw* launchers and the account check). set -o errexit set -o nounset @@ -26,20 +17,22 @@ set -o pipefail readonly PROGRAM_NAME="${0##*/}" -# Agents this launcher knows, and the wrapper each one runs. Adding a name -# here is the only way to make it available. +# The bw* wrappers sit next to this script, and are run by absolute path: sudo +# replaces PATH with its secure_path, and the profile.d snippet that adds them +# is only read by a login shell. +SCRIPT_DIR="$(cd -P -- "$(dirname -- "$(readlink -f -- "$0")")" && pwd -P)" +readonly SCRIPT_DIR + declare -A AGENT_WRAPPERS=( [opencode]=bwopencode [opencode2]=bwopencode2 [claude]=bwclaude ) -# Where the n2c_agent role puts the gateway key and the minted tokens. The -# defaults match roles/n2c_agent/defaults/main.yml in NSLS2/ansible. -readonly AIFAPIM_KEY_PATH="${BL_AGENT_AIFAPIM_KEY_PATH:-/etc/nsls2/agent/aifapim/key}" -readonly AGENT_CREDS_DIR="${BL_AGENT_CREDS_DIR:-/run/nsls2/agent/creds}" -readonly AIFAPIM_GATEWAY_HOST="${BL_AGENT_AIFAPIM_HOST:-aifapim.nsls2.bnl.gov}" # gitleaks:allow - +# Installed by the n2c_agent role; see its defaults in NSLS2/ansible. +readonly AIFAPIM_KEY_PATH=/etc/nsls2/agent/aifapim/key +readonly AGENT_CREDS_DIR=/run/nsls2/agent/creds +readonly AIFAPIM_GATEWAY_HOST=aifapim.nsls2.bnl.gov # gitleaks:allow readonly ACCOUNT_CHECK=/opt/nsls2/libexec/agent-account-check die() { @@ -48,50 +41,26 @@ die() { } usage() { - cat < ${PROGRAM_NAME} -Start a beamline coding agent in its sandbox. The agent runs as the account -this is invoked as, reads the beamline's AI gateway key and the NSLS-II API -tokens kept by the host, and may write only in the calling user's agent -directory. +Start a beamline coding agent in its sandbox. It may write only in your agent +directory, and reaches the AI gateway and the read-only NSLS-II APIs with the +credentials this host keeps. Agents: $(printf ' %s\n' "${!AGENT_WRAPPERS[@]}" | sort) -No other options are accepted: this launcher, not the caller, decides what -the agent can reach. +No other options are accepted. EOF } -# calling_user -# The person who invoked sudo. SUDO_USER is set by sudo and is the name of -# the user who ran it, which is what the audit line and the writable -# directory are based on. -calling_user() { - local user="${SUDO_USER:-}" - [[ -n "${user}" ]] || die "SUDO_USER is not set; run this with sudo -u ${PROGRAM_NAME} " - [[ "${user}" != "root" ]] || die "refusing to run for root" - printf '%s\n' "${user}" -} - -# agent_home_dir USER -# The writable directory for USER, created by the host setup role. The agent -# works in a clone here and a person moves changes into the live profile. -agent_home_dir() { - local user="$1" home - home="$(getent passwd "${user}" | cut -d: -f6)" - [[ -n "${home}" ]] || die "cannot find the home directory of '${user}'" - printf '%s/agent\n' "${home}" -} - main() { - [[ $# -ge 1 ]] || { - usage >&2 - exit 1 - } - - case "$1" in + case "${1:-}" in + '') + usage >&2 + exit 1 + ;; -h | --help) usage exit 0 @@ -103,43 +72,44 @@ main() { [[ $# -eq 0 ]] || die "no options are accepted after the agent name (got: $*)" local wrapper="${AGENT_WRAPPERS[${agent}]:-}" - [[ -n "${wrapper}" ]] || die "unknown agent '${agent}'. Known agents: $(printf '%s ' "${!AGENT_WRAPPERS[@]}" | sort | tr -d '\n')" + [[ -n "${wrapper}" ]] || + die "unknown agent '${agent}'. Known agents: $(echo "${!AGENT_WRAPPERS[@]}" | tr ' ' '\n' | sort | tr '\n' ' ')" + + # Advisory in the bw* launchers; run here so a refusal comes before setup. + [[ ! -x "${ACCOUNT_CHECK}" ]] || "${ACCOUNT_CHECK}" || exit $? + + local user="${SUDO_USER:-}" + [[ -n "${user}" ]] || die "SUDO_USER is not set; run this through sudo -u " + [[ "${user}" != root ]] || die "refusing to run for root" - # The same check the bw* launchers run. It is advisory there; running it - # here as well means a refusal is reported before anything is set up. - if [[ -x "${ACCOUNT_CHECK}" ]]; then - "${ACCOUNT_CHECK}" || exit $? - fi + local home + home="$(getent passwd "${user}" | cut -d: -f6)" + [[ -n "${home}" ]] || die "cannot find the home directory of '${user}'" - local user agent_dir - user="$(calling_user)" - agent_dir="$(agent_home_dir "${user}")" + # The one writable place: the agent works in a clone here and a person + # moves changes into the live profile. + local agent_dir="${home}/agent" [[ -d "${agent_dir}" ]] || die "'${agent_dir}' does not exist; the host setup role creates it" [[ -w "${agent_dir}" ]] || die "'${agent_dir}' is not writable by this account; check its ACL" - [[ -r "${AIFAPIM_KEY_PATH}" ]] || die "cannot read the AI gateway key '${AIFAPIM_KEY_PATH}'; is this a beamline host with the n2c_agent role?" - - # The key is read here and passed in the environment, because the wrappers - # take it as AIFAPIM_API_KEY. The file itself is never mounted. - local aifapim_key - aifapim_key="$(< "${AIFAPIM_KEY_PATH}")" - [[ -n "${aifapim_key}" ]] || die "the AI gateway key '${AIFAPIM_KEY_PATH}' is empty" + # Passed in the environment because that is how the wrappers take it; the + # file itself is never mounted. + local key + key="$(< "${AIFAPIM_KEY_PATH}")" || die "cannot read the AI gateway key '${AIFAPIM_KEY_PATH}'" + [[ -n "${key}" ]] || die "the AI gateway key '${AIFAPIM_KEY_PATH}' is empty" + # Audit before anything runs: no log line, no agent. logger -t "${PROGRAM_NAME}" -p auth.notice \ - "agent start: user=${user} host=$(hostname -s) agent=${agent} wrapper=${wrapper} dir=${agent_dir}" || - true + "agent start: user=${user} host=${HOSTNAME%%.*} agent=${agent} dir=${agent_dir}" - # N2SN_CREDS_DIR points the wrapper at the tokens the root minter keeps, - # instead of a per-user n2c-token session this account does not have. + # The tokens come from the root minter, not an n2c-token session this + # account does not have. export N2SN_CREDS_DIR="${AGENT_CREDS_DIR}" export AIFAPIM_HOST="${AIFAPIM_GATEWAY_HOST}" - export AIFAPIM_API_KEY="${aifapim_key}" + export AIFAPIM_API_KEY="${key}" cd "${agent_dir}" || die "cannot enter '${agent_dir}'" - - # --n2c-token all mounts every token the minter keeps, read-only, one file - # each; a token the account cannot read is skipped by the wrapper. - exec "${wrapper}" --n2c-token all + exec "${SCRIPT_DIR}/${wrapper}" --n2c-token all } main "$@" From 6d6acc0a53beef97b563f3b588f85d15ca3dda02 Mon Sep 17 00:00:00 2001 From: Garrett Bischof Date: Thu, 5 Nov 2026 14:46:48 -0500 Subject: [PATCH 03/19] docs(bl-agent): add the docs page and README entry 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 --- README.md | 1 + bin/bl-agent | 7 ++++-- docs/bl-agent.md | 64 ++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 70 insertions(+), 2 deletions(-) create mode 100644 docs/bl-agent.md diff --git a/README.md b/README.md index b1b6f45..b66feb7 100644 --- a/README.md +++ b/README.md @@ -19,6 +19,7 @@ docs/ Per-script and per-library documentation | Script | Purpose | Docs | | --- | --- | --- | | `azoidcapp` | Create or reconcile an Entra ID OIDC app + service principal | [docs/azoidcapp.md](docs/azoidcapp.md) | +| `bl-agent` | Start a beamline coding agent as the agent service account | [docs/bl-agent.md](docs/bl-agent.md) | | `bwclaude` | Claude CLI in a bubblewrap sandbox | [docs/bw-wrappers.md](docs/bw-wrappers.md) | | `bwcodex` | OpenAI Codex CLI in a bubblewrap sandbox | [docs/bw-wrappers.md](docs/bw-wrappers.md) | | `bwcopilot` | GitHub Copilot CLI in a bubblewrap sandbox | [docs/bw-wrappers.md](docs/bw-wrappers.md) | diff --git a/bin/bl-agent b/bin/bl-agent index 024f75d..433b425 100755 --- a/bin/bl-agent +++ b/bin/bl-agent @@ -75,8 +75,11 @@ main() { [[ -n "${wrapper}" ]] || die "unknown agent '${agent}'. Known agents: $(echo "${!AGENT_WRAPPERS[@]}" | tr ' ' '\n' | sort | tr '\n' ' ')" - # Advisory in the bw* launchers; run here so a refusal comes before setup. - [[ ! -x "${ACCOUNT_CHECK}" ]] || "${ACCOUNT_CHECK}" || exit $? + # The bw* launchers run this too; running it before the audit line keeps a + # refused account out of the log and away from the key. + if [[ -f "${ACCOUNT_CHECK}" && -x "${ACCOUNT_CHECK}" ]]; then + "${ACCOUNT_CHECK}" || exit $? + fi local user="${SUDO_USER:-}" [[ -n "${user}" ]] || die "SUDO_USER is not set; run this through sudo -u " diff --git a/docs/bl-agent.md b/docs/bl-agent.md new file mode 100644 index 0000000..b72a009 --- /dev/null +++ b/docs/bl-agent.md @@ -0,0 +1,64 @@ +# `bl-agent` + +Starts a beamline coding agent as the agent service account. Beamline staff do +not run the `bw*` wrappers as that account themselves: + +```bash +sudo -u xfagent /opt/nsls2/scripts/bin/bl-agent opencode2 +``` + +The launcher, not the caller, decides what the agent can reach. 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`. + +## Agents + +| Name | Wrapper | +| --- | --- | +| `opencode` | `bwopencode` | +| `opencode2` | `bwopencode2` | +| `claude` | `bwclaude` | + +The wrapper is run by absolute path, from the directory this script is in. +`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. + +## What the launcher sets + +- **The AI gateway key.** Read from `/etc/nsls2/agent/aifapim/key` and passed + as `AIFAPIM_API_KEY`, with `AIFAPIM_HOST`. Every `bw*` wrapper understands + those two; `bwclaude` turns them into `ANTHROPIC_FOUNDRY_*` itself. The file + is never mounted into the sandbox. +- **The NSLS-II API tokens.** `N2SN_CREDS_DIR=/run/nsls2/agent/creds` and + `--n2c-token all`, so the wrapper mounts every token the root minter keeps, + read-only, one file each. `all` rather than a list of names because the + minter decides which tokens the account gets; the launcher does not need + changing when that set does. +- **The working directory.** `~/agent`, which must exist and be + writable by the agent account. The host setup role creates it and gives the + agent account traverse-only access to the home above it. + +Both the key and the tokens come from the `n2c_agent` role in NSLS2/ansible. + +## Audit + +Before anything starts: + +```text +bl-agent: agent start: user= host= agent= dir= +``` + +to syslog at `auth.notice`, so an action is traceable to a person even though +the agent runs as a shared account. If the log line cannot be written the run +stops: no log line, no agent. + +`SUDO_USER` names the caller, so the launcher refuses to run without it, and +refuses when the caller is root. + +## Account check + +`/opt/nsls2/libexec/agent-account-check` (ansible `base` role) runs first, as +it does in the `bw*` wrappers, so a refused account never reaches the audit +line or the gateway key. When the script is not installed this is a no-op. From 8b7046cc942433943bc0c1132b86fd6ac0da1b6e Mon Sep 17 00:00:00 2001 From: Garrett Bischof Date: Thu, 5 Nov 2026 15:00:55 -0500 Subject: [PATCH 04/19] fix(bl-agent): set PATH and HOME for the wrapper 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 --- bin/bl-agent | 14 ++++++++++++++ docs/bl-agent.md | 10 ++++++++++ 2 files changed, 24 insertions(+) diff --git a/bin/bl-agent b/bin/bl-agent index 433b425..69ff189 100755 --- a/bin/bl-agent +++ b/bin/bl-agent @@ -23,6 +23,10 @@ readonly PROGRAM_NAME="${0##*/}" SCRIPT_DIR="$(cd -P -- "$(dirname -- "$(readlink -f -- "$0")")" && pwd -P)" readonly SCRIPT_DIR +# The wrappers find their agent by name, and sudo's secure_path does not hold +# /usr/local/bin, where npm installs them. +readonly AGENT_PATH=/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin + declare -A AGENT_WRAPPERS=( [opencode]=bwopencode [opencode2]=bwopencode2 @@ -35,6 +39,12 @@ readonly AGENT_CREDS_DIR=/run/nsls2/agent/creds readonly AIFAPIM_GATEWAY_HOST=aifapim.nsls2.bnl.gov # gitleaks:allow readonly ACCOUNT_CHECK=/opt/nsls2/libexec/agent-account-check +# A tmpfs the host setup role mounts, so nothing the agent writes outside the +# caller's agent directory survives a reboot. The wrappers need it to exist +# before they start: they create their authoring directories under it on the +# host and bind-mount those into the sandbox. +readonly AGENT_HOME=/home/xfagent + die() { echo "${PROGRAM_NAME}: $*" >&2 exit 1 @@ -95,6 +105,8 @@ main() { [[ -d "${agent_dir}" ]] || die "'${agent_dir}' does not exist; the host setup role creates it" [[ -w "${agent_dir}" ]] || die "'${agent_dir}' is not writable by this account; check its ACL" + [[ -w "${AGENT_HOME}" ]] || die "'${AGENT_HOME}' is not writable; the host setup role mounts it" + # Passed in the environment because that is how the wrappers take it; the # file itself is never mounted. local key @@ -110,6 +122,8 @@ main() { export N2SN_CREDS_DIR="${AGENT_CREDS_DIR}" export AIFAPIM_HOST="${AIFAPIM_GATEWAY_HOST}" export AIFAPIM_API_KEY="${key}" + export PATH="${AGENT_PATH}" + export HOME="${AGENT_HOME}" cd "${agent_dir}" || die "cannot enter '${agent_dir}'" exec "${SCRIPT_DIR}/${wrapper}" --n2c-token all diff --git a/docs/bl-agent.md b/docs/bl-agent.md index b72a009..413ca74 100644 --- a/docs/bl-agent.md +++ b/docs/bl-agent.md @@ -39,6 +39,16 @@ adds them is only read by a login shell. - **The working directory.** `~/agent`, which must exist and be writable by the agent account. The host setup role creates it and gives the agent account traverse-only access to the home above it. +- **`HOME`.** `/home/xfagent`, a tmpfs the host setup role mounts. The wrappers + create their authoring directories (`~/.config/opencode/{skills,agents,commands}`) + there on the host before bind-mounting them into the sandbox, so it has to + exist and be writable. On a tmpfs nothing the agent writes outside the + caller's agent directory survives a reboot. It cannot be the working + directory itself: a wrapper refuses to run where the working directory is + `$HOME` or above it, because that would mount the whole home tree. +- **`PATH`.** `sudo` replaces it with its `secure_path`, which does not hold + `/usr/local/bin`, where the agents are installed, so the wrappers would not + find them. Both the key and the tokens come from the `n2c_agent` role in NSLS2/ansible. From 4818d781ed24ff26d722029615d78ece472c4461 Mon Sep 17 00:00:00 2001 From: Garrett Bischof Date: Thu, 5 Nov 2026 15:26:23 -0500 Subject: [PATCH 05/19] feat(bl-agent): mount the profile collection read-only 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 --- bin/bl-agent | 33 +++++++++++++++++++++++++++++---- 1 file changed, 29 insertions(+), 4 deletions(-) diff --git a/bin/bl-agent b/bin/bl-agent index 69ff189..c19596f 100755 --- a/bin/bl-agent +++ b/bin/bl-agent @@ -17,6 +17,11 @@ set -o pipefail readonly PROGRAM_NAME="${0##*/}" +# The account the agents run as. Staff run this script as themselves; it +# re-runs itself through sudo, so nobody has to remember the account name or +# the sudo line. The sudoers rule still decides who is allowed. +readonly AGENT_ACCOUNT=xfagent + # The bw* wrappers sit next to this script, and are run by absolute path: sudo # replaces PATH with its secure_path, and the profile.d snippet that adds them # is only read by a login shell. @@ -45,6 +50,12 @@ readonly ACCOUNT_CHECK=/opt/nsls2/libexec/agent-account-check # host and bind-mount those into the sandbox. readonly AGENT_HOME=/home/xfagent +# The live profile collection, relative to the caller's home. $HOME is a tmpfs +# in the sandbox, so the rest of the home stays hidden and this one directory +# is mounted read-only; the agent works on a clone of it in the agent +# directory. Not every host has one. +readonly PROFILE_COLLECTION=.ipython/profile_collection + die() { echo "${PROGRAM_NAME}: $*" >&2 exit 1 @@ -52,7 +63,7 @@ die() { usage() { cat << EOF -Usage: sudo -u ${PROGRAM_NAME} +Usage: ${PROGRAM_NAME} Start a beamline coding agent in its sandbox. It may write only in your agent directory, and reaches the AI gateway and the read-only NSLS-II APIs with the @@ -66,6 +77,12 @@ EOF } main() { + # Staff run this as themselves; re-run as the agent account. Everything + # below this point is already the agent. + if [[ "$(id -un)" != "${AGENT_ACCOUNT}" ]]; then + exec sudo -u "${AGENT_ACCOUNT}" "${SCRIPT_DIR}/${PROGRAM_NAME}" "$@" + fi + case "${1:-}" in '') usage >&2 @@ -92,7 +109,7 @@ main() { fi local user="${SUDO_USER:-}" - [[ -n "${user}" ]] || die "SUDO_USER is not set; run this through sudo -u " + [[ -n "${user}" ]] || die "cannot tell who you are: run ${PROGRAM_NAME} as yourself, not as ${AGENT_ACCOUNT}" [[ "${user}" != root ]] || die "refusing to run for root" local home @@ -115,7 +132,7 @@ main() { # Audit before anything runs: no log line, no agent. logger -t "${PROGRAM_NAME}" -p auth.notice \ - "agent start: user=${user} host=${HOSTNAME%%.*} agent=${agent} dir=${agent_dir}" + "agent start: user=${user} host=$(uname -n) agent=${agent} dir=${agent_dir}" # The tokens come from the root minter, not an n2c-token session this # account does not have. @@ -126,7 +143,15 @@ main() { export HOME="${AGENT_HOME}" cd "${agent_dir}" || die "cannot enter '${agent_dir}'" - exec "${SCRIPT_DIR}/${wrapper}" --n2c-token all + + local -a mounts=(--n2c-token all) + if [[ -d "${home}/${PROFILE_COLLECTION}" ]]; then + mounts+=(--ro-path "${home}/${PROFILE_COLLECTION}") + else + echo "${PROGRAM_NAME}: no profile collection at '${home}/${PROFILE_COLLECTION}'; starting without it" >&2 + fi + + exec "${SCRIPT_DIR}/${wrapper}" "${mounts[@]}" } main "$@" From 65cb647e7c4744c7a83a04e8e2c6cf8496d00f77 Mon Sep 17 00:00:00 2001 From: Garrett Bischof Date: Thu, 5 Nov 2026 15:39:05 -0500 Subject: [PATCH 06/19] feat(bl-agent): set up its own directories, no root needed 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-: 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 --- bin/bl-agent | 58 ++++++++++++++++++++++++++++++++++++++---------- docs/bl-agent.md | 24 +++++++++++--------- 2 files changed, 60 insertions(+), 22 deletions(-) diff --git a/bin/bl-agent b/bin/bl-agent index c19596f..88465c6 100755 --- a/bin/bl-agent +++ b/bin/bl-agent @@ -44,11 +44,13 @@ readonly AGENT_CREDS_DIR=/run/nsls2/agent/creds readonly AIFAPIM_GATEWAY_HOST=aifapim.nsls2.bnl.gov # gitleaks:allow readonly ACCOUNT_CHECK=/opt/nsls2/libexec/agent-account-check -# A tmpfs the host setup role mounts, so nothing the agent writes outside the -# caller's agent directory survives a reboot. The wrappers need it to exist -# before they start: they create their authoring directories under it on the -# host and bind-mount those into the sandbox. -readonly AGENT_HOME=/home/xfagent +# $HOME for the agent account, per caller. The bw* launchers create their +# authoring directories under it on the host before bind-mounting them in, so +# it has to exist and be writable. It cannot be the caller's agent directory: +# a wrapper refuses to run where the working directory is $HOME or above it. +# In /tmp because the agent account has no home and no XDG runtime directory, +# and nothing here needs to outlive a reboot. +readonly AGENT_HOME_BASE=/tmp/bl-agent # The live profile collection, relative to the caller's home. $HOME is a tmpfs # in the sandbox, so the rest of the home stays hidden and this one directory @@ -56,11 +58,40 @@ readonly AGENT_HOME=/home/xfagent # directory. Not every host has one. readonly PROFILE_COLLECTION=.ipython/profile_collection +# The one directory the agent may write in, inside the caller's home. +readonly AGENT_SUBDIR=agent + die() { echo "${PROGRAM_NAME}: $*" >&2 exit 1 } +# ensure_agent_dir HOME +# Create the agent directory and the ACLs that share it with the agent +# account. Runs as the caller, who owns their home, so this needs no root +# and no prior ansible run. Idempotent: setfacl -m is a no-op when the entry +# is already there. +# +# Traverse-only on the home: the agent reaches its own directory and the +# profile collection, nothing else. Both accounts get default entries on the +# agent directory, or whichever one did not create a file cannot read it. +ensure_agent_dir() { + local home="$1" dir="$1/${AGENT_SUBDIR}" user="$2" + + [[ -d "${dir}" ]] || { + mkdir -p "${dir}" || die "cannot create '${dir}'" + echo "${PROGRAM_NAME}: created ${dir}" >&2 + } + + setfacl -m "u:${AGENT_ACCOUNT}:x" "${home}" || _acl_failed + setfacl -m "u:${AGENT_ACCOUNT}:rwx" -m "d:u:${AGENT_ACCOUNT}:rwx" "${dir}" || _acl_failed + setfacl -m "d:u:${user}:rwx" "${dir}" || _acl_failed +} + +_acl_failed() { + die "cannot share the agent directory with ${AGENT_ACCOUNT}: does this filesystem support ACLs?" +} + usage() { cat << EOF Usage: ${PROGRAM_NAME} @@ -77,9 +108,11 @@ EOF } main() { - # Staff run this as themselves; re-run as the agent account. Everything - # below this point is already the agent. + # Staff run this as themselves; set up the agent directory while we still + # are them (they own their home), then re-run as the agent account. if [[ "$(id -un)" != "${AGENT_ACCOUNT}" ]]; then + [[ "$(id -un)" != root ]] || die "refusing to run for root" + ensure_agent_dir "${HOME}" "$(id -un)" exec sudo -u "${AGENT_ACCOUNT}" "${SCRIPT_DIR}/${PROGRAM_NAME}" "$@" fi @@ -118,11 +151,12 @@ main() { # The one writable place: the agent works in a clone here and a person # moves changes into the live profile. - local agent_dir="${home}/agent" - [[ -d "${agent_dir}" ]] || die "'${agent_dir}' does not exist; the host setup role creates it" - [[ -w "${agent_dir}" ]] || die "'${agent_dir}' is not writable by this account; check its ACL" + local agent_dir="${home}/${AGENT_SUBDIR}" + [[ -w "${agent_dir}" ]] || die "'${agent_dir}' is not writable by ${AGENT_ACCOUNT}: check its ACL" - [[ -w "${AGENT_HOME}" ]] || die "'${AGENT_HOME}' is not writable; the host setup role mounts it" + local agent_home="${AGENT_HOME_BASE}-${user}" + mkdir -p "${agent_home}" || die "cannot create '${agent_home}'" + chmod 700 "${agent_home}" || die "cannot secure '${agent_home}'" # Passed in the environment because that is how the wrappers take it; the # file itself is never mounted. @@ -140,7 +174,7 @@ main() { export AIFAPIM_HOST="${AIFAPIM_GATEWAY_HOST}" export AIFAPIM_API_KEY="${key}" export PATH="${AGENT_PATH}" - export HOME="${AGENT_HOME}" + export HOME="${agent_home}" cd "${agent_dir}" || die "cannot enter '${agent_dir}'" diff --git a/docs/bl-agent.md b/docs/bl-agent.md index 413ca74..2221fa1 100644 --- a/docs/bl-agent.md +++ b/docs/bl-agent.md @@ -36,16 +36,20 @@ adds them is only read by a login shell. read-only, one file each. `all` rather than a list of names because the minter decides which tokens the account gets; the launcher does not need changing when that set does. -- **The working directory.** `~/agent`, which must exist and be - writable by the agent account. The host setup role creates it and gives the - agent account traverse-only access to the home above it. -- **`HOME`.** `/home/xfagent`, a tmpfs the host setup role mounts. The wrappers - create their authoring directories (`~/.config/opencode/{skills,agents,commands}`) - there on the host before bind-mounting them into the sandbox, so it has to - exist and be writable. On a tmpfs nothing the agent writes outside the - caller's agent directory survives a reboot. It cannot be the working - directory itself: a wrapper refuses to run where the working directory is - `$HOME` or above it, because that would mount the whole home tree. +- **The working directory.** `~/agent`, created on first use + along with the ACLs that share it: traverse-only for the agent account on + the home, read-write on the agent directory, with default entries for both + accounts so each can read what the other writes. This runs as the caller, + who owns their home, so it needs no root and no prior ansible run. +- **`HOME`.** `/tmp/bl-agent-`, created on first use, mode `0700`. The + wrappers create their authoring directories + (`~/.config/opencode/{skills,agents,commands}`) there on the host before + bind-mounting them into the sandbox, so it has to exist and be writable. The + agent account has no home of its own and no XDG runtime directory, and + nothing kept here needs to outlive a reboot. It is per caller, so two people + using the account do not share a cache. It cannot be the caller's agent + directory: a wrapper refuses to run where the working directory is `$HOME` + or above it, because that would mount the whole home tree. - **`PATH`.** `sudo` replaces it with its `secure_path`, which does not hold `/usr/local/bin`, where the agents are installed, so the wrappers would not find them. From 513a54bead87f87fc2526d855324448a171f21ef Mon Sep 17 00:00:00 2001 From: Garrett Bischof Date: Thu, 5 Nov 2026 16:07:32 -0500 Subject: [PATCH 07/19] style(bl-agent): put the agent map on one line for shfmt 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 --- bin/bl-agent | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/bin/bl-agent b/bin/bl-agent index 88465c6..8020d05 100755 --- a/bin/bl-agent +++ b/bin/bl-agent @@ -32,11 +32,10 @@ readonly SCRIPT_DIR # /usr/local/bin, where npm installs them. readonly AGENT_PATH=/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin -declare -A AGENT_WRAPPERS=( - [opencode]=bwopencode - [opencode2]=bwopencode2 - [claude]=bwclaude -) +# The agents that may be started, and the wrapper each one runs in. On one +# line because shfmt's keep_padding indents a multi-line array one space +# further on every run, so it never settles and CI never goes green. +declare -A AGENT_WRAPPERS=([opencode]=bwopencode [opencode2]=bwopencode2 [claude]=bwclaude) # Installed by the n2c_agent role; see its defaults in NSLS2/ansible. readonly AIFAPIM_KEY_PATH=/etc/nsls2/agent/aifapim/key From 9a224dac7b9437e67072a027f32327e8c50d50c1 Mon Sep 17 00:00:00 2001 From: Garrett Bischof Date: Thu, 5 Nov 2026 16:47:22 -0500 Subject: [PATCH 08/19] fix(bl-agent): check arguments and the agent directory before acting 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 --- bin/bl-agent | 44 ++++++++++++++++++++++++++++++++------------ 1 file changed, 32 insertions(+), 12 deletions(-) diff --git a/bin/bl-agent b/bin/bl-agent index 8020d05..b2f4ab9 100755 --- a/bin/bl-agent +++ b/bin/bl-agent @@ -81,6 +81,7 @@ ensure_agent_dir() { mkdir -p "${dir}" || die "cannot create '${dir}'" echo "${PROGRAM_NAME}: created ${dir}" >&2 } + reject_symlink "${dir}" setfacl -m "u:${AGENT_ACCOUNT}:x" "${home}" || _acl_failed setfacl -m "u:${AGENT_ACCOUNT}:rwx" -m "d:u:${AGENT_ACCOUNT}:rwx" "${dir}" || _acl_failed @@ -91,6 +92,17 @@ _acl_failed() { die "cannot share the agent directory with ${AGENT_ACCOUNT}: does this filesystem support ACLs?" } +# reject_symlink DIR +# The agent directory has to be a real directory in the caller's home. A +# symlink would move the agent's one writable mount somewhere else, and the +# caller owns their home, so only this stops them pointing it anywhere. +# Checked again as the agent account, after the caller's last chance to swap +# it. +reject_symlink() { + [[ ! -L "$1" ]] || + die "'$1' is a symlink: the agent directory has to be a real directory in your home" +} + usage() { cat << EOF Usage: ${PROGRAM_NAME} @@ -107,14 +119,8 @@ EOF } main() { - # Staff run this as themselves; set up the agent directory while we still - # are them (they own their home), then re-run as the agent account. - if [[ "$(id -un)" != "${AGENT_ACCOUNT}" ]]; then - [[ "$(id -un)" != root ]] || die "refusing to run for root" - ensure_agent_dir "${HOME}" "$(id -un)" - exec sudo -u "${AGENT_ACCOUNT}" "${SCRIPT_DIR}/${PROGRAM_NAME}" "$@" - fi - + # Before anything else, so asking what this is needs no sudo rule and + # creates nothing. case "${1:-}" in '') usage >&2 @@ -127,12 +133,22 @@ main() { esac local agent="$1" - shift - [[ $# -eq 0 ]] || die "no options are accepted after the agent name (got: $*)" + # All argument checking before anything is created, so a typo does not + # leave a directory behind. Named first, or an option in the agent's place + # is reported as a stray argument instead of an unknown agent. local wrapper="${AGENT_WRAPPERS[${agent}]:-}" [[ -n "${wrapper}" ]] || die "unknown agent '${agent}'. Known agents: $(echo "${!AGENT_WRAPPERS[@]}" | tr ' ' '\n' | sort | tr '\n' ' ')" + [[ $# -eq 1 ]] || die "no options are accepted after the agent name (got: ${*:2})" + + # Staff run this as themselves; set up the agent directory while we still + # are them (they own their home), then re-run as the agent account. + if [[ "$(id -un)" != "${AGENT_ACCOUNT}" ]]; then + [[ "$(id -un)" != root ]] || die "refusing to run for root" + ensure_agent_dir "${HOME}" "$(id -un)" + exec sudo -u "${AGENT_ACCOUNT}" "${SCRIPT_DIR}/${PROGRAM_NAME}" "$@" + fi # The bw* launchers run this too; running it before the audit line keeps a # refused account out of the log and away from the key. @@ -151,6 +167,7 @@ main() { # The one writable place: the agent works in a clone here and a person # moves changes into the live profile. local agent_dir="${home}/${AGENT_SUBDIR}" + reject_symlink "${agent_dir}" [[ -w "${agent_dir}" ]] || die "'${agent_dir}' is not writable by ${AGENT_ACCOUNT}: check its ACL" local agent_home="${AGENT_HOME_BASE}-${user}" @@ -158,9 +175,12 @@ main() { chmod 700 "${agent_home}" || die "cannot secure '${agent_home}'" # Passed in the environment because that is how the wrappers take it; the - # file itself is never mounted. + # file itself is never mounted. Readability is checked first, or bash + # prints its own error about the path before ours. local key - key="$(< "${AIFAPIM_KEY_PATH}")" || die "cannot read the AI gateway key '${AIFAPIM_KEY_PATH}'" + [[ -r "${AIFAPIM_KEY_PATH}" ]] || + die "cannot read the AI gateway key '${AIFAPIM_KEY_PATH}': is the n2c_agent role deployed on this host?" + key="$(< "${AIFAPIM_KEY_PATH}")" [[ -n "${key}" ]] || die "the AI gateway key '${AIFAPIM_KEY_PATH}' is empty" # Audit before anything runs: no log line, no agent. From 33d4ee9f1bfe101bfecfed207ce7bd968055a644 Mon Sep 17 00:00:00 2001 From: Garrett Bischof Date: Mon, 9 Nov 2026 14:20:28 -0500 Subject: [PATCH 09/19] feat(bl-agent): own session, own identity, and the live profile collection 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 --- bin/bl-agent | 154 ++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 139 insertions(+), 15 deletions(-) diff --git a/bin/bl-agent b/bin/bl-agent index b2f4ab9..6b5468a 100755 --- a/bin/bl-agent +++ b/bin/bl-agent @@ -43,23 +43,30 @@ readonly AGENT_CREDS_DIR=/run/nsls2/agent/creds readonly AIFAPIM_GATEWAY_HOST=aifapim.nsls2.bnl.gov # gitleaks:allow readonly ACCOUNT_CHECK=/opt/nsls2/libexec/agent-account-check -# $HOME for the agent account, per caller. The bw* launchers create their -# authoring directories under it on the host before bind-mounting them in, so -# it has to exist and be writable. It cannot be the caller's agent directory: -# a wrapper refuses to run where the working directory is $HOME or above it. -# In /tmp because the agent account has no home and no XDG runtime directory, -# and nothing here needs to outlive a reboot. -readonly AGENT_HOME_BASE=/tmp/bl-agent +# $HOME for the agent account. The bw* launchers create their authoring +# directories under it on the host before bind-mounting them in, so it has to +# exist and be writable. It cannot be the caller's agent directory: a wrapper +# refuses to run where the working directory is $HOME or above it. +# +# Made by the n2c_agent role, on the tmpfs next to the tokens: owned by the +# agent account with mode 0700, so no one else can take a caller's name, and +# nothing kept here outlives a reboot. +readonly AGENT_HOME_BASE=/run/nsls2/agent/home # The live profile collection, relative to the caller's home. $HOME is a tmpfs # in the sandbox, so the rest of the home stays hidden and this one directory -# is mounted read-only; the agent works on a clone of it in the agent -# directory. Not every host has one. +# is mounted read-write: the agent edits and commits in the real repository, +# and a person reviews and pushes afterwards. Not every host has one. readonly PROFILE_COLLECTION=.ipython/profile_collection # The one directory the agent may write in, inside the caller's home. readonly AGENT_SUBDIR=agent +# What the agent's commits are signed with. The account is shared, so the +# name carries the caller; the address does not receive mail. +readonly GIT_IDENTITY="beamline agent" +readonly GIT_EMAIL=noreply@bnl.gov + die() { echo "${PROGRAM_NAME}: $*" >&2 exit 1 @@ -103,6 +110,104 @@ reject_symlink() { die "'$1' is a symlink: the agent directory has to be a real directory in your home" } +# write_npm_config AGENT_HOME CACHE_DIR +# Point npm at the per-caller cache. npm reads ~/.npm, which is in the +# per-session home and so would be thrown away and re-downloaded every +# time. npm_config_cache in the environment does not survive the sandbox's +# fixed variable list, but a dotfile in $HOME is mounted. +write_npm_config() { + local agent_home="$1" cache_dir="$2" + + printf '# %s\ncache=%s/npm\n' "written by ${PROGRAM_NAME}" "${cache_dir}" \ + > "${agent_home}/.npmrc" || die "cannot write '${agent_home}/.npmrc'" +} + +# write_git_config AGENT_HOME CALLER DIR... +# Give the agent an identity to commit with, and mark DIRs safe. Both are +# needed: the agent account has no git config of its own, and git refuses to +# work in a repository owned by someone else, which every one of these is — +# they belong to the caller, or to the beamline on shared storage. +# +# Written in $HOME, which the wrappers mount into the sandbox. The identity +# names the caller because the account is shared: the commit says who asked +# for it, matching the audit line. The address does not receive mail. +write_git_config() { + local agent_home="$1" caller="$2" dir + shift 2 + { + printf '# %s\n[user]\n\tname = %s (%s)\n\temail = %s\n' \ + "written by ${PROGRAM_NAME}" "${caller}" "${GIT_IDENTITY}" "${GIT_EMAIL}" + printf '[safe]\n' + for dir in "$@"; do + [[ -n "${dir}" ]] && printf '\tdirectory = %s\n' "${dir}" + done + } > "${agent_home}/.gitconfig" || die "cannot write '${agent_home}/.gitconfig'" +} + +# say_how_to_publish CALLER [PROFILE] +# The agent can commit but never push: the sandbox has no GitHub credentials +# and no SSH. Say so at the start, with the command to publish afterwards, +# or the work looks lost. +say_how_to_publish() { + local caller="$1" profile="$2" + + [[ -n "${profile}" ]] || return 0 + cat >&2 << EOF +${PROGRAM_NAME}: the profile collection is mounted read-write at + ${profile} +The agent commits there as '${caller} (${GIT_IDENTITY})'. It cannot push: the +sandbox has no GitHub credentials. Review and publish it yourself afterwards: + cd ${profile} && git log --oneline && git push +EOF +} + +# check_profile_collection HOME +# The agent may only reach what the caller can reach. +# +# The link is in the caller's home, so they choose where it points, and the +# sandbox mounts whatever it resolves to. The agent account is granted on +# every beamline's storage, so without this check a caller could aim the +# link at another beamline's profile collection and have the agent open it +# read-write on their behalf — access they do not have themselves. +# +# Run as the caller, so -w is their access, not the agent account's. This +# catches a mistake, not a determined caller: they own the link and can +# repoint it after the check. Scoping the agent account per beamline is +# what would make that pointless. +check_profile_collection() { + local dir="$1/${PROFILE_COLLECTION}" real + + # -L before -e: a link to a directory the caller cannot traverse is not + # -e, and returning here would skip the check in the one case it is for. + [[ -L "${dir}" || -e "${dir}" ]] || return 0 + + # || true: readlink -f fails on a path the caller cannot resolve, and + # errexit would end the script here with no message at all. + real="$(readlink -f "${dir}" 2> /dev/null || true)" + [[ -n "${real}" && -d "${real}" ]] || + die "'${dir}' points somewhere you cannot reach" + [[ -w "${real}" ]] || + die "'${dir}' points at '${real}', which you cannot write: the agent will not open it for you" +} + +# share_profile_collection HOME CALLER +# The agent commits in the live profile collection, so both accounts write +# in one repository. Without default entries, files and git objects created +# by one are unwritable by the other, and the person is locked out of +# committing after the agent has — which is the whole hand-off. +# +# Resolved first: on some hosts this is a symlink to shared storage, and +# setfacl on a symlink fails. Not fatal, because shared storage may not take +# POSIX ACLs at all, and the agent is still worth starting without them. +share_profile_collection() { + local dir="$1/${PROFILE_COLLECTION}" caller="$2" + + [[ -d "${dir}" ]] || return 0 + dir="$(readlink -f "${dir}")" + setfacl -R -m "u:${AGENT_ACCOUNT}:rwx" -m "d:u:${AGENT_ACCOUNT}:rwx" -m "d:u:${caller}:rwx" "${dir}" 2> /dev/null || + echo "${PROGRAM_NAME}: could not share '${dir}' with ${AGENT_ACCOUNT}; it may not be able to commit there" >&2 +} + usage() { cat << EOF Usage: ${PROGRAM_NAME} @@ -147,6 +252,8 @@ main() { if [[ "$(id -un)" != "${AGENT_ACCOUNT}" ]]; then [[ "$(id -un)" != root ]] || die "refusing to run for root" ensure_agent_dir "${HOME}" "$(id -un)" + check_profile_collection "${HOME}" + share_profile_collection "${HOME}" "$(id -un)" exec sudo -u "${AGENT_ACCOUNT}" "${SCRIPT_DIR}/${PROGRAM_NAME}" "$@" fi @@ -164,15 +271,23 @@ main() { home="$(getent passwd "${user}" | cut -d: -f6)" [[ -n "${home}" ]] || die "cannot find the home directory of '${user}'" - # The one writable place: the agent works in a clone here and a person - # moves changes into the live profile. + # Writable, and shared with the caller by ACL so each can read what the + # other writes. local agent_dir="${home}/${AGENT_SUBDIR}" reject_symlink "${agent_dir}" [[ -w "${agent_dir}" ]] || die "'${agent_dir}' is not writable by ${AGENT_ACCOUNT}: check its ACL" - local agent_home="${AGENT_HOME_BASE}-${user}" - mkdir -p "${agent_home}" || die "cannot create '${agent_home}'" - chmod 700 "${agent_home}" || die "cannot secure '${agent_home}'" + # A $HOME per session, so two agents started at once do not race to create + # the same database, and two people sharing an operator account do not + # read each other's conversations. The cache is per caller instead: it is + # most of the size and holds nothing personal. + [[ -d "${AGENT_HOME_BASE}" ]] || + die "'${AGENT_HOME_BASE}' is missing: is the n2c_agent role deployed on this host?" + local caller_dir="${AGENT_HOME_BASE}/${user}" + mkdir -p "${caller_dir}/cache" || die "cannot create '${caller_dir}'" + local agent_home + agent_home="$(mktemp -d "${caller_dir}/session-XXXXXX")" || + die "cannot create a session directory in '${caller_dir}'" # Passed in the environment because that is how the wrappers take it; the # file itself is never mounted. Readability is checked first, or bash @@ -194,16 +309,25 @@ main() { export AIFAPIM_API_KEY="${key}" export PATH="${AGENT_PATH}" export HOME="${agent_home}" + export XDG_CACHE_HOME="${caller_dir}/cache" cd "${agent_dir}" || die "cannot enter '${agent_dir}'" local -a mounts=(--n2c-token all) + local profile="" if [[ -d "${home}/${PROFILE_COLLECTION}" ]]; then - mounts+=(--ro-path "${home}/${PROFILE_COLLECTION}") + # Resolved, because on some hosts this is a symlink to shared storage: + # the sandbox mounts the target, so the link path is not there inside. + profile="$(readlink -f "${home}/${PROFILE_COLLECTION}")" + mounts+=(--rw-path "${profile}") else echo "${PROGRAM_NAME}: no profile collection at '${home}/${PROFILE_COLLECTION}'; starting without it" >&2 fi + write_git_config "${agent_home}" "${user}" "${agent_dir}" "${profile}" + write_npm_config "${agent_home}" "${caller_dir}/cache" + say_how_to_publish "${user}" "${profile}" + exec "${SCRIPT_DIR}/${wrapper}" "${mounts[@]}" } From 842a9a84e1de2690b106f329ad0acc2929241ccc Mon Sep 17 00:00:00 2001 From: Garrett Bischof Date: Mon, 9 Nov 2026 14:57:07 -0500 Subject: [PATCH 10/19] docs(bl-agent): describe the session home and the profile collection The page still said HOME was /tmp/bl-agent- 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 --- docs/bl-agent.md | 48 ++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 40 insertions(+), 8 deletions(-) diff --git a/docs/bl-agent.md b/docs/bl-agent.md index 2221fa1..193e66e 100644 --- a/docs/bl-agent.md +++ b/docs/bl-agent.md @@ -41,15 +41,47 @@ adds them is only read by a login shell. the home, read-write on the agent directory, with default entries for both accounts so each can read what the other writes. This runs as the caller, who owns their home, so it needs no root and no prior ansible run. -- **`HOME`.** `/tmp/bl-agent-`, created on first use, mode `0700`. The - wrappers create their authoring directories +- **The profile collection.** `~/.ipython/profile_collection`, mounted + read-write so the agent can edit and commit in the real repository, and + resolved first because on some hosts it is a symlink to shared storage and + the sandbox mounts the target. The same ACLs are applied to it: without + default entries, the git objects the agent writes are unwritable by the + caller, who is then locked out of committing after the agent has — which is + the whole hand-off. Not fatal if the filesystem refuses them, since the + agent is still useful read-only. + + A caller cannot aim that symlink at another beamline: the launcher resolves + it as them and refuses a target they cannot write. That catches a mistake + rather than a determined caller, who owns the link and can repoint it after + the check; scoping the agent account per beamline is what would make it + pointless. +- **A git identity.** The agent account has no git config, and git refuses to + work in a repository someone else owns, so the launcher writes a + `.gitconfig` in `$HOME` with `user.name` naming the caller + (` (beamline agent)`) and `safe.directory` for the agent directory + and the profile collection. There are no GitHub credentials in the sandbox, + so the agent commits and a person pushes; the launcher says so at startup + and gives the command. +- **`HOME`.** A directory per session, `mktemp -d` under + `/run/nsls2/agent/home//`, which the `n2c_agent` role makes on the + tmpfs next to the tokens. The wrappers create their authoring directories (`~/.config/opencode/{skills,agents,commands}`) there on the host before - bind-mounting them into the sandbox, so it has to exist and be writable. The - agent account has no home of its own and no XDG runtime directory, and - nothing kept here needs to outlive a reboot. It is per caller, so two people - using the account do not share a cache. It cannot be the caller's agent - directory: a wrapper refuses to run where the working directory is `$HOME` - or above it, because that would mount the whole home tree. + bind-mounting them into the sandbox, so it has to exist and be writable. + + Per session, not per caller: two agents started at once would otherwise + race to create the same database, and one dies with a `CREATE TABLE` + error. It also keeps two people sharing an operator account from reading + each other's conversations. + + It cannot be the caller's agent directory: a wrapper refuses to run where + the working directory is `$HOME` or above it, because that would mount the + whole home tree. +- **`XDG_CACHE_HOME`.** `/run/nsls2/agent/home//cache`, shared across + that caller's sessions, so the ~11 MB the agent downloads on a cold start is + not fetched again each time. It holds nothing personal, unlike the session + database. `npm` reads `~/.npm` rather than this, and `npm_config_cache` does + not survive the sandbox's fixed variable list, so the launcher writes an + `.npmrc` in `$HOME` pointing at the same place. - **`PATH`.** `sudo` replaces it with its `secure_path`, which does not hold `/usr/local/bin`, where the agents are installed, so the wrappers would not find them. From 4bcd2298827e44baa709074515d4397078ffc030 Mon Sep 17 00:00:00 2001 From: Garrett Bischof Date: Mon, 9 Nov 2026 15:05:36 -0500 Subject: [PATCH 11/19] feat(bla)!: rename bl-agent to bla and default to opencode 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 --- README.md | 2 +- bin/{bl-agent => bla} | 27 +++++++++++++++------------ docs/{bl-agent.md => bla.md} | 10 +++++++--- 3 files changed, 23 insertions(+), 16 deletions(-) rename bin/{bl-agent => bla} (95%) rename docs/{bl-agent.md => bla.md} (95%) diff --git a/README.md b/README.md index b66feb7..fcbb497 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ docs/ Per-script and per-library documentation | Script | Purpose | Docs | | --- | --- | --- | | `azoidcapp` | Create or reconcile an Entra ID OIDC app + service principal | [docs/azoidcapp.md](docs/azoidcapp.md) | -| `bl-agent` | Start a beamline coding agent as the agent service account | [docs/bl-agent.md](docs/bl-agent.md) | +| `bla` | Start a beamline coding agent as the agent service account | [docs/bla.md](docs/bla.md) | | `bwclaude` | Claude CLI in a bubblewrap sandbox | [docs/bw-wrappers.md](docs/bw-wrappers.md) | | `bwcodex` | OpenAI Codex CLI in a bubblewrap sandbox | [docs/bw-wrappers.md](docs/bw-wrappers.md) | | `bwcopilot` | GitHub Copilot CLI in a bubblewrap sandbox | [docs/bw-wrappers.md](docs/bw-wrappers.md) | diff --git a/bin/bl-agent b/bin/bla similarity index 95% rename from bin/bl-agent rename to bin/bla index 6b5468a..6db1ecd 100755 --- a/bin/bl-agent +++ b/bin/bla @@ -1,7 +1,8 @@ #!/usr/bin/env bash -# bl-agent — start a beamline coding agent as the agent service account. +# bla — start a beamline coding agent as the agent service account. # -# sudo -u xfagent /opt/nsls2/scripts/bin/bl-agent opencode2 +# bla # the default agent +# bla opencode2 # a named one # # This launcher, not the caller, decides what the agent can reach: only the # agent name is taken from the command line, from a fixed list, and no option @@ -37,6 +38,9 @@ readonly AGENT_PATH=/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin # further on every run, so it never settles and CI never goes green. declare -A AGENT_WRAPPERS=([opencode]=bwopencode [opencode2]=bwopencode2 [claude]=bwclaude) +# Started when no agent is named, so the common case is just "bla". +readonly DEFAULT_AGENT=opencode + # Installed by the n2c_agent role; see its defaults in NSLS2/ansible. readonly AIFAPIM_KEY_PATH=/etc/nsls2/agent/aifapim/key readonly AGENT_CREDS_DIR=/run/nsls2/agent/creds @@ -139,7 +143,10 @@ write_git_config() { "written by ${PROGRAM_NAME}" "${caller}" "${GIT_IDENTITY}" "${GIT_EMAIL}" printf '[safe]\n' for dir in "$@"; do - [[ -n "${dir}" ]] && printf '\tdirectory = %s\n' "${dir}" + # continue, not &&: a false test on the last argument would be the + # group's exit status and look like a write failure. + [[ -n "${dir}" ]] || continue + printf '\tdirectory = %s\n' "${dir}" done } > "${agent_home}/.gitconfig" || die "cannot write '${agent_home}/.gitconfig'" } @@ -210,13 +217,13 @@ share_profile_collection() { usage() { cat << EOF -Usage: ${PROGRAM_NAME} +Usage: ${PROGRAM_NAME} [agent] Start a beamline coding agent in its sandbox. It may write only in your agent directory, and reaches the AI gateway and the read-only NSLS-II APIs with the credentials this host keeps. -Agents: +Agents (${DEFAULT_AGENT} when none is named): $(printf ' %s\n' "${!AGENT_WRAPPERS[@]}" | sort) No other options are accepted. @@ -227,17 +234,13 @@ main() { # Before anything else, so asking what this is needs no sudo rule and # creates nothing. case "${1:-}" in - '') - usage >&2 - exit 1 - ;; -h | --help) usage exit 0 ;; esac - local agent="$1" + local agent="${1:-${DEFAULT_AGENT}}" # All argument checking before anything is created, so a typo does not # leave a directory behind. Named first, or an option in the agent's place @@ -245,7 +248,7 @@ main() { local wrapper="${AGENT_WRAPPERS[${agent}]:-}" [[ -n "${wrapper}" ]] || die "unknown agent '${agent}'. Known agents: $(echo "${!AGENT_WRAPPERS[@]}" | tr ' ' '\n' | sort | tr '\n' ' ')" - [[ $# -eq 1 ]] || die "no options are accepted after the agent name (got: ${*:2})" + [[ $# -le 1 ]] || die "no options are accepted after the agent name (got: ${*:2})" # Staff run this as themselves; set up the agent directory while we still # are them (they own their home), then re-run as the agent account. @@ -254,7 +257,7 @@ main() { ensure_agent_dir "${HOME}" "$(id -un)" check_profile_collection "${HOME}" share_profile_collection "${HOME}" "$(id -un)" - exec sudo -u "${AGENT_ACCOUNT}" "${SCRIPT_DIR}/${PROGRAM_NAME}" "$@" + exec sudo -u "${AGENT_ACCOUNT}" "${SCRIPT_DIR}/${PROGRAM_NAME}" "${agent}" fi # The bw* launchers run this too; running it before the audit line keeps a diff --git a/docs/bl-agent.md b/docs/bla.md similarity index 95% rename from docs/bl-agent.md rename to docs/bla.md index 193e66e..a2d4e0a 100644 --- a/docs/bl-agent.md +++ b/docs/bla.md @@ -1,12 +1,16 @@ -# `bl-agent` +# `bla` Starts a beamline coding agent as the agent service account. Beamline staff do not run the `bw*` wrappers as that account themselves: ```bash -sudo -u xfagent /opt/nsls2/scripts/bin/bl-agent opencode2 +bla # the default agent, opencode +bla opencode2 # a named one ``` +Staff run it as themselves; it re-runs itself through `sudo` as the agent +account. + The launcher, not the caller, decides what the agent can reach. 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`, @@ -93,7 +97,7 @@ Both the key and the tokens come from the `n2c_agent` role in NSLS2/ansible. Before anything starts: ```text -bl-agent: agent start: user= host= agent= dir= +bla: agent start: user= host= agent= dir= ``` to syslog at `auth.notice`, so an action is traceable to a person even though From d4349bb978b25ca1317e409245d75e4293e2321b Mon Sep 17 00:00:00 2001 From: Garrett Bischof Date: Mon, 9 Nov 2026 15:09:29 -0500 Subject: [PATCH 12/19] docs: call the tool beamline-agent, the command bla 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 --- README.md | 2 +- bin/bla | 3 ++- docs/{bla.md => beamline-agent.md} | 14 +++++++------- 3 files changed, 10 insertions(+), 9 deletions(-) rename docs/{bla.md => beamline-agent.md} (91%) diff --git a/README.md b/README.md index fcbb497..332fe85 100644 --- a/README.md +++ b/README.md @@ -19,7 +19,7 @@ docs/ Per-script and per-library documentation | Script | Purpose | Docs | | --- | --- | --- | | `azoidcapp` | Create or reconcile an Entra ID OIDC app + service principal | [docs/azoidcapp.md](docs/azoidcapp.md) | -| `bla` | Start a beamline coding agent as the agent service account | [docs/bla.md](docs/bla.md) | +| `bla` | beamline-agent: start a beamline coding agent as the agent service account | [docs/beamline-agent.md](docs/beamline-agent.md) | | `bwclaude` | Claude CLI in a bubblewrap sandbox | [docs/bw-wrappers.md](docs/bw-wrappers.md) | | `bwcodex` | OpenAI Codex CLI in a bubblewrap sandbox | [docs/bw-wrappers.md](docs/bw-wrappers.md) | | `bwcopilot` | GitHub Copilot CLI in a bubblewrap sandbox | [docs/bw-wrappers.md](docs/bw-wrappers.md) | diff --git a/bin/bla b/bin/bla index 6db1ecd..8418b65 100755 --- a/bin/bla +++ b/bin/bla @@ -1,5 +1,6 @@ #!/usr/bin/env bash -# bla — start a beamline coding agent as the agent service account. +# bla — the beamline-agent launcher. Starts a beamline coding agent as the +# agent service account. # # bla # the default agent # bla opencode2 # a named one diff --git a/docs/bla.md b/docs/beamline-agent.md similarity index 91% rename from docs/bla.md rename to docs/beamline-agent.md index a2d4e0a..18ee4d8 100644 --- a/docs/bla.md +++ b/docs/beamline-agent.md @@ -1,7 +1,7 @@ -# `bla` +# beamline-agent -Starts a beamline coding agent as the agent service account. Beamline staff do -not run the `bw*` wrappers as that account themselves: +Starts a beamline coding agent as the agent service account, so beamline staff +do not run the `bw*` wrappers as that account themselves. The command is `bla`: ```bash bla # the default agent, opencode @@ -11,10 +11,10 @@ bla opencode2 # a named one Staff run it as themselves; it re-runs itself through `sudo` as the agent account. -The launcher, not the caller, decides what the agent can reach. 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`. +beamline-agent, not the caller, decides what the agent can reach. 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`. ## Agents From 14af0f74514159a2e1d42ea74bc77bd0035ade94 Mon Sep 17 00:00:00 2001 From: Garrett Bischof Date: Mon, 9 Nov 2026 16:30:28 -0500 Subject: [PATCH 13/19] feat(bla)!: the agent edits but no longer commits 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 --- bin/bla | 51 +++++++++++++++++++----------------------- docs/beamline-agent.md | 30 +++++++++++++------------ 2 files changed, 39 insertions(+), 42 deletions(-) diff --git a/bin/bla b/bin/bla index 8418b65..7f26540 100755 --- a/bin/bla +++ b/bin/bla @@ -67,11 +67,6 @@ readonly PROFILE_COLLECTION=.ipython/profile_collection # The one directory the agent may write in, inside the caller's home. readonly AGENT_SUBDIR=agent -# What the agent's commits are signed with. The account is shared, so the -# name carries the caller; the address does not receive mail. -readonly GIT_IDENTITY="beamline agent" -readonly GIT_EMAIL=noreply@bnl.gov - die() { echo "${PROGRAM_NAME}: $*" >&2 exit 1 @@ -127,22 +122,22 @@ write_npm_config() { > "${agent_home}/.npmrc" || die "cannot write '${agent_home}/.npmrc'" } -# write_git_config AGENT_HOME CALLER DIR... -# Give the agent an identity to commit with, and mark DIRs safe. Both are -# needed: the agent account has no git config of its own, and git refuses to -# work in a repository owned by someone else, which every one of these is — -# they belong to the caller, or to the beamline on shared storage. +# write_git_config AGENT_HOME DIR... +# Mark DIRs safe. git refuses every command in a repository owned by someone +# else — which each of these is, belonging to the caller or to the beamline +# on shared storage — so without this the agent cannot even run git status. +# +# No identity is set. The agent edits but does not commit, and 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. # -# Written in $HOME, which the wrappers mount into the sandbox. The identity -# names the caller because the account is shared: the commit says who asked -# for it, matching the audit line. The address does not receive mail. +# Written in $HOME, which the wrappers mount into the sandbox. write_git_config() { - local agent_home="$1" caller="$2" dir - shift 2 + local agent_home="$1" dir + shift { - printf '# %s\n[user]\n\tname = %s (%s)\n\temail = %s\n' \ - "written by ${PROGRAM_NAME}" "${caller}" "${GIT_IDENTITY}" "${GIT_EMAIL}" - printf '[safe]\n' + printf '# %s\n[safe]\n' "written by ${PROGRAM_NAME}" for dir in "$@"; do # continue, not &&: a false test on the last argument would be the # group's exit status and look like a write failure. @@ -152,20 +147,20 @@ write_git_config() { } > "${agent_home}/.gitconfig" || die "cannot write '${agent_home}/.gitconfig'" } -# say_how_to_publish CALLER [PROFILE] -# The agent can commit but never push: the sandbox has no GitHub credentials -# and no SSH. Say so at the start, with the command to publish afterwards, -# or the work looks lost. +# say_how_to_publish [PROFILE] +# The agent edits but neither commits nor pushes: the sandbox has no git +# identity, no GitHub credentials and no SSH. Say so at the start, with the +# command to review afterwards, or the work looks lost. say_how_to_publish() { - local caller="$1" profile="$2" + local profile="$1" [[ -n "${profile}" ]] || return 0 cat >&2 << EOF ${PROGRAM_NAME}: the profile collection is mounted read-write at ${profile} -The agent commits there as '${caller} (${GIT_IDENTITY})'. It cannot push: the -sandbox has no GitHub credentials. Review and publish it yourself afterwards: - cd ${profile} && git log --oneline && git push +The agent edits it but does not commit, and cannot push: the sandbox has no +git identity and no GitHub credentials. Review and commit yourself afterwards: + cd ${profile} && git diff EOF } @@ -328,9 +323,9 @@ main() { echo "${PROGRAM_NAME}: no profile collection at '${home}/${PROFILE_COLLECTION}'; starting without it" >&2 fi - write_git_config "${agent_home}" "${user}" "${agent_dir}" "${profile}" + write_git_config "${agent_home}" "${agent_dir}" "${profile}" write_npm_config "${agent_home}" "${caller_dir}/cache" - say_how_to_publish "${user}" "${profile}" + say_how_to_publish "${profile}" exec "${SCRIPT_DIR}/${wrapper}" "${mounts[@]}" } diff --git a/docs/beamline-agent.md b/docs/beamline-agent.md index 18ee4d8..3657383 100644 --- a/docs/beamline-agent.md +++ b/docs/beamline-agent.md @@ -46,26 +46,28 @@ adds them is only read by a login shell. accounts so each can read what the other writes. This runs as the caller, who owns their home, so it needs no root and no prior ansible run. - **The profile collection.** `~/.ipython/profile_collection`, mounted - read-write so the agent can edit and commit in the real repository, and - resolved first because on some hosts it is a symlink to shared storage and - the sandbox mounts the target. The same ACLs are applied to it: without - default entries, the git objects the agent writes are unwritable by the - caller, who is then locked out of committing after the agent has — which is - the whole hand-off. Not fatal if the filesystem refuses them, since the - agent is still useful read-only. + read-write so the agent can edit the real repository, and resolved first + because on some hosts it is a symlink to shared storage and the sandbox + mounts the target. The same ACLs are applied to it: without default + entries, the files the agent writes are unwritable by the caller, who is + then locked out of committing them — which is the whole hand-off. Not fatal + if the filesystem refuses them, since the agent is still useful read-only. A caller cannot aim that symlink at another beamline: the launcher resolves it as them and refuses a target they cannot write. That catches a mistake rather than a determined caller, who owns the link and can repoint it after the check; scoping the agent account per beamline is what would make it pointless. -- **A git identity.** The agent account has no git config, and git refuses to - work in a repository someone else owns, so the launcher writes a - `.gitconfig` in `$HOME` with `user.name` naming the caller - (` (beamline agent)`) and `safe.directory` for the agent directory - and the profile collection. There are no GitHub credentials in the sandbox, - so the agent commits and a person pushes; the launcher says so at startup - and gives the command. +- **A git config.** git refuses every command in a repository someone else + owns, so the launcher writes a `.gitconfig` in `$HOME` with + `safe.directory` for the agent directory and the profile collection. + Without it the agent cannot even run `git status`. + + No `user.name` is set. The agent edits but does not commit, and leaving the + identity out makes a commit fail with "please tell me who you are" rather + than succeed quietly. That guards a mistake rather than a determined agent, + which can pass `git -c user.name`. There are no GitHub credentials either, + so a person reviews and commits; the launcher says so at startup. - **`HOME`.** A directory per session, `mktemp -d` under `/run/nsls2/agent/home//`, which the `n2c_agent` role makes on the tmpfs next to the tokens. The wrappers create their authoring directories From 7a8d09d3cdaeafbef5589c75b36c573c429955fa Mon Sep 17 00:00:00 2001 From: Garrett Bischof Date: Mon, 9 Nov 2026 17:23:01 -0500 Subject: [PATCH 14/19] fix(bla): only share the profile collection where ACLs work 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 --- bin/bla | 31 +++++++++++++++++++++++-------- 1 file changed, 23 insertions(+), 8 deletions(-) diff --git a/bin/bla b/bin/bla index 7f26540..465e9d2 100755 --- a/bin/bla +++ b/bin/bla @@ -67,6 +67,11 @@ readonly PROFILE_COLLECTION=.ipython/profile_collection # The one directory the agent may write in, inside the caller's home. readonly AGENT_SUBDIR=agent +# Filesystems that take POSIX ACLs, so the agent directory and the profile +# collection can be shared with the agent account. Shared storage is not one: +# see the ansible compliance role's compliance_agent_acls_fstypes. +readonly ACL_FSTYPES="xfs ext4 ext3 btrfs" + die() { echo "${PROGRAM_NAME}: $*" >&2 exit 1 @@ -194,21 +199,31 @@ check_profile_collection() { } # share_profile_collection HOME CALLER -# The agent commits in the live profile collection, so both accounts write -# in one repository. Without default entries, files and git objects created -# by one are unwritable by the other, and the person is locked out of -# committing after the agent has — which is the whole hand-off. +# Both accounts write in one directory, so without default entries the files +# one creates are unwritable by the other and the person is locked out of +# committing what the agent wrote — which is the whole hand-off. +# +# Only on a filesystem that takes POSIX ACLs. A profile collection usually +# lives on shared storage, where setfacl fails and a recursive attempt walks +# thousands of files to achieve nothing. The list matches the ansible +# compliance role's compliance_agent_acls_fstypes. # # Resolved first: on some hosts this is a symlink to shared storage, and -# setfacl on a symlink fails. Not fatal, because shared storage may not take -# POSIX ACLs at all, and the agent is still worth starting without them. +# setfacl on a symlink fails. share_profile_collection() { - local dir="$1/${PROFILE_COLLECTION}" caller="$2" + local dir="$1/${PROFILE_COLLECTION}" caller="$2" fstype [[ -d "${dir}" ]] || return 0 dir="$(readlink -f "${dir}")" + + fstype="$(findmnt -no FSTYPE --target "${dir}" 2> /dev/null)" + if [[ " ${ACL_FSTYPES} " != *" ${fstype} "* ]]; then + echo "${PROGRAM_NAME}: '${dir}' is on ${fstype:-an unknown filesystem}, which does not take POSIX ACLs; the agent can read it but not change it" >&2 + return 0 + fi + setfacl -R -m "u:${AGENT_ACCOUNT}:rwx" -m "d:u:${AGENT_ACCOUNT}:rwx" -m "d:u:${caller}:rwx" "${dir}" 2> /dev/null || - echo "${PROGRAM_NAME}: could not share '${dir}' with ${AGENT_ACCOUNT}; it may not be able to commit there" >&2 + echo "${PROGRAM_NAME}: could not share '${dir}' with ${AGENT_ACCOUNT}; it can read it but not change it" >&2 } usage() { From dbd9aef91cc3745695e8f3e9649a73ecb86b20ff Mon Sep 17 00:00:00 2001 From: Garrett Bischof Date: Mon, 9 Nov 2026 17:57:44 -0500 Subject: [PATCH 15/19] feat(bla): take the gateway host from the host, not the script 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 --- bin/bla | 22 +++++++++++++++++++--- 1 file changed, 19 insertions(+), 3 deletions(-) diff --git a/bin/bla b/bin/bla index 465e9d2..e8b23f9 100755 --- a/bin/bla +++ b/bin/bla @@ -39,12 +39,19 @@ readonly AGENT_PATH=/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin # further on every run, so it never settles and CI never goes green. declare -A AGENT_WRAPPERS=([opencode]=bwopencode [opencode2]=bwopencode2 [claude]=bwclaude) -# Started when no agent is named, so the common case is just "bla". -readonly DEFAULT_AGENT=opencode +# Started when no agent is named, so the common case is just "bla". opencode2 +# because it is the wrapper that sends the gateway an Entra token; opencode +# sends only the subscription key and the gateway refuses it. +readonly DEFAULT_AGENT=opencode2 # Installed by the n2c_agent role; see its defaults in NSLS2/ansible. readonly AIFAPIM_KEY_PATH=/etc/nsls2/agent/aifapim/key readonly AGENT_CREDS_DIR=/run/nsls2/agent/creds +# The gateway. The n2c_agent role writes the host next to the key, from the +# same variable the base role puts in /etc/profile.d/aifapim.sh, so a gateway +# move is fixed by a baseline run rather than a release of this script. The +# constant is only the fallback for a host the role has not reached yet. +readonly AIFAPIM_HOST_PATH=/etc/nsls2/agent/aifapim/host readonly AIFAPIM_GATEWAY_HOST=aifapim.nsls2.bnl.gov # gitleaks:allow readonly ACCOUNT_CHECK=/opt/nsls2/libexec/agent-account-check @@ -319,8 +326,17 @@ main() { # The tokens come from the root minter, not an n2c-token session this # account does not have. export N2SN_CREDS_DIR="${AGENT_CREDS_DIR}" - export AIFAPIM_HOST="${AIFAPIM_GATEWAY_HOST}" + local gateway="${AIFAPIM_GATEWAY_HOST}" + if [[ -r "${AIFAPIM_HOST_PATH}" ]]; then + gateway="$(< "${AIFAPIM_HOST_PATH}")" + [[ -n "${gateway}" ]] || die "'${AIFAPIM_HOST_PATH}' is empty" + fi + export AIFAPIM_HOST="${gateway}" export AIFAPIM_API_KEY="${key}" + # The gateway wants an Entra token as well as the key. The path, not the + # token: the file is mounted by --n2c-token and the wrapper's plugin reads + # it, so a token minted mid-session is picked up without a restart. + export AIFAPIM_TOKEN_FILE="${AGENT_CREDS_DIR}/aifapim/token" export PATH="${AGENT_PATH}" export HOME="${agent_home}" export XDG_CACHE_HOME="${caller_dir}/cache" From d375527a0156387c43244db181c2bd345ab2c576 Mon Sep 17 00:00:00 2001 From: Garrett Bischof Date: Fri, 13 Nov 2026 13:09:59 -0500 Subject: [PATCH 16/19] docs(bla): say why the session home is on the host 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 --- bin/bla | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/bin/bla b/bin/bla index e8b23f9..436343e 100755 --- a/bin/bla +++ b/bin/bla @@ -63,6 +63,9 @@ readonly ACCOUNT_CHECK=/opt/nsls2/libexec/agent-account-check # Made by the n2c_agent role, on the tmpfs next to the tokens: owned by the # agent account with mode 0700, so no one else can take a caller's name, and # nothing kept here outlives a reboot. +# +# On the host rather than a tmpfs inside the sandbox, so a session's state +# outlives the sandbox that wrote it and a session can be reopened later. readonly AGENT_HOME_BASE=/run/nsls2/agent/home # The live profile collection, relative to the caller's home. $HOME is a tmpfs @@ -302,6 +305,10 @@ main() { # the same database, and two people sharing an operator account do not # read each other's conversations. The cache is per caller instead: it is # most of the size and holds nothing personal. + # + # Each run makes a new session directory, so nothing is reopened yet. The + # state is kept rather than discarded so that reopening one is a change + # here, not a change to where every agent stores its data. [[ -d "${AGENT_HOME_BASE}" ]] || die "'${AGENT_HOME_BASE}' is missing: is the n2c_agent role deployed on this host?" local caller_dir="${AGENT_HOME_BASE}/${user}" From 5fb17ad7840dd68549435f3cbb2fc0279d019fc7 Mon Sep 17 00:00:00 2001 From: Garrett Bischof Date: Fri, 13 Nov 2026 17:09:30 -0500 Subject: [PATCH 17/19] docs(bla): the caller is the operator account, not staff themselves 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 --- bin/bla | 15 +++++++++------ 1 file changed, 9 insertions(+), 6 deletions(-) diff --git a/bin/bla b/bin/bla index 436343e..727e019 100755 --- a/bin/bla +++ b/bin/bla @@ -19,9 +19,11 @@ set -o pipefail readonly PROGRAM_NAME="${0##*/}" -# The account the agents run as. Staff run this script as themselves; it -# re-runs itself through sudo, so nobody has to remember the account name or -# the sudo line. The sudoers rule still decides who is allowed. +# The account the agents run as. The caller runs this script as whoever they +# are -- the sudoers rule names the beamline operator account, so that is +# normally it -- and it re-runs itself through sudo, so nobody has to remember +# the account name or the sudo line. The sudoers rule still decides who is +# allowed. readonly AGENT_ACCOUNT=xfagent # The bw* wrappers sit next to this script, and are run by absolute path: sudo @@ -271,8 +273,9 @@ main() { die "unknown agent '${agent}'. Known agents: $(echo "${!AGENT_WRAPPERS[@]}" | tr ' ' '\n' | sort | tr '\n' ' ')" [[ $# -le 1 ]] || die "no options are accepted after the agent name (got: ${*:2})" - # Staff run this as themselves; set up the agent directory while we still - # are them (they own their home), then re-run as the agent account. + # Still the caller here, normally the beamline operator account. Set up the + # agent directory now, while we are the account that owns the home, because + # the agent account cannot create it there. Then re-run as the agent. if [[ "$(id -un)" != "${AGENT_ACCOUNT}" ]]; then [[ "$(id -un)" != root ]] || die "refusing to run for root" ensure_agent_dir "${HOME}" "$(id -un)" @@ -288,7 +291,7 @@ main() { fi local user="${SUDO_USER:-}" - [[ -n "${user}" ]] || die "cannot tell who you are: run ${PROGRAM_NAME} as yourself, not as ${AGENT_ACCOUNT}" + [[ -n "${user}" ]] || die "cannot tell who you are: run ${PROGRAM_NAME} from the account you logged in with, not as ${AGENT_ACCOUNT}" [[ "${user}" != root ]] || die "refusing to run for root" local home From d417e06f6172e269749138edd741c02dbdd52ba3 Mon Sep 17 00:00:00 2001 From: Garrett Bischof Date: Fri, 13 Nov 2026 17:12:40 -0500 Subject: [PATCH 18/19] fix(bla): derive the re-exec path from the resolved script path 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 --- bin/bla | 18 ++++++++++-------- 1 file changed, 10 insertions(+), 8 deletions(-) diff --git a/bin/bla b/bin/bla index 727e019..851ce12 100755 --- a/bin/bla +++ b/bin/bla @@ -17,7 +17,15 @@ set -o errexit set -o nounset set -o pipefail -readonly PROGRAM_NAME="${0##*/}" +# Where this script really is. Everything is derived from the resolved path, so +# running it through a symlink cannot change the command sudo is asked for, or +# the name in the audit line. SCRIPT_DIR is where the bw* wrappers sit: they are +# run by absolute path, because sudo replaces PATH with its secure_path and the +# profile.d snippet that adds them is only read by a login shell. +SCRIPT_PATH="$(readlink -f -- "$0")" +readonly SCRIPT_PATH +readonly SCRIPT_DIR="${SCRIPT_PATH%/*}" +readonly PROGRAM_NAME="${SCRIPT_PATH##*/}" # The account the agents run as. The caller runs this script as whoever they # are -- the sudoers rule names the beamline operator account, so that is @@ -26,12 +34,6 @@ readonly PROGRAM_NAME="${0##*/}" # allowed. readonly AGENT_ACCOUNT=xfagent -# The bw* wrappers sit next to this script, and are run by absolute path: sudo -# replaces PATH with its secure_path, and the profile.d snippet that adds them -# is only read by a login shell. -SCRIPT_DIR="$(cd -P -- "$(dirname -- "$(readlink -f -- "$0")")" && pwd -P)" -readonly SCRIPT_DIR - # The wrappers find their agent by name, and sudo's secure_path does not hold # /usr/local/bin, where npm installs them. readonly AGENT_PATH=/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin @@ -281,7 +283,7 @@ main() { ensure_agent_dir "${HOME}" "$(id -un)" check_profile_collection "${HOME}" share_profile_collection "${HOME}" "$(id -un)" - exec sudo -u "${AGENT_ACCOUNT}" "${SCRIPT_DIR}/${PROGRAM_NAME}" "${agent}" + exec sudo -u "${AGENT_ACCOUNT}" "${SCRIPT_PATH}" "${agent}" fi # The bw* launchers run this too; running it before the audit line keeps a From 2a50357ac304dbd283418929cde82e41db54858d Mon Sep 17 00:00:00 2001 From: Garrett Bischof Date: Fri, 13 Nov 2026 17:15:33 -0500 Subject: [PATCH 19/19] docs(bla): say why the caller has to be known 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 --- bin/bla | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/bin/bla b/bin/bla index 851ce12..3d21cd5 100755 --- a/bin/bla +++ b/bin/bla @@ -292,8 +292,13 @@ main() { "${ACCOUNT_CHECK}" || exit $? fi + # Not a permission check: the agent account is already here. SUDO_USER is + # the only way to tell whose home to find ~/agent and the profile + # collection in, whose session directory to use, and whose name to log. + # The agent account's own home holds none of that, so guessing it would + # mount an empty directory and attribute the session to nobody. local user="${SUDO_USER:-}" - [[ -n "${user}" ]] || die "cannot tell who you are: run ${PROGRAM_NAME} from the account you logged in with, not as ${AGENT_ACCOUNT}" + [[ -n "${user}" ]] || die "cannot tell whose home to mount: run ${PROGRAM_NAME} from the account you logged in with, not as ${AGENT_ACCOUNT}" [[ "${user}" != root ]] || die "refusing to run for root" local home