@mmerterden/multi-agent-pipeline 20.28.0 → 20.30.0

package/pipeline/contract/manifest.json

@@ -1,5 +1,5 @@
 {
-  "contractVersion": "1.3.0",
+  "contractVersion": "1.4.0",
   "supportedMajors": [1],
   "description": "The pipeline's client contract: every surface a client reads or writes, the CLI invocation and the HTTP route that carry it, and the schema its JSON follows. Schemas are not copied here; schemasDir points at the one tree the producers validate against. Paths in cli are relative to the pipeline directory (installed: ~/.claude).",
   "schemasDir": "../schemas",
@@ -13,7 +13,9 @@
       "redact": "1 drops every x-sensitivity local field, as --redact does; forced for a request that carries an Origin",
       "v": "the major to serve; see README.md"
     },
-    "confirm": "POST /v1/runs/{id}/kill and POST /v1/gc take two requests: the first returns a preview, confirmToken and expiresAt; the second sends confirmToken back. Tokens are 32 random bytes held in the server's memory, single use, valid 120 seconds, bound to the route and run id."
+    "confirm": "POST /v1/runs/{id}/kill, POST /v1/gc, POST /v1/autopilot/on, POST /v1/stack, POST /v1/runs/{id}/steer and POST /v1/runs/{id}/review-verdict take two requests: the first returns a preview, confirmToken and expiresAt; the second sends confirmToken back. DELETE /v1/routines/{name} takes the token as ?confirm=. Tokens are 32 random bytes held in the server's memory, single use, valid 120 seconds, bound to the route and its target.",
+    "tags": "Every surface carries remote (the scope a remote carrier would require: read, answer, launch, or local-only for anything that widens what runs on this machine) and risk (the confirmation tier it would require: read, low, high). Locally the bearer token is the only credential; nothing enforces the tags yet.",
+    "origin": "A request may carry no Origin, the server's own (http://127.0.0.1:<port>), or one passed with --allow-origin. Writes (POST, DELETE) and the chat route accept no Origin but the server's own. The bearer token is read from the Authorization header only."
   },
   "phone": {
     "description": "Routes a phone reaches through a forwarder (a private network or a local relay; see multi-agent-refs/features/phone-api.md). Every request is signed with an enrolled device's Ed25519 key; the bearer token is neither needed nor accepted here, and a signature opens no desktop route. Responses are always the redacted view.",
@@ -72,6 +74,29 @@
     "autopilot-off-request.schema.json",
     "autopilot-off.schema.json",
     "repos.schema.json",
+    "activity.schema.json",
+    "activity-chat.schema.json",
+    "routines.schema.json",
+    "routine-delete.schema.json",
+    "stack.schema.json",
+    "stack-request.schema.json",
+    "stack-change.schema.json",
+    "autopilot-on-request.schema.json",
+    "autopilot-on.schema.json",
+    "steer-request.schema.json",
+    "steer.schema.json",
+    "ledger.schema.json",
+    "run-results.schema.json",
+    "run-evidence.schema.json",
+    "issue-maturity.schema.json",
+    "prs.schema.json",
+    "review-verdict-request.schema.json",
+    "review-verdict.schema.json",
+    "tools.schema.json",
+    "tool-call-request.schema.json",
+    "tool-call.schema.json",
+    "service-read.schema.json",
+    "permissions.schema.json",
     "contract-error.schema.json"
   ],
   "surfaces": [
@@ -82,7 +107,9 @@
       "query": ["group", "redact"],
       "cli": ["node", "scripts/runs-index.mjs", "--json", "[--group <group>]", "[--redact]"],
       "schema": "runs-index.schema.json",
-      "version": "1.2.0"
+      "version": "1.2.0",
+      "remote": "read",
+      "risk": "read"
     },
     {
       "id": "run",
@@ -91,7 +118,9 @@
       "query": ["redact"],
       "cli": ["node", "scripts/runs-index.mjs", "--json", "--task-id", "{id}", "[--redact]"],
       "schema": "runs-index.schema.json",
-      "version": "1.2.0"
+      "version": "1.2.0",
+      "remote": "read",
+      "risk": "read"
     },
     {
       "id": "commands",
@@ -100,7 +129,9 @@
       "query": ["redact"],
       "cli": ["node", "scripts/commands.mjs", "--json"],
       "schema": "command-parameters.schema.json",
-      "version": "1.0.0"
+      "version": "1.0.0",
+      "remote": "read",
+      "risk": "read"
     },
     {
       "id": "questions",
@@ -109,7 +140,9 @@
       "query": ["redact"],
       "cli": ["node", "scripts/launch-request.mjs", "questions"],
       "schema": "run-questions.schema.json",
-      "version": "1.1.0"
+      "version": "1.1.0",
+      "remote": "read",
+      "risk": "read"
     },
     {
       "id": "issues",
@@ -125,7 +158,9 @@
         "[--max <n>]"
       ],
       "schema": "issues.schema.json",
