@zhixuan92/multi-model-agent 4.5.4 → 4.7.0

package/dist/skills/mma-investigate/SKILL.md

@@ -12,7 +12,7 @@ when_to_use: >-
   git-history queries. OR you are about to read 3+ files / run any grep in main
   context — that's the inline-labor-leakage anti-pattern (AP2); delegate to this
   skill instead.
-version: 4.5.4
+version: 4.7.0
 ---
 
 # mma-investigate
@@ -88,7 +88,7 @@ digraph when_to_use {
 ❌ `{ "question": "Where is parseConfig called?" }` — searches the whole repo
 ✅ `{ "question": "Where is parseConfig called?", "filePaths": ["src/"] }` — bounded
 
-**Why:** the worker greps and reads under its cost ceiling. Without anchors, broad questions exhaust the budget before they finish.
+**Why:** the worker greps and reads under a turn and wall-clock budget. Without anchors, broad questions exhaust those budgets before they finish.
 
 ## Full example
 
@@ -127,43 +127,70 @@ Each task carries an `investigation` field on its per-task report:
 }
 ```
 
-`workerStatus` is one of `done`, `done_with_concerns`, `needs_context`, `blocked`. When `done_with_concerns`, the per-task report carries `incompleteReason` (`turn_cap`, `cost_cap`, `timeout`, or `missing_sections`). When `needs_context`, the worker flagged a `[needs_context]` bullet under `## Unresolved` — re-dispatch with extra context (anchor paths or a context block).
+The authoritative success signals are `completed`, `message`, and `findings`. See "v5 wire shape" above for the full envelope.
 
-## Reading the findings (3.10.5+)
+## v5 wire shape (read route)
 
-The terminal envelope's `results[N].annotatedFindings` is a list of structured
-findings the reviewer extracted and scored from the implementer's narrative.
-Every finding has the same shape:
+Every task result is a `ComposePayload` — seven main-agent fields plus a telemetry block.
+The main-agent fields are authoritative; the telemetry block is diagnostics.
 
-| Field | Type | Notes |
+```json
+{
+  "completed": true,
+  "message": "Investigation complete; 3 files analysed.",
+  "findings": [
+    {
+      "id": "F1",
+      "severity": "high",
+      "category": "correctness",
+      "claim": "The refresh handler reads bearer from Authorization header unconditionally.",
+      "evidence": "src/auth/refresh.ts:45-72 — verbatim substring from worker output.",
+      "suggestion": "Add a guard to handle missing Authorization header gracefully.",
+      "source": "implementer"
+    }
+  ],
+  "summary": "...",
+  "filesChanged": [],
+  "commitSha": null,
+  "blockId": null,
+  "telemetry": {
+    "totalDurationMs": 1234,
+    "totalCostUSD": 0.08,
+    "workerSelfAssessment": "done",
+    "reviewVerdict": null,
+    "commitOutcome": "not_applicable",
+    "stopReason": "normal",
+    "haltedStage": null,
+    "stages": [...]
+  }
+}
+```
+
+### Key fields
+
+| Field | When populated | Notes |
 |---|---|---|
