@mmerterden/multi-agent-pipeline 20.28.0 → 20.30.0

package/pipeline/schemas/agent-state.schema.json

@@ -38,6 +38,10 @@
       "type": ["string", "null"],
       "description": "The Claude Code session id this run was launched under, copied by Phase 0 from MULTI_AGENT_SESSION_ID when the launcher set it. Continuous mode sets it to the id it passed as --session-id, and matches this field to find ITS run's state rather than another run in the same repo. Absent or null on an attended run: nothing sets the variable there."
     },
+    "hostSessionId": {
+      "type": ["string", "null"],
+      "description": "The host session that made this run's last phase transition: write-state.mjs copies CLAUDE_CODE_SESSION_ID from its environment when a write creates the state or sets currentPhase, and never otherwise, so a second session editing the state (steer) does not take the run over. run-stop-guard.mjs and run-scope-guard.mjs match it against a hook payload's session_id to find the run a hook call belongs to. Absent on a host that sets no such variable."
+    },
     "title": {
       "type": ["string", "null"],
       "description": "The issue title Phase 0 fetched (GitHub title, Jira summary). runs-index.mjs carries it as the run's title; absent when the input was free text or nothing was fetched."
@@ -275,9 +279,16 @@
       }
     },
     "waitingFor": {
-      "type": "string",
-      "enum": ["maturity", "user-channels-choice", "question"],
-      "description": "The step a paused run must RE-ENTER, as opposed to the phase it should continue past. resume reads this first and falls back to currentPhase + 1 when it is absent. maturity: Phase 0's maturity step, with the item re-fetched (refs/features/maturity-followup.md). user-channels-choice: Phase 5's channels menu, with the stored channelsInput. question: the step named by pendingQuestion.stepId, answered by `resume <id> --answer <optionId>`; open-questions-gate.mjs writes it as the last step of Phase 1 with stepId phase-1/open-questions."
+      "type": ["string", "null"],
+      "enum": [
+        "maturity",
+        "user-channels-choice",
+        "local-test",
+        "attended-reply",
+        "question",
+        null
+      ],
+      "description": "The step a paused run must RE-ENTER, as opposed to the phase it should continue past. resume reads this first and falls back to currentPhase + 1 when it is absent or null (null is how a wait is cleared through write-state). maturity: Phase 0's maturity step, with the item re-fetched (refs/features/maturity-followup.md). user-channels-choice: Phase 5's channels menu, with the stored channelsInput. local-test: Phase 3's user-test gate. attended-reply: a typed reply asked for in plain text inside currentPhase; resume re-enters currentPhase and asks again. question: the step named by pendingQuestion.stepId, answered by `resume <id> --answer <optionId>`, and never written without that pendingQuestion; open-questions-gate.mjs writes it as the last step of Phase 1 with stepId phase-1/open-questions. write-state clears every value but question when a write advances currentPhase."
     },
     "workspaceSource": {
       "type": "string",
@@ -497,7 +508,7 @@
     "status": {
       "type": "string",
       "enum": ["in_progress", "awaiting_input", "paused", "complete", "failed", "abandoned"],
-      "description": "Overall task status. `abandoned` is written through the locked state writer by the autopilot runner, for a run its session launched that ended with neither a PR nor a parked question, and by a kill; `abandonedBy` names the writer. `awaiting_input` is deliberately distinct from both `in_progress` and `paused`: the run is not broken and not resumable by a retry - it is finished with what it can do alone and is holding for a human answer, which is what Phase 5 does by design after the PR is open. Without a word for it, a run whose work had landed read exactly like one that crashed mid-development, and a state file in the wild had already invented `awaiting-user-test-main-checkout` to say it. `paused` stays what it was: stopped deliberately, resumable, nothing expected from anyone."
+      "description": "Overall task status. `complete` is earned, not claimed: write-state.mjs refuses a write that moves the run into it unless currentPhase is the mode's last phase and, for a mode that commits, Phase 4 left evidence (commit.sha, pr, publish, projects[].commit, or phases.4 skipped with notes) and gates[] holds a passing plan-coverage verdict (lib/run-completion.mjs); the autopilot runner files a complete state without that evidence as stopped-incomplete. `abandoned` is written through the locked state writer by the autopilot runner, for a run its session launched that ended with neither a PR nor a parked question, and by a kill; `abandonedBy` names the writer. `awaiting_input` is deliberately distinct from both `in_progress` and `paused`: the run is not broken and not resumable by a retry - it is finished with what it can do alone and is holding for a human answer, which is what Phase 5 does by design after the PR is open. Without a word for it, a run whose work had landed read exactly like one that crashed mid-development, and a state file in the wild had already invented `awaiting-user-test-main-checkout` to say it. `paused` stays what it was: stopped deliberately, resumable, nothing expected from anyone."
     },
     "abandonedBy": {
       "type": "string",
@@ -2059,7 +2070,7 @@
     },
     "gates": {
       "type": "array",
-      "description": "Gate ledger, written while the quality gates are active (lib/unattended.mjs gatesActive: MULTI_AGENT_UNATTENDED=1, or state.autopilot true): one entry per verdict, appended by gate-ledger.mjs under the write-state lock. With MULTI_AGENT_UNATTENDED=1 in its environment, pre-commit-check.sh blocks a commit unless the latest entry of every mandatory gate for HEAD is pass or not-applicable. Absent in a run with neither.",
+      "description": "Gate ledger, written while the quality gates are active (lib/unattended.mjs gatesActive: MULTI_AGENT_UNATTENDED=1, or state.autopilot true): one entry per verdict, appended by gate-ledger.mjs under the write-state lock. With MULTI_AGENT_UNATTENDED=1 in its environment, pre-commit-check.sh blocks a commit unless the latest entry of every mandatory gate for HEAD is pass or not-applicable. A run with neither records only the gates in gate-ledger.mjs ATTENDED_RECORDED, each entry marked attended: true, which the unattended commit check never counts.",
       "items": {
         "type": "object",
         "additionalProperties": false,
@@ -2082,6 +2093,10 @@
             "type": ["string", "null"],
             "description": "Repository HEAD the gate ran against."
           },
+          "attended": {
+            "type": "boolean",
+            "description": "True on an entry written while the quality gates were off (an attended run). lib/run-completion.mjs and the attended commit check read it; gate-ledger.mjs checkCommit ignores it."
+          },
           "detail": {
             "type": "object",
             "additionalProperties": true

package/pipeline/schemas/autopilot-on-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/autopilot-on-request.schema.json",
+  "title": "Autopilot on request",
+  "description": "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.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contractVersion"],
+  "properties": {
+    "contractVersion": {
+      "type": "string",
+      "pattern": "^1\\.[0-9]+\\.[0-9]+$",
+      "x-sensitivity": "none"
+    },
+    "repos": {
+      "type": "array",
+      "minItems": 1,
+      "maxItems": 50,
+      "items": {
+        "type": "string",
+        "pattern": "^[A-Za-z0-9._-]{1,100}(/[A-Za-z0-9._-]{1,100})?$"
+      }
+    },
+    "configureOnly": {
+      "type": "boolean",
+      "description": "Save the selection without scheduling anything."
+    },
+    "confirmToken": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]{16,128}$"
+    }
+  }
+}

