@mmerterden/multi-agent-pipeline 20.29.0 → 20.33.0

package/pipeline/contract/README.md

@@ -42,7 +42,11 @@ same bytes (`test/contract-parity.test.mjs`):
 | Assigned issues | `issues.mjs --json [--source S] [--project K] [--max N]` | `GET /v1/issues` |
 | Worktrees | `worktrees.mjs --json [--measure] [--redact]` | `GET /v1/worktrees` |
 | Launch shape | `launch-request.mjs spec` | `GET /v1/launch-spec` |
-| Launch repositories | `launch-request.mjs repos [--redact]` | `GET /v1/repos` |
+| Launch repositories | `launch-request.mjs repos [--redact] [--all]` | `GET /v1/repos[?all=1]` |
+| Add a launch repository (two steps; the route also requires a git checkout) | `launch-request.mjs register-repo <path>` | `POST /v1/repos` |
+| Remove a registered repository (two steps) | - | `DELETE /v1/repos/{id}` |
+| Office jobs | `job-launch.mjs list` | `GET /v1/jobs` |
+| Start an office job (two steps) | - | `POST /v1/jobs` |
 | Start a run | write the request file, then `launch-request.mjs plan FILE --repo P --session-id U [--channel phone]` | `POST /v1/launch?repo=P` |
 | Answer a question | `answer-question.mjs STATE --question Q --answer IDS` | `POST /v1/runs/{id}/answer` |
 | A run's log | `run-log.mjs ID [--tail N]` (1-2000, default 200) | `GET /v1/runs/{id}/log?tail=N` |
@@ -51,12 +55,46 @@ same bytes (`test/contract-parity.test.mjs`):
 | Garbage-collect (two steps) | `gc-plan.mjs preview [--scope S,...]`, then `gc-plan.mjs apply < items` | `POST /v1/gc` |
 | Autopilot status | `autopilot-control.mjs status` | `GET /v1/autopilot` |
 | Autopilot off | `autopilot-control.mjs off [--now]` | `POST /v1/autopilot/off` |
-
-Starting a run is always the client's act. `POST /v1/launch` validates the
+| Autopilot on (two steps) | `autopilot-control.mjs on-preview --repo R...`, then `on --repo R... [--configure-only]` | `POST /v1/autopilot/on` |
+| Steer a run (two steps on the server) | `steer-run.mjs STATE --text T` | `POST /v1/runs/{id}/steer` |
+| Agent activity | `activity-snapshot.mjs --json` | `GET /v1/activity`, `GET /v1/activity/stream` (SSE) |
+| An agent's chat | `activity-snapshot.mjs chat SESSION [AGENT] [--before N] [--limit N]` | `GET /v1/agents/{sessionId}/{agentId}/chat` |
+| Cost ledger | `office-ledger.mjs --json` | `GET /v1/ledger` |
+| Machine resources | `system-status.mjs --json` | `GET /v1/system` |
+| Key cabinet (names and verdicts, never values) | `office-credentials.mjs --json [--probe]` | `GET /v1/credentials` |
+| Institutional memory | `office-memory.mjs --json` | `GET /v1/memory` |
+| Prune old run logs (two steps) | `office-prune.mjs preview\|apply N --json` | `POST /v1/prune-logs` |
+| Office settings | `office-settings.mjs --json` | `GET /v1/settings` |
+| Change one setting (two steps) | `office-settings.mjs set SETTING VALUE --json` | `POST /v1/settings` |
+| What a run produced | `run-results.mjs ID --json` | `GET /v1/runs/{id}/results` |
+| One screenshot | `run-results.mjs ID --evidence NAME` | `GET /v1/runs/{id}/evidence/{name}` |
+| Post a review verdict (two steps) | `work-items.mjs verdict ID [--post]` | `POST /v1/runs/{id}/review-verdict` |
+| An issue's maturity | `work-items.mjs maturity KEY` | `GET /v1/issues/{key}/maturity` |
+| Open pull requests | `work-items.mjs prs` | `GET /v1/prs` |
+| Toolkit MCP tools | `toolkit-tools.mjs list` | `GET /v1/tools` |
+| Call an allowed toolkit tool (read-only, no location argument) | `toolkit-tools.mjs call NAME JSON` | `POST /v1/tools/{name}/call` |
+| A Confluence page, a Crashlytics issue, a Figma frame | `service-read.mjs confluence\|crashlytics\|figma ...` | `GET /v1/services/{confluence,crashlytics,figma}` |
+| Pending host permission prompts | (none can be read yet) | `GET /v1/permissions` |
+| Routines | `routine-registry.mjs list --json` | `GET /v1/routines` |
+| Remove a routine (two steps) | `routine-registry.mjs remove --name N` | `DELETE /v1/routines/{name}` |
+| A repo's stacks | `stack-toggle.mjs status --repo P --json` | `GET /v1/stack?repo=R` |
+| Set a repo's stacks (two steps) | `stack-toggle.mjs set --repo P STACK... --json` | `POST /v1/stack` |
+
+Every surface in `manifest.json` carries `remote` (the scope a remote carrier
+would require: `read`, `answer`, `launch`, or `local-only` for anything that
+widens what runs on this machine (autopilot on, stack, routine removal, kill,
+gc, prune, settings) and for a read that stays on this machine for privacy
+(credentials, memory, settings)) and `risk` (the confirmation tier: `read`, `low`, `high`). Locally the
+bearer token is the only credential; nothing enforces the tags yet. They are
+there so a later carrier reuses these routes without redefining them.
+
+Starting a run is the client's act. `POST /v1/launch` validates the
 request, writes it (0600) and returns the argv, environment and working
