@mutagent/cli 0.1.341 → 0.1.342

package/README.md

@@ -366,6 +366,131 @@ mutagent feedback send "the CLI crashed on init" \
 
 ---
 
+## Command surface
+
+The `mutagent helix` and `mutagent agent` trees as the CLI registers them, and the API each verb
+calls. Line anchors are to origin/main `0b4f9ce11` (17 Sep 2026); paths are repository-relative.
+For how each cloud verb maps to the local `helix` binary, see
+[docs/helix-surface-map.md](docs/helix-surface-map.md). That map was read from `4488d23b0`
+(12 Sep 2026) and predates the launch route, the reference-addressed session verbs and managed
+agents; where it and this section disagree, this section follows the source.
+
+```mermaid
+flowchart LR
+  ROOT["mutagent"] --> HX["helix"]
+  ROOT --> AG["agent"]
+
+  HX --> HXRUN["helix -p or --mode json or --mode rpc<br/>classic arm, --prime selects the prime arm"]
+  HX --> HXAGENT["helix agent"]
+  HX --> HXSESSION["helix session"]
+  HX --> HXMODELS["helix models"]
+  HX --> HXDOCTOR["helix doctor"]
+  HX --> HXSMOKE["helix smoke"]
+  HX --> HXVERSION["helix version"]
+  HX --> HXUPDATE["helix update<br/>always refused"]
+
+  HXAGENT --> HXAGENTDEF["definition: positional, --prompt, --file, --name"]
+  HXAGENT --> HXAGENTSLUG["@slug, @slug:vN, @slug:latest<br/>managed agent"]
+
+  HXSESSION --> SLS["ls"]
+  HXSESSION --> SATTACH["attach"]
+  HXSESSION --> SSEND["send"]
+  HXSESSION --> SSIGNAL["signal"]
+  HXSESSION --> SCLOSE["close-input"]
+  HXSESSION --> SCHECKPOINT["checkpoint"]
+  HXSESSION --> SCHECKPOINTS["checkpoints"]
+  HXSESSION --> SRESTORE["restore"]
+  HXSESSION --> SSTART["start<br/>internal, sandbox id"]
+
+  HXMODELS --> MDEFAULT["default"]
+
+  AG --> ACHECK["check<br/>local"]
+  AG --> APACK["pack<br/>local"]
+  AG --> ARUN["run<br/>local Helix binary"]
+  AG --> ADEPLOY["deploy"]
+  AG --> AACTIVATE["activate"]
+  AG --> ALIST["list"]
+  AG --> AINSPECT["inspect"]
+  AG --> ARETIRE["retire"]
+```
+
+Registration: `mutagent-cli/src/bin/cli.ts:243` (`helix`) and `:252` (`agent`);
+`mutagent-cli/src/commands/helix/index.ts:81-87` attaches `agent`, `session`, `models`, `doctor`,
+`smoke`, `version` and `update`; `mutagent-cli/src/commands/helix/session-commands.ts:55-63`
+attaches the session verbs; `mutagent-cli/src/commands/agent/index.ts:32-108` declares the
+`agent` verbs.
+
+### Credentials
+
+The two trees authenticate differently.
+
+- **`mutagent helix …`** goes through `requestJson` (`mutagent-cli/src/lib/sandbox-api.ts:606`).
+  Each request carries `Authorization: Bearer <operator token>` and `x-workspace-id`
+  (`sandbox-api.ts:391`, `:490-495`). The operator token is minted from the platform API key by
+  `POST /api/sandbox/token` (`mutagent-cli/src/lib/sandbox-token.ts:259-260`) and cached; a 401
+  drops the cached token and mints once more (`sandbox-api.ts:462-467`).
+- **`mutagent agent …`** (the remote verbs) goes through the generated SDK client
+  `sdk.helixAgentDeployments` with the platform API key and an `x-workspace-id` header, and no
+  token exchange (`mutagent-cli/src/lib/agent/sdk.ts:61`, `:107-112`). The server mounts these
+  routes under `/api/helix-agent` (`mutagent/src/modules/helix-agent/deployment/module.ts:47`).
+
+### `mutagent helix` verbs
+
+`<ref>` is a session reference (`hs1_…`). `SESSIONS` is `/api/sandbox/helix/sessions`
+(`mutagent-cli/src/lib/helix-session-api.ts:40`).
+
+| Verb | API call | CLI source |
+|---|---|---|
+| `helix [argv…]` (classic arm; `--prime` = prime arm) | `POST SESSIONS` (launch), then the attach loop below | `commands/helix/index.ts:65-79` → `commands/helix/run-cloud.ts:44-48` → `lib/helix-session-api.ts:117-118` |
+| `helix … --sandbox <id>` (internal) | `POST /api/sandbox/:id/session`, then the attach loop | `commands/helix/run-cloud.ts:42-43` → `lib/sandbox-api.ts:741-749` |
+| attach loop after a launch | `GET SESSIONS/<ref>/stream[?since=]`; stdin lines `POST SESSIONS/<ref>/input`; stdin EOF `POST SESSIONS/<ref>/close-input`; Ctrl-C `POST SESSIONS/<ref>/signal` `{signal: SIGINT}` | `commands/helix/run-cloud.ts:107-118`; `lib/helix-session-api.ts:121-144` |
+| `helix --version`, `-v` | `GET /api/sandbox/presets` (the preset description, not a live probe) | `commands/helix/index.ts:67-69` → `commands/helix/doctor.ts:280-306` → `lib/sandbox-catalog.ts:34` |
+| `helix agent <definition> …` | `POST SESSIONS` with `arm: agent` (or `POST /api/sandbox/:id/session` with `--sandbox`), then the attach loop | `commands/helix/agent.ts:114-140` → `commands/helix/run-cloud.ts:20-62` |
+| `helix agent @slug[:vN\|:latest]` | `POST SESSIONS` with body `agent: {slug, revision?}`, `mode` when `-p` or `--rpc` is given, `args: ["-p", task]`; prints the receipt `{reference, sandboxId, agent, mode}` on stderr; then the attach loop | `commands/helix/agent.ts:99-111` → `commands/helix/managed-agent.ts:54-90` → `commands/helix/run-cloud.ts:76-105` |
+| `helix session ls` | `GET SESSIONS[?limit=&cursor=]` | `commands/helix/session-commands.ts:280` → `lib/helix-session-api.ts:76-84` |
+| `helix session ls <sandbox-id>` (internal) | `GET /api/sandbox/:id/sessions` | `commands/helix/session-commands.ts:261-262` → `lib/sandbox-api.ts:805-806` |
+| `helix session attach <ref>` | `GET SESSIONS/<ref>/stream[?since=]` | `commands/helix/session-commands.ts:347-356` → `lib/helix-session-api.ts:140-144` |
+| `helix session send <ref>` | `POST SESSIONS/<ref>/input` `{line}` | `commands/helix/send.ts:107` → `lib/helix-session-api.ts:121-125` |
+| `helix session send <id> --session <sid>` (internal) | `POST /api/sandbox/:id/input` `{sessionId, line}` | `commands/helix/send.ts:125` → `lib/sandbox-api.ts:707-708` |
+| `helix session signal <ref>` | `POST SESSIONS/<ref>/signal` `{signal}` (default `SIGINT`) | `commands/helix/signal.ts:100` → `lib/helix-session-api.ts:134-138` |
+| `helix session signal <id> --session <sid>` (internal) | `POST /api/sandbox/:id/signal` `{sessionId, signal}` | `commands/helix/signal.ts:118` → `lib/sandbox-api.ts:726-727` |
+| `helix session close-input <ref>` | `POST SESSIONS/<ref>/close-input` | `commands/helix/reference-commands.ts:91` → `lib/helix-session-api.ts:128-132` |
+| `helix session checkpoint <ref>` | `POST SESSIONS/<ref>/checkpoint` | `commands/helix/session-commands.ts:398` → `lib/helix-session-api.ts:86-90` |
+| `helix session checkpoint <id> --session <sid>` (internal) | `POST /api/sandbox/:id/checkpoint` | `commands/helix/session-commands.ts:407` → `lib/sandbox-checkpoints.ts:140-141` |
+| `helix session checkpoints <ref>` | `GET SESSIONS/<ref>/checkpoints` | `commands/helix/reference-commands.ts:39` → `lib/helix-session-api.ts:93-95` |
+| `helix session restore <ref>` | `POST SESSIONS/<ref>/restore` `{snapshotId?, onWorkspaceDrift?, partial?}`; retried when the answer is 409 `sandbox_stopping` | `commands/helix/restore-command.ts:85-95` → `lib/helix-session-api.ts:98-108`, `lib/sandbox-stopping-retry.ts:21-27` |
+| `helix session start <sandbox-id>` (internal) | `POST /api/sandbox/:id/session` `{mode, args?, cwd?, environment?}` | `commands/helix/session-commands.ts:139-150` → `lib/sandbox-api.ts:741-749` |
+| `helix models` | `GET /api/sandbox/helix/defaults` | `commands/helix/models.ts:85` → `lib/sandbox-api.ts:780-781` |
+| `helix models default <ids…>`, `--clear` | `PUT /api/sandbox/helix/defaults` `{models}` (`--clear` sends `[]`) | `commands/helix/models.ts:138` → `lib/sandbox-api.ts:785-787` |
+| `helix doctor`, `helix smoke` | `POST /api/sandbox/run` (fresh preset box, torn down after), or `POST /api/sandbox/:id/exec` with `--sandbox` | `commands/helix/doctor.ts:135`, `:179`, `:308-327` → `lib/sandbox-api.ts:692-693`, `:753-754` |
+| `helix version` | `GET /api/sandbox/presets` | `commands/helix/doctor.ts:263-268`, `:301-302` → `lib/sandbox-catalog.ts:34` |
+| `helix update` | `GET /api/sandbox/presets` to name the pinned version, then exit 2 | `commands/helix/doctor.ts:210-220` |
+
+All source paths in this table are under `mutagent-cli/src/`.
+
+### `mutagent agent` verbs
+
+| Verb | API call | CLI source |
+|---|---|---|
+| `agent check <agent.md>` | local, no API: compile and validate the folder | `commands/agent/index.ts:32-36` → `lib/agent/local.ts:44-47` |
+| `agent pack <agent.md> --output <archive>` | local, no API: write the package archive | `commands/agent/index.ts:37-43` → `lib/agent/local.ts:48-60` |
+| `agent run <agent.md> <task…>` | local, no API: runs the package with the local Helix binary; a slug argument is refused before any work | `commands/agent/index.ts:44-55` → `lib/agent/local.ts:61-75` |
+| `agent deploy <agent.md> [--env] [--no-activate] [--idempotency-key]` | compiles locally, then `GET /api/helix-agent/capabilities`, then `POST /api/helix-agent/agents/{slug}/deployments` `{archiveBase64, archiveDigest, artifactDigest, archiveSize, environment?, activate, idempotencyKey}` | `commands/agent/index.ts:56-66` → `lib/agent/service.ts:15-18` → `lib/agent/remote.ts:35-74` → `lib/agent/sdk.ts:64-67`, `:81-87` |
+| `agent activate <slug> --revision vN [--env] [--idempotency-key]` | `POST /api/helix-agent/agents/{slug}/activate` `{revision, environment?, idempotencyKey}` | `commands/agent/index.ts:67-78` → `lib/agent/remote.ts:105-118` → `lib/agent/sdk.ts:88-91` |
+| `agent list [--limit] [--cursor] [--include-archived]` | `GET /api/helix-agent/agents` | `commands/agent/index.ts:79-88` → `lib/agent/remote.ts:76-92` → `lib/agent/sdk.ts:68-71` |
+| `agent inspect <slug> [--env] [--limit] [--cursor]` | `GET /api/helix-agent/agents/{slug}` (revisions, slots, sessions; `--env` filters on the client) | `commands/agent/index.ts:89-102` → `lib/agent/remote.ts:94-103` → `lib/agent/sdk.ts:72-80` |
+| `agent inspect --operation <id>` | `GET /api/helix-agent/operations/{operationId}` | `lib/agent/remote.ts:95` → `lib/agent/sdk.ts:93` |
+| `agent retire <slug> [--env]` | `POST /api/helix-agent/agents/{slug}/retire` `{environment?}` | `commands/agent/index.ts:103-108` → `lib/agent/remote.ts:120-126` → `lib/agent/sdk.ts:92` |
+
+All source paths in this table are under `mutagent-cli/src/`. The route paths are the generated SDK's
+(`mutagent-sdk/src/funcs/helix-agent-deployments-*.ts`) and match the server routes in
+`mutagent/src/modules/helix-agent/deployment/routes.ts:69-173`.
+
+Running a deployed agent is not an `agent` verb: it is `mutagent helix agent @slug`, which uses the
+same launch route as every cloud run (row above).
+
+---
+
 ## AI-First Usage
 
 Every command supports `--json` for machine-readable output with `_directive`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mutagent/cli",
-  "version": "0.1.341",
+  "version": "0.1.342",
   "description": "Bun-native CLI for the MutagenT AI platform - auth, provider config, and lifecycle-tool installer for AI-native workflows",
   "type": "module",
   "bin": {