package/pipeline/schemas/autopilot-on.schema.json

@@ -0,0 +1,111 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/autopilot-on.schema.json",
+  "title": "Autopilot on",
+  "description": "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.",
+  "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": ["keep", "drop", "probe", "configureOnly"],
+      "properties": {
+        "keep": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "drop": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "probe": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["ready", "problems", "warnings"],
+          "properties": {
+            "ready": {
+              "type": "boolean"
+            },
+            "problems": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            },
+            "warnings": {
+              "type": "array",
+              "items": {
+                "type": "string"
+              }
+            }
+          }
+        },
+        "configureOnly": {
+          "type": "boolean"
+        }
+      }
+    },
+    "confirmToken": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9_-]{16,128}$"
+    },
+    "expiresAt": {
+      "type": "string",
+      "format": "date-time"
+    },
+    "enabled": {
+      "type": "boolean"
+    },
+    "scheduled": {
+      "type": "boolean"
+    },
+    "awake": {
+      "type": ["boolean", "null"]
+    },
+    "repos": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "dropped": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "probe": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["ready", "problems", "warnings"],
+      "properties": {
+        "ready": {
+          "type": "boolean"
+        },
+        "problems": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "warnings": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/pipeline/schemas/contract-error.schema.json

@@ -47,13 +47,43 @@
         "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"
       ],
       "x-sensitivity": "none"
     },