-| `id` | string | Reviewer-assigned, e.g. `F1`, `F2`. |
-| `severity` | `'critical' \| 'high' \| 'medium' \| 'low'` | 4-tier. |
-| `claim` | string | One-sentence summary. |
-| `evidence` | string ≥20 chars | Quoted from worker output when grounded. |
-| `suggestion?` | string | Optional fix recommendation. |
-| `annotatorConfidence` | `number \| null` | 0–100 from the reviewer; `null` when emitted via deterministic fallback. |
-| `evidenceGrounded` | boolean | True when `evidence` is a verbatim substring of worker output. |
-
-### Verdict states (`qualityReviewVerdict`)
-
-- `'annotated'` — every finding is structured. May be reviewer-emitted (with
-  numeric `annotatorConfidence`) or deterministic-fallback (with
-  `annotatorConfidence: null`). The route ALWAYS reaches `'annotated'` unless
-  the reviewer call itself fails transport.
-- `'error'` — only when the reviewer call fails transport (network / 5xx).
-
-### Recommended rendering by the main agent
-
-1. Show ALL findings — never silently drop. Confidence and grounding are
-   soft signals, not gates.
-2. Default sort: severity (critical → low) then `annotatorConfidence` desc
-   (nulls last).
-3. `severity` is the reviewer's authoritative final value — use it directly.
-4. Mark findings with `evidenceGrounded: false` or
-   `annotatorConfidence < 70` as "lower-trust" (collapsed section, lighter
-   color, or `(low confidence)` annotation). User decides what to do.
-5. Severity-tier counts feed the dashboard via V3 `findingsBySeverity`.
+| `completed` | always | `true` when at least one criterion succeeded; `false` on annotator transport failure OR unmet annotate preconditions (e.g. non-`done` worker self-assessment on a read route) |
+| `message` | always | human-readable summary; names blocking gates or finding IDs on failure |
+| `findings` | always | `source: 'implementer'` for investigate; findings are the deliverable on read routes |
+| `workerSelfAssessment` | always | `'done'` or `'failed'` — never `done_with_concerns` |
+| `blockId` | always `null` | investigate is a task route, not register-context-block |
+
+### No second review
+
+The LLM-judge stage (`annotate`) runs once, after the worker's output. Its preconditions for read-route `completed: true`:
+
+```
+gates.implement.outcome === 'advance'
+&& gates.implement.payload.workerSelfAssessment === 'done'
+&& (criteriaSucceeded.length > 0 || criteriaErrors.length === 0)
+```
+
+Findings are the deliverable — a task that surfaces 5 issues is `completed: true`. Finding nothing wrong is also a valid completion.
+
+### `completed: false` — what it means
+
+Only on annotator transport failure. The `message` names the blocking gate. Re-dispatch with tighter `filePaths` if the worker's citations were unusable.
 
 ## Best practices
 
@@ -180,15 +207,12 @@ Anti-pattern alert: **`inline-labor-leakage`** (AP2). If you find yourself readi
 
 The investigator can't write — `tools: 'readonly'`. **Fix:** use `mma-delegate` for research-then-edit, or split: investigate first, then dispatch the edit.
 
-❌ **Treating `done_with_concerns` as failure**
-The worker still produced citations and a confidence level. Read them — partial coverage with `incompleteReason: 'turn_cap'` often answers the question well enough. Re-dispatch with a tighter scope only if the citations are unusable.
-
 ❌ **Inline-reading instead of delegating**
 About to `Read` 3+ files just to answer one question? That's the wrong tradeoff — the worker reads on its cheap budget; you read its synthesis on yours.
 
 ## Terminal context block
 
-Every completed task automatically registers a terminal markdown context block containing the full task report (headline, investigation synthesis, citations, and annotated findings). The `blockId` is returned in each task result as `terminalBlockId`. This block is immutable, lives for the session duration, and counts against the project's `maxEntries` quota (default 500).
+Every completed task automatically registers a terminal markdown context block containing the full task report (headline, investigation synthesis, citations, and annotated findings). The `blockId` is returned in each task result under the shared `blockId` field (not a separate `terminalBlockId` field). This block is immutable, lives for the session duration, and counts against the project's `maxEntries` quota (default 500).
 
 **Use cases:**
 - Pass investigation results to a downstream planning step

package/dist/skills/mma-research/SKILL.md

@@ -10,7 +10,7 @@ when_to_use: >-
   others do, what published methods exist) AND mmagent is running. Delegate the
   multi-source web/adapter research to a worker so the main context stays on
   judgment. NOT for codebase questions — those are mma-investigate.
-version: 4.5.4
+version: 4.7.0
 ---
 
 # mma-research
@@ -89,10 +89,59 @@ BATCH_ID=$(echo "$BATCH" | jq -r '.batchId')
 
 @include _shared/response-shape.md
 
