@mmerterden/multi-agent-pipeline 20.28.0 → 20.30.0

package/pipeline/schemas/stack-change.schema.json

@@ -0,0 +1,82 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/stack-change.schema.json",
+  "title": "Stack change",
+  "description": "What POST /v1/stack returns (`stack-toggle.mjs set`). Step one: preview {stacks, changed, enabledPlugins, dropped} with confirmToken and expiresAt, nothing written. Step two: the written enabledPlugins, the keys that changed and written.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contractVersion"],
+  "properties": {
+    "contractVersion": {
+      "type": "string",
+      "pattern": "^1\\.[0-9]+\\.[0-9]+$",
+      "x-sensitivity": "none"
+    },
+    "preview": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["stacks", "changed", "enabledPlugins", "dropped"],
+      "properties": {
+        "stacks": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "changed": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "enabledPlugins": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "boolean"
+          }
+        },
+        "dropped": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "confirmToken": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]{16,128}$"
+    },
+    "expiresAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "stacks": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "enabledPlugins": {
+      "type": "object",
+      "additionalProperties": {
+        "type": "boolean"
+      }
+    },
+    "changed": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "dropped": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "written": {
+      "type": "boolean"
+    }
+  }
+}

package/pipeline/schemas/stack-request.schema.json

@@ -0,0 +1,33 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/stack-request.schema.json",
+  "title": "Stack change request",
+  "description": "The body of POST /v1/stack. The first request names repo (a name from GET /v1/repos or its path) and stacks (as /multi-agent:stack takes them, aliases allowed); the second sends only confirmToken.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contractVersion"],
+  "properties": {
+    "contractVersion": {
+      "type": "string",
+      "pattern": "^1\\.[0-9]+\\.[0-9]+$",
+      "x-sensitivity": "none"
+    },
+    "repo": {
+      "type": "string",
+      "maxLength": 4096
+    },
+    "stacks": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 8,
+      "items": {
+        "type": "string",
+        "pattern": "^[a-z]{2,16}$"
+      }
+    },
+    "confirmToken": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]{16,128}$"
+    }
+  }
+}

package/pipeline/schemas/stack.schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/stack.schema.json",
+  "title": "Stack status",
+  "description": "What GET /v1/stack?repo= returns (`stack-toggle.mjs status --json`): the stacks a repository enables in .claude/settings.json and every marketplace plugin with its skills. manifestVerified is false when the marketplace manifest could not be read and the plugin list is the convention.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contractVersion", "stacks", "knownStacks", "plugins", "manifestVerified"],
+  "properties": {
+    "contractVersion": {
+      "type": "string",
+      "pattern": "^1\\.[0-9]+\\.[0-9]+$",
+      "x-sensitivity": "none"
+    },
+    "stacks": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "knownStacks": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "plugins": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "enabled", "alwaysOn", "stack", "skills"],
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "enabled": {
+            "type": "boolean"
+          },
+          "alwaysOn": {
+            "type": "boolean"
+          },
+          "stack": {
+            "type": ["string", "null"]
+          },
+          "skills": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        }
+      }
+    },
+    "manifestVerified": {
+      "type": "boolean"
+    }
+  }
+}

package/pipeline/schemas/steer-request.schema.json

@@ -0,0 +1,25 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/steer-request.schema.json",
+  "title": "Steer request",
+  "description": "The body of POST /v1/runs/{id}/steer. The first request carries text (verbatim, up to 4000 characters) and gets a preview and a confirm token bound to the run and that text; the second carries only confirmToken.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contractVersion"],
+  "properties": {
+    "contractVersion": {
+      "type": "string",
+      "pattern": "^1\\.[0-9]+\\.[0-9]+$",
+      "x-sensitivity": "none"
+    },
+    "text": {
+      "type": "string",
+      "minLength": 1,
+      "maxLength": 4000
+    },
+    "confirmToken": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]{16,128}$"
+    }
+  }
+}

package/pipeline/schemas/steer.schema.json