-    "message": { "type": "string", "x-sensitivity": "none" },
-    "errors": { "type": "array", "items": { "type": "string" }, "x-sensitivity": "none" },
-    "supported": { "type": "array", "items": { "type": "integer" }, "x-sensitivity": "none" },
+    "message": {
+      "type": "string",
+      "x-sensitivity": "none"
+    },
+    "errors": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      },
+      "x-sensitivity": "none"
+    },
+    "supported": {
+      "type": "array",
+      "items": {
+        "type": "integer"
+      },
+      "x-sensitivity": "none"
+    },
     "remedy": {
       "type": "string",
       "x-sensitivity": "none",

package/pipeline/schemas/issue-maturity.schema.json

@@ -0,0 +1,68 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/issue-maturity.schema.json",
+  "title": "Issue maturity",
+  "description": "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.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "contractVersion",
+    "key",
+    "kind",
+    "title",
+    "type",
+    "status",
+    "maturity",
+    "description"
+  ],
+  "properties": {
+    "contractVersion": {
+      "type": "string",
+      "pattern": "^1\\.[0-9]+\\.[0-9]+$",
+      "x-sensitivity": "none"
+    },
+    "key": {
+      "type": "string"
+    },
+    "kind": {
+      "enum": ["jira", "github", "freetext"]
+    },
+    "title": {
+      "type": "string"
+    },
+    "type": {
+      "type": ["string", "null"]
+    },
+    "status": {
+      "type": ["string", "null"]
+    },
+    "maturity": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["score", "blockers", "warnings", "summary"],
+      "properties": {
+        "score": {
+          "type": ["number", "null"]
+        },
+        "blockers": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "warnings": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        },
+        "summary": {
+          "type": ["string", "null"]
+        }
+      }
+    },
+    "description": {
+      "type": ["string", "null"]
+    }
+  }
+}

package/pipeline/schemas/ledger.schema.json

@@ -0,0 +1,202 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/ledger.schema.json",
+  "title": "Office ledger",
+  "description": "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.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contractVersion", "generatedAt", "prices", "windows"],
+  "properties": {
+    "contractVersion": {
+      "type": "string",
+      "pattern": "^1\\.[0-9]+\\.[0-9]+$",
+      "x-sensitivity": "none"
+    },
+    "generatedAt": {
+      "type": "string",
+      "format": "date-time",
+      "x-sensitivity": "none"
+    },
+    "prices": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["table", "verifiedAt", "ageDays", "stale", "warning"],
+      "x-sensitivity": "none",
+      "properties": {
+        "table": {
+          "const": "cost-table.json"
+        },
+        "verifiedAt": {
+          "type": ["string", "null"]
+        },
+        "ageDays": {
+          "type": ["integer", "null"]
+        },
+        "stale": {
+          "type": "boolean"
+        },
+        "warning": {
+          "type": ["string", "null"]
+        }
+      }
+    },
+    "windows": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["today", "week", "month"],
+      "x-sensitivity": "none",
+      "properties": {
+        "today": {
+          "$ref": "#/$defs/window"
+        },
+        "week": {
+          "$ref": "#/$defs/window"
+        },
+        "month": {
+          "$ref": "#/$defs/window"
+        }
+      }
+    }
+  },
+  "$defs": {
+    "source": {
+      "enum": ["tracker-state", "transcript", "mixed", "not-measured"],
+      "description": "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."
+    },
+    "tokens": {
+      "oneOf": [
+        {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["in", "out", "cacheRead", "cacheWrite"],
+          "properties": {
+            "in": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "out": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "cacheRead": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "cacheWrite": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        },
+        {
+          "type": "null"
+        }
+      ]
+    },
+    "amount": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["tokens", "usd", "source", "unpriced"],
+      "properties": {
+        "tokens": {
+          "$ref": "#/$defs/tokens"
+        },
+        "usd": {
+          "type": ["number", "null"]
+        },
+        "source": {
+          "$ref": "#/$defs/source"
+        },
+        "unpriced": {
+          "type": "integer",
+          "minimum": 0,
+          "description": "Usage records whose model has no price; their tokens are counted, their cost is not."
+        }
+      }
+    },
+    "row": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["key", "tokens", "usd", "source", "unpriced"],
+      "properties": {
+        "key": {
+          "type": "string"
+        },
+        "repo": {
+          "type": ["string", "null"],
+          "description": "On byRun rows: the run repository."
+        },
+        "tokens": {
+          "$ref": "#/$defs/tokens"
+        },
+        "usd": {
+          "type": ["number", "null"]
+        },
+        "source": {
+          "$ref": "#/$defs/source"
+        },
+        "unpriced": {
+          "type": "integer",
+          "minimum": 0
+        }
+      }
+    },
+    "window": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "since",
+        "total",
+        "outsidePipeline",
+        "notMeasured",
+        "byRun",
+        "byRepo",
+        "byModel",
+        "byPhase"
+      ],
+      "properties": {
+        "since": {
+          "type": "string",
+          "format": "date-time"
+        },
+        "total": {
+          "$ref": "#/$defs/amount"
+        },
+        "outsidePipeline": {
+          "$ref": "#/$defs/amount"
+        },
+        "notMeasured": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          },
+          "description": "Task ids of runs active in the window whose cost could not be measured."
+        },
+        "byRun": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/row"
+          }
+        },
+        "byRepo": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/row"
+          }
+        },
+        "byModel": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/row"
+          }
+        },
+        "byPhase": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/row"
+          }
+        }
+      }
+    }
+  }
+}