-## Per-task report shape
+## Per-task report shape (v5 envelope)
+
+Each `results[N]` is the v5 `ComposePayload`:
+
+```json
+{
+  "completed": true,
+  "message": "Research complete; 4 sources synthesised.",
+  "findings": [
+    {
+      "id": "F1",
+      "severity": "medium",
+      "category": "evidence",
+      "claim": "Pattern X is the canonical approach as of 2026 per upstream RFC.",
+      "evidence": "https://example.org/rfc/...",
+      "source": "implementer"
+    }
+  ],
+  "summary": "Pattern X dominates; pattern Y is a 2024 fork.",
+  "filesChanged": [],
+  "commitSha": null,
+  "blockId": null,
+  "telemetry": {
+    "totalDurationMs": 12400,
+    "totalCostUSD": 0.06,
+    "workerSelfAssessment": "done",
+    "reviewVerdict": null,
+    "commitOutcome": "not_applicable",
+    "stopReason": "normal",
+    "haltedStage": null,
+    "stages": [
+      { "name": "prepare",    "outcome": "advance" },
+      { "name": "implement",  "outcome": "advance" },
+      { "name": "annotate",   "outcome": "advance" },
+      { "name": "compose",    "outcome": "advance" },
+      { "name": "terminal",   "outcome": "advance" }
+    ]
+  }
+}
+```
+
+| Field | Notes |
+|---|---|
+| `completed: true` | At least one criterion succeeded; sources synthesised. |
+| `completed: false` | Annotator transport failure OR worker self-assessed as `failed`. `message` names the blocking gate. |
+| `findings` | The deliverable. `source: 'implementer'`. Empty `findings` on a research route means "no signal found" — still a valid completion. |
+| `workerSelfAssessment` | `'done'` or `'failed'` — never `done_with_concerns`. |
+| `blockId` | Always `null` — research is a task route, not register-context-block. |
+
+Legacy aliases (still emitted for back-compat):
 
 ```
-results[0].structuredReport.findings[]    // numbered findings with citations
+results[0].structuredReport.findings[]    // mirror of findings above
 results[0].structuredReport.sourcesUsed[] // table of sources tried
 results[0].output                          // raw narrative report
 ```

package/dist/skills/mma-retry/SKILL.md

@@ -10,7 +10,7 @@ when_to_use: >-
   re-try the failed indices only. Prefer this over re-dispatching the whole
   batch or inline-retrying — it's idempotent and preserves the original batch's
   diagnostics.
-version: 4.5.4
+version: 4.7.0
 ---
 
 # mma-retry
