muonroi-cli 1.7.2 → 1.8.0

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 muonroi
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 muonroi
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,122 +1,122 @@
-<p align="center">
-  <h1 align="center">muonroi-cli</h1>
-  <p align="center">
-    <em>An AI coding agent where models argue with each other before answering.</em>
-  </p>
-  <p align="center">
-    <a href="https://github.com/muonroi/muonroi-cli/actions/workflows/ci-matrix.yml"><img alt="CI" src="https://github.com/muonroi/muonroi-cli/actions/workflows/ci-matrix.yml/badge.svg"></a>
-    <a href="https://www.npmjs.com/package/muonroi-cli"><img alt="npm" src="https://img.shields.io/npm/v/muonroi-cli.svg"></a>
-    <img alt="Providers" src="https://img.shields.io/badge/providers-7%20supported-blue">
-    <img alt="License" src="https://img.shields.io/badge/license-MIT-yellow">
-    <img alt="Runtime" src="https://img.shields.io/badge/runtime-Bun%201.3%2B-orange">
-  </p>
-</p>
-
----
-
-> Routes each task to the optimal model, runs adversarial multi-model debates for high-stakes decisions, and persists behavioral memory across sessions. Bring your own API keys. Total cost: ~$5/month.
-
-<p align="center">
-  <img src="https://raw.githubusercontent.com/muonroi/muonroi-cli/master/docs/demo.gif" alt="Council debate — REST vs gRPC decision" width="840" />
-</p>
-
-## Quick Start
-
-### Install
-
-**Recommended — prebuilt standalone binary (zero runtime deps, no prereqs):**
-
-Linux / macOS:
-```bash
-curl -fsSL https://raw.githubusercontent.com/muonroi/muonroi-cli/master/install.sh | bash
-```
-
-Windows PowerShell:
-```powershell
-irm https://raw.githubusercontent.com/muonroi/muonroi-cli/master/install.ps1 | iex
-```
-
-The installers download a `bun --compile` binary from GitHub Releases — single executable, all native deps bundled, no Node/Bun/build tools required.
-
-**Bun runtime (requires Bun ≥ 1.x):**
-```bash
-bun add -g muonroi-cli
-muonroi-cli
-```
-
-> **⚠ Why no `npm install -g`?** The TUI engine (`@opentui/core`) uses Bun-only `import ... with { type: "file" }` for Tree-sitter syntax highlight queries (`.scm` files). Node ESM cannot load these, so running under bare Node throws `ERR_UNKNOWN_FILE_EXTENSION`. Use the standalone installer (above) or `bun add -g`.
-
-### First run
-
-On first launch the CLI shows a wizard that:
-1. Lists supported providers (currently **DeepSeek** and **SiliconFlow**).
-2. Offers four ways to add credentials: paste an API key, import an encrypted bundle (`keys export`/`keys import`), sync from Bitwarden, or skip and add later via `/providers` inside the TUI.
-
-After setup, role routing auto-balances across enabled providers:
-
-```json
-// ~/.muonroi-cli/user-settings.json (generated by the wizard — edit if needed)
-{
-  "defaultProvider": "deepseek",
-  "providers": {
-    "deepseek":    { "enabled": true },
-    "siliconflow": { "enabled": true }
-  },
-  "roleModels": {
-    "leader":    "deepseek-v4-pro",
-    "implement": "deepseek-v4-flash",
-    "verify":    "deepseek-v4-pro",
-    "research":  "deepseek-v4-flash"
-  }
-}
-```
-
-### Moving keys between devices
-
-```bash
-# Source device — encrypts every stored key into one passphrase-protected file
-muonroi-cli keys export ~/muonroi-keys.json
-
-# Move the file via any channel (USB, Drive, AirDrop, email...)
-
-# Target device — same passphrase rehydrates the OS keychain
-muonroi-cli keys import ~/muonroi-keys.json
-```
-
-Inside the TUI press `/providers` then `B` to sync directly from a Bitwarden vault instead.
-
-### Updates
-
-The CLI checks npm once per day on startup and prompts when a newer version is available. Set `autoUpdate: true` in `user-settings.json` to skip the prompt and update silently. Manual: `muonroi-cli update`.
-
-## Documentation
-
-Full documentation at **[docs.muonroi.com/docs/cli](https://docs.muonroi.com/docs/cli/overview)**
-
-| Topic | Link |
-|---|---|
-| Overview & architecture | [CLI Overview](https://docs.muonroi.com/docs/cli/overview) |
-| Multi-Model Council | [Council Debate Guide](https://docs.muonroi.com/docs/cli/guides/council-debate) |
-| Prompt Intelligence Layer | [PIL Pipeline Guide](https://docs.muonroi.com/docs/cli/guides/pil-pipeline) |
-| Experience Engine | [Experience Engine Guide](https://docs.muonroi.com/docs/cli/guides/experience-engine) |
-| Agent Harness | [Agent Harness Guide](https://docs.muonroi.com/docs/cli/guides/agent-harness) |
-| Settings reference | [CLI Settings Reference](https://docs.muonroi.com/docs/cli/reference/cli-settings-reference) |
-| Commands reference | [Commands Reference](https://docs.muonroi.com/docs/cli/reference/commands-reference) |
-| Providers reference | [Providers Reference](https://docs.muonroi.com/docs/cli/reference/providers-reference) |
-
-## Development
-
-```bash
-git clone https://github.com/muonroi/muonroi-cli.git
-cd muonroi-cli && bun install
-
-bun run dev           # run from source
-bun run typecheck     # type check
-bun run test          # vitest
-bun run lint          # biome check
-bun run build:binary  # standalone binary
-```
-
-## License
-
-MIT
+<p align="center">
+  <h1 align="center">muonroi-cli</h1>
+  <p align="center">
+    <em>An AI coding agent where models argue with each other before answering.</em>
+  </p>
+  <p align="center">
+    <a href="https://github.com/muonroi/muonroi-cli/actions/workflows/ci-matrix.yml"><img alt="CI" src="https://github.com/muonroi/muonroi-cli/actions/workflows/ci-matrix.yml/badge.svg"></a>
+    <a href="https://www.npmjs.com/package/muonroi-cli"><img alt="npm" src="https://img.shields.io/npm/v/muonroi-cli.svg"></a>
+    <img alt="Providers" src="https://img.shields.io/badge/providers-7%20supported-blue">
+    <img alt="License" src="https://img.shields.io/badge/license-MIT-yellow">
+    <img alt="Runtime" src="https://img.shields.io/badge/runtime-Bun%201.3%2B-orange">
+  </p>
+</p>
+
+---
+
+> Routes each task to the optimal model, runs adversarial multi-model debates for high-stakes decisions, and persists behavioral memory across sessions. Bring your own API keys. Total cost: ~$5/month.
+
+<p align="center">
+  <img src="https://raw.githubusercontent.com/muonroi/muonroi-cli/master/docs/demo.gif" alt="Council debate — REST vs gRPC decision" width="840" />
+</p>
+
+## Quick Start
+
+### Install
+
+**Recommended — prebuilt standalone binary (zero runtime deps, no prereqs):**
+
+Linux / macOS:
+```bash
+curl -fsSL https://raw.githubusercontent.com/muonroi/muonroi-cli/master/install.sh | bash
+```
+
+Windows PowerShell:
+```powershell
+irm https://raw.githubusercontent.com/muonroi/muonroi-cli/master/install.ps1 | iex
+```
+
+The installers download a `bun --compile` binary from GitHub Releases — single executable, all native deps bundled, no Node/Bun/build tools required.
+
+**Bun runtime (requires Bun ≥ 1.x):**
+```bash
+bun add -g muonroi-cli
+muonroi-cli
+```
+
+> **⚠ Why no `npm install -g`?** The TUI engine (`@opentui/core`) uses Bun-only `import ... with { type: "file" }` for Tree-sitter syntax highlight queries (`.scm` files). Node ESM cannot load these, so running under bare Node throws `ERR_UNKNOWN_FILE_EXTENSION`. Use the standalone installer (above) or `bun add -g`.
+
+### First run
+
+On first launch the CLI shows a wizard that:
+1. Lists supported providers (currently **DeepSeek** and **SiliconFlow**).
+2. Offers four ways to add credentials: paste an API key, import an encrypted bundle (`keys export`/`keys import`), sync from Bitwarden, or skip and add later via `/providers` inside the TUI.
+
+After setup, role routing auto-balances across enabled providers:
+
+```json
+// ~/.muonroi-cli/user-settings.json (generated by the wizard — edit if needed)
+{
+  "defaultProvider": "deepseek",
+  "providers": {
+    "deepseek":    { "enabled": true },
+    "siliconflow": { "enabled": true }
+  },
+  "roleModels": {
+    "leader":    "deepseek-v4-pro",
+    "implement": "deepseek-v4-flash",
+    "verify":    "deepseek-v4-pro",
+    "research":  "deepseek-v4-flash"
+  }
+}
+```
+
+### Moving keys between devices
+
+```bash
+# Source device — encrypts every stored key into one passphrase-protected file
+muonroi-cli keys export ~/muonroi-keys.json
+
+# Move the file via any channel (USB, Drive, AirDrop, email...)
+
+# Target device — same passphrase rehydrates the OS keychain
+muonroi-cli keys import ~/muonroi-keys.json
+```
+
+Inside the TUI press `/providers` then `B` to sync directly from a Bitwarden vault instead.
+
+### Updates
+
+The CLI checks npm once per day on startup and prompts when a newer version is available. Set `autoUpdate: true` in `user-settings.json` to skip the prompt and update silently. Manual: `muonroi-cli update`.
+
+## Documentation
+
+Full documentation at **[docs.muonroi.com/docs/cli](https://docs.muonroi.com/docs/cli/overview)**
+
+| Topic | Link |
+|---|---|
+| Overview & architecture | [CLI Overview](https://docs.muonroi.com/docs/cli/overview) |
+| Multi-Model Council | [Council Debate Guide](https://docs.muonroi.com/docs/cli/guides/council-debate) |
+| Prompt Intelligence Layer | [PIL Pipeline Guide](https://docs.muonroi.com/docs/cli/guides/pil-pipeline) |
+| Experience Engine | [Experience Engine Guide](https://docs.muonroi.com/docs/cli/guides/experience-engine) |
+| Agent Harness | [Agent Harness Guide](https://docs.muonroi.com/docs/cli/guides/agent-harness) |
+| Settings reference | [CLI Settings Reference](https://docs.muonroi.com/docs/cli/reference/cli-settings-reference) |
+| Commands reference | [Commands Reference](https://docs.muonroi.com/docs/cli/reference/commands-reference) |
+| Providers reference | [Providers Reference](https://docs.muonroi.com/docs/cli/reference/providers-reference) |
+
+## Development
+
+```bash
+git clone https://github.com/muonroi/muonroi-cli.git
+cd muonroi-cli && bun install
+
+bun run dev           # run from source
+bun run typecheck     # type check
+bun run test          # vitest
+bun run lint          # biome check
+bun run build:binary  # standalone binary
+```
+
+## License
+
+MIT

package/dist/packages/agent-harness-core/src/event-filter.js

@@ -22,6 +22,7 @@ export const LIFECYCLE_PRESET = new Set([
     "llm-done",
     "council-step",
     "council-speaker",
+    "council-turn-length",
     "askcard-open",
     "askcard-answered",
     "askcard-cancel",

package/dist/packages/agent-harness-core/src/event-redact.js

@@ -54,6 +54,14 @@ const ALLOWED_FIELDS = {
         round: "pass",
         correlationId: "pass",
     },
+    "council-turn-length": {
+        role: "pass",
+        round: "pass",
+        charCount: "pass",
+        wordCount: "pass",
+        model: "pass",
+        correlationId: "pass",
+    },
     "askcard-open": {
         questionId: "pass",
         question: 300, // cap to 300 chars, then scrub

package/dist/packages/agent-harness-core/src/mcp-server.d.ts

@@ -46,6 +46,22 @@ export declare function validateStartArgs(args: string[]): {
     bad: string;
 };
 export declare function sanitizeEnv(env: Record<string, string>): Record<string, string>;
+/**
+ * Opt-in extra cwd roots for tui.start, layered ON TOP of the default
+ * {home, repo-root} allowlist. The posture stays deny-by-default: only roots an
+ * operator has explicitly listed are added. Two union sources:
+ *
+ *   1. env `MUONROI_HARNESS_EXTRA_ROOTS` — a path list separated by the OS path
+ *      separator (";" on win32, ":" elsewhere) and/or commas.
+ *   2. `<REPO_ROOT>/.muonroi-harness-roots.json` — `{ "roots": string[] }`.
+ *
+ * Rationale: the drive-harness needs to dogfood sibling ecosystem repos (e.g.
+ * `D:\sources\Core\*`) that live outside both home and the muonroi-cli checkout.
+ * Without an explicit opt-in those cwds are rejected, which blocks real-task
+ * evaluation. Clean checkouts have neither the env nor the (gitignored) config
+ * file, so behaviour is identical to the original home+repo-only boundary.
+ */
+export declare function loadExtraRoots(): string[];
 export declare function validateCwd(cwd: string): {
     ok: true;
 } | {

package/dist/packages/agent-harness-core/src/mcp-server.js

@@ -11,7 +11,7 @@
  *   fd 3/4, named pipes, WebSocket, …). The consumer (muonroi-cli) provides the
  *   spawn implementation via createMcpHarnessServer({ spawn }).
  */
-import { existsSync, realpathSync } from "node:fs";
+import { existsSync, readFileSync, realpathSync } from "node:fs";
 import { homedir } from "node:os";
 import { isAbsolute, resolve } from "node:path";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
@@ -50,6 +50,51 @@ export function sanitizeEnv(env) {
     return out;
 }
 const REPO_ROOT = process.cwd();
+/**
+ * Opt-in extra cwd roots for tui.start, layered ON TOP of the default
+ * {home, repo-root} allowlist. The posture stays deny-by-default: only roots an
+ * operator has explicitly listed are added. Two union sources:
+ *
+ *   1. env `MUONROI_HARNESS_EXTRA_ROOTS` — a path list separated by the OS path
+ *      separator (";" on win32, ":" elsewhere) and/or commas.
+ *   2. `<REPO_ROOT>/.muonroi-harness-roots.json` — `{ "roots": string[] }`.
+ *
+ * Rationale: the drive-harness needs to dogfood sibling ecosystem repos (e.g.
+ * `D:\sources\Core\*`) that live outside both home and the muonroi-cli checkout.
+ * Without an explicit opt-in those cwds are rejected, which blocks real-task
+ * evaluation. Clean checkouts have neither the env nor the (gitignored) config
+ * file, so behaviour is identical to the original home+repo-only boundary.
+ */
+export function loadExtraRoots() {
+    const roots = [];
+    const envVal = process.env.MUONROI_HARNESS_EXTRA_ROOTS;
+    if (envVal) {
+        // Split on the OS path separator or commas. On win32 the separator is ";"
+        // (not ":") so drive letters like "D:\..." stay intact.
+        const listSep = process.platform === "win32" ? ";" : ":";
+        for (const part of envVal.split(new RegExp(`[${listSep},]`))) {
+            const trimmed = part.trim();
+            if (trimmed)
+                roots.push(trimmed);
+        }
+    }
+    const cfgPath = resolve(REPO_ROOT, ".muonroi-harness-roots.json");
+    if (existsSync(cfgPath)) {
+        try {
+            const parsed = JSON.parse(readFileSync(cfgPath, "utf8"));
+            if (Array.isArray(parsed.roots)) {
+                for (const r of parsed.roots) {
+                    if (typeof r === "string" && r.trim())
+                        roots.push(r.trim());
+                }
+            }
+        }
+        catch (err) {
+            console.error(`[harness/mcp-server] failed to parse ${cfgPath}: ${err?.message}`);
+        }
+    }
+    return roots;
+}
 export function validateCwd(cwd) {
     let real;
     try {
@@ -58,16 +103,22 @@ export function validateCwd(cwd) {
     catch {
         return { ok: false, reason: "cwd does not exist or unreadable" };
     }
-    const home = realpathSync(homedir());
-    const root = realpathSync(REPO_ROOT);
     const sep = process.platform === "win32" ? "\\" : "/";
-    if (real === home || real.startsWith(home + sep)) {
-        return { ok: true };
+    const allowedRoots = [realpathSync(homedir()), realpathSync(REPO_ROOT)];
+    for (const extra of loadExtraRoots()) {
+        try {
+            allowedRoots.push(realpathSync(extra));
+        }
+        catch (err) {
+            console.error(`[harness/mcp-server] extra cwd root unresolved, skipping: ${extra} (${err?.message})`);
+        }
     }
-    if (real === root || real.startsWith(root + sep)) {
-        return { ok: true };
+    for (const root of allowedRoots) {
+        if (real === root || real.startsWith(root + sep)) {
+            return { ok: true };
+        }
     }
-    return { ok: false, reason: "cwd escapes home and repo root" };
+    return { ok: false, reason: "cwd escapes home, repo root, and configured extra roots" };
 }
 export function validateMockLlmPath(value) {
     const resolved = isAbsolute(value) ? value : resolve(REPO_ROOT, value);
@@ -255,7 +306,34 @@ export function registerAsyncTools(server, getDriver, deps) {
     });
     server.registerTool("tui.last_event", {
         description: "Return the most recent event of the given kind (null if none).",
-        inputSchema: { kind: z.enum(["toast", "stream.delta"]) },
+        // Full protocol event set (minus the idle sentinel) so an external agent can
+        // observe lifecycle events — council/sprint/route/askcard, not just toasts.
+        // The Driver accepts any kind; this enum is the MCP-boundary validation.
+        inputSchema: {
+            kind: z.enum([
+                "toast",
+                "stream.delta",
+                "llm-token",
+                "llm-done",
+                "council-step",
+                "council-speaker",
+                "council-turn-length",
+                "askcard-open",
+                "askcard-answered",
+                "askcard-cancel",
+                "sprint-stage",
+                "sprint-halt",
+                "sprint-plan-committed",
+                "route-decision",
+                "steer-inject",
+                "usage",
+                "grounding-flag",
+                "ee-timeout",
+                "ee-error",
+                "stream-retry",
+                "disconnect",
+            ]),
+        },
     }, async ({ kind }) => {
         const d = getDriver();
         if (!d)
@@ -353,7 +431,7 @@ export function createMcpHarnessServer({ spawn }) {
         }
         if (!finalArgs.includes("--agent-mode"))
             finalArgs.push("--agent-mode");
-        const entry = process.cwd() + "/src/index.ts";
+        const entry = `${process.cwd()}/src/index.ts`;
         // Delegate to the injected spawn implementation — the core package has no
         // knowledge of the concrete transport (fd 3/4, named pipes, WebSocket …).
         let spawnResult;

package/dist/packages/agent-harness-core/src/protocol.d.ts

@@ -73,6 +73,21 @@ export type LiveEvent = {
     round?: number;
     /** Correlation ID linking this speaker event to the enclosing council run. */
     correlationId: string;
+} | {
+    t: "event";
+    kind: "council-turn-length";
+    /** Council role label (e.g. "architect"); matches council-speaker.role. */
+    role: string;
+    /** Debate round: 0 = opening statements, 1+ = discussion rounds. */
+    round: number;
+    /** Full character count of the speaker's output (trimmed; never truncated). */
+    charCount: number;
+    /** Word count of the speaker's output (whitespace-split, empties dropped). */
+    wordCount: number;
+    /** The speaker's model id, for per-model thrift attribution. */
+    model: string;
+    /** Correlation ID tying turns to the enclosing council run (= sessionId). */
+    correlationId: string;
 } | {
     t: "event";
     kind: "askcard-open";

package/dist/packages/agent-harness-core/src/selector.js

@@ -1,4 +1,4 @@
-const FLAGS = new Set(["focus", "selected", "disabled"]);
+const _FLAGS = new Set(["focus", "selected", "disabled"]);
 export function parseSelector(input) {
     // First, split by child combinator >>
     const childCombinatorRegex = /\s*>>\s*/;
@@ -146,7 +146,7 @@ function readField(node, key) {
         return node.state;
     if (key.startsWith("props.")) {
         const dot = key.slice("props.".length);
-        return (node.props ?? {})[dot];
+        return node.props?.[dot];
     }
     return undefined;
 }

package/dist/packages/agent-harness-core/src/transports/sidechannel.js

@@ -1,6 +1,6 @@
 const MAX_BYTES = 1024 * 1024; // 1 MiB
 function serialize(msg) {
-    const line = JSON.stringify(msg) + "\n";
+    const line = `${JSON.stringify(msg)}\n`;
     if (Buffer.byteLength(line, "utf8") > MAX_BYTES) {
         throw new Error(`sidechannel message exceeds 1 MiB cap`);
     }

package/dist/packages/agent-harness-opentui/src/agent-mode.js

@@ -17,8 +17,8 @@
  */
 import { createReadStream, createWriteStream } from "node:fs";
 import { createEventFilter } from "@muonroi/agent-harness-core/event-filter";
-import { createIdleDetector } from "@muonroi/agent-harness-core/idle";
 import { redactEvent } from "@muonroi/agent-harness-core/event-redact";
+import { createIdleDetector } from "@muonroi/agent-harness-core/idle";
 import { createLineSplitter, createSidechannelWriter } from "@muonroi/agent-harness-core/transports/sidechannel";
 import { installOpenTUIHarness } from "./install.js";
 import { createSemanticRegistry } from "./reconciler-hook.js";

package/dist/packages/agent-harness-opentui/src/install.js

@@ -41,7 +41,7 @@ export function installOpenTUIHarness(opts) {
         if (frame === null)
             return; // dedup — no change
         try {
-            opts.transport.send(JSON.stringify(frame) + "\n");
+            opts.transport.send(`${JSON.stringify(frame)}\n`);
             opts.onFrame?.(frame);
         }
         catch {

package/dist/src/__test-stubs__/vitest-setup.js

@@ -3,6 +3,10 @@
  * Any module that transitively imports db.ts will resolve to this stub.
  */
 import { vi } from "vitest";
+// vitest 2+ removed vi.mocked(). This shim restores it for the 93+ call sites across the
+// codebase without a codemod. Safe no-op: vi.mocked(item) just returns item (typed cast).
+// @ts-expect-error — vi.mocked is intentionally absent from vitest 4 types.
+vi.mocked ??= ((item, _options) => item);
 // @opentui/react is a pre-bundled CJS package that requires 'react-reconciler/constants'
 // without the .js extension — this fails in the vitest ESM environment. None of the unit
 // tests exercise OpenTUI hooks directly (those are covered by E2E harness specs), so mocking

package/dist/src/agent-harness/__tests__/mock-model.spec.js

@@ -5,9 +5,11 @@
 import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
+import { APICallError } from "@ai-sdk/provider";
 import { generateObject, stepCountIs, streamText, tool } from "ai";
 import { afterAll, describe, expect, it } from "vitest";
 import { z } from "zod";
+import { humanizeApiError } from "../../orchestrator/error-utils.js";
 import { createMockModel, loadMockModelFromDir, textOnlyStream, toolCallStream } from "../mock-model.js";
 // biome-ignore lint/suspicious/noExplicitAny: streamText result generic is provider-specific
 async function drainStream(result) {
@@ -188,6 +190,58 @@ describe("loadMockModelFromDir", () => {
         });
         expect(object).toEqual({ ok: true, label: "built" });
     });
+    it("constructs an APICallError from a structured error fixture (drives the humanizeApiError 5xx branch)", async () => {
+        // A pure-JSON fixture cannot otherwise build an APICallError (it arrives as
+        // a plain string). buildFixtureError() in mock-model.ts upgrades a structured
+        // `error` object carrying a statusCode into a real APICallError so harness/
+        // unit specs can exercise the orchestrator's status-aware 5xx path.
+        const dir = mkFixtureDir({
+            provider: "mock",
+            modelId: "mock-gpt",
+            stream: [
+                [
+                    { type: "stream-start", warnings: [] },
+                    {
+                        type: "error",
+                        error: {
+                            apiCallError: true,
+                            statusCode: 500,
+                            message: "AI_APICallError: Request failed",
+                            responseBody: JSON.stringify({ code: 60000, message: "Request failed: Unknown error." }),
+                            url: "https://api.siliconflow.cn/v1/chat/completions",
+                            isRetryable: true,
+                        },
+                    },
+                    {
+                        type: "finish",
+                        finishReason: { unified: "error", raw: null },
+                        usage: {
+                            inputTokens: { total: 0, noCache: 0, cacheRead: null, cacheWrite: null },
+                            outputTokens: { total: 0, text: 0, reasoning: null },
+                        },
+                    },
+                ],
+            ],
+        });
+        const handle = await loadMockModelFromDir(dir);
+        expect(handle).not.toBeNull();
+        const r = streamText({ model: handle.model, prompt: "hi" });
+        let errPart = null;
+        for await (const part of r.fullStream) {
+            if (part.type === "error")
+                errPart = part;
+        }
+        expect(errPart).not.toBeNull();
+        expect(APICallError.isInstance(errPart?.error)).toBe(true);
+        expect((errPart?.error).statusCode).toBe(500);
+        // The 5xx branch must surface the canned actionable text + (HTTP 500) and
+        // SUPPRESS the opaque provider body (the SiliconFlow "Unknown error" mask).
+        const msg = humanizeApiError(errPart?.error);
+        expect(msg).toContain("HTTP 500");
+        expect(msg.toLowerCase()).toContain("try again later");
+        expect(msg).not.toContain("Unknown error");
+        expect(msg).not.toContain("Request failed");
+    });
     it("supports multi-round stream arrays from the fixture file", async () => {
         const dir = mkFixtureDir({
             provider: "mock",

package/dist/src/agent-harness/mock-model.d.ts

@@ -22,7 +22,7 @@
  *   const calls = handle.calls; // LanguageModelV3CallOptions[]
  *   expect(calls[0].maxOutputTokens).toBeUndefined();
  */
-import type { LanguageModelV3CallOptions, LanguageModelV3StreamPart } from "@ai-sdk/provider";
+import { type LanguageModelV3CallOptions, type LanguageModelV3StreamPart } from "@ai-sdk/provider";
 import { MockLanguageModelV3 } from "ai/test";
 export type StreamChunks = LanguageModelV3StreamPart[];
 export interface MockModelFixture {