-directory from `launch.json`; it never starts a session (the only `claude` the
-server runs is `claude stop`, for a kill). Spawn the argv without
-a shell. `launch.json` is marked `verified: false` until a live launch trial, so
+directory from `launch.json`; spawn the argv without a shell. The office panel
+is a client that starts its own: `POST /v1/jobs` (two steps, `local-only`)
+starts a job from `schemas/office-jobs.json` in the background after the
+unattended profile, workspace trust and sandbox checks. Besides that the only
+`claude` the server runs is `claude stop`, for a kill. `launch.json` is marked `verified: false` until a live launch trial, so
 treat the shape as provisional.
 
 The run starts with no permission prompts, so its input is held to a shape: a
@@ -90,7 +128,8 @@ Resuming is the client's act too: `POST /v1/runs/{id}/resume` returns the plan
 root, `409 not-resumable` for any other, a finished or a killed one, and `409
 run-active` while its session runs.
 
-Kill and gc remove things, so each takes two requests. The first (no
+Kill, gc, autopilot on and a stack change take two requests (a routine
+removal takes its token as `?confirm=`). The first (no
 `confirmToken`) returns the preview with `confirmToken` and `expiresAt`; the
 second sends the token back and acts on exactly what was previewed. A token is
 single use, lives 120 seconds in the server's memory only, and is bound to the
@@ -113,14 +152,35 @@ answer to the old one.
   that spawned the server can pass `--print-token` to get it on the ready line.
 - Every request sends `Authorization: Bearer <token>` and a `Host` of
   `127.0.0.1:<port>` or `localhost:<port>`.
-- A browser page is allowed only from an origin passed with `--allow-origin`;
-  CORS is off without one. A request carrying an `Origin` is always served
-  redacted.
+- A browser page is allowed only from the server's own origin (the optional
+  panel at `GET /office`) or an origin passed with `--allow-origin`; CORS is
+  off without one. A write (POST, DELETE) and the chat route accept no Origin
+  but the server's own, even an allowed one. A request carrying an `Origin` is
+  always served redacted.
+- The token is read from the `Authorization` header only, never from a cookie
+  or a query parameter.
+- `GET /office` serves the panel page (`MA_OFFICE_PAGE`, else
+  `prefs.global.office.page`, else the installed `office/index.html` beside the
+  package) without a token, with a per-response CSP nonce, and is 404 when no
+  page exists. The page never sees the token in a URL: `POST /office/code`
+  (bearer, no Origin) mints a code valid for 10 seconds and one use, the page
+  is opened with it in the fragment, and trades it at `POST /office/exchange`
+  (own Origin only, no bearer); a used, expired or unknown code is 401.
+  `GET /office/assets/<name>.png` serves the page's sprites, also without a
+  token: a plain file name, a PNG of at most 256 KiB directly in the assets
+  directory beside the page, and 404 for anything else. `GET /favicon.ico`
+  answers an empty 204 without a token, since browsers request it on their own.
+- Every write route appends one line (who, route, step, status; never a body
+  or token) to `~/.claude/logs/multi-agent/office-actions.jsonl`.
 - Bodies are JSON, at most 64 KiB, and must satisfy the route's schema.
 - Errors follow `contract-error.schema.json`; switch on `error`, never on
   `message`.
-- The server exits after 15 idle minutes (`--idle-minutes`) or on SIGTERM. It
-  is never a service; start it when you need it.
+- Service reads, the work list, the review verdict and autopilot control run
+  in child processes and never block other routes; a second request for the
+  same one while the first runs is 429 `busy`.
+- The server exits after 15 idle minutes (`--idle-minutes`), after 8 hours in
+  any case (`--max-hours`, an open event stream does not extend it) or on
+  SIGTERM. It is never a service; start it when you need it.
 
 A client that relays anything off this machine uses `redact=1` (or
 `--redact`) for every read.

