@rackbops/ac-agent 2.0.0-alpha.53 → 2.0.0-alpha.55

package/README.md

@@ -272,7 +272,12 @@ packaged app (see **Run install from a normal shell** above), which also prints
 session's AppData is virtualized (<packageFamily>); the logon task cannot see <stateDir> -- see
 README, Install` line to stderr. `serve` logs the same warning line once at startup, in the same
 circumstance, without refusing to start. `update` (#659) is the last `install --update`'s record from
-`update.json`, or `null` when there is none or it is unreadable.
+`update.json`, or `null` when there is none or it is unreadable. `toolchainUpgrade: true/false` (#675) is
+the machine owner's own opt-in to `POST /v1/toolchain/upgrade` (`toolchain_upgrade` in `agent.toml`, or
+`AC_AGENT_TOOLCHAIN_UPGRADE`), `false` by default. Like the other fields it is what `status` loads from
+`agent.toml` and the environment of the shell that ran `status`: what a start from that file and shell
+would load, not what the running agent holds (it read its config once, at start, and an installed
+task/unit does not see that shell's variables).
 
 ## Pair
 
@@ -368,6 +373,22 @@ written (as `publish_dir`'s is, so a typo in an optional key can never stop `ser
 path` (or a `preflight-unusable` warning naming `tunnel_preflight`). A blank or non-string value in the
 file is treated as unset. `install` takes no flag for either and `status` does not report them.
 
+`toolchain_upgrade` (#675; `false` unless set) is **the machine owner's own opt-in** to `POST
+/v1/toolchain/upgrade`, the verb that installs software here (see **`POST /v1/toolchain/upgrade`**).
+It is a TOML boolean, written to `agent.toml` only when `true`; only a boolean `true` counts (a quoted
+string, a number or a misspelled key is `false`; an unquoted word that is not a TOML boolean, such as
+`True` or `yes`, is invalid TOML and fails the whole config load). Live override
+`AC_AGENT_TOOLCHAIN_UPGRADE`: `1`/`true` or `0`/`false` (case-insensitive); blank is unset; anything
+else throws at load, naming the value. **The override only reaches the process that reads it**: a
+foreground `serve` started from that shell, or a unit/task whose own environment sets it (the
+installed task and unit do not see the shell's variables, as the paragraph above explains). A fresh `install` run with it
+set writes `toolchain_upgrade = true` into the new `agent.toml`, where it then stays. Like every key it
+is read once when the agent starts, so a change needs `ac-agent stop` and `start` (or a restart of the
+task/unit). `status` prints `toolchainUpgrade: true|false`: what a start from `agent.toml` and the
+shell's own environment would load, not what the running agent holds, so after a change restart first
+and treat the agent's `403 not-opted-in` as the truth. The console's grant alone never turns it on: the
+verb answers `403 not-opted-in` until this key is set.
+
 ## Verbs
 
 Everything under `/v1/*` except `/v1/health` and `/v1/pair` requires pairing (see **Security
@@ -375,7 +396,8 @@ model**). The verb registry fills `GET /v1/health`'s `capabilities` field with t
 list of every registered verb's capability name — with every verb group registered, that's
 `["agent.desktop.open", "agent.exec.claude", "agent.exec.gh", "agent.git.pull", "agent.git.read",
 "agent.publish.mirror", "agent.scan.context-pressure", "agent.scan.memory-footprint",
-"agent.scan.subagent-cost", "agent.scan.toolchain-inventory", "agent.tunnel.lint"]`.
+"agent.scan.subagent-cost", "agent.scan.toolchain-inventory", "agent.toolchain.upgrade",
+"agent.tunnel.lint"]`.
 
 **Every verb also requires two headers, checked in this order** (#50), after the bearer check
 passes: `X-AC-Plugin` (the calling plugin's id) missing or shaped wrong is `400 {ok: false, error:
@@ -492,14 +514,18 @@ capability, plugin}`. See **Security model** for how a grant reaches the agent i
   `^[A-Za-z0-9._-]{1,64}$` string. Any other shape is `400` before anything spawns. `claude` runs as
   `claude -p <prompt> --permission-mode <mode> --add-dir <repo path> [--model <model>]`, `cwd` the
   resolved repo. **At most 4 `claude` jobs run at once** — a 5th concurrent request is
-  `429 {ok: false, error: "too many running jobs"}`, checked before spawning, not after.
+  `429 {ok: false, error: "too many running jobs"}`, checked before spawning, not after. Only `claude`
+  jobs count: a running toolchain upgrade (#675) neither uses up a slot nor is blocked by a claude job.
 - **`GET /v1/jobs`** (`agent.exec.claude`) → `{ok: true, jobs: [view...]}`, newest first.
   **`GET /v1/jobs/:id`** → `{ok: true, job: view}` or `404` for an unknown id. A job view is
   `{id, kind: "claude", label, status: "running"|"done"|"failed", startedAt, endedAt?,
   exitCode?: number|null, repo, permissionMode}`. **`POST /v1/jobs/clear-finished`** →
-  `{ok: true, cleared}`, dropping every done/failed job (running ones are kept).
+  `{ok: true, cleared}`, dropping every done/failed job (running ones are kept). **These routes serve
+  `claude` jobs only (#675):** the registry also holds `toolchain-upgrade` jobs, which a plugin holding
+  only `agent.exec.claude` must not list, read, stream or clear, so another kind's job id is `404 no such
+  job` here, exactly like an unknown one, and `clear-finished` leaves them alone.
 - **`GET /v1/jobs/:id/events`** (`agent.exec.claude`) streams a job's log as Server-Sent Events: a
-  `404` for an unknown id up front, otherwise a finished job replays its whole buffer and closes,
+  `404` for an unknown id (or another kind's) up front, otherwise a finished job replays its whole buffer and closes,
   and a running job replays its buffer then streams new lines live as they arrive, closing once the
   job finishes. Two frame shapes only: `event: line` with `data` the JSON-encoded line text and `id`
   the line's absolute position in the job's log (so a reconnecting client can tell whether it missed
@@ -726,6 +752,197 @@ the preflight's own finding messages are passed through as the script wrote them
 <engine> ok=<bool> errors=<n> warns=<n> hostnames=<n>` or `tunnel lint: unavailable (<reason>)`, with
 any line break in a path flattened to a space.
 
+## `POST /v1/toolchain/upgrade` (#675)
+
+**`POST /v1/toolchain/upgrade`** (`agent.toolchain.upgrade`) upgrades one tool on this machine with
+the package manager's own command, so the Environment panel can bring a machine that is behind the
+fleet standard back to it. **It is the one verb that installs software here**, so it is built so that
+the console can ask for exactly one kind of thing and nothing else.
+
+**Two gates, both required.** The console's grant for `agent.toolchain.upgrade` (the ordinary guard,
+see **Verbs**), then this machine's own opt-in, `toolchain_upgrade = true` in `agent.toml` (see
+**Config and state directories**): without it the answer is `403 {ok: false, error: "toolchain upgrades
+are not enabled on this machine (agent.toml toolchain_upgrade)", reason: "not-opted-in"}`, and it is
+given before the body is even read, so a machine that has not opted in does no work for a request. A body
+over **4096 bytes** is `413 {ok: false, error: "request body too large"}` (a valid one is a few hundred),
+by header and as it streams, before it is parsed.
+
+**The request** is `{tool, cmd, manager, packageId}`. Every field is checked against a grammar before
+anything starts; a request that fails is `400 {ok: false, error: "<field>: <why>"}`.
+
+| Field | Meaning | Must be |
+|---|---|---|
+| `tool` | the standard's tool key; the job's label and the audit lines only, never part of a command | `^[A-Za-z0-9][A-Za-z0-9 ._+-]{0,63}$` (words, spaces allowed as in `GitHub CLI`: no `"`, `:`, `(`, `)`, `>` or `,`, and the audit lines print it in quotes, so one run's line cannot imitate another's outcome) |
+| `cmd` | the tool whose `--version` is read before and after; found with `which`, run for nothing else | one of **`git`, `gh`, `node`, `claude`**: the tools the agent's own preflight already runs `--version` on (`PREREQ_TABLE` minus `chromium`, which it never executes), which are the `cmd`s of the preflight rows the Environment panel sends. Any other name is `400 cmd: not a tool this agent reads the version of` |
+| `manager` | which package manager | `winget` (Windows only), `apt` (Linux only) or `native` |
+| `packageId` | the package | `winget`: `^[A-Za-z0-9][A-Za-z0-9.+_-]{0,127}$` with a `.` (a `Publisher.Name` id); `apt`: the Debian package-name grammar `^[a-z0-9][a-z0-9+.-]{1,127}$`, not ending in `-`; `native`: exactly `claude` (and `cmd` exactly `claude`) |
+
+A field is read only as the body's own property. An `apt` name ending in `-` is refused because
+`apt-get` reads a trailing `-` on a package argument as "remove it".
+
+**The command is never built from free text.** There are three fixed shapes, and the package id is the only
+variable in them:
+
+- `winget upgrade --id <id> --exact --silent --accept-package-agreements --accept-source-agreements
+  --disable-interactivity`
+- `sudo -n apt-get install --only-upgrade -y --no-remove <package>`
+- `claude update` (the native Claude Code updater; a `claude` that is only an npm `.cmd` shim is
+  `502 claude is a .cmd shim; install the native binary`)
+
+`--no-remove` is a tightening of the shape on top of `-y` (`apt-get(8)`: "If any packages are to be
+removed apt-get immediately aborts without prompting"). For `-y`, `apt-get(8)` says: "If an undesirable
+situation, such as changing a held package, trying to install an unauthenticated package or removing an
+essential package occurs then apt-get will abort." Removing a package that is not essential is not on
+that list, so an upgrade whose new version Conflicts with or Breaks another installed package could,
+as far as the manual says, remove that package without asking (an inference from the manual; not run
+here). It still installs the new dependencies the upgrade needs (`apt-get(8)`).
+
+The worst a hostile console can do with a valid request is upgrade an installed package the operator
+did not mean, with the new dependencies that upgrade needs (never removing a package). Apart from the
+package id, the one thing the request names is `cmd`, and it can only pick
+one of the four tools above to run `--version` on (never a program of its choosing); it cannot install
+or run anything else from the request's text. The verb does not tie `cmd` to `packageId`: `cmd` only says
+whose version is read, so a request naming `git` with another package's id reports the status of git's
+version. The audit lines name `cmd` for that reason. For `apt` the package must also **be an installed
+package, exactly**: just before the upgrade starts (after the `before` version read, so a package removed
+in between is caught), the agent runs `dpkg-query --show` on
+the literal name and refuses (`400 packageId: <name> is not an installed package`) unless it reports that
+name as installed. This matters because `apt-get` falls back to treating a package argument that matches
+nothing as a POSIX regular expression (`apt-get(8)`: "applied to all package names in the database"),
+which with `--only-upgrade` would upgrade every installed package it matches.
+
+**One at a time.** A second request while one runs is `429 {ok: false, error: "an upgrade is already
+running on this machine"}`; the cap check and the reservation of the slot are one synchronous step, so
+two simultaneous requests cannot both pass, and the self-update refusal (`/v1/update`, `409 jobs running`)
+counts an upgrade that has passed its check but not yet started its job. A tool that cannot be found
+(`winget`, `sudo`, `dpkg-query`, `cmd`) is `502 {ok: false, error: "<name> not found on PATH"}`. A running
+claude job does not count against it, and it does not count against the claude cap.
+
+**The job.** The answer is `202 {ok: true, jobId}` and the upgrade runs as a job (`kind:
+"toolchain-upgrade"`, `repo` the manager, `permissionMode` empty, `label` `<tool> via <manager>
+<packageId>`) because `apt` and `winget` outlast the host's 30 s body budget. It is killed after **15
+minutes** (on Windows with its whole process tree, since winget's work runs in child installers) or once
+it has printed **1 MiB** (counting a line that never ends); the output cap and the timeout both end it as
+`failed` or `timed-out`, with a log line (`[timed out after N ms; killed]`, `[output capped at N
+characters; killed]`). A child's `close` event waits for every holder of its output pipes, so a
+process it started (an `apt-get` under `sudo`, an installer's helper) that keeps them open would hold the
+job `running` after the command is over, and the one upgrade slot with it. Two bounds stop that. **A
+command that has exited** keeps its real exit code (the code a kill left, `null` for a signal): its output
+is given 5 seconds to close, then the job finishes as the exit code says, with the line `[the command
+exited, but its output never closed; processes it started may still be running]`. The timeout and the
+output cap are never applied to a command that has already exited (its process id may by then be another
+process's, and `taskkill /t /f` on it would take that one and everything it started): a cap crossed by a
+descendant's output after the exit is recorded (`failed`; the log line `[output capped at N characters;
+killed]` is printed as always although there was nothing left to kill) and the rest dropped. **A command
+that was killed (a limit) and never even exits** is finished 15 seconds after the kill with a null exit
+code and the line `[killed, but its output never closed; processes it started may still be running]`; one
+that does exit meanwhile is finished at the earlier of 5 seconds after its exit and 15 seconds after the
+kill, as above. In both cases the agent's end of the pipes is **drained, not closed**: closing the read
+end makes the next write of whoever still holds the pipe raise SIGPIPE, which by default ends it, and
+these are processes the agent must not disturb (a root-owned `apt-get` in the middle of a dpkg
+transaction, a service a maintainer script started). What they write from then on is discarded, up to
+64 MiB: past that the pipes are closed after all, because draining a flood costs the agent most of a
+core for as long as the writer runs, and closing ends only that writer. The agent cannot signal a
+process it does not own either way. The job then finishes after the outcome is computed (a PATH refresh, up to about 10
+seconds on Windows, and the `after` version read, up to about 25), and that is when the slot is free. The
+log is: the exact command as its first line, then `before: <version|missing>`,
+the command's own output, then `after: <version|missing>` and `result: <status>` (with ` (<reason>)` when
+there is one). The trailer is the agent's; a child can print its own `result:` line earlier in the log, so
+read the outcome from the status route, never by scanning the log. `before` and `after` are the first line of
+`<cmd> --version`, read with the PATH refreshed from the registry on Windows (the preflight's own search)
+so a tool the upgrade just installed is seen; a read that exits non-zero, prints nothing, or has not
+answered within 25 seconds is `missing`, and its output is bounded at 64 KiB.
+
+**Routes, all under `agent.toolchain.upgrade`** (a plugin holding only this capability reads only this
+kind's jobs, and one holding only `agent.exec.claude` never reads these):
+
+- **`GET /v1/toolchain/upgrade/:jobId`** → `{ok: true, job: <view>, outcome?: {status, reason?, before,
+  after}}`; `outcome` is present once the agent has worked the outcome out, when the command is over (a
+  job whose launch threw has none: its request was a `500` that returned no job id). `404 no such job` for
+  an unknown id or another kind's.
+- **`GET /v1/toolchain/upgrade/:jobId/events`** → the same Server-Sent Events as `/v1/jobs/:id/events`
+  (`event: line`, then `event: done` with the exit code), `404` for another kind's job.
+
+**Outcomes** (the job's `status` is `done` for the first two and `failed` for the rest):
+
+| `status` | When | Its `reason` |
+|---|---|---|
+| `upgraded` | exit 0 and the version changed (apt: `N upgraded` with `N` of 1 or more also counts) | none |
+| `already-current` | exit 0 and the version is unchanged; winget's `0x8A15002B` (no applicable update) also maps here, and means "no newer version this machine can install", which is not always the same as "current" | for the winget code |
+| `needs-sudoers` | `apt`: `sudo -n` refused, in sudo 1.9's wording (`a password is required`, `is not in the sudoers file`, `is not allowed to execute`, `is not allowed to run sudo on`, `user <u> may not run sudo on <host>`) or sudo-rs's, the default `sudo` of recent Ubuntu (`interactive authentication is required`, `I'm afraid I can't do that`, `user <u> may not run <command> on <host>`) | the sudoers rule to add, with what it grants |
+| `needs-elevation` | `winget`: its `0x8A150019` return code (command requires administrator privileges) | the command to paste into an elevated terminal |
+| `failed` | any other non-zero exit (the last output line, printable and cut at 300 characters), winget's `0x8A150014` (no installed package with that id), the output cap, a version that cannot be read after an exit 0, a command that could not start | what failed |
+| `timed-out` | the 15-minute limit | check the package before retrying: it may be half-installed |
+
+The winget return codes are pinned by number from winget's own generated table
+(`microsoft/winget-cli`, `doc/windows/package-manager/winget/returnCodes.md`); Node reports a Windows exit
+code unsigned, so the job's `exitCode` for `0x8A15002B` is `2316632107`. Only `0x8A150019` is documented as
+a "needs administrator" code, and it is a command-level one. **What winget does for a machine-scope
+package, or an installer that elevates itself, when its caller is not elevated has not been verified
+here**: it may relaunch the installer through UAC, which puts a consent prompt on the logon user's
+desktop (the agent is a logon task in that session) that the agent cannot answer; the job then waits
+until it is answered or the 15-minute limit fires (`timed-out`), and a limited `taskkill` cannot end an
+elevated installer. Anything else an installer fails with is `failed`, with its last output line.
+
+**Audit.** Two lines in the agent log per run: `toolchain upgrade started: "<tool>" via <manager>
+<packageId> (version of <cmd>)` when the job starts (so a run the agent does not survive is on record),
+and, when it finishes, `toolchain upgrade: "<tool>" via <manager> <packageId>: <before> -> <after> (<status>,
+exit <code>, version of <cmd>)`. The tool key is console-supplied, so it is printed in quotes (its
+grammar has none); `cmd` is named because the versions are `cmd`'s, which the verb does not tie to the
+package id. `exit none` means the command left no exit code: it could not be started, or it was killed
+(by the timeout, the output cap or a signal, which on Linux closes with no code). A request that throws
+while starting (before or after its job exists) logs `toolchain upgrade: request failed: <message>` and
+answers `500 {ok: false, error: "the upgrade could not be started"}` (the job, if one was created, is
+finished `failed`); an unparseable body is `400 {ok: false, error: "invalid JSON body"}`. The console
+records the click on its side. These lines are only as trustworthy as the log they are in, so **every
+`agent.log` entry is one line**: any control character in an entry (the request line carries the
+request's own path, percent-decoded and chosen by whoever calls, with or without the bearer token, so
+`%0A` would otherwise start a line of the caller's own wording, and an escape sequence would erase real
+ones on a terminal) is written as `\xNN`, and so are U+2028 and U+2029 (which Python's `splitlines` and
+most editors break lines on) and the explicit bidirectional embeddings, overrides and isolates
+U+202A-202E and U+2066-2069 (which reorder text), as `\uNNNN`. So a request path cannot forge or split an
+audit line, or reorder one with an explicit bidi control; the implicit marks U+200E, U+200F and U+061C
+are passed through and can only reorder neutral characters within the line. The log is rotated only when `serve` starts (one previous
+file is kept, overwritten at the next rotation), and a failed write is dropped, so a run is on record
+for as long as that file is, not for ever.
+
+### Operator setup
+
+- **Opt in**: `toolchain_upgrade = true` in `agent.toml`, then restart the agent (the key is read once
+  at start-up). `AC_AGENT_TOOLCHAIN_UPGRADE=1` works only for the process whose environment has it (a
+  foreground `serve`, or a task/unit whose own environment sets it). `status` shows what a start would
+  load; the running agent's `403 not-opted-in` or its first `202` is the proof. Then grant
+  `agent.toolchain.upgrade` to the agents plugin from the Grants grid; the plugin declares that capability
+  (the console's PR 2 for #675), so the grid has a row for it once the console runs that release.
+- **Linux**: `sudo -n` cannot ask for a password, so the agent's user needs a sudoers rule scoped to this
+  one form. In `/etc/sudoers.d/ac-agent-upgrade`, mode `0440`, checked with `visudo -c -f`:
+
+  ```
+  <user> ALL=(root) NOPASSWD: /usr/bin/apt-get install --only-upgrade -y *
+  ```
+
+  The trailing `*` takes the rest of the argv the agent builds (`--no-remove <package>`), and the rule
+  parses under both sudo 1.9 and sudo-rs (`visudo -c -f` and `visudo-rs -c -f`, checked with sudo-rs 0.2.13 on Ubuntu 26.04).
+  If the verb's flags or their order ever change, an installed rule stops matching and every upgrade
+  turns into `needs-sudoers`.
+
+  Until it exists the verb answers `needs-sudoers` and prints this rule with the user filled in.
+  **Understand what the rule grants.** A sudoers `*` matches any arguments, including `-o` options, and
+  `apt-get -o DPkg::Pre-Invoke::=<command>` runs a command as root, so this rule lets any process running
+  as that user become root without a password, not only this agent. That is fit for a machine whose user
+  already has unrestricted `sudo` (the usual dev box), and not otherwise. A narrower arrangement (a
+  root-owned wrapper that validates one package name and runs `apt-get`, with the sudoers rule naming only
+  the wrapper) is a hardening step this verb does not require.
+- **Windows**: the agent runs as a limited logon task and never tries to elevate itself, so it can
+  upgrade **user-scope** packages. When winget itself reports that the command needs administrator rights
+  (`0x8A150019`) the outcome is `needs-elevation` with the exact command to paste into an elevated
+  terminal. **Not verified**: how winget behaves for a machine-scope package or a self-elevating
+  installer under a limited task (see the outcomes above: a UAC prompt may appear on the desktop). Treat a
+  `needs-elevation` as certain and the absence of one as no promise that nothing will ask for consent.
+- **Environment**: the child gets `NO_COLOR=1`; for `apt`, also `DEBIAN_FRONTEND=noninteractive` and
+  `LC_ALL=C`, which `sudo`'s default `env_reset` may strip (the agent's stdin is closed and `-y` is set,
+  so a configuration-file prompt fails the upgrade instead of waiting).
+
 ## Health: `claudeDesktop`
 
 `GET /v1/health` carries `claudeDesktop: boolean` (#457) — whether this machine can open a
@@ -826,8 +1043,9 @@ software is never something a grant could hand to a plugin.
    - 409 `a downgrade is not supported` (semver precedence).
    - 409 `update in progress` while another request is still verifying in this process, or while
      `update.json` reads `installing` and is under 10 minutes old.
-   - 409 `jobs running` while any `exec/claude` job runs. This is checked again after verification,
-     just before the hand-off.
+   - 409 `jobs running` while any agent job runs (a claude run, or a toolchain upgrade, #675, including
+     one that has passed its cap check but not yet started its job). This is checked again after
+     verification, just before the hand-off.
 2. **Resolves exactly that version on the public npm registry** (`https://registry.npmjs.org`, a
    constant, never configurable):
    - The metadata must be a JSON object naming `@rackbops/ac-agent` and that version.
@@ -891,6 +1109,13 @@ Every refusal, the verified hand-off, and a failed hand-off are logged as
   — as public as `capabilities`.
   `/v1/pair` authenticates by a one-time code instead of a bearer token, since pairing is what mints
   the token in the first place.
+- **`POST /v1/toolchain/upgrade` is the one verb that installs software** (#675), so it is behind two
+  independent gates (the console's grant, and the machine owner's own `toolchain_upgrade` key in
+  `agent.toml`, off by default), upgrades with only three fixed command shapes and a validated package
+  id (the one other program a request can name, `cmd`, is limited to four tools whose `--version` the
+  preflight already runs), takes its elevation from the machine's own configuration rather than ever
+  elevating itself, and logs every run. See **`POST /v1/toolchain/upgrade`**, including what the Linux
+  sudoers rule it needs actually grants.
 - **Every other route requires `Authorization: Bearer <token>`**, compared with a
   constant-time equality check against a stored hash (never the token itself). Before pairing,
   every such route answers `401 {"error": "not paired"}`; a present-but-wrong token answers