@mmerterden/multi-agent-pipeline 20.28.0 → 20.30.0

package/pipeline/contract/types/index.d.ts

@@ -1,8 +1,8 @@
 // Generated by pipeline/contract/build.mjs from pipeline/schemas/*.schema.json.
 // Do not edit: change the schema and run `node pipeline/contract/build.mjs --write`.
 
-export type ContractVersion = "1.3.0";
-export type SurfaceId = "runs" | "run" | "commands" | "questions" | "issues" | "worktrees" | "launch-spec" | "repos" | "launch" | "answer" | "run-log" | "resume" | "kill" | "gc" | "autopilot" | "autopilot-off" | "phone-runs" | "phone-run" | "phone-answer" | "phone-launch";
+export type ContractVersion = "1.4.0";
+export type SurfaceId = "runs" | "run" | "commands" | "questions" | "issues" | "worktrees" | "launch-spec" | "repos" | "launch" | "answer" | "run-log" | "resume" | "kill" | "gc" | "autopilot" | "autopilot-off" | "phone-runs" | "phone-run" | "phone-answer" | "phone-launch" | "autopilot-on" | "steer" | "activity" | "activity-stream" | "agent-chat" | "routines" | "routine-delete" | "stack" | "stack-set" | "ledger" | "run-results" | "run-evidence" | "review-verdict" | "issue-maturity" | "prs" | "tools" | "tool-call" | "service-confluence" | "service-crashlytics" | "service-figma" | "permissions";
 
 /** What `runs-index.mjs --json` prints: every run under the log root and the unattended log root (one record per task id), grouped per status/SKILL.md 3b. Fields are only ever added - a decoder ignores keys it does not know. `--redact` drops every x-sensitivity local field (and `logsRoot`) and scrubs the free text in the title, `now`, sub-step names, task subjects and the pending question. */
 export interface RunsIndex {
@@ -38,7 +38,7 @@ export interface RunsIndexRun {
   rev: number | null;
   /** The session id the run was launched under (agent-state sessionId). A client that launched a run through launch.json finds it by this id. Added in 1.1.0. */
   sessionId?: string | null;
-  /** The step a paused run re-enters (agent-state waitingFor): maturity, user-channels-choice or question. Added in 1.1.0. */
+  /** The step a paused run re-enters (agent-state waitingFor): maturity, user-channels-choice, local-test, attended-reply or question; null or absent when the run is not waiting. Added in 1.1.0. */
   waitingFor?: string | null;
   /** The question the run stopped on, present only with waitingFor question. Answer it with one of options[].id through `answer-question.mjs` or POST /v1/runs/{id}/answer. text and labels are scrubbed under --redact. Added in 1.1.0. */
   pendingQuestion?: null | RunsIndexQuestion;
@@ -500,10 +500,537 @@ export interface Repos {
   }>;
 }
 
+/** What GET /v1/activity returns and `activity-snapshot.mjs --json` prints, and what each GET /v1/activity/stream event carries: one room per repository, one table per run (its team; a session no run claims sits at a table of its own), one seat per agent seen in the recent window, the orchestrator at the head. Derived from disk on every call. No field is machine-local: there are no paths, seat labels come from allow-listed fields only (tool name, file basename, sidecar description), and every free-text string has been through the redactor, so the redacted and the full view are the same document. */
+export interface Activity {
+  contractVersion: string;
+  generatedAt: string;
+  /** A session or subagent whose transcript changed within this window has a desk. */
+  recentMinutes: number;
+  counts: {
+    rooms: number;
+    tables: number;
+    seats: number;
+    live: number;
+    waiting: number;
+  };
+  rooms: Array<{
+    repo: string;
+    tables: Array<ActivityTable>;
+  }>;
+  /** Runs over more than one repository: the table and the rooms its corridor joins. */
+  corridors: Array<{
+    tableId: string;
+    repos: Array<string>;
+  }>;
+}
+
+export interface ActivityTable {
+  id: string;
+  /** run: a pipeline run; session: a session no run claims (outside the pipeline); unmatched: a session more than one run could claim, kept apart rather than guessed. */
+  kind: "run" | "session" | "unmatched";
+  taskId: string | null;
+  title: string | null;
+  host: "claude" | "copilot" | "codex";
+  /** true for a Copilot CLI or Codex session: no subagent detail exists there. */
+  limited: boolean;
+  sessionId: string | null;
+  /** How the session was tied to the run: the session id the run recorded, or its working directory and branch. */
+  matchedBy: "session" | "cwd-branch" | null;
+  repos: Array<string>;
+  phase: {
+    id: number;
+    name: string;
+    /** The last phase id, for an n of last display. */
+    last: number;
+  } | null;
+  now: string | null;
+  status: string | null;
+  waitingForYou: boolean;
+  pendingQuestion: {
+    id: string;
+    text: string;
+    kind: "single-select" | "multi-select";
+    options: Array<{
+      id: string;
+      label: string;
+    }>;
+  } | null;
+  tokens: {
+    in: number;
+    out: number;
+    cached: number;
+  } | null;
+  estUsd: number | null;
+  /** Where tokens and estUsd come from. not-measured means the numbers are null, never 0. */
+  costSource: "tracker-state" | "not-measured";
+  /** The room this table stands in. */
+  repo: string;
+  /** worktree: the run works in its own worktree; local: in the main checkout; unknown when the state does not say. */
+  location: "worktree" | "local" | "unknown";
+  branch: string | null;
+  phaseHistory: Array<{
+    id: number | null;
+    name: string;
+    status: string;
+    startedAt: string | null;
+    completedAt: string | null;
+  }>;
+  startedAt: string | null;
+  elapsedSeconds: number | null;
+  /** The seat id that holds the work now. */
+  holder: string | null;
+  /** The last seat of an earlier phase, for drawing the handoff. */
+  previousHolder: string | null;
+  seats: Array<ActivitySeat>;
+}
+
+export interface ActivitySeat {
+  id: string;
+  sessionId: string | null;
+  /** null for the session's own (orchestrator) desk. */
+  agentId: string | null;
+  agentType: string | null;
+  role: string;
+  /** The role, numbered when agents of the same role sit at one table (Reviewer 1, Reviewer 2). */
+  label: string;
+  /** false when the agent type is in no role table entry and the raw type is shown. */
+  known: boolean;
+  sprite: number;
+  color: string;
+  model: string | null;
+  modelLabel: string | null;
+  description: string | null;
+  state: "reading" | "writing" | "spawning" | "waiting" | "idle" | "done";
+  tool: string | null;
+  detail: string | null;
+  /** Whether the session is alive per `claude agents --json`; null when that list cannot be read. */
+  live: boolean | null;
+  startedAt: string | null;
+  lastAt: string | null;
+  /** The run phase the agent was spawned in; null for the orchestrator or outside a run. */
+  phase: number | null;
+  status: "working" | "idle" | "done";
+  /** What the seat is doing in a few plain words (Reading Foo.swift, Running a command), else the raw tool name. */
+  doing: string;
+}
+
+/** What GET /v1/agents/{sessionId}/{agentId}/chat returns and `activity-snapshot.mjs chat` prints: one page of an agent's transcript read from its end, oldest first, at most `limit` messages. Only user and assistant records are read; api-request records are never parsed and thinking blocks are never emitted. Every text has been through the redactor; a text the outbound gate still flags is replaced by a marker. `before` is the byte offset to send back for the previous page, null at the start of the file. */
+export interface ActivityChat {
+  contractVersion: string;
+  sessionId: string;
+  /** null for the session's own transcript (the orchestrator). */
+  agentId: string | null;
+  messages: Array<{
+    offset: number;
+    role: "user" | "assistant";
+    at: string | null;
+    blocks: Array<{
+      kind: "text";
+      text: string;
+    } | {
+      kind: "tool";
+      name: string;
+      summary: string;
+      toolUseId: string | null;
+    } | {
+      kind: "result";
+      toolUseId: string | null;
+      text: string;
+      isError: boolean;
+    }>;
+  }>;
+  before: number | null;
+  /** How many items the redactor replaced on this page. */
+  redacted: number;
+}
+
+/** What GET /v1/routines returns (`routine-registry.mjs list --json`): the routines saved with /multi-agent:save. Description and source are scrubbed. */
+export interface Routines {
+  contractVersion: string;
+  routines: Array<{
+    name: string;
+    description: string;
+    createdAt: string | null;
+    source: string | null;
+  }>;
+}
+
+/** What DELETE /v1/routines/{name} returns. Without ?confirm: preview (the routine) with confirmToken and expiresAt. With it: removed, from `routine-registry.mjs remove`. A shipped command is never removed. */
+export interface RoutineDelete {
+  contractVersion: string;
+  preview?: {
+    name: string;
+    description: string;
+    createdAt: string | null;
+    source: string | null;
+  };
+  confirmToken?: string;
+  expiresAt?: string;
+  removed?: {
+    name: string;
+    removedDir: boolean;
+    removedEntry: boolean;
+  };
+}
+
+/** 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. */
+export interface Stack {
+  contractVersion: string;
+  stacks: Array<string>;
+  knownStacks: Array<string>;
+  plugins: Array<{
+    name: string;
+    enabled: boolean;
+    alwaysOn: boolean;
+    stack: string | null;
+    skills: Array<string>;
+  }>;
+  manifestVerified: boolean;
+}
+
+/** 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. */
+export interface StackRequest {
+  contractVersion: string;
+  repo?: string;
+  stacks?: Array<string>;
+  confirmToken?: string;
+}
+
+/** 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. */
+export interface StackChange {
+  contractVersion: string;
+  preview?: {
+    stacks: Array<string>;
+    changed: Array<string>;
+    enabledPlugins: {
+      [key: string]: boolean;
+    };
+    dropped: Array<string>;
+  };
+  confirmToken?: string;
+  expiresAt?: string;
+  stacks?: Array<string>;
+  enabledPlugins?: {
+    [key: string]: boolean;
+  };
+  changed?: Array<string>;
+  dropped?: Array<string>;
+  written?: boolean;
+}
+
+/** The body of POST /v1/autopilot/on. The first request names the selection (repos, by nameWithOwner, each already in the autopilot config) and gets a preview and a confirm token; the second sends only the token and turns the mode on for exactly what was previewed. An empty selection is refused: the mode is never turned on without a repository. */
+export interface AutopilotOnRequest {
+  contractVersion: string;
+  repos?: Array<string>;
+  /** Save the selection without scheduling anything. */
+  configureOnly?: boolean;
+  confirmToken?: string;
+}
+
+/** What POST /v1/autopilot/on returns (`autopilot-control.mjs on-preview`, then `on`). Step one: preview {keep, drop, probe, configureOnly} with confirmToken and expiresAt. Step two: enabled and scheduled say whether the schedule was loaded; it is not when configureOnly was asked or a credential probe failed, and probe says which. */
+export interface AutopilotOn {
+  contractVersion: string;
+  preview?: {
+    keep: Array<string>;
+    drop: Array<string>;
+    probe: {
+      ready: boolean;
+      problems: Array<string>;
+      warnings: Array<string>;
+    };
+    configureOnly: boolean;
+  };
+  confirmToken?: string;
+  expiresAt?: string;
+  enabled?: boolean;
+  scheduled?: boolean;
+  awake?: boolean | null;
+  repos?: Array<string>;
+  dropped?: Array<string>;
+  probe?: {
+    ready: boolean;
+    problems: Array<string>;
+    warnings: Array<string>;
+  };
+}
+
+/** 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. */
+export interface SteerRequest {
+  contractVersion: string;
+  text?: string;
+  confirmToken?: string;
+}
+
+/** 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. */
+export interface Steer {
+  contractVersion: string;
+  taskId: string;
+  queuedAt?: string;
+  replaced?: string | null;
+  status?: string | null;
+  currentPhase?: number | null;
+  preview?: {
+    text: string;
+    status: string | null;
+    currentPhase: number | null;
+    replaces: string | null;
+  };
+  confirmToken?: string;
+  expiresAt?: string;
+}
+
+/** What GET /v1/ledger returns and `office-ledger.mjs --json` prints: tokens and estimated USD for today, this week (from Monday) and this month, in local time, broken down by run, repository, model and phase. A run's numbers come from its tracker-state.json when the tracker carries tokens, else from the usage records of the transcripts tied to it; a run with neither is not-measured, and its usd and tokens are null, never 0. Sessions no run claims are counted apart as outside the pipeline. Prices come from cost-table.json; a cache write is priced at 1.25 times input. Every amount names its source. */
+export interface Ledger {
+  contractVersion: string;
+  generatedAt: string;
+  prices: {
+    table: "cost-table.json";
+    verifiedAt: string | null;
+    ageDays: number | null;
+    stale: boolean;
+    warning: string | null;
+  };
+  windows: {
+    today: LedgerWindow;
+    week: LedgerWindow;
+    month: LedgerWindow;
+  };
+}
+
+/** tracker-state: the pipeline's own ledger; transcript: derived from the host's usage records; mixed: a sum of both kinds; not-measured: nothing could be read, so the numbers are null. */
+export type LedgerSource = "tracker-state" | "transcript" | "mixed" | "not-measured";
+
+export type LedgerTokens = {
+  in: number;
+  out: number;
+  cacheRead: number;
+  cacheWrite: number;
+} | null;
+
+export interface LedgerAmount {
+  tokens: LedgerTokens;
+  usd: number | null;
+  source: LedgerSource;
+  /** Usage records whose model has no price; their tokens are counted, their cost is not. */
+  unpriced: number;
+}
+
+export interface LedgerRow {
+  key: string;
+  /** On byRun rows: the run repository. */
+  repo?: string | null;
+  tokens: LedgerTokens;
+  usd: number | null;
+  source: LedgerSource;
+  unpriced: number;
+}
+
+export interface LedgerWindow {
+  since: string;
+  total: LedgerAmount;
+  outsidePipeline: LedgerAmount;
+  /** Task ids of runs active in the window whose cost could not be measured. */
+  notMeasured: Array<string>;
+  byRun: Array<LedgerRow>;
+  byRepo: Array<LedgerRow>;
+  byModel: Array<LedgerRow>;
+  byPhase: Array<LedgerRow>;
+}
+
+/** What GET /v1/runs/{id}/results returns (`run-results.mjs <id> --json`): what a run produced, read from its own files. diff from agent-state diffRisk or .review-diff.txt; findings from triage-output.json or agent-state review; tests from the test-summary gate and uiTest; evidence the screenshot names under .pipeline/evidence; analysis the documents an analysis run wrote. A part with no source is null. Text is scrubbed and redacted; paths are reduced to file names. */
+export interface RunResults {
+  contractVersion: string;
+  taskId: string;
+  diff: {
+    files: number;
+    added: number | null;
+    removed: number | null;
+    maxScore: number | null;
+    signals: Array<string>;
+    changed: Array<string>;
+    source: string;
+  } | null;
+  findings: {
+    approved: boolean | null;
+    items: Array<{
+      severity: string;
+      file: string | null;
+      line: number | null;
+      issue: string;
+      fix: string | null;
+      reviewer: string | null;
+      verdict: string;
+    }>;
+    total: number;
+    source: string;
+  } | null;
+  tests: {
+    status: string | null;
+    passed: number | null;
+    failed: number | null;
+    skipped: number | null;
+    uiTest: {
+      ran: boolean;
+      status: string | null;
+      notRunReason: string | null;
+    } | null;
+    source: string;
+  } | null;
+  evidence: Array<{
+    name: string;
+    phase: "before" | "after" | null;
+  }>;
+  analysis: {
+    documents: Array<{
+      name: string;
+      text: string | null;
+    }>;
+    confluencePages: number;
+    jiraIssueKey: string | null;
+  } | null;
+}
+
+/** What GET /v1/runs/{id}/evidence/{name} returns (`run-results.mjs <id> --evidence <name>`): one screenshot from the run's .pipeline/evidence directory, base64. name is a bare png or jpg file name; one that resolves outside the directory is not found. */
+export interface RunEvidence {
+  contractVersion: string;
+  taskId: string;
+  name: string;
+  mime: "image/png" | "image/jpeg";
+  data: string;
+}
+
+/** What GET /v1/issues/{key}/maturity returns (`work-items.mjs maturity <key>`, from lib/issue-fetcher.sh): the maturity check the pipeline runs before it starts on an issue. key is a Jira key, owner/repo#N or #N. Blockers stop a run; warnings are asked about. Text is redacted. */
+export interface IssueMaturity {
+  contractVersion: string;
+  key: string;
+  kind: "jira" | "github" | "freetext";
+  title: string;
+  type: string | null;
+  status: string | null;
+  maturity: {
+    score: number | null;
+    blockers: Array<string>;
+    warnings: Array<string>;
+    summary: string | null;
+  };
+  description: string | null;
+}
+
+/** What GET /v1/prs returns (`work-items.mjs prs`): open pull requests where you are asked to review or are the author. sources says per host whether it was read; Bitbucket listing is not implemented and says so rather than showing an empty list. url is dropped under redact. */
+export interface Prs {
+  contractVersion: string;
+  items: Array<{
+    source: "github" | "bitbucket";
+    repo: string;
+    number: number;
+    title: string;
+    url: string | null;
+    author: string | null;
+    updatedAt: string | null;
+    role: "reviewer" | "author";
+  }>;
+  sources: Array<{
+    source: string;
+    ok: boolean;
+    count: number;
+    reason?: string;
+  }>;
+}
+
+/** The body of POST /v1/runs/{id}/review-verdict: empty for the preview, confirmToken to post. The verdict is never chosen by the request; it follows from the review's recorded findings. */
+export interface ReviewVerdictRequest {
+  contractVersion: string;
+  confirmToken?: string;
+}
+
+/** What POST /v1/runs/{id}/review-verdict returns (`work-items.mjs verdict <id> [--post]`). Only a finished review whose every finding is triaged (accepted, rejected or deferred) is previewed (409 review-incomplete otherwise). The preview carries findingsDigest, the hash of the findings it was made from, and the decision lib/post-pr-review.sh would post (approve with no accepted blocking or important finding, else needs-work), a confirmToken bound to that decision and digest, and expiresAt; a confirmation after either changed is 409 confirm-mismatch; the confirmation runs post-pr-review.sh, which posts the comments and the verdict with the user's own credential, and says posted. */
+export interface ReviewVerdict {
+  contractVersion: string;
+  taskId: string;
+  provider: "github" | "bitbucket-server" | null;
+  prNumber: number | null;
+  decision: "approve" | "needs-work";
+  acceptedBlocking: number;
+  acceptedImportant: number;
+  findings: number;
+  posted?: boolean;
+  confirmToken?: string;
+  expiresAt?: string;
+  findingsDigest: string;
+}
+
+/** 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. */
+export interface Tools {
+  contractVersion: string;
+  tools: Array<{
+    name: string;
+    title: string | null;
+    category: string;
+    description: string;
+    risk: "read" | "low" | "high";
+    inputSchema: Record<string, unknown>;
+    /** 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. */
+    allowed: boolean;
+    reason: string | null;
+  }>;
+}
+
+/** The body of POST /v1/tools/{name}/call: the tool's arguments, which must satisfy its inputSchema. At most 64 KiB. */
+export interface ToolCallRequest {
+  contractVersion: string;
+  arguments?: Record<string, unknown>;
+}
+
+/** 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. */
+export interface ToolCall {
+  contractVersion: string;
+  tool: string;
+  risk: "read" | "low" | "high";
+  isError: boolean;
+  content: Array<{
+    kind: "text" | "json" | "image";
+    text?: string;
+    mime?: string;
+    data?: string;
+  }>;
+}
+
+/** What GET /v1/services/confluence, /crashlytics and /figma return (`service-read.mjs`): one Confluence page, one Crashlytics issue or one Figma frame render, through the pipeline's own clients. Text is redacted; a frame comes back as base64 PNG. */
+export interface ServiceRead {
+  contractVersion: string;
+  service: "confluence" | "crashlytics" | "figma";
+  pageId?: string | null;
+  title?: string;
+  body?: string;
+  apiContracts?: number;
+  type?: string | null;
+  occurrences?: number | null;
+  impactedUsers?: number | null;
+  stackTrace?: Array<string>;
+  fileKey?: string;
+  nodeId?: string;
+  mime?: "image/png";
+  data?: string;
+}
+
+/** What GET /v1/permissions returns: the host permission prompts waiting on the user. available is false while the host records none where another process can read them; requests is then empty and reason says so. When available, each request names its session, the tool and a redacted summary. */
+export interface Permissions {
+  contractVersion: string;
+  available: boolean;
+  reason: string | null;
+  requests: Array<{
+    id: string;
+    sessionId: string;
+    tool: string;
+    summary: string;
+    at: string;
+  }>;
+}
+
 /** Every non-2xx body contract-server.mjs sends, on the desktop and the phone routes alike. `error` is a fixed code a client switches on; `message` is for a person and names no path, host or token. `errors` lists schema or rule violations for invalid-body and invalid-request; `supported` lists the majors ?v= accepts for unsupported-version. run-active and not-resumable answer POST /v1/runs/{id}/resume; confirm-expired and confirm-mismatch answer the confirming request of a kill or gc. */
 export interface ContractError {
   contractVersion: string;
-  error: "unauthorized" | "forbidden-host" | "forbidden-origin" | "not-found" | "method-not-allowed" | "invalid-query" | "unsupported-version" | "unsupported-media-type" | "invalid-body" | "invalid-request" | "no-launch-shape" | "not-waiting" | "wrong-question" | "wrong-arity" | "not-an-option" | "state-moved" | "unsigned" | "unknown-device" | "revoked-device" | "bad-signature" | "stale-request" | "replayed" | "replay-store-full" | "unknown-verb" | "forbidden-scope" | "launch-disabled" | "repo-not-allowed" | "run-active" | "not-resumable" | "confirm-expired" | "confirm-mismatch" | "unattended-profile-missing" | "workspace-not-trusted" | "internal";
+  error: "unauthorized" | "forbidden-host" | "forbidden-origin" | "not-found" | "method-not-allowed" | "invalid-query" | "unsupported-version" | "unsupported-media-type" | "invalid-body" | "invalid-request" | "no-launch-shape" | "not-waiting" | "wrong-question" | "wrong-arity" | "not-an-option" | "state-moved" | "unsigned" | "unknown-device" | "revoked-device" | "bad-signature" | "stale-request" | "replayed" | "replay-store-full" | "unknown-verb" | "forbidden-scope" | "launch-disabled" | "repo-not-allowed" | "run-active" | "not-resumable" | "confirm-expired" | "confirm-mismatch" | "unattended-profile-missing" | "workspace-not-trusted" | "no-selection" | "repo-not-configured" | "invalid-config" | "not-installed" | "repo-ambiguous" | "unreadable-settings" | "not-removable" | "not-steerable" | "too-many-streams" | "no-review" | "upstream-failed" | "tool-not-allowed" | "busy" | "review-incomplete" | "host-not-allowed" | "internal";
   message: string;
   errors?: Array<string>;
   supported?: Array<number>;