@@ -41,7 +41,7 @@ digraph when_to_use {
 ```
 
 **Use when:**
-- A previous batch's terminal envelope shows mixed `done` / `done_with_concerns` / `failed`
+- A previous batch's terminal envelope shows mixed `completed: true` / `completed: false`
 - 1–N tasks (but not all) need a re-run with the same config
 - You want to keep the original batch's diagnostics intact for comparison
 
@@ -88,7 +88,106 @@ BATCH_ID=$(echo "$BATCH" | jq -r '.batchId')   # NEW batchId — not the origina
 
 @include _shared/polling.md
 
-@include _shared/response-shape.md
+## Response shapes
+
+### POST /retry?cwd=<abs> — dispatch response (202)
+
+```json
+{ "batchId": "<uuid>", "statusUrl": "/batch/<uuid>" }
+```
+
+Use `batchId` to poll. `statusUrl` is a convenience pointer. **This is a new batchId** — polling the original batch returns its terminal state.
+
+### GET /batch/:id — polling response
+
+The HTTP status is the state discriminator:
+
+| Status | Meaning |
+|---|---|
+| `202 text/plain` | Still pending — body is the running headline string |
+| `200 application/json` | Terminal — body is the batch envelope below |
+| `404` / `401` / `5xx` | Error — see Error response below; stop polling |
+
+### GET /batch/:id?taskIndex=N — single task slice
+
+Same envelope. `results` contains exactly the task at index `N`. Returns `404 unknown_task_index` if `N` is out of range.
+
+### Reading the task result
+
+Each task result is the per-task wire object (`ComposePayload`):
+
+```json
+{
+  "completed": true,
+  "message": "Task completed; tests passed; one file changed.",
+  "findings": [
+    {
+      "id": "F1",
+      "severity": "high",
+      "category": "correctness",
+      "claim": "The function does not handle empty input",
+      "evidence": "function foo() { ... } // no null check",
+      "suggestion": "Add an explicit null guard at the top",
+      "source": "reviewer"
+    }
+  ],
+  "summary": "Refactored utils.ts — removed 3 dead branches, added JSDoc",
+  "filesChanged": ["/project/src/utils.ts"],
+  "commitSha": "abc123def",
+  "blockId": null,
+  "telemetry": {
+    "totalDurationMs": 12400,
+    "totalCostUSD": 0.08,
+    "workerSelfAssessment": "done",
+    "reviewVerdict": "approved",
+    "commitOutcome": "committed",
+    "stopReason": "normal",
+    "haltedStage": null,
+    "stages": [
+      { "name": "prepare",        "outcome": "advance", "durationMs": 2,    "costUSD": 0 },
+      { "name": "register-block", "outcome": "skip",    "comment": "register-block does not apply to route=delegate", "durationMs": 0, "costUSD": 0 },
+      { "name": "implement",      "outcome": "advance", "durationMs": 8900, "costUSD": 0.05 },
+      { "name": "review",         "outcome": "advance", "durationMs": 2100, "costUSD": 0.02 },
+      { "name": "rework",         "outcome": "skip",    "comment": "rework skipped because review approved", "durationMs": 0, "costUSD": 0 },
+      { "name": "commit",         "outcome": "advance", "durationMs": 340,  "costUSD": 0 },
+      { "name": "annotate",       "outcome": "advance", "durationMs": 890,  "costUSD": 0.01 },
+      { "name": "compose",        "outcome": "advance", "durationMs": 68,   "costUSD": 0 },
+      { "name": "terminal",       "outcome": "advance", "durationMs": 100,  "costUSD": 0 }
+    ]
+  }
+}
+```
+
+**Top-level fields to read for the main-agent verdict:**
+
+| Field | When `true` / populated |
+|---|---|
+| `completed: true` | Task succeeded. `message` is the summary; `findings` are post-review issues (if any). |
+| `completed: false` | Task did not complete. `message` names the blocking gate or finding; `findings` carry any discovered issues. |
+| `findings` | Issues surfaced by the worker or reviewer. `severity` = `critical` \| `high` \| `medium` \| `low`. `source` = `implementer` \| `reviewer`. |
+| `filesChanged` | File paths modified (empty for read-only routes). |
+| `commitSha` | Git SHA of the committed diff; `null` for read-only routes or when commit was skipped. |
+| `blockId` | `terminalBlockId` — pass to `contextBlockIds` in a follow-up task to chain results without re-inlining. |
+
+**The stages array** (always 9 rows) is the canonical telemetry log. `outcome` is one of:
+- `advance` — stage ran and produced its payload
+- `skip` — stage did not run; `comment` explains why
+- `halt` — stage stopped the chain; `comment` is the failure message
+- `not_run` — stage was not reached because a prior stage halted
+
+Use `telemetry.haltedStage` to find the first halt; `telemetry.stopReason` to find why.
+
+### Error response (4xx / 5xx)
+
+```json
+{
+  "error": "<code>",
+  "message": "<human-readable>",
+  "details": { /* optional structured context, e.g. fieldErrors for 400 */ }
+}
+```
+
+`details` is optional and present only when the server has structured additional context.
 
 ## Best practices
 

package/dist/skills/mma-review/SKILL.md

@@ -10,7 +10,7 @@ when_to_use: >-
   AND mmagent is running. Delegate so each file reviews on its own worker; the
   main agent only decides what to merge. Review on SOURCE CODE — use mma-audit
   for prose specs / configs.
-version: 4.5.4
+version: 4.7.0
 ---
 
 # mma-review
@@ -90,43 +90,54 @@ BATCH_ID=$(echo "$BATCH" | jq -r '.batchId')
 
 @include _shared/response-shape.md
 
-## Reading the findings (3.10.5+)
+## Reading the findings
 
-The terminal envelope's `results[N].annotatedFindings` is a list of structured
-findings the reviewer extracted and scored from the implementer's narrative.
-Every finding has the same shape:
+The main agent reads `completed` + `message` + `findings` — the findings are the answer. For
+read-only routes, `filesChanged` is always `[]` and `commitSha` is always `null`.
+
+```json
+{
+  "completed": true,
+  "message": "Review complete; 3 findings.",
+  "findings": [
+    { "id": "F1", "severity": "critical", "category": "test-gap",
+      "claim": "login.ts has no test for null username edge case.",
+      "evidence": "Worker read login.ts and grepped for test files — no null-case test found.",
+      "suggestion": "Add test case: `login(null) throws ValidationError`.",
+      "source": "reviewer" }
+  ],
+  "filesChanged": [],
+  "commitSha": null,
+  "summary": "...",
+  "telemetry": { ... }
+}
+```
+
+### Finding shape
+
+Every finding has this shape:
 
 | Field | Type | Notes |
 |---|---|---|
-| `id` | string | Reviewer-assigned, e.g. `F1`, `F2`. |
+| `id` | string | Worker-assigned, e.g. `F1`, `F2`. Stable across chain. |
 | `severity` | `'critical' \| 'high' \| 'medium' \| 'low'` | 4-tier. |
+| `category` | string | Topical bucket, e.g. `test-gap`, `cross-file-ripple`. |
 | `claim` | string | One-sentence summary. |
-| `evidence` | string ≥20 chars | Quoted from worker output when grounded. |
+| `evidence` | string ≥20 chars | Verbatim from source when grounded. |
 | `suggestion?` | string | Optional fix recommendation. |
-| `annotatorConfidence` | `number \| null` | 0–100 from the reviewer; `null` when emitted via deterministic fallback. |
-| `evidenceGrounded` | boolean | True when `evidence` is a verbatim substring of worker output. |
-
-### Verdict states (`qualityReviewVerdict`)
+| `source` | `'implementer' \| 'reviewer'` | Who produced the finding. |
 
-- `'annotated'` — every finding is structured. May be reviewer-emitted (with
-  numeric `annotatorConfidence`) or deterministic-fallback (with
-  `annotatorConfidence: null`). The route ALWAYS reaches `'annotated'` unless
-  the reviewer call itself fails transport.
-- `'error'` — only when the reviewer call fails transport (network / 5xx).
+`annotatorConfidence` and `evidenceGrounded` are retired — they were v4 fields with no producers.
 
 ### Recommended rendering by the main agent
 
-1. Show ALL findings — never silently drop. Confidence and grounding are
-   soft signals, not gates.
-2. Default sort: severity (critical → low) then `annotatorConfidence` desc
-   (nulls last).
-3. `severity` is the reviewer's authoritative final value — use it directly.
-4. Mark findings with `evidenceGrounded: false` or
-   `annotatorConfidence < 70` as "lower-trust" (collapsed section, lighter
-   color, or `(low confidence)` annotation). User decides what to do.
-5. Severity-tier counts feed the dashboard via V3 `findingsBySeverity`.
-
-@include _shared/budget-defaults.md
+1. Show ALL findings — never silently drop. Severity and grounding are soft
+   signals, not gates.
+2. Default sort: severity (critical → low), then `id` ascending.
+3. `severity` is the authoritative value — use it directly.
+4. Mark findings with `evidence` shorter than 30 chars as "low-evidence"
+   (lighter color or `(low evidence)` annotation). User decides what to do.
+5. Severity-tier counts feed the dashboard.
 
 ## Best practices
 

package/dist/skills/multi-model-agent/SKILL.md

@@ -11,7 +11,7 @@ when_to_use: >-
   tasks — AND mmagent is running. Read this once, pick the matching mma-* skill,
   and delegate there. Applies equally whether the user invoked a superpowers
   methodology skill or asked directly.
-version: 4.5.4
+version: 4.7.0
 ---
 
 # multi-model-agent (router)
@@ -153,7 +153,7 @@ Every request requires `Authorization: Bearer $MMAGENT_AUTH_TOKEN`. The token ro
 Only `mma-delegate` accepts `agentType: "standard" | "complex"` per task — default `"standard"` (cheaper, faster). Pick `"complex"` when:
 
 - The task touches many files or requires multi-step reasoning a standard-tier model cannot hold in context.
-- A prior standard run came back with `filesWritten: 0` or `incompleteReason: "turn_cap"` / `"cost_cap"` / `"timeout"`.
+- A prior standard run came back with `filesWritten: 0` or `incompleteReason: "turn_cap"` / `"timeout"`.
 - The task is security-sensitive or ambiguous enough that being wrong is costly.
 
 Every other route hardcodes its tier and rejects `agentType` with HTTP 400:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhixuan92/multi-model-agent",
-  "version": "4.5.4",
+  "version": "4.7.0",
   "type": "module",
   "license": "MIT",
   "description": "Standalone HTTP server for multi-model-agent. Routes tool-invocation work to Claude, Codex, or OpenAI-compatible sub-agents with async-polling REST dispatch and installable skills for Claude Code, Gemini CLI, Codex CLI, and Cursor.",
@@ -53,7 +53,7 @@
   },
   "dependencies": {
     "@asteasolutions/zod-to-openapi": "^8.5.0",
-    "@zhixuan92/multi-model-agent-core": "^4.5.4",
+    "@zhixuan92/multi-model-agent-core": "^4.7.0",
     "gray-matter": "^4.0.3",
     "minimist": "^1.2.8",
     "proper-lockfile": "^4.1.2",

package/dist/http/middleware/body-size.d.ts

@@ -1,7 +0,0 @@
-export declare const COMPRESSED_BODY_LIMIT_BYTES: number;
-/** Decompressed body cap — 2 MiB. Enforced by the decompress middleware. */
-export declare const DECOMPRESSED_BODY_LIMIT_BYTES: number;
-export declare function buildServerOpts(): {
-    bodyLimit: number;
-};
-//# sourceMappingURL=body-size.d.ts.map

package/dist/http/middleware/body-size.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"body-size.d.ts","sourceRoot":"","sources":["../../../src/http/middleware/body-size.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,2BAA2B,QAAa,CAAC;AAEtD,4EAA4E;AAC5E,eAAO,MAAM,6BAA6B,QAAkB,CAAC;AAE7D,wBAAgB,eAAe;;EAE9B"}

package/dist/http/middleware/body-size.js

@@ -1,7 +0,0 @@
-export const COMPRESSED_BODY_LIMIT_BYTES = 256 * 1024; // 256 KiB
-/** Decompressed body cap — 2 MiB. Enforced by the decompress middleware. */
-export const DECOMPRESSED_BODY_LIMIT_BYTES = 2 * 1024 * 1024; // 2 MiB
-export function buildServerOpts() {
-    return { bodyLimit: COMPRESSED_BODY_LIMIT_BYTES };
-}
-//# sourceMappingURL=body-size.js.map

package/dist/http/middleware/body-size.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"body-size.js","sourceRoot":"","sources":["../../../src/http/middleware/body-size.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,2BAA2B,GAAG,GAAG,GAAG,IAAI,CAAC,CAAC,UAAU;AAEjE,4EAA4E;AAC5E,MAAM,CAAC,MAAM,6BAA6B,GAAG,CAAC,GAAG,IAAI,GAAG,IAAI,CAAC,CAAC,QAAQ;AAEtE,MAAM,UAAU,eAAe;IAC7B,OAAO,EAAE,SAAS,EAAE,2BAA2B,EAAE,CAAC;AACpD,CAAC"}

package/dist/skills/_shared/budget-defaults.md

@@ -1,13 +0,0 @@
-## Budget defaults
-
-| Constant | Value | Notes |
-|---|---|---|
-| Task timeout | 1 h (3,600,000 ms) | Wall-clock cap per task |
-| Stall timeout | 20 min (1,200,000 ms) | Idle gap before force-abort |
-| Max cost | $10 USD | Per-task cost cap |
-| Cost pre-stop ratio | 0.80 | Pre-stop threshold; see cushion semantics below |
-| Time pre-stop ratio | 0.80 | Same pre-stop for timeouts |
-
-**Cushion semantics:** `MAX_COST_PRESTOP_RATIO` and `MAX_TIME_PRESTOP_RATIO` are *pre-stop thresholds*, not overshoot allowances. The runtime warns and may refuse new turns when cost reaches `DEFAULT_MAX_COST_USD × MAX_COST_PRESTOP_RATIO` ($8), but allows an already-in-flight turn to complete. The worst-case total is therefore `DEFAULT_MAX_COST_USD / MAX_COST_PRESTOP_RATIO` ($12.50). Same logic applies to time: worst-case = `DEFAULT_TASK_TIMEOUT_MS / MAX_TIME_PRESTOP_RATIO` (1.25 h).
-
-Callers can override `maxCostUSD` per task. Timeouts are config-wide defaults set in the server config file.