@zhixuan92/multi-model-agent 3.0.1 → 3.1.0

package/dist/skills/_shared/polling.md

@@ -3,38 +3,65 @@
 After a tool call returns a `batchId`, poll `GET /batch/:id` until the batch
 reaches a terminal state.
 
-### Terminal states
+### HTTP response shapes (3.1.0)
 
-| State | Meaning |
-|---|---|
-| `complete` | All tasks finished — read results |
-| `failed` | Batch failed — read error details |
-| `expired` | Batch TTL exceeded — retry if needed |
+| Status | Content-Type | Meaning |
+|---|---|---|
+| `202` | `text/plain` | Still working — body is the running headline (e.g. `1/1 running, 47s elapsed`) |
+| `200` | `application/json` | Terminal — body is the uniform 7-field envelope (see `response-shape.md`) |
+| `404` / `401` / other | — | Error — stop polling |
+
+### Terminal envelope states
 
-### Awaiting clarification
+Every terminal envelope has the same seven fields; inspect these to tell
+which terminal state you're in:
 
-If `GET /batch/:id` returns `state: 'awaiting_clarification'`, the service
-needs your confirmation before it can continue. Read `proposedInterpretation`
-from the response, then call `POST /clarifications/confirm` with your chosen
-`interpretation` (accept or correct the proposal).
+| Shape | Meaning |
+|---|---|
+| `error` is a real object | Batch failed — read `error.code` + `error.message` |
+| `proposedInterpretation` is a string | Batch is awaiting clarification — invoke `mma-clarifications` |
+| Both are `{kind: "not_applicable", ...}` | Batch succeeded — read `results` |
 
-### Poll loop (shell)
+### Poll loop (POSIX sh)
 
 ```bash
 DELAY=1
+START=$(date +%s)
+TIMEOUT_S=${MMAGENT_POLL_TIMEOUT_S:-1800}
+BODY_FILE=$(mktemp -t mmagent-poll.XXXXXX)
+trap 'rm -f "$BODY_FILE"' EXIT
+
 while true; do
-  RESP=$(curl -sf -H "Authorization: Bearer $TOKEN" \
-    "http://localhost:$PORT/batch/$BATCH_ID")
-  STATE=$(echo "$RESP" | jq -r '.state')
-  case "$STATE" in
-    complete|failed|expired) echo "$RESP"; break ;;
-    awaiting_clarification)
-      # Invoke mma-clarifications to confirm interpretation, then continue
-      break ;;
-    *) sleep $DELAY; DELAY=$(( DELAY < 5 ? DELAY * 2 : 5 )) ;;
+  NOW=$(date +%s)
+  if [ $((NOW - START)) -ge "$TIMEOUT_S" ]; then
+    echo "mmagent: poll timed out after ${TIMEOUT_S}s" >&2
+    exit 124
+  fi
+
+  STATUS=$(curl -f --show-error -o "$BODY_FILE" -w "%{http_code}" -s \
+    -H "Authorization: Bearer $TOKEN" \
+    "http://127.0.0.1:$PORT/batch/$BATCH_ID" || true)
+
+  case "$STATUS" in
+    202)
+      cat "$BODY_FILE"; echo
+      sleep "$DELAY"
+      DELAY=$(( DELAY < 30 ? DELAY * 2 : 30 ))
+      ;;
+    200)
+      cat "$BODY_FILE"
+      exit 0
+      ;;
+    "")
+      echo "mmagent: unreachable (curl failed)" >&2; exit 1 ;;
+    *)
+      echo "mmagent: HTTP $STATUS"; cat "$BODY_FILE" >&2; exit 1 ;;
   esac
 done
 ```
 
-Start at 1 s, double each iteration, cap at 5 s. Most batches complete in
-under 60 s; long tasks may take several minutes.
+Start at 1 s, double each iteration, cap at 30 s. The 1800-second client-side
+timeout is a safety cap; most batches complete in under 60 s. Discover `$PORT`
+at runtime with `mmagent info --json | jq -r .port` (default: 7337).
+
+Windows/PowerShell equivalent is planned for a later release.

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

@@ -1,7 +1,16 @@
 ---
 name: mma-audit