-      "version": "1.0.0"
+      "version": "1.0.0",
+      "remote": "read",
+      "risk": "read"
     },
     {
       "id": "worktrees",
@@ -134,7 +169,9 @@
       "query": ["measure", "redact"],
       "cli": ["node", "scripts/worktrees.mjs", "--json", "[--measure]", "[--redact]"],
       "schema": "worktrees.schema.json",
-      "version": "1.0.0"
+      "version": "1.0.0",
+      "remote": "read",
+      "risk": "read"
     },
     {
       "id": "launch-spec",
@@ -143,7 +180,9 @@
       "query": ["redact"],
       "cli": ["node", "scripts/launch-request.mjs", "spec"],
       "schema": "launch.schema.json",
-      "version": "1.2.0"
+      "version": "1.2.0",
+      "remote": "read",
+      "risk": "read"
     },
     {
       "id": "repos",
@@ -153,7 +192,9 @@
       "cli": ["node", "scripts/launch-request.mjs", "repos", "[--redact]"],
       "schema": "repos.schema.json",
       "version": "1.1.0",
-      "note": "The repositories POST /v1/launch?repo= accepts: configured autopilot repos and registered ones."
+      "note": "The repositories POST /v1/launch?repo= accepts: configured autopilot repos and registered ones.",
+      "remote": "read",
+      "risk": "read"
     },
     {
       "id": "launch",
@@ -174,7 +215,9 @@
       ],
       "schema": "launch-plan.schema.json",
       "version": "1.1.0",
-      "note": "The server writes the request file (0600, named for a session id it mints) and returns the plan; the CLI plans a file the client wrote. Neither starts the host."
+      "note": "The server writes the request file (0600, named for a session id it mints) and returns the plan; the CLI plans a file the client wrote. Neither starts the host.",
+      "remote": "launch",
+      "risk": "high"
     },
     {
       "id": "answer",
@@ -192,7 +235,9 @@
         "<optionId>[,<optionId>...]"
       ],
       "schema": "answer-result.schema.json",
-      "version": "1.0.0"
+      "version": "1.0.0",
+      "remote": "answer",
+      "risk": "low"
     },
     {
       "id": "run-log",
@@ -202,7 +247,9 @@
       "cli": ["node", "scripts/run-log.mjs", "{id}", "[--tail <n>]", "--json"],
       "schema": "run-log.schema.json",
       "version": "1.0.0",
-      "note": "tail is 1 to 2000, 200 by default. Lines are scrubbed under redact."
+      "note": "tail is 1 to 2000, 200 by default. Lines are scrubbed under redact.",
+      "remote": "read",
+      "risk": "read"
     },
     {
       "id": "resume",
@@ -225,7 +272,9 @@
       ],
       "schema": "launch-plan.schema.json",
       "version": "1.1.0",
