@zhixuan92/multi-model-agent-mcp 0.3.1 → 1.0.0

package/README.md

@@ -2,16 +2,17 @@
 
 **Delegate work from your expensive parent-session model to a fleet of cheaper sub-agents, in parallel, from a single MCP tool call.**
 
-This is the MCP stdio server for [`multi-model-agent`](https://github.com/zhixuan312/multi-model-agent). Your MCP client (Claude Code, Claude Desktop, Codex CLI, Cursor, …) spawns it on demand and gets four tools: `delegate_tasks`, `register_context_block`, `retry_tasks`, and `get_task_output`. Each `delegate_tasks` call runs the supplied tasks in parallel across the providers you configured, auto-routing each to the cheapest one that has the required capabilities and quality tier — or pinning to a specific provider when you want control.
+This is the MCP stdio server for [`multi-model-agent`](https://github.com/zhixuan312/multi-model-agent). Your MCP client (Claude Code, Claude Desktop, Codex CLI, Cursor, …) spawns it on demand and gets nine tools: `delegate_tasks`, `register_context_block`, `retry_tasks`, `get_batch_slice`, `execute_plan_task`, `audit_document`, `debug_task`, `review_code`, and `verify_work`. Each `delegate_tasks` call runs the supplied tasks in parallel across the agents you configured, auto-routing each to the cheapest one that has the required capabilities and agent type — or pinning to a specific agent when you want control. Every response envelope carries a pre-computed `headline` field so the calling agent can narrate the ROI story in one line without any arithmetic.
 
 ## Why use it
 
-- **Cut cost and context.** Mechanical work (file edits, search, doc lookups) runs on cheap providers in a clean worker context. Your parent session's window stays lean and its judgment unblocked.
+- **Cut cost and context.** Mechanical work (file edits, search, doc lookups) runs on cheap agents in a clean worker context. Your parent session's window stays lean and its judgment unblocked.
 - **Run tasks in parallel.** Independent tasks in one call execute concurrently; wall-clock time drops with task count.
-- **Mix providers in one config.** Claude, Codex, and any OpenAI-compatible endpoint (MiniMax, DeepSeek, Groq, local vLLM, …) live side-by-side.
-- **Auto-route and escalate.** Capability filter → tier filter → cheapest qualifying provider; on failure the chain is walked automatically, stopping at the first success.
+- **Mix agents in one config.** Claude, Codex, and any OpenAI-compatible endpoint (MiniMax, DeepSeek, Groq, local vLLM, …) live side-by-side.
+- **Auto-route and escalate.** Capability filter → agent type routing; on failure the chain is walked automatically, stopping at the first success.
 - **No bare failures.** Every termination path (incomplete, max_turns, timeout, error) populates `output` from the runner's scratchpad.
 - **Sandboxed by default.** `cwd-only` file tool confinement and shell-disabled by default. Opt out per-task only when needed.
+- **Pre-computed ROI headline**: every `delegate_tasks` response carries a `headline` field — a one-line summary of tasks, success rate, wall-clock, serial savings, cost, and ROI. Quote it verbatim; no arithmetic required.
 - **Visible ROI.** Every response surfaces `aggregateCost`, `timings`, and per-task `savedCostUSD` for delegation savings.
 
 ## How it works
@@ -26,24 +27,16 @@ Create `~/.multi-model/config.json`:
 
 ```json
 {
-  "providers": {
-    "claude": {
-      "type": "claude",
+  "agents": {
+    "standard": {
+      "type": "openai-compatible",
       "model": "claude-sonnet-4-6",
-      "costTier": "medium"
-    },
-    "codex": {
-      "type": "codex",
-      "model": "gpt-5-codex",
-      "costTier": "medium"
+      "baseUrl": "https://api.claude.ai/v1"
     },
-    "minimax": {
+    "complex": {
       "type": "openai-compatible",
-      "model": "MiniMax-M2",
-      "baseUrl": "https://api.minimax.io/v1",
-      "apiKeyEnv": "MINIMAX_API_KEY",
-      "costTier": "free",
-      "hostedTools": ["web_search"]
+      "model": "claude-opus-4-6",
+      "baseUrl": "https://api.claude.ai/v1"
     }
   },
   "defaults": {
@@ -56,11 +49,10 @@ Create `~/.multi-model/config.json`:
 
 Config lookup order: `--config <path>` → `MULTI_MODEL_CONFIG` env var → `~/.multi-model/config.json`.
 
-Provider auth:
+Agent auth:
 
-- **`codex`** uses `codex login` if available, otherwise `OPENAI_API_KEY`
-- **`claude`** uses `ANTHROPIC_API_KEY` if set, otherwise the local Claude auth flow
-- **`openai-compatible`** uses `apiKeyEnv` (preferred) or inline `apiKey`
+- **OpenAI-compatible** agents use `apiKeyEnv` (preferred) or inline `apiKey`
+- **Claude** agents use `ANTHROPIC_API_KEY` if set, otherwise the local Claude auth flow
 
 ## Setup
 
@@ -72,7 +64,7 @@ One command — the client will spawn the server on demand. Use `-s user` so the
 claude mcp add multi-model-agent -s user -- npx -y @zhixuan92/multi-model-agent-mcp serve
 ```
 
-If your providers need environment variables:
+If your agents need environment variables:
 
 ```bash
 claude mcp add multi-model-agent -s user \
@@ -99,7 +91,7 @@ ANTHROPIC_API_KEY = "sk-ant-..."
 MINIMAX_API_KEY = "..."
 ```
 
-Only set the env keys for the providers you actually configured. If you use `codex login`, the `codex` provider inside `multi-model-agent` reuses that auth automatically — but Claude, MiniMax, and other API-key providers still need to be passed through `[mcp_servers.multi-model-agent.env]` because the spawned MCP process does not inherit your shell environment. Restart `codex` after editing the file.
+Only set the env keys for the agents you actually configured. If you use `codex login`, the `codex` agent inside `multi-model-agent` reuses that auth automatically — but Claude, MiniMax, and other API-key agents still need to be passed through `[mcp_servers.multi-model-agent.env]` because the spawned MCP process does not inherit your shell environment. Restart `codex` after editing the file.
 
 ### Claude Desktop
 
@@ -145,7 +137,7 @@ args = ["-y", "@zhixuan92/multi-model-agent-mcp@0.3.0", "serve"]
 
 ## Recommended: delegation rule for Claude Code
 
-Claude Code's native `Task` / `Agent` subagents inherit your parent session's expensive model and eat its context window. We ship a drop-in rule file that teaches Claude Code **when** to delegate work through `delegate_tasks` instead — mechanical edits go to free providers, reasoning-tier work escalates only when needed, and independent tasks run in parallel.
+Claude Code's native `Task` / `Agent` subagents inherit your parent session's expensive model and eat its context window. We ship a drop-in rule file that teaches Claude Code **when** to delegate work through `delegate_tasks` instead — mechanical edits go to free agents, reasoning-tier work escalates only when needed, and independent tasks run in parallel.
 
 Install globally:
 
@@ -190,12 +182,22 @@ Accepts an array of tasks and runs them concurrently. Auto-routes each task by c
 }
 ```
 
-Per-task fields: `prompt`, `tier`, `requiredCapabilities`, `provider?`, `tools?`, `maxTurns?`, `timeoutMs?`, `cwd?`, `effort?`, `sandboxPolicy?`, `contextBlockIds?`, `expectedCoverage?`, `includeProgressTrace?`, `parentModel?`.
+Per-task fields: `prompt`, `tier`, `requiredCapabilities`, `provider?`, `tools?`, `maxTurns?`, `timeoutMs?`, `cwd?`, `effort?`, `sandboxPolicy?`, `contextBlockIds?`, `expectedCoverage?`, `includeProgressTrace?`, `parentModel?`, `skipCompletionHeuristic?`.
 
-`expectedCoverage` supports `minSections?`, `sectionPattern?`, and `requiredMarkers?`. `includeProgressTrace` opts a task into returning its bounded post-hoc progress trace. `parentModel` lets the server estimate `savedCostUSD` relative to the calling model.
+`expectedCoverage` supports `minSections?`, `sectionPattern?`, and `requiredMarkers?`. `includeProgressTrace` opts a task into returning its bounded post-hoc progress trace. `parentModel` lets the server estimate `savedCostUSD` relative to the calling model. `skipCompletionHeuristic: true` disables the short-output completion heuristic in the runner's supervision layer — use for tight-format outputs (single-line verdicts, CSV rows, opaque identifiers) that don't follow prose conventions. The `empty` and `thinking_only` degeneracy checks still fire independently. If you also set `expectedCoverage`, the coverage contract is authoritative and the short-output heuristic is automatically skipped on coverage pass — you don't need both.
 
 Capabilities: `file_read`, `file_write`, `grep`, `glob`, `shell`, `web_search`, `web_fetch`.
 
+### ROI headline
+
+Every `delegate_tasks` response envelope — both `full` mode and `summary` mode — carries a pre-computed `headline` field: a one-line summary of tasks / success rate / wall-clock / serial-savings / actual cost / saved cost / ROI multiplier (when a single baseline is declared). The calling agent is expected to quote it verbatim to the user after every dispatch, with no arithmetic. Example:
+
+> *"11 tasks, 5/11 ok (45.5%), wall 5m 54s, saved ~18m 30s vs serial, $1.37 actual / $8.91 saved vs claude-opus-4-6 (7.5x ROI)"*
+
+When a batch declares mixed parent models across its tasks, the ROI multiplier is suppressed (because a single ratio across different baselines is not coherent) and the cost clause reads `$X actual / $Y saved vs multiple baselines`. When no `parentModel` is declared, the cost clause collapses to `$X actual`.
+
+If the primary response came back via summary mode or a client-side limit obscured the envelope, call `get_batch_slice({ batchId, slice: 'telemetry' })` — it returns the same `headline` plus the envelope with a ~600-byte header and ~200 bytes per task in `results[]`. A typical 10–30-task batch comes back at 2–7 KB, well under the client's tool-result size limit; very large batches (100+ tasks) scale linearly and may approach the limit.
+
 ## Security
 
 ### Sandbox enforcement

package/dist/cli.d.ts

@@ -8,25 +8,11 @@ export declare function computeTimings(wallClockMs: number, results: RunResult[]
 export declare function computeBatchProgress(results: RunResult[]): BatchProgress;
 export declare function computeAggregateCost(results: RunResult[]): BatchAggregateCost;
 export declare const SERVER_VERSION: string;
-export declare function buildTaskSchema(availableProviders: [string, ...string[]]): z.ZodObject<{
+export declare function buildTaskSchema(availableAgents: [string, ...string[]]): z.ZodObject<{
     prompt: z.ZodString;
-    provider: z.ZodOptional<z.ZodEnum<{
+    agentType: z.ZodOptional<z.ZodEnum<{
         [x: string]: string;
     }>>;
-    tier: z.ZodEnum<{
-        reasoning: "reasoning";
-        standard: "standard";
-        trivial: "trivial";
-    }>;
-    requiredCapabilities: z.ZodArray<z.ZodEnum<{
-        file_read: "file_read";
-        file_write: "file_write";
-        grep: "grep";
-        glob: "glob";
-        shell: "shell";
-        web_search: "web_search";
-        web_fetch: "web_fetch";
-    }>>;
     tools: z.ZodOptional<z.ZodEnum<{
         full: "full";
         none: "none";
@@ -44,14 +30,28 @@ export declare function buildTaskSchema(availableProviders: [string, ...string[]
         none: "none";
         "cwd-only": "cwd-only";
     }>>;
+    requiredCapabilities: z.ZodOptional<z.ZodArray<z.ZodString>>;
     contextBlockIds: z.ZodOptional<z.ZodArray<z.ZodString>>;
     expectedCoverage: z.ZodOptional<z.ZodObject<{
         minSections: z.ZodOptional<z.ZodNumber>;
         sectionPattern: z.ZodOptional<z.ZodString>;
         requiredMarkers: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strip>>;
-    includeProgressTrace: z.ZodOptional<z.ZodBoolean>;
+    skipCompletionHeuristic: z.ZodOptional<z.ZodBoolean>;
     parentModel: z.ZodOptional<z.ZodString>;
+    maxCostUSD: z.ZodOptional<z.ZodNumber>;
+    reviewPolicy: z.ZodOptional<z.ZodEnum<{
+        full: "full";
+        spec_only: "spec_only";
+        off: "off";
+    }>>;
+    maxReviewRounds: z.ZodOptional<z.ZodNumber>;
+    briefQualityPolicy: z.ZodOptional<z.ZodEnum<{
+        off: "off";
+        normalize: "normalize";
+        strict: "strict";
+        warn: "warn";
+    }>>;
 }, z.core.$strip>;
 export declare function buildMcpServer(config: Parameters<typeof runTasks>[1], options?: {
     /** Character threshold that triggers auto-switch from 'full' to
@@ -61,6 +61,8 @@ export declare function buildMcpServer(config: Parameters<typeof runTasks>[1], o
      *  MULTI_MODEL_LARGE_RESPONSE_THRESHOLD_CHARS > config file
      *  defaults.largeResponseThresholdChars > this option > default. */
     largeResponseThresholdChars?: number;
+    /** Internal test-only hook for injecting a stubbed runTasks implementation. */
+    _testRunTasksOverride?: typeof runTasks;
 }): McpServer;
 /**
  * MCP CLI config discovery (owned by MCP, not core):

package/dist/cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAQA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,QAAQ,EAAE,MAAM,6CAA6C,CAAC;AAEvE,OAAO,KAAK,EACV,gBAAgB,EAGhB,SAAS,EACT,YAAY,EACZ,aAAa,EACb,kBAAkB,EACnB,MAAM,mCAAmC,CAAC;AAG3C,eAAO,MAAM,WAAW,sBAAsB,CAAC;AAc/C,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,YAAY,CAItF;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,aAAa,CAgBxE;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,kBAAkB,CAyB7E;AAwFD,eAAO,MAAM,cAAc,QAAc,CAAC;AAE1C,wBAAgB,eAAe,CAAC,kBAAkB,EAAE,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBAwCxE;AAkCD,wBAAgB,cAAc,CAC5B,MAAM,EAAE,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC,CAAC,CAAC,EACtC,OAAO,CAAC,EAAE;IACR;;;;;wEAKoE;IACpE,2BAA2B,CAAC,EAAE,MAAM,CAAC;CACtC,aAoXF;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,gBAAgB,CAAC,CAuBhE"}
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":";AAQA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEpE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAGxB,OAAO,EAAE,QAAQ,EAAE,MAAM,6CAA6C,CAAC;AAEvE,OAAO,KAAK,EACV,gBAAgB,EAGhB,SAAS,EACT,YAAY,EACZ,aAAa,EACb,kBAAkB,EAEnB,MAAM,mCAAmC,CAAC;AAS3C,eAAO,MAAM,WAAW,sBAAsB,CAAC;AAc/C,wBAAgB,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,GAAG,YAAY,CAItF;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,aAAa,CAgBxE;AAED,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,SAAS,EAAE,GAAG,kBAAkB,CAiB7E;AA4GD,eAAO,MAAM,cAAc,QAAc,CAAC;AAE1C,wBAAgB,eAAe,CAAC,eAAe,EAAE,CAAC,MAAM,EAAE,GAAG,MAAM,EAAE,CAAC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;kBA4HrE;AAkCD,wBAAgB,cAAc,CAC5B,MAAM,EAAE,UAAU,CAAC,OAAO,QAAQ,CAAC,CAAC,CAAC,CAAC,EACtC,OAAO,CAAC,EAAE;IACR;;;;;wEAKoE;IACpE,2BAA2B,CAAC,EAAE,MAAM,CAAC;IACrC,+EAA+E;IAC/E,qBAAqB,CAAC,EAAE,OAAO,QAAQ,CAAC;CACzC,aA6cF;AAED;;;;;GAKG;AACH,wBAAsB,cAAc,IAAI,OAAO,CAAC,gBAAgB,CAAC,CA4BhE"}