-description: Audit a document for security, performance, correctness, or style issues. Sub-agents run in parallel per file.
-when_to_use: When you need to audit a spec, design doc, or configuration file for correctness, security, style, or performance issues.
+description: >-
+  Audit a document, spec, or config for security, performance, correctness, or
+  style issues via the local mmagent HTTP service. Sub-agents run in parallel
+  per file — no context pollution in the main model.
+when_to_use: >-
+  The user asks to audit a document, spec, or config (for security, correctness,
+  performance, or style) OR a methodology skill
+  (superpowers:dispatching-parallel-agents, /security-review) points at an audit
+  task. Delegate via mmagent so the audit runs on independent workers — your
+  main context stays free to synthesize findings.
+version: 3.1.0
 ---
 
 ## mma-audit
@@ -38,7 +47,7 @@ Either `document` or `filePaths` (or both) must be provided.
 ### Full example
 
 ```bash
-BATCH=$(curl -sf -X POST \
+BATCH=$(curl -f --show-error -s -X POST \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"auditType":"correctness","filePaths":["/project/docs/api-spec.md"]}' \

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

@@ -1,7 +1,15 @@
 ---
 name: mma-clarifications
-description: Confirm or correct the service's proposed interpretation when a batch is awaiting clarification before it can proceed.
-when_to_use: When polling GET /batch/:id returns state 'awaiting_clarification'. Read proposedInterpretation, then call this skill to confirm or correct it.
+description: >-
+  Confirm or correct mmagent's proposed interpretation when a batch is awaiting
+  clarification before it can proceed. Paired skill to every mma-* task
+  dispatcher.
+when_to_use: >-
+  A previous mma-delegate / mma-audit / mma-review / mma-execute-plan / etc.
+  terminal envelope has `proposedInterpretation` as a string (not a
+  NotApplicable sentinel). Read the proposal and call this skill to accept or
+  correct it. The batch resumes after the POST returns.
+version: 3.1.0
 ---
 
 ## mma-clarifications
@@ -46,15 +54,15 @@ executor was already waiting and finishes immediately.
 
 ```bash
 # 1. Poll until awaiting_clarification