-      "note": "Returns the plan (mode resume) the client spawns; nothing starts the host. Only a run recorded under the unattended log root resumes here (409 not-resumable otherwise, and for a finished or killed run); a run whose session is alive is 409 run-active. answers answers the question the run is parked on before the plan is returned."
+      "note": "Returns the plan (mode resume) the client spawns; nothing starts the host. Only a run recorded under the unattended log root resumes here (409 not-resumable otherwise, and for a finished or killed run); a run whose session is alive is 409 run-active. answers answers the question the run is parked on before the plan is returned.",
+      "remote": "launch",
+      "risk": "high"
     },
     {
       "id": "kill",
@@ -236,7 +285,9 @@
       "cli": ["node", "scripts/run-kill.mjs", "preview|apply", "{id}", "--json"],
       "schema": "kill.schema.json",
       "version": "1.0.0",
-      "note": "Two steps: without confirmToken the preview and a token (single use, 120 s, bound to this route and run); with it the kill. 409 confirm-expired, 409 confirm-mismatch. Never deletes the remote branch or the logs."
+      "note": "Two steps: without confirmToken the preview and a token (single use, 120 s, bound to this route and run); with it the kill. 409 confirm-expired, 409 confirm-mismatch. Never deletes the remote branch or the logs.",
+      "remote": "local-only",
+      "risk": "high"
     },
     {
       "id": "gc",
@@ -253,7 +304,9 @@
       ],
       "schema": "gc.schema.json",
       "version": "1.0.0",
-      "note": "Two steps, the same token flow as kill. Step 2 removes exactly the items step 1 listed."
+      "note": "Two steps, the same token flow as kill. Step 2 removes exactly the items step 1 listed.",
+      "remote": "local-only",
+      "risk": "high"
     },
     {
       "id": "autopilot",
@@ -262,7 +315,9 @@
       "query": ["redact"],
       "cli": ["node", "scripts/autopilot-control.mjs", "status"],
       "schema": "autopilot-status.schema.json",
-      "version": "1.0.0"
+      "version": "1.0.0",
+      "remote": "read",
+      "risk": "read"
     },
     {
       "id": "autopilot-off",
@@ -273,7 +328,9 @@
       "cli": ["node", "scripts/autopilot-control.mjs", "off", "[--now]"],
       "schema": "autopilot-off.schema.json",
       "version": "1.0.0",
-      "note": "Turning autopilot on stays a terminal command: it picks repositories with the user."
+      "note": "Turning autopilot on stays a terminal command: it picks repositories with the user.",
+      "remote": "launch",
+      "risk": "low"
     },
     {
       "id": "phone-runs",
@@ -285,7 +342,8 @@
       "cli": ["node", "scripts/runs-index.mjs", "--json", "[--group <group>]", "--redact"],
       "schema": "runs-index.schema.json",
       "version": "1.2.0",
-      "note": "Always redacted; redact=0 is refused."
+      "note": "Always redacted; redact=0 is refused.",
+      "risk": "read"
     },
     {
       "id": "phone-run",
@@ -297,7 +355,8 @@
       "cli": ["node", "scripts/runs-index.mjs", "--json", "--task-id", "{id}", "--redact"],
       "schema": "runs-index.schema.json",
       "version": "1.2.0",
-      "note": "Always redacted; redact=0 is refused."
+      "note": "Always redacted; redact=0 is refused.",
+      "risk": "read"
     },
     {
       "id": "phone-answer",
@@ -318,7 +377,8 @@
       ],
       "schema": "answer-result.schema.json",
       "version": "1.0.0",
-      "note": "The same refusals as POST /v1/runs/{id}/answer: only an option id the pending question offered is recorded."
+      "note": "The same refusals as POST /v1/runs/{id}/answer: only an option id the pending question offered is recorded.",
+      "risk": "low"
     },
     {
       "id": "phone-launch",
@@ -343,7 +403,285 @@
       ],
       "schema": "launch-plan.schema.json",
       "version": "1.1.0",
