@mmerterden/multi-agent-pipeline 20.29.0 → 20.33.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.6.0";
+export type SurfaceId = "runs" | "run" | "commands" | "questions" | "issues" | "worktrees" | "launch-spec" | "repos" | "repo-add" | "repo-remove" | "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" | "jobs" | "job-start" | "stack" | "stack-set" | "ledger" | "system" | "prune-logs" | "settings" | "settings-set" | "credentials" | "memory" | "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 {
@@ -51,6 +51,8 @@ export interface RunsIndexRun {
   };
   estUsd: number;
   unlockedWrites: number;
+  /** agent-state.json mode as the run recorded it (analysis, test-gen, review...), so a reader can name the command; null when none was recorded. */
+  mode?: string | null;
   /** autopilot when the run is in autopilot mode; analysis for an analysis-family run (agent-state mode analysis, or a tracker with no agent state); development otherwise. Added in 1.2.0. */
   runType?: "analysis" | "development" | "autopilot";
   /** The issue summary Phase 0 recorded (agent-state title), else the input the run was launched with (launchRequest.input), else null. Scrubbed under --redact. Added in 1.2.0. */
@@ -64,6 +66,27 @@ export interface RunsIndexRun {
     subject: string;
     activeForm: string | null;
   } | null;
+  /** Where the work came from: a Jira key, a GitHub issue (owner/repo#N) or free text; a GitHub issue that got a Jira has both. Null when the run recorded neither. Added in 1.3.0. */
+  source?: {
+    kind: "jira" | "github" | "text";
+    jira: string | null;
+    issue: string | null;
+  } | null;
+  /** The pull request's number, from the state or its URL; the URL itself is prUrl (local). Added in 1.3.0. */
+  prNumber?: number | null;
+  /** Where Phase 5 sent the report, per adapter (state.channelResults); empty before then. Added in 1.3.0. */
+  channels?: Array<{
+    channel: "pr" | "jira" | "confluence" | "wiki" | "issue";
+    status: "posted" | "skipped" | "failed";
+  }>;
+  /** The address each adapter posted to, https only; dropped from a redacted answer. Added in 1.3.0. */
+  channelUrls?: {
+    pr?: string;
+    jira?: string;
+    confluence?: string;
+    wiki?: string;
+    issue?: string;
+  };
 }
 
 export interface RunsIndexQuestion {
@@ -490,7 +513,7 @@ export interface AutopilotOff {
   stoppedInFlight: boolean;
 }
 
-/** What GET /v1/repos returns and `launch-request.mjs repos` prints: the repositories POST /v1/launch?repo= accepts, by real path. source autopilot is a configured autopilot repo (config.json repos[], named by nameWithOwner); registered is one added with `launch-request.mjs register-repo` (launch-repos.json, named by its directory). path is dropped under redact. */
+/** What GET /v1/repos returns and `launch-request.mjs repos` prints: the repositories POST /v1/launch?repo= accepts, by real path. source autopilot is a configured autopilot repo (config.json repos[], named by nameWithOwner); registered is one added with `launch-request.mjs register-repo` (launch-repos.json, named by its directory). path is dropped under redact. With --all (?all=1): suggested lists checkouts earlier runs worked in that launch does not accept yet, and missing lists registered entries that are no longer a directory; each carries an id that POST /v1/repos and DELETE /v1/repos/{id} take. */
 export interface Repos {
   contractVersion: string;
   repos: Array<{
@@ -498,15 +521,817 @@ export interface Repos {
     name: string;
     source: "autopilot" | "registered";
   }>;
+  suggested?: Array<{
+    id: string;
+    path?: string;
+    name: string;
+  }>;
+  missing?: Array<{
+    id: string;
+    path?: string;
+    name: string;
+  }>;
+}
+
+/** The body of POST /v1/repos. The first request names suggestion (an id from GET /v1/repos?all=1) or path (an absolute path to a git checkout); the second sends only confirmToken. */
+export interface RepoRequest {
+  contractVersion: string;
+  suggestion?: string;
+  path?: string;
+  confirmToken?: string;
+}
+
+/** What POST /v1/repos and DELETE /v1/repos/{id} return. Without a token: preview (the repository's name) with confirmToken and expiresAt. With it: registered or removed, by name. Paths never leave the server here. */
+export interface RepoChange {
+  contractVersion: string;
+  preview?: {
+    name: string;
+  };
+  confirmToken?: string;
+  expiresAt?: string;
+  registered?: {
+    name: string;
+  };
+  removed?: {
+    name: string;
+  };
+}
+
+/** The catalog of jobs the office can start (office-jobs.json), read by job-launch.mjs and served by GET /v1/jobs. */
+export interface OfficeJobs {
+  $schema?: string;
+  contractVersion: string;
+  description?: string;
+  jobs: Array<{
+    id: string;
+    command: string;
+    role: string;
+    team: boolean;
+    launch?: "development" | "analysis" | "autopilot";
+    available?: boolean;
+    reason?: string | null;
+    params: Array<{
+      name: string;
+      kind: "work-item" | "pull-request" | "branch" | "run-id" | "jira-key" | "github-issue" | "enum" | "repo-path";
+      values?: Array<string>;
+      required: boolean;
+    }>;
+    writes: "none" | "branch" | "branch-pr" | "pr-comments" | "issue-comment";
+  }>;
+}
+
+/** The body of POST /v1/jobs. The first request names jobId (from GET /v1/jobs), repo (a name from GET /v1/repos or its path) and args (by parameter name), plus answers for a pipeline run; the second sends only confirmToken. */
+export interface JobRequest {
+  contractVersion: string;
+  jobId?: string;
+  repo?: string;
+  args?: {
+    [key: string]: string;
+  };
+  answers?: Record<string, unknown>;
+  confirmToken?: string;
+}
+
+/** What POST /v1/jobs returns. Without a token: preview (the job, the role that does it, team or solo, the repository by name, the exact prompt the session receives and what it writes outside the machine) with confirmToken and expiresAt. With it: started, the session the server began. */
+export interface JobChange {
+  contractVersion: string;
+  preview?: {
+    jobId: string;
+    role: string;
+    team: boolean;
+    repo: string;
+    prompt: string;
+    writes: "none" | "branch" | "branch-pr" | "pr-comments" | "issue-comment";
+  };
+  confirmToken?: string;
+  expiresAt?: string;
+  started?: {
+    sessionId: string;
+    jobId: string;
+    role: string;
+    team: boolean;
+    repo: string;
+  };
+}
+
+/** 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. solo: a session the office started for a one-person job, seated at a desk. */
+  kind: "run" | "session" | "solo" | "unmatched";
+  /** The command the table runs, for its room sign: /multi-agent, /multi-agent:analysis, /multi-agent:test-gen. Null for a session no command owns. */
+  command: string | null;
+  /** Which pipeline the table runs: /multi-agent (development), /multi-agent:analysis, or an autopilot run. Null for a session no pipeline owns. The office names the room after it. */
+  runType: "development" | "analysis" | "autopilot" | null;
+  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;
+  /** The task in progress in the phase in progress, from the mirrored task list. */
+  currentTask: string | null;
+  progress: 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;
+    /** How far the phase is, from its mirrored task list; null when it has none. */
+    progress: number | null;
+    /** The phase's task list as the host task widget shows it (mirrored by phase-tracker.sh task), redacted and cut short. */
+    tasks: Array<{
+      subject: string;
+      status: "pending" | "in_progress" | "completed";
+    }>;
+    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>;
+  /** The office job a session was started for (run tables carry none). */
+  job?: null | {
+    id: string;
+    role: string;
+    team: boolean;
+  };
+  /** Where the run's work came from, for the table sign: a Jira key, a GitHub issue or free text. Null for a session or a run that recorded neither. */
+  source: {
+    kind: "jira" | "github" | "text";
+    jira: string | null;
+    issue: string | null;
+  } | null;
+  /** The pull request the run opened, by number only. */
+  pr: {
+    number: number;
+  } | null;
+  /** What a waiting run waits for: a step it paused at (the run's waitingFor), or terminal when its session holds a question open in its own window. */
+  waitingFor: "maturity" | "user-channels-choice" | "local-test" | "attended-reply" | "question" | "terminal" | null;
+  /** Where the run's report went, per adapter, for the run window; empty for a session or before Phase 5. */
+  channels: Array<{
+    channel: "pr" | "jira" | "confluence" | "wiki" | "issue";
+    status: "posted" | "skipped" | "failed";
+  }>;
+}
+
+export interface ActivitySeat {
+  /** The desk's own task list from its transcript (TaskCreate / TaskUpdate / TodoWrite), phase tiles left out, redacted and cut short. */
+  tasks: Array<{
+    subject: string;
+    status: "pending" | "in_progress" | "completed";
+  }>;
+  /** The desk's last MCP calls, newest last: server, tool, whether it is still running, failed or answered, and how long it took. No input or result. */
+  mcp: Array<{
+    server: string;
+    tool: string;
+    state: "running" | "ok" | "error";
+    ms: number | null;
+    at: string | null;
+  }>;
+  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/system returns and `system-status.mjs --json` prints: CPU load, memory, free disk and what the pipeline itself uses. Numbers only: no path, process argument, user name or host name. A value that could not be measured is null, never 0. */
+export interface SystemStatus {
+  contractVersion: string;
+  generatedAt: string;
+  cpu: {
+    cores: number;
+    /** Busy share of all cores over a short sampling window. */
+    usage: number | null;
+    /** Load average over 1, 5 and 15 minutes. */
+    load: Array<number>;
+  };
+  memory: {
+    totalMb: number;
+    /** Total minus what the OS reports free; on macOS that counts the file cache as used. */
+    usedMb: number;
+  };
+  disk: {
+    home: SystemStatusDisk;
+    /** The disk the run logs live on, when it is not the home disk; null when it is the same disk. */
+    logs: SystemStatusDisk;
+  };
+  pipeline: {
+    /** Claude Code processes running. */
+    sessions: number | null;
+    /** multi-agent-toolkit server processes running. */
+    toolkit: number | null;
+    /** Their resident memory together. */
+    rssMb: number | null;
+    /** Size of the run log folder; null when it could not be measured in time. */
+    logsMb: number | null;
+  };
+  /** disk-low: under 10 percent of the home disk is free. cpu-busy: the 5-minute load is above the core count. */
+  warnings: (Array<"disk-low" | "cpu-busy">);
+}
+
+export type SystemStatusDisk = {
+  totalMb: number;
+  freeMb: number;
+} | null;
+
+/** What GET /v1/credentials returns and `office-credentials.mjs --json` prints: for each credential the pipeline knows by logical name, whether the store holds it and, with probe, whether its service accepted it. Never a value: lib/credential-inventory.sh reads each through the store with stdout discarded. Renewal stays in the terminal (/multi-agent:setup). */
+export interface OfficeCredentials {
+  contractVersion: string;
+  generatedAt: string;
+  probed: boolean;
+  /** False when the inventory could not run on this host. */
+  available: boolean;
+  credentials: Array<{
+    logical: string;
+    state: "present" | "mapped-but-missing" | "unmapped";
+    reachability: "not-probed" | "reachable" | "auth-rejected" | "unreachable" | "no-host-configured" | "well-formed" | "not-probeable" | "malformed" | "no-credential" | "probe-error" | "server-error" | "tier-1-ready" | "tier-2-ready" | "tier-1-no-grant" | "unknown";
+    capability: string | null;
+  }>;
+}
+
+/** What GET /v1/memory returns and `office-memory.mjs --json` prints: per repository, the code graph's age and size and how many learnings, past review findings and session notes the learning loop holds, with the newest learnings redacted and cut short. An empty shelf is reported, never left out. */
+export interface OfficeMemory {
+  contractVersion: string;
+  generatedAt: string;
+  shelves: Array<{
+    repo: string;
+    graph: null | {
+      builtAt: string | null;
+      ageDays: number;
+      sizeKb: number;
+    };
+    learnings: number;
+    findings: number;
+    sessionNotes: number;
+    recent: Array<{
+      kind: string | null;
+      statement: string;
+      at: string | null;
+    }>;
+    lastWrite: string | null;
+  }>;
+}
+
+/** What POST /v1/prune-logs returns. The preview (body {olderThanDays}) is prune-logs.sh's dry run for that age with a confirm token; the confirmation (body {confirmToken}) runs it again with the same age and --yes. The audit trail, the metrics corpus and task counters are never removed, and a folder written in the last minutes is spared. */
+export interface PruneLogs {
+  contractVersion: string;
+  olderThanDays: 7 | 30 | 90;
+  applied: boolean;
+  count: number;
+  freedMb: number;
+  /** project/task folders, at most 200 listed. */
+  folders: Array<string>;
+  confirmToken?: string;
+  expiresAt?: string;
+}
+
+/** The body of POST /v1/prune-logs. Step 1 names the age in days (7, 30 or 90); step 2 sends only the confirmToken step 1 returned. */
+export interface PruneLogsRequest {
+  contractVersion: string;
+  olderThanDays?: 7 | 30 | 90;
+  /** The confirmToken the preview returned. Single use, bound to the route. */
+  confirmToken?: string;
+}
+
+/** 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";
+    /** The GitHub login the pull request was listed under, when gh is logged in to more than one account (personal and corporate). Null for Bitbucket. */
+    account?: string | null;
+    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 exact toolkit version the panel starts: the registration's own when it names one, else the version the install recorded from the release. */
+  version?: 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" | "unknown-job" | "command-not-installed" | "invalid-repo" | "invalid-args" | "room-busy" | "sandbox-unavailable" | "launch-failed" | "guard-missing" | "name-taken" | "already-registered" | "not-registered";
   message: string;
   errors?: Array<string>;
   supported?: Array<number>;
   /** What fixes the refusal: for unattended-profile-missing the installer step that writes the unattended permission profile; for workspace-not-trusted opening Claude Code once in the repository to accept the trust prompt (the path is left out under redact). */
   remedy?: string;
 }
+
+/** What GET /v1/settings returns and POST /v1/settings returns after a change: the output language, the fable rung and model routing. A preview (the first POST) adds the change it would make and a confirmToken. */
+export interface OfficeSettings {
+  contractVersion: string;
+  language: "en" | "tr";
+  /** Whether the fable rung is in play. */
+  model: "on" | "off";
+  /** Whether model routing is on. */
+  route: "on" | "off";
+  change?: {
+    setting: "language" | "model" | "route";
+    from: string;
+    to: string;
+    /** Present when turning routing on brings back a saved free provider chain: the confirmation names it. */
+    freeChain?: {
+      enabled: true;
+      allowTraining: boolean;
+    };
+  };
+  confirmToken?: string;
+  expiresAt?: string;
+}
+
+/** The body of POST /v1/settings. Step 1 names the setting and its new value; step 2 sends only the confirmToken step 1 returned. */
+export interface OfficeSettingsRequest {
+  contractVersion: string;
+  setting?: "language" | "model" | "route";
+  value?: "en" | "tr" | "on" | "off";
+  /** The confirmToken the preview returned. Single use, bound to the route. */
+  confirmToken?: string;
+}