package/pipeline/contract/fixtures/error-invalid-request.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "1.3.0",
+  "contractVersion": "1.6.0",
   "error": "invalid-request",
   "message": "the launch request was refused",
   "errors": [

package/pipeline/contract/fixtures/error-unauthorized.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "1.3.0",
+  "contractVersion": "1.6.0",
   "error": "unauthorized",
   "message": "a bearer token is required"
 }

package/pipeline/contract/fixtures/error-unsigned.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "1.3.0",
+  "contractVersion": "1.6.0",
   "error": "unsigned",
   "message": "a device signature is required"
 }

package/pipeline/contract/fixtures/launch-plan.json

@@ -22,7 +22,7 @@
     "MULTI_AGENT_UNATTENDED": "1",
     "MULTI_AGENT_SESSION_ID": "00000000-0000-4000-8000-000000000201",
     "MCP_TOOLKIT_URL_POLICY": "strict",
-    "MCP_TOOLKIT_INDEX_DENY": "~/.ssh,~/.aws,~/.gnupg,~/Library/Keychains",
+    "MCP_TOOLKIT_INDEX_DENY": "~/.ssh,~/.aws,~/.gnupg,~/Library/Keychains,~/.claude/logs/multi-agent/contract-server,~/.claude/logs/multi-agent/office",
     "LOGS_ROOT": "/Users/example/.multi-agent-unattended/logs",
     "MA_LAUNCH_REQUEST": "/Users/example/.claude/autopilot/requests/00000000-0000-4000-8000-000000000201.json"
   },

package/pipeline/contract/fixtures/runs-awaiting-question.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "1.2.0",
+  "contractVersion": "1.3.0",
   "logsRoot": "/Users/example/.claude/logs/multi-agent",
   "count": 1,
   "runs": [
@@ -68,7 +68,12 @@
       "estUsd": 0,
       "unlockedWrites": 0,
       "runType": "autopilot",
+      "mode": null,
       "title": null,
+      "source": null,
+      "prNumber": null,
+      "channels": [],
+      "channelUrls": {},
       "progress": 0,
       "currentTask": null,
       "processAlive": false

package/pipeline/contract/fixtures/runs-empty.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "1.2.0",
+  "contractVersion": "1.3.0",
   "logsRoot": "/Users/example/.claude/logs/multi-agent",
   "count": 0,
   "runs": []

package/pipeline/contract/fixtures/runs-failed.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "1.2.0",
+  "contractVersion": "1.3.0",
   "logsRoot": "/Users/example/.claude/logs/multi-agent",
   "count": 1,
   "runs": [
@@ -88,7 +88,12 @@
       "estUsd": 0.0353,
       "unlockedWrites": 0,
       "runType": "development",
+      "mode": null,
       "title": null,
+      "source": null,
+      "prNumber": null,
+      "channels": [],
+      "channelUrls": {},
       "progress": 0.75,
       "currentTask": null,
       "processAlive": null

package/pipeline/contract/fixtures/runs-old-schema.json

@@ -64,7 +64,12 @@
         "cached": 1800
       },
       "estUsd": 0.0236,
-      "unlockedWrites": 0
+      "unlockedWrites": 0,
+      "mode": null,
+      "source": null,
+      "prNumber": null,
+      "channels": [],
+      "channelUrls": {}
     }
   ]
 }

package/pipeline/contract/fixtures/runs-pr-opened-redacted.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "1.2.0",
+  "contractVersion": "1.3.0",
   "count": 1,
   "runs": [
     {
@@ -109,7 +109,11 @@
       "estUsd": 0.0707,
       "unlockedWrites": 0,
       "runType": "development",
+      "mode": null,
       "title": null,
+      "source": null,
+      "prNumber": 104,
+      "channels": [],
       "progress": 1,
       "currentTask": null,
       "processAlive": null

package/pipeline/contract/fixtures/runs-pr-opened.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "1.2.0",
+  "contractVersion": "1.3.0",
   "logsRoot": "/Users/example/.claude/logs/multi-agent",
   "count": 1,
   "runs": [
@@ -114,7 +114,12 @@
       "estUsd": 0.0707,
       "unlockedWrites": 0,
       "runType": "development",
+      "mode": null,
       "title": null,
+      "source": null,
+      "prNumber": 104,
+      "channels": [],
+      "channelUrls": {},
       "progress": 1,
       "currentTask": null,
       "processAlive": null

package/pipeline/contract/fixtures/runs-running.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "1.2.0",
+  "contractVersion": "1.3.0",
   "logsRoot": "/Users/example/.claude/logs/multi-agent",
   "count": 1,
   "runs": [
@@ -99,7 +99,12 @@
       "estUsd": 0.0236,
       "unlockedWrites": 0,
       "runType": "autopilot",
+      "mode": null,
       "title": "Fix the crash on the login screen",
+      "source": null,
+      "prNumber": null,
+      "channels": [],
+      "channelUrls": {},
       "progress": 0.8333333333333334,
       "currentTask": {
         "subject": "Make the test pass",