@@ -0,0 +1,59 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/steer.schema.json",
+  "title": "Steer queued",
+  "description": "What POST /v1/runs/{id}/steer returns (`steer-run.mjs`). Step one: preview {text, status, currentPhase, replaces} with confirmToken and expiresAt, nothing written. Step two: the instruction is queued as the run's pendingSteer and applied at the entry to its next phase; replaced is the unconsumed instruction it replaced, or null.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contractVersion", "taskId"],
+  "properties": {
+    "contractVersion": {
+      "type": "string",
+      "pattern": "^1\\.[0-9]+\\.[0-9]+$",
+      "x-sensitivity": "none"
+    },
+    "taskId": {
+      "type": "string"
+    },
+    "queuedAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "replaced": {
+      "type": ["string", "null"]
+    },
+    "status": {
+      "type": ["string", "null"]
+    },
+    "currentPhase": {
+      "type": ["integer", "null"]
+    },
+    "preview": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["text", "status", "currentPhase", "replaces"],
+      "properties": {
+        "text": {
+          "type": "string"
+        },
+        "status": {
+          "type": ["string", "null"]
+        },
+        "currentPhase": {
+          "type": ["integer", "null"]
+        },
+        "replaces": {
+          "type": ["string", "null"]
+        }
+      }
+    },
+    "confirmToken": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]{16,128}$"
+    },
+    "expiresAt": {
+      "type": "string",
+      "format": "date-time"
+    }
+  }
+}

package/pipeline/schemas/tool-call-request.schema.json

@@ -0,0 +1,19 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/tool-call-request.schema.json",
+  "title": "Tool call request",
+  "description": "The body of POST /v1/tools/{name}/call: the tool's arguments, which must satisfy its inputSchema. At most 64 KiB.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contractVersion"],
+  "properties": {
+    "contractVersion": {
+      "type": "string",
+      "pattern": "^1\\.[0-9]+\\.[0-9]+$",
+      "x-sensitivity": "none"
+    },
+    "arguments": {
+      "type": "object"
+    }
+  }
+}

package/pipeline/schemas/tool-call.schema.json

@@ -0,0 +1,47 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/tool-call.schema.json",
+  "title": "Tool call result",
+  "description": "What POST /v1/tools/{name}/call returns (`toolkit-tools.mjs call`): the tool's result as text, JSON (as text) and images (base64, image types only). Every text is redacted.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contractVersion", "tool", "risk", "isError", "content"],
+  "properties": {
+    "contractVersion": {
+      "type": "string",
+      "pattern": "^1\\.[0-9]+\\.[0-9]+$",
+      "x-sensitivity": "none"
+    },
+    "tool": {
+      "type": "string"
+    },
+    "risk": {
+      "enum": ["read", "low", "high"]
+    },
+    "isError": {
+      "type": "boolean"
+    },
+    "content": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["kind"],
+        "properties": {
+          "kind": {
+            "enum": ["text", "json", "image"]
+          },
+          "text": {
+            "type": "string"
+          },
+          "mime": {
+            "type": "string"
+          },
+          "data": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/pipeline/schemas/tools.schema.json

@@ -0,0 +1,60 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/tools.schema.json",
+  "title": "Toolkit tools",
+  "description": "What GET /v1/tools returns (`toolkit-tools.mjs list`): every tool the registered multi-agent-toolkit MCP server serves, with its category (the name's prefix), risk from its own annotations (readOnlyHint read, destructiveHint high, else low) and its inputSchema, from which a client builds the form. Calls are denied by default; allowed says which tools can be called and reason why the others cannot.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contractVersion", "tools"],
+  "properties": {
+    "contractVersion": {
+      "type": "string",
+      "pattern": "^1\\.[0-9]+\\.[0-9]+$",
+      "x-sensitivity": "none"
+    },
+    "tools": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": [
+          "name",
+          "title",
+          "category",
+          "description",
+          "risk",
+          "inputSchema",
+          "allowed",
+          "reason"
+        ],
+        "properties": {
+          "name": {
+            "type": "string"
+          },
+          "title": {
+            "type": ["string", "null"]
+          },
+          "category": {
+            "type": "string"
+          },
+          "description": {
+            "type": "string"
+          },
+          "risk": {
+            "enum": ["read", "low", "high"]
+          },
+          "inputSchema": {
+            "type": "object"
+          },
+          "allowed": {
+            "type": "boolean",
+            "description": "Whether POST /v1/tools/{name}/call accepts this tool: only a readOnlyHint tool whose inputSchema takes no location (path, URL, file, directory, output, project, root) and that is not in the web or context family."
+          },
+          "reason": {
+            "type": ["string", "null"]
+          }
+        }
+      }
+    }
+  }
+}