-      "note": "Off until `phone-devices.mjs launch on`. Writes the request file and returns the redacted plan; nothing starts the host."
+      "note": "Off until `phone-devices.mjs launch on`. Writes the request file and returns the redacted plan; nothing starts the host.",
+      "risk": "high"
+    },
+    {
+      "id": "autopilot-on",
+      "method": "POST",
+      "path": "/v1/autopilot/on",
+      "query": [],
+      "body": "autopilot-on-request.schema.json",
+      "cli": [
+        "node",
+        "scripts/autopilot-control.mjs",
+        "on-preview|on",
+        "--repo",
+        "<owner/name>",
+        "[--repo <owner/name>...]",
+        "[--configure-only]"
+      ],
+      "schema": "autopilot-on.schema.json",
+      "version": "1.0.0",
+      "note": "Two steps, the confirm-token flow of kill: the preview names what is kept, dropped and probed; the confirmation turns the mode on for exactly that selection. Only repositories already in the autopilot config can be selected; adding one, with its sources and label, stays /multi-agent:autopilot-on.",
+      "remote": "local-only",
+      "risk": "high"
+    },
+    {
+      "id": "steer",
+      "method": "POST",
+      "path": "/v1/runs/{id}/steer",
+      "query": [],
+      "body": "steer-request.schema.json",
+      "cli": ["node", "scripts/steer-run.mjs", "<agent-state.json>", "--text", "<instruction>"],
+      "schema": "steer.schema.json",
+      "version": "1.0.0",
+      "note": "Two steps: the text and a preview with a token bound to this run and this text, then the token alone queues it as pendingSteer, applied at the next phase entry. 409 not-steerable for a finished run.",
+      "remote": "launch",
+      "risk": "high"
+    },
+    {
+      "id": "activity",
+      "method": "GET",
+      "path": "/v1/activity",
+      "query": [],
+      "cli": ["node", "scripts/activity-snapshot.mjs", "--json"],
+      "schema": "activity.schema.json",
+      "version": "1.0.0",
+      "note": "Derived from disk on every call; no field is machine-local, so redact changes nothing.",
+      "remote": "read",
+      "risk": "read"
+    },
+    {
+      "id": "activity-stream",
+      "method": "GET",
+      "path": "/v1/activity/stream",
+      "query": [],
+      "cli": ["node", "scripts/activity-snapshot.mjs", "--json"],
+      "schema": "activity.schema.json",
+      "version": "1.0.0",
+      "note": "text/event-stream: an `activity` event carrying the document whenever it changes (checked every 2 seconds), a comment line as heartbeat. At most 4 streams at once (429 too-many-streams).",
+      "remote": "read",
+      "risk": "read"
+    },
+    {
+      "id": "agent-chat",
+      "method": "GET",
+      "path": "/v1/agents/{sessionId}/{agentId}/chat",
+      "query": ["before", "limit"],
+      "cli": [
+        "node",
+        "scripts/activity-snapshot.mjs",
+        "chat",
+        "<sessionId>",
+        "[<agentId>]",
+        "[--before <offset>]",
+        "[--limit <n>]"
+      ],
+      "schema": "activity-chat.schema.json",
+      "version": "1.0.0",
+      "note": "agentId main is the session itself. Refused (403) to any Origin but the server's own page, even an allowed one. limit is 1 to 500, 200 by default; before is the offset the previous page returned.",
+      "remote": "read",
+      "risk": "read"
+    },
+    {
+      "id": "routines",
+      "method": "GET",
+      "path": "/v1/routines",
+      "query": [],
+      "cli": ["node", "scripts/routine-registry.mjs", "list", "--json"],
+      "schema": "routines.schema.json",
+      "version": "1.0.0",
+      "remote": "read",
+      "risk": "read"
+    },
+    {
+      "id": "routine-delete",
+      "method": "DELETE",
+      "path": "/v1/routines/{name}",
+      "query": ["confirm"],
+      "cli": ["node", "scripts/routine-registry.mjs", "remove", "--name", "{name}"],
+      "schema": "routine-delete.schema.json",
+      "version": "1.0.0",
+      "note": "Two steps: without confirm the preview and a token; with ?confirm=<token> the removal. A shipped command is refused (409 not-removable).",
+      "remote": "local-only",
+      "risk": "high"
+    },
+    {
+      "id": "stack",
+      "method": "GET",
+      "path": "/v1/stack",
+      "query": ["repo"],
+      "cli": ["node", "scripts/stack-toggle.mjs", "status", "--repo", "<path>", "--json"],
+      "schema": "stack.schema.json",
+      "version": "1.0.0",
+      "note": "repo is a name from GET /v1/repos or its path, and must be one of those repositories.",
+      "remote": "read",
+      "risk": "read"
+    },
+    {
+      "id": "stack-set",
+      "method": "POST",
+      "path": "/v1/stack",
+      "query": [],
+      "body": "stack-request.schema.json",
+      "cli": [
+        "node",
+        "scripts/stack-toggle.mjs",
+        "set",
+        "--repo",
+        "<path>",
+        "<stack>...",
+        "--json"
+      ],
+      "schema": "stack-change.schema.json",
+      "version": "1.0.0",
+      "note": "Two steps: the planned enabledPlugins (nothing written), then the write. The same writer /multi-agent:stack uses.",
+      "remote": "local-only",
+      "risk": "high"
+    },
+    {
+      "id": "ledger",
+      "method": "GET",
+      "path": "/v1/ledger",
+      "query": [],
+      "cli": ["node", "scripts/office-ledger.mjs", "--json"],
+      "schema": "ledger.schema.json",
+      "version": "1.0.0",
+      "remote": "read",
+      "risk": "read",
+      "note": "Estimates at list price from cost-table.json. Each amount names its source (tracker-state, transcript, mixed); a run nobody could measure is not-measured with null numbers, never 0. prices.warning names a price table older than 60 days."
+    },
+    {
+      "id": "run-results",
+      "method": "GET",
+      "path": "/v1/runs/{id}/results",
+      "query": [],
+      "cli": ["node", "scripts/run-results.mjs", "{id}", "--json"],
+      "schema": "run-results.schema.json",
+      "version": "1.0.0",
+      "remote": "read",
+      "risk": "read"
+    },
+    {
+      "id": "run-evidence",
+      "method": "GET",
+      "path": "/v1/runs/{id}/evidence/{name}",
+      "query": [],
+      "cli": ["node", "scripts/run-results.mjs", "{id}", "--evidence", "{name}"],
+      "schema": "run-evidence.schema.json",
+      "version": "1.0.0",
+      "remote": "read",
+      "risk": "read"
+    },
+    {
+      "id": "review-verdict",
+      "method": "POST",
+      "path": "/v1/runs/{id}/review-verdict",
+      "query": [],
+      "body": "review-verdict-request.schema.json",
+      "cli": ["node", "scripts/work-items.mjs", "verdict", "{id}", "[--post]"],
+      "schema": "review-verdict.schema.json",
+      "version": "1.0.0",
+      "note": "Two steps. Only a finished review whose every finding is triaged is previewed (409 review-incomplete); the token is bound to the decision and findingsDigest, and a confirmation after either changed is 409 confirm-mismatch.",
+      "remote": "launch",
+      "risk": "high"
+    },
+    {
+      "id": "issue-maturity",
+      "method": "GET",
+      "path": "/v1/issues/{key}/maturity",
+      "query": [],
+      "cli": ["node", "scripts/work-items.mjs", "maturity", "{key}"],
+      "schema": "issue-maturity.schema.json",
+      "version": "1.0.0",
+      "note": "key is URL-encoded (owner%2Frepo%23N for a GitHub issue).",
+      "remote": "read",
+      "risk": "read"
+    },
+    {
+      "id": "prs",
+      "method": "GET",
+      "path": "/v1/prs",
+      "query": ["redact"],
+      "cli": ["node", "scripts/work-items.mjs", "prs"],
+      "schema": "prs.schema.json",
+      "version": "1.0.0",
+      "note": "Bitbucket listing is not implemented; its source entry says so.",
+      "remote": "read",
+      "risk": "read"
+    },
+    {
+      "id": "tools",
+      "method": "GET",
+      "path": "/v1/tools",
+      "query": [],
+      "cli": ["node", "scripts/toolkit-tools.mjs", "list"],
+      "schema": "tools.schema.json",
+      "version": "1.0.0",
+      "note": "One toolkit MCP child per server, started on first use, closed when the server stops. 409 not-installed when no toolkit is registered.",
+      "remote": "read",
+      "risk": "read"
+    },
+    {
+      "id": "tool-call",
+      "method": "POST",
+      "path": "/v1/tools/{name}/call",
+      "query": [],
+      "body": "tool-call-request.schema.json",
+      "cli": ["node", "scripts/toolkit-tools.mjs", "call", "{name}", "<json arguments>"],
+      "schema": "tool-call.schema.json",
+      "version": "1.0.0",
+      "note": "Denied by default: only a readOnlyHint tool whose inputSchema takes no location, outside the web and context families, can be called (403 tool-not-allowed otherwise); a confirm argument is refused; the toolkit child always runs with MULTI_AGENT_UNATTENDED=1 and MCP_TOOLKIT_URL_POLICY=strict; an unknown tool is 404, invalid arguments 400.",
+      "remote": "local-only",
+      "risk": "high"
+    },
+    {
+      "id": "service-confluence",
+      "method": "GET",
+      "path": "/v1/services/confluence",
+      "query": ["page"],
+      "cli": ["node", "scripts/service-read.mjs", "confluence", "<page-id|https-url>"],
+      "schema": "service-read.schema.json",
+      "version": "1.0.0",
+      "remote": "read",
+      "risk": "read",
+      "note": "A page id, or an https URL on the configured Confluence host only (409 host-not-allowed otherwise, and for any URL when no host is configured). One request at a time (429 busy)."
+    },
+    {
+      "id": "service-crashlytics",
+      "method": "GET",
+      "path": "/v1/services/crashlytics",
+      "query": ["issue"],
+      "cli": ["node", "scripts/service-read.mjs", "crashlytics", "<https-issue-url>"],
+      "schema": "service-read.schema.json",
+      "version": "1.0.0",
+      "remote": "read",
+      "risk": "read"
+    },
+    {
+      "id": "service-figma",
+      "method": "GET",
+      "path": "/v1/services/figma",
+      "query": ["file", "node"],
+      "cli": ["node", "scripts/service-read.mjs", "figma", "<file-key>", "<node-id>"],
+      "schema": "service-read.schema.json",
+      "version": "1.0.0",
+      "note": "Rendered over the Figma REST API with the stored token; the Figma MCP is never called.",
+      "remote": "read",
+      "risk": "read"
+    },
+    {
+      "id": "permissions",
+      "method": "GET",
+      "path": "/v1/permissions",
+      "query": [],
+      "cli": ["node", "scripts/contract-server.mjs"],
+      "schema": "permissions.schema.json",
+      "version": "1.0.0",
+      "note": "available is false today: the host records no pending permission prompt another process can read.",
+      "remote": "read",
+      "risk": "read"
     }
   ],
   "fixtures": {
@@ -361,5 +699,12 @@
     "error-unauthorized.json": "contract-error.schema.json",
     "error-invalid-request.json": "contract-error.schema.json",
     "error-unsigned.json": "contract-error.schema.json"
+  },
+  "page": {
+    "path": "/office",
+    "auth": "none for the page; the token reaches it through a one-time code in the URL fragment (POST /office/code with the bearer and no Origin mints it, valid 10 seconds and one use), traded at POST /office/exchange from the page's own origin only",
+    "source": "MA_OFFICE_PAGE, else prefs.global.office.page, else the installed office/index.html (~/.claude/office, pipeline/office in a checkout); 404 when none exists",
+    "csp": "default-src 'none'; script-src and style-src a per-response nonce; img-src 'self' data:; connect-src 'self'; frame-ancestors 'none'; base-uri 'none'; form-action 'none'",
+    "assets": "GET /office/assets/<name>.png without a token: a sprite from the assets directory beside the page; the name is a plain file name (letters, digits, underscore), the file a PNG of at most 256 KiB whose real path is directly in that directory; anything else is 404, a query 400"
   }
 }