package/pipeline/schemas/permissions.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/permissions.schema.json",
+  "title": "Pending permission prompts",
+  "description": "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.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["contractVersion", "available", "reason", "requests"],
+  "properties": {
+    "contractVersion": {
+      "type": "string",
+      "pattern": "^1\\.[0-9]+\\.[0-9]+$",
+      "x-sensitivity": "none"
+    },
+    "available": {
+      "type": "boolean"
+    },
+    "reason": {
+      "type": ["string", "null"]
+    },
+    "requests": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["id", "sessionId", "tool", "summary", "at"],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "sessionId": {
+            "type": "string"
+          },
+          "tool": {
+            "type": "string"
+          },
+          "summary": {
+            "type": "string"
+          },
+          "at": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  }
+}

package/pipeline/schemas/phases.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://github.com/mmerterden/multi-agent-pipeline/pipeline/schemas/phases.json",
-  "description": "The phase contract, in one place: the phase ids and names, which phases each mode runs, the per-phase token ceilings and the phase numbers other code compares against. gen-mode-dispatch.mjs, render-work-summary.sh, the autopilot runner, runs-index.mjs, usage-report.mjs and gen-facts.mjs read it; smoke-phase-contract.sh holds every copy that cannot read it (the phase docs and prose counts, agent-state.schema.json, token-budget.json, phase-tracker.sh, phase-banner.sh, gc-abandoned.sh) to it. Adding or merging a phase means editing here. Ceilings are measured against the current phase documents, never summed from earlier ones: smoke-token-budget.sh fails a ceiling more than 25% above the measurement.",
+  "description": "The phase contract, in one place: the phase ids and names, which phases each mode runs, the per-phase token ceilings and the phase numbers other code compares against. gen-mode-dispatch.mjs, render-work-summary.sh, the autopilot runner, runs-index.mjs, usage-report.mjs and gen-facts.mjs read it; smoke-phase-contract.sh holds every copy that cannot read it (the phase docs and prose counts, agent-state.schema.json, token-budget.json, phase-tracker.sh, phase-banner.sh, gc-abandoned.sh) to it. Adding or merging a phase means editing here. A mode with `commits: false` delivers no commit in its Phase 4 (analysis publishes a document), so lib/run-completion.mjs asks it for no commit evidence before `status: complete`; any other mode commits. Ceilings are measured against the current phase documents, never summed from earlier ones: smoke-token-budget.sh fails a ceiling more than 25% above the measurement.",
   "contractVersion": "2.0.0",
   "phaseSchema": 2,
   "phaseSchemaNote": "The phase vocabulary generation. metrics.jsonl is append-only and v19.0.0 renumbered the phases, so every line written from v19.0.0 on carries this number and a line without the field is generation 1. Aggregators pick their name table from it; without it phase 3 means Dev in old rows and Review in new ones and no reader can tell them apart.",
@@ -72,7 +72,8 @@
     },
     "analysis": {
       "phases": [0, 1, 3, 4, 5],
-      "autopilot": false
+      "autopilot": false,
+      "commits": false
     }
   },
   "thresholds": {

package/pipeline/schemas/phases.schema.json

@@ -50,7 +50,11 @@
             "items": { "type": "integer", "minimum": 0 },
             "uniqueItems": true
           },
-          "autopilot": { "type": "boolean" }
+          "autopilot": { "type": "boolean" },
+          "commits": {
+            "type": "boolean",
+            "description": "false when the mode delivers no commit in its Phase 4; lib/run-completion.mjs then asks for no commit evidence before status complete. Absent means the mode commits."
+          }
         }
       }
     },