package/pipeline/scripts/_active-run.mjs

@@ -0,0 +1,158 @@
+/**
+ * @file _active-run.mjs  -  which pipeline run a hook call belongs to, and where
+ * that run stands against its mode's phase list.
+ *
+ * A hook receives the host's session id and working directory, never a task id.
+ * A run is bound to a session by one of three facts, strongest first:
+ *
+ *   1. `sessionId` equals MULTI_AGENT_SESSION_ID in the hook's environment: the
+ *      id a launcher started the run with (continuous mode, a client).
+ *   2. `hostSessionId` equals the payload's `session_id`: write-state.mjs stamps
+ *      the host session that made the run's last phase transition
+ *      (CLAUDE_CODE_SESSION_ID), so the session driving a run is the one bound
+ *      to it, and a resume in a new session rebinds it at its first transition.
+ *   3. A state with no `hostSessionId` whose `worktreePath` is the git toplevel
+ *      of the payload's cwd: a run written before the stamp existed. A state
+ *      that carries a different `hostSessionId` is another session's run and
+ *      never matches this way.
+ *
+ * Nothing here decides anything; callers (run-stop-guard, run-scope-guard)
+ * apply their own rule to the run this returns. Zero runtime dependencies.
+ *
+ * @module pipeline/scripts/_active-run
+ */
+
+import { spawnSync } from "node:child_process";
+import { appendFileSync, mkdirSync, realpathSync, statSync } from "node:fs";
+import { dirname, join } from "node:path";
+
+import { readRegularJson } from "../lib/regular-file.mjs";
+import { listRuns, logsRoot, resolveRunFile } from "./_run-paths.mjs";
+
+export {
+  finalPhaseOf,
+  modeOf,
+  modePhases,
+  nextPhaseOf,
+  phaseContract,
+  phaseName,
+} from "../lib/run-completion.mjs";
+
+function real(p) {
+  try {
+    return realpathSync(p);
+  } catch {
+    return p;
+  }
+}
+
+/** The git toplevel of `dir`, real-pathed, or null outside a repository. */
+export function gitToplevel(dir) {
+  if (!dir) return null;
+  const r = spawnSync("git", ["-C", dir, "rev-parse", "--show-toplevel"], {
+    encoding: "utf8",
+    timeout: 5000,
+  });
+  return r.status === 0 ? real(r.stdout.trim()) : null;
+}
+
+function mtime(p) {
+  try {
+    return statSync(p).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
+const LIVE_STATUSES = new Set(["in_progress", "awaiting_input"]);
+
+/**
+ * The run bound to this hook call, or null.
+ *
+ * @param {{sessionId?: string|null, cwd?: string|null, env?: Record<string,string|undefined>}} opts
+ * @returns {{statePath: string, state: object, matchedBy: "session"|"host-session"|"worktree"} | null}
+ *   with `unreadable` (count of state files that did not parse) on the returned
+ *   object or on the `findActiveRun.lastUnreadable` property when nothing matched
+ */
+export function findActiveRun({ sessionId = null, cwd = null, env = process.env } = {}) {
+  const launched = env.MULTI_AGENT_SESSION_ID || "";
+  let top;
+  const topOf = () => {
+    if (top === undefined) top = cwd ? gitToplevel(cwd) : null;
+    return top;
+  };
+  const hits = [];
+  let unreadable = 0;
+  const prevRoot = process.env.LOGS_ROOT;
+  if (env.LOGS_ROOT !== undefined) process.env.LOGS_ROOT = env.LOGS_ROOT;
+  try {
+    for (const run of listRuns()) {
+      const p = resolveRunFile(run.taskId, "agent-state.json", run.project);
+      if (!p) continue;
+      const doc = readRegularJson(p, null);
+      if (!doc || typeof doc !== "object" || Array.isArray(doc)) {
+        unreadable += 1;
+        continue;
+      }
+      let matchedBy = null;
+      if (launched && doc.sessionId === launched) matchedBy = "session";
+      else if (sessionId && doc.hostSessionId === sessionId) matchedBy = "host-session";
+      else if (
+        !doc.hostSessionId &&
+        typeof doc.worktreePath === "string" &&
+        doc.worktreePath &&
+        topOf() &&
+        real(doc.worktreePath) === topOf()
+      ) {
+        matchedBy = "worktree";
+      }
+      if (matchedBy) hits.push({ statePath: p, state: doc, matchedBy, t: mtime(p) });
+    }
+  } finally {
+    if (prevRoot === undefined) delete process.env.LOGS_ROOT;
+    else process.env.LOGS_ROOT = prevRoot;
+  }
+  findActiveRun.lastUnreadable = unreadable;
+  if (!hits.length) return null;
+  const rank = { session: 0, "host-session": 1, worktree: 2 };
+  hits.sort((a, b) => rank[a.matchedBy] - rank[b.matchedBy] || b.t - a.t);
+  const lead = hits.filter((h) => h.matchedBy === hits[0].matchedBy);
+  // A session can hold a finished run next to a live one. The run started
+  // last is the one the session is on: a live run started after the finished
+  // one wins however recently the finished file was touched, and a live run
+  // started before it was abandoned without a halt and does not hold the
+  // session. startedAt orders them; the state's mtime stands in without it.
+  const started = (h) => Date.parse(h.state?.startedAt) || h.t;
+  const isLive = (h) => LIVE_STATUSES.has(h.state?.status);
+  const liveRun = lead.find(isLive);
+  const finished = lead.filter((h) => !isLive(h));
+  const lastFinished = finished.sort((a, b) => started(b) - started(a))[0];
+  let pick = lead[0];
+  if (liveRun)
+    pick = lastFinished && started(lastFinished) > started(liveRun) ? lastFinished : liveRun;
+  const { t: _t, ...best } = pick;
+  return { ...best, unreadable };
+}
+findActiveRun.lastUnreadable = 0;
+
+/**
+ * Append one line to the hook failure log under the log root. A hook that
+ * fails open says why somewhere a person can read later; this never throws.
+ *
+ * @param {string} hook
+ * @param {string} reason
+ * @param {Record<string,string|undefined>} [env]
+ */
+export function logHookFailure(hook, reason, env = process.env) {
+  try {
+    const root = env.LOGS_ROOT || logsRoot();
+    mkdirSync(root, { recursive: true });
+    const line = `${new Date().toISOString()} ${hook}: ${String(reason).replace(/\s+/g, " ")}\n`;
+    appendFileSync(join(root, "hook-failures.log"), line);
+  } catch {
+    // Logging is best-effort; the hook's verdict never depends on it.
+  }
+}
+
+/** The run directory that holds a state file. */
+export const runDirOf = (statePath) => dirname(statePath);

package/pipeline/scripts/_autopilot-outcomes.mjs

@@ -27,6 +27,7 @@ export const OUTCOME = Object.freeze({
   MERGED: "merged",
   SKIPPED: "skipped",
   COMPLETED_NO_PR: "completed-no-pr",
+  STOPPED_INCOMPLETE: "stopped-incomplete",
   NEEDS_INPUT: "needs-input",
   AWAITING_ANSWER: "awaiting-answer",
   VERIFICATION_FAILED: "verification-failed",

package/pipeline/scripts/_cost.mjs

@@ -1,6 +1,7 @@
 /**
  * @file _cost.mjs  -  shared token-cost pricing math for the .mjs cost scripts
- * (cost-budget-check.mjs, run-aggregator.mjs).
+ * (cost-budget-check.mjs, run-aggregator.mjs, cost-analyze.mjs,
+ * office-ledger.mjs).
  *
  * The single source of the pricing formula for Node callers. Rate DATA still
  * lives in cost-table.json; this module owns only the arithmetic so the formula
@@ -73,3 +74,67 @@ export function attemptSpend(rows) {
   }
   return { usd, unknown };
 }
+
+/**
+ * Wire ID -> rate. Transcripts carry the wire value ("claude-opus-5-5"); the
+ * price table is keyed by rung, so each rung's `modelId` and `copilotModelId`
+ * map to its rate, `legacy` adds previous-generation IDs at their own rates,
+ * and `models` overrides the rung rate for a dispatched ID whose model is not
+ * the rung's (Copilot CLI's older models bill at their own rate). Matching on
+ * the ID rather than the rung name keeps a generation move a data edit, which
+ * is the contract cost-table.json states for itself. A rung name ("opus")
+ * prices as its rung, which is what a tracker records.
+ *
+ * @param {object} table  cost-table.json
+ * @returns {(modelId: string|null|undefined) => object|null}
+ */
+export function modelRateLookup(table) {
+  const byId = new Map([
+    ...Object.entries(table.legacy || {}),
+    ...Object.values(table.prices || {}).flatMap((p) =>
+      [p.modelId, p.copilotModelId].filter(Boolean).map((id) => [id, p]),
+    ),
+    ...Object.entries(table.models || {}),
+  ]);
+  const longestFirst = [...byId.keys()].sort((a, b) => b.length - a.length);
+  return (modelId) => {
+    if (!modelId) return null;
+    const exact = byId.get(modelId) ?? table.prices?.[modelId];
+    if (exact) return exact;
+    // A dated snapshot id (a known id, a hyphen, a release date) prices as that
+    // id; the longest known id wins, so a current id is never read as a shorter
+    // legacy one. Written as a shape rather than as a literal, because
+    // smoke-model-fallback.sh reads every model id in this tree and requires it
+    // to exist in cost-table.json. An id nobody knows prices as nothing and is
+    // COUNTED as unpriced rather than folded in at zero.
+    const id = longestFirst.find(
+      (known) => modelId.startsWith(`${known}-`) || modelId.startsWith(`${known}[`),
+    );
+    return id ? byId.get(id) : null;
+  };
+}
+
+/**
+ * Cache WRITES are not a discount, they are a surcharge: Anthropic prices a
+ * 1h cache write above fresh input. cost-table.json carries cacheReadPerMtok
+ * only, so the write rate is derived at the published 1.25x of input - an
+ * unpriced component silently dropped would make every long-context session
+ * look cheap, which is the direction that hurts.
+ */
+export const CACHE_WRITE_MULTIPLIER = 1.25;
+
+/**
+ * USD for one transcript usage record, or null without a rate.
+ *
+ * @param {object|null} rate
+ * @param {{input_tokens?:number, output_tokens?:number, cache_read_input_tokens?:number, cache_creation_input_tokens?:number}} u
+ */
+export function priceUsage(rate, u) {
+  const fresh = Number(u.input_tokens || 0);
+  const out = Number(u.output_tokens || 0);
+  const cacheRead = Number(u.cache_read_input_tokens || 0);
+  const cacheWrite = Number(u.cache_creation_input_tokens || 0);
+  const base = costUsd(rate, fresh, out, cacheRead);
+  if (base === null) return null;
+  return base + (cacheWrite / 1_000_000) * (rate.inPerMtok || 0) * CACHE_WRITE_MULTIPLIER;
+}