-STATE=$(curl -sf -H "Authorization: Bearer $TOKEN" \
+STATE=$(curl -f --show-error -s -H "Authorization: Bearer $TOKEN" \
   "http://localhost:$PORT/batch/$BATCH_ID" | jq -r '.state')
 
 # 2. Read the proposal
-PROPOSAL=$(curl -sf -H "Authorization: Bearer $TOKEN" \
+PROPOSAL=$(curl -f --show-error -s -H "Authorization: Bearer $TOKEN" \
   "http://localhost:$PORT/batch/$BATCH_ID" | jq -r '.proposedInterpretation')
 
 # 3. Confirm (accept proposal or supply corrected text)
-curl -sf -X POST \
+curl -f --show-error -s -X POST \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
   -d "{\"batchId\":\"$BATCH_ID\",\"interpretation\":\"$PROPOSAL\"}" \

package/dist/skills/mma-context-blocks/SKILL.md

@@ -1,7 +1,16 @@
 ---
 name: mma-context-blocks
-description: Register large reused documents as context blocks and reference them by ID across multiple tool calls. Avoids re-sending the same content repeatedly.
-when_to_use: When the same large document (spec, plan, codebase summary) needs to be referenced by multiple mma-* calls. Register once, reference by ID.
+description: >-
+  Register large reused documents (spec, plan, codebase summary) as a context
+  block the mmagent service caches, then reference it by ID across multiple
+  mma-* calls. Avoids re-uploading the same content on every task.
+when_to_use: >-
+  A document larger than ~2 KB will be referenced by two or more mma-* calls in
+  a row. Register once here, then pass the returned ID via the contextBlockIds
+  field on mma-delegate / mma-execute-plan / mma-audit / mma-review / mma-verify
+  / mma-debug. Cheaper and faster than inlining the same content in every
+  request body.
+version: 3.1.0
 ---
 
 ## mma-context-blocks
@@ -52,14 +61,14 @@ wait for those batches to complete before deleting.
 
 ```bash
 # Register spec document
-ID=$(curl -sf -X POST \
+ID=$(curl -f --show-error -s -X POST \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
   -d "{\"content\":$(jq -Rs . < /project/docs/spec.md)}" \
   "http://localhost:$PORT/context-blocks?cwd=/project" | jq -r '.id')
 
 # Use in a delegate call
-curl -sf -X POST \
+curl -f --show-error -s -X POST \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
   -d "{\"tasks\":[{\"prompt\":\"Implement per spec\",\"contextBlockIds\":[\"$ID\"]}]}" \

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

@@ -1,7 +1,16 @@
 ---
 name: mma-debug
-description: Debug a failure using a structured hypothesis. All provided files are investigated together in a single task.
-when_to_use: When a test fails, a build breaks, or unexpected behavior appears and you need a structured investigation with a hypothesis.
+description: >-
+  Debug a failure using a structured hypothesis via the local mmagent HTTP
+  service. All provided files are investigated together in a single task on a
+  worker.
+when_to_use: >-
+  A test fails, a build breaks, or behavior is unexpected AND you need to read
+  files, reproduce the failure, or narrow root cause OR a methodology skill
+  (superpowers:systematic-debugging) points at the investigation step. Delegate
+  the read/reproduce/trace work to a mmagent worker so your main context stays
+  focused on the hypothesis and the fix.
+version: 3.1.0
 ---
 
 ## mma-debug
@@ -42,7 +51,7 @@ in a single task (not parallelised per file).
 ### Full example
 
 ```bash
-BATCH=$(curl -sf -X POST \
+BATCH=$(curl -f --show-error -s -X POST \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"problem":"Tests fail on CI only","hypothesis":"Missing env var","filePaths":["/project/src/config.ts"]}' \

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

@@ -1,7 +1,17 @@
 ---
 name: mma-delegate
-description: Fan out ad-hoc implementation or research tasks to sub-agents in parallel. Use when there is no plan file on disk.
-when_to_use: When you need to delegate one or more implementation or research tasks to sub-agents without a pre-existing plan file. Each task runs in parallel.
+description: >-
+  Fan out ad-hoc implementation or research tasks to sub-agents in parallel via
+  the local mmagent HTTP service. Tasks run on cheap workers that don't consume
+  your main-model context window.
+when_to_use: >-
+  You have one or more ad-hoc implementation or research tasks WITHOUT a plan
+  file on disk AND mmagent is running. Prefer this over inline Agent dispatches
+  or superpowers:dispatching-parallel-agents — delegated workers are cheaper,
+  parallel-safe, and keep main context free. If a plan file exists, use
+  mma-execute-plan; if the task is an audit/review/verify/debug, prefer the
+  matching mma-* skill instead.
+version: 3.1.0
 ---
 
 ## mma-delegate
@@ -46,7 +56,7 @@ Use `agentType: "complex"` for ambiguous scope or security-sensitive tasks.
 ### Full example
 
 ```bash
-BATCH=$(curl -sf -X POST \
+BATCH=$(curl -f --show-error -s -X POST \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"tasks":[{"prompt":"Refactor utils.ts to remove dead code","filePaths":["/project/src/utils.ts"]}]}' \

package/dist/skills/mma-execute-plan/SKILL.md

@@ -1,7 +1,17 @@
 ---
 name: mma-execute-plan
-description: Implement tasks from a plan or spec file on disk. Task descriptors match plan headings; tasks run in parallel.
-when_to_use: When you have a written plan or spec file and want sub-agents to implement specific tasks from it.
+description: >-
+  Execute tasks from a plan or spec file on disk via the local mmagent HTTP
+  service. Delegates to cheap sub-agents that don't consume your main-model
+  context window. Task descriptors match plan headings; tasks run in parallel.
+when_to_use: >-
+  A plan file exists on disk (any markdown with numbered task headings —
+  docs/superpowers/plans/*.md, a TODO list, a spec doc) AND you need to
+  implement one or more tasks from it. Prefer this over inline Agent dispatches
+  or superpowers:subagent-driven-development / superpowers:executing-plans when
+  mmagent is running — delegated workers are cheaper and don't pollute main
+  context. Task descriptors must match the plan headings verbatim.
+version: 3.1.0
 ---
 
 ## mma-execute-plan
@@ -46,7 +56,7 @@ to confirm or correct the proposed interpretation.
 ### Full example
 
 ```bash
-BATCH=$(curl -sf -X POST \
+BATCH=$(curl -f --show-error -s -X POST \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"tasks":["3. Migrate database schema"],"filePaths":["/project/docs/plan.md"]}' \

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

@@ -1,7 +1,15 @@
 ---
 name: mma-retry
-description: Re-run specific failed or incomplete tasks from a previous batch by index.
-when_to_use: When some tasks in a previous batch failed or returned incomplete results and you want to re-run only those tasks without re-running the whole batch.
+description: >-
+  Re-run specific failed or incomplete tasks from a previous mmagent batch by
+  index. Preserves the original task specs and only re-executes the named
+  indices.
+when_to_use: >-
+  A previous mma-delegate / mma-execute-plan batch returned partial results and
+  you want to re-try the failed indices only. Prefer this over redispatching the
+  whole batch or inline-retrying — it's idempotent and keeps the original
+  batch's diagnostics intact.
+version: 3.1.0
 ---
 
 ## mma-retry
@@ -37,7 +45,7 @@ indices from `0` to `tasks.length - 1`.
 
 ```bash
 # Original batch had 4 tasks; re-run tasks at index 1 and 3
-BATCH=$(curl -sf -X POST \
+BATCH=$(curl -f --show-error -s -X POST \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"batchId":"550e8400-e29b-41d4-a716-446655440000","taskIndices":[1,3]}' \

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

@@ -1,7 +1,15 @@
 ---
 name: mma-review
-description: Review code for quality, security, performance, or correctness. Sub-agents run in parallel per file.
-when_to_use: When you need an independent code review after implementing a feature or fix, or before merging a branch.
+description: >-
+  Review code for quality, security, performance, or correctness via the local
+  mmagent HTTP service. Sub-agents run in parallel per file, independent
+  context.
+when_to_use: >-
+  The user asks for a code review, pre-merge check, or quality pass over one or
+  more files OR a methodology skill (superpowers:requesting-code-review,
+  /review, /security-review) points at a review task. Delegate the reviewer pass
+  to mmagent workers — your main context stays free to decide what to merge.
+version: 3.1.0
 ---
 
 ## mma-review
@@ -38,7 +46,7 @@ Either `code` or `filePaths` (or both) must be provided.
 ### Full example
 
 ```bash
-BATCH=$(curl -sf -X POST \
+BATCH=$(curl -f --show-error -s -X POST \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"focus":["security","correctness"],"filePaths":["/project/src/auth/login.ts"]}' \

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

@@ -1,7 +1,14 @@
 ---
 name: mma-verify
-description: Verify work against a checklist. Sub-agents check each item independently.
-when_to_use: When you need to confirm that implemented work meets a set of acceptance criteria or a review checklist before claiming completion.
+description: >-
+  Verify work against a checklist via the local mmagent HTTP service. Sub-agents
+  check each item independently.
+when_to_use: >-
+  The user (or a methodology skill like
+  superpowers:verification-before-completion) wants acceptance-criteria checked
+  against implemented work. Delegate the evidence-gathering to mmagent workers —
+  each checklist item is verified independently and in parallel.
+version: 3.1.0
 ---
 
 ## mma-verify
@@ -40,7 +47,7 @@ Each checklist item is verified in parallel; results are index-aligned.
 ### Full example
 
 ```bash
-BATCH=$(curl -sf -X POST \
+BATCH=$(curl -f --show-error -s -X POST \
   -H "Authorization: Bearer $TOKEN" \
   -H "Content-Type: application/json" \
   -d '{"checklist":["Error handler exists","Tests pass"],"filePaths":["/project/src/handler.ts"]}' \

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

@@ -1,7 +1,17 @@
 ---
 name: multi-model-agent
-description: Overview of the multi-model-agent local service. Use this skill to understand which specialized mma-* skill to invoke for a given task.
-when_to_use: When the user asks about delegating tool-using work, or when auth/setup issues arise before a specific mma-* skill can run.
+description: >-
+  Router for the multi-model-agent local service. Use first when you're about to
+  delegate any tool-using work — picks the right mma-* skill for the task
+  (audit, review, verify, debug, plan execution, ad-hoc delegation) instead of
+  defaulting to inline Agent dispatches.
+when_to_use: >-
+  The user asks for work you'd normally delegate — audit, code review, checklist
+  verification, debugging, plan execution, or ad-hoc parallel 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 just asked directly.
+version: 3.1.0
 ---
 
 ## multi-model-agent overview
@@ -48,8 +58,15 @@ Every request requires `Authorization: Bearer <token>`.
 ### General flow
 
 1. Call the appropriate `mma-*` skill → receive `{ batchId }`.
-2. Poll `GET /batch/:id` until `state` is terminal.
-3. Read `results` from the completed batch.
+2. Poll `GET /batch/:id`: `202 text/plain` while pending (body is the running headline), `200 application/json` on terminal.
+3. Read `results` / `error` / `proposedInterpretation` from the terminal envelope.
 
-If the batch reaches `awaiting_clarification`, use `mma-clarifications`
-to confirm or correct the proposed interpretation before the batch resumes.
+If the terminal envelope has `proposedInterpretation` as a string, use `mma-clarifications` to confirm or correct it.
+
+### Diagnosing slow tasks
+
+Start the server with `mmagent serve --verbose` (or set `diagnostics.verbose: true` in config) to record `tool_call` and `llm_turn` events. Then tail them:
+
+```bash
+mmagent logs --follow --batch=$BATCH_ID
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zhixuan92/multi-model-agent",
-  "version": "3.0.1",
+  "version": "3.1.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.",
@@ -23,7 +23,8 @@
   "homepage": "https://github.com/zhixuan312/multi-model-agent#readme",
   "bugs": "https://github.com/zhixuan312/multi-model-agent/issues",
   "files": [
-    "dist"
+    "dist",
+    "scripts/postinstall.js"
   ],
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -42,7 +43,8 @@
     }
   },
   "scripts": {
-    "build": "tsc && rm -rf dist/skills && cp -R src/skills dist/skills && chmod +x dist/cli/index.js",
+    "build": "tsc && rm -rf dist/skills && cp -R src/skills dist/skills && node scripts/inject-skill-version.mjs && chmod +x dist/cli/index.js",
+    "postinstall": "node scripts/postinstall.js",
     "prepublishOnly": "npm run build"
   },
   "engines": {
@@ -50,7 +52,8 @@
   },
   "dependencies": {
     "@asteasolutions/zod-to-openapi": "^8.5.0",
-    "@zhixuan92/multi-model-agent-core": "^3.0.1",
+    "@zhixuan92/multi-model-agent-core": "^3.1.0",
+    "gray-matter": "^4.0.3",
     "minimist": "^1.2.8",
     "zod": "^4.0.0"
   },

package/scripts/postinstall.js

@@ -0,0 +1,36 @@
+#!/usr/bin/env node
+/**
+ * postinstall.js — stable wrapper.
+ *
+ * Runs on every `npm install @zhixuan92/multi-model-agent`.
+ *
+ * Calls `mmagent update-skills --if-exists --silent --best-effort` so that
+ * users who previously installed skills get their Claude Code / Gemini /
+ * Codex / Cursor copies refreshed to match this release. Exits 0 on every
+ * failure mode so npm install never breaks the user's environment.
+ *
+ * The wrapper is committed (always present) so publishing does not
+ * accidentally bundle a CLI build step that references a missing file.
+ */
+import { existsSync } from 'node:fs';
+import { spawn } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+const cli = join(here, '..', 'dist', 'cli', 'index.js');
+
+// If dist hasn't been built yet (e.g. during the repo's own install before
+// build), do nothing — the published tarball always includes dist.
+if (!existsSync(cli)) {
+  process.exit(0);
+}
+
+const child = spawn(
+  process.execPath,
+  [cli, 'update-skills', '--if-exists', '--silent', '--best-effort'],
+  { stdio: 'inherit' },
+);
+
+child.on('exit', (code) => process.exit(code ?? 0));
+child.on('error', () => process.exit(0));