muonroi-cli 1.3.4 → 1.4.1

package/dist/src/tools/registry.js

@@ -6,11 +6,27 @@
  * is sent to the API for all providers (including DeepSeek, Gemini, etc.).
  */
 import { dynamicTool, jsonSchema } from "ai";
+import { canonicalizeBashCommand } from "../orchestrator/tool-args-hash.js";
 import { analyzeImageFromSource, askVisionProxy, listCachedImages } from "../providers/mcp-vision-bridge.js";
 import { needsVisionProxy } from "../providers/vision-proxy.js";
+import { getBashRun, sliceBashOutput } from "./bash-output-cache.js";
 import { editFile, readFile, writeFile } from "./file.js";
 import { FileTracker } from "./file-tracker.js";
 import { executeGrep } from "./grep.js";
+import { VISION_TOOL_NAMES } from "./vision-gate.js";
+function getBashRepeatState() {
+    if (!globalThis.__muonroiBashRepeatState) {
+        globalThis.__muonroiBashRepeatState = new Map();
+    }
+    return globalThis.__muonroiBashRepeatState;
+}
+let __anonRepeatCounter = 0;
+function resolveBashRepeatKey(sessionId) {
+    if (sessionId && sessionId.length > 0)
+        return sessionId;
+    __anonRepeatCounter += 1;
+    return `__no_session__:${process.pid}:${Date.now()}:${__anonRepeatCounter}`;
+}
 /**
  * Default per-tool-call output cap in characters (~8k tokens).
  *
@@ -45,6 +61,16 @@ function formatResult(result) {
     }
     return truncateOutput(`ERROR: ${result.error ?? result.output ?? "Unknown error"}`);
 }
+// ee_query routing: tool-artifact rehydration ("tool-artifact id=<id>" / "full
+// tool result id=<id>") is an exact-lookup of a persisted elided output and
+// must stay on /api/search (raw single-collection vector lookup). Every other
+// query is general recall → /api/recall (recallMode: 3 collections, raw cosine,
+// integrity gates, records a surface for exp-feedback). Splitting on intent
+// keeps the rehydration contract intact while upgrading recall to the fixed,
+// feedback-closing pipeline.
+export function isToolArtifactQuery(query) {
+    return /\b(?:tool-artifact|full tool result)\b/i.test(query) && /\bid\s*=/i.test(query);
+}
 export function createBuiltinTools(bash, mode, opts) {
     const tools = {};
     // One tracker per tool registry instance — shared across read/write/edit
@@ -84,9 +110,25 @@ export function createBuiltinTools(bash, mode, opts) {
             return formatResult(result);
         },
     });
-    // bash
+    // bash — every foreground call goes through here. We track the LAST
+    // canonical command + runId in SESSION-SCOPED state so we can inject a
+    // reminder when the model issues another bash call that canonicalizes to
+    // the same shape (e.g. `bunx vitest run | tail` followed by
+    // `bunx vitest run | head` — both canonicalize to `bunx vitest run`).
+    // The reminder rides on the tool_result of the SECOND call, which the
+    // model is forced to read before its next step — far stronger signal
+    // than a system-prompt rule it can attention-decay past.
+    //
+    // Phase 4R: state was previously a per-closure local; now it lives on a
+    // process-global Map keyed by sessionId so a registry rebuild between
+    // user turns / askcards no longer wipes it. See getBashRepeatState().
+    const repeatState = getBashRepeatState();
+    const repeatKey = resolveBashRepeatKey(opts?.sessionId);
     tools.bash = dynamicTool({
-        description: "Execute a shell command. Set background=true for long-running processes.",
+        description: "Execute a shell command. Output is automatically cached — every call returns a " +
+            "run_id you can re-query via bash_output_get(run_id, mode=tail|head|grep|lines). " +
+            "Do NOT pipe `| tail`, `| head`, `| grep`, or `> file` — that hides output from " +
+            "the cache. Run unpiped and slice via bash_output_get instead. For collecting system info (OS, versions, cwd layout, git, disk, processes) batch with ; or && in ONE call, e.g. 'uname -a; node -v; bun --version; ls -la | head -15; git status --short; df -h .; ps aux | head -5'. Set background=true for long-running processes (dev servers, watchers).",
         inputSchema: jsonSchema({
             type: "object",
             properties: {
@@ -97,12 +139,93 @@ export function createBuiltinTools(bash, mode, opts) {
             required: ["command"],
         }),
         execute: async (input) => {
+            // Corrective guard for malformed calls: a cheap model sometimes emits a
+            // bash call with a missing / empty `command` (live: deepseek sent `{}`
+            // repeatedly until the loop-guard fired). Passing undefined to
+            // bash.execute() throws an opaque TypeError that doesn't steer the model
+            // to self-correct, and a whitespace command "succeeds" with no output —
+            // both look like progress and feed the loop. Return a crisp instruction
+            // so the next step supplies a real command instead of repeating.
+            if (typeof input.command !== "string" || input.command.trim() === "") {
+                return 'ERROR: the `bash` tool requires a non-empty "command" string, but the call had empty arguments. Provide the shell command to run, e.g. {"command":"ls -la"}.';
+            }
             if (input.background) {
                 const result = await bash.startBackground(input.command);
                 return formatResult(result);
             }
+            // 3-3: compute canonical form BEFORE running so we can attach an
+            // inline reminder if it matches the previous bash call.
+            const cmd = typeof input.command === "string" ? input.command : "";
+            const canonical = cmd ? canonicalizeBashCommand(cmd) : "";
+            const entry = repeatState.get(repeatKey) ?? { lastCanonical: null, lastRunId: null };
+            const repeatedIntent = canonical !== "" && canonical === entry.lastCanonical && entry.lastRunId !== null;
+            const prevRunId = entry.lastRunId;
             const result = await bash.execute(input.command, input.timeout ?? 30000);
-            return formatResult(result);
+            const formatted = formatResult(result);
+            // Update last-canonical state AFTER we compared, so the current call's
+            // runId becomes the comparison target for the next one. Session-scoped
+            // map persists across createBuiltinTools() rebuilds (Phase 4R).
+            if (result.bashRunId) {
+                repeatState.set(repeatKey, { lastCanonical: canonical, lastRunId: result.bashRunId });
+            }
+            // 3-3 reminder rides on the tool_result of the SECOND+ same-intent
+            // bash call. Cheap models that ignored the system-prompt rule still
+            // see this — it's inside the actual tool output they parse next step.
+            const reminder = repeatedIntent
+                ? `\n\n[reminder: previous bash call had the same canonical intent and produced run_id=${prevRunId}. Use bash_output_get("${prevRunId}", mode=tail|head|grep|lines) to slice the cached output instead of re-running.]`
+                : "";
+            // 3-1: ALWAYS surface the run_id footer (no truncation gate). The
+            // previous gate created a Catch-22 — when the model used `| tail -40`,
+            // exec captured only ~5K, totalChars stayed below MAX_TOOL_OUTPUT_CHARS,
+            // footer never fired, model never learned the cache existed. The hint
+            // about bash_output_get fires only when the cached output is large
+            // enough that slicing makes sense (>= 4K chars).
+            if (result.bashRunId) {
+                const chars = result.bashTotalChars ?? 0;
+                const hint = chars >= 4_000
+                    ? ` — ${chars} chars cached; use bash_output_get(run_id, mode=tail|head|grep|lines) to re-query`
+                    : "";
+                return `${formatted}\n\n[bash_run_id: ${result.bashRunId}${hint}]${reminder}`;
+            }
+            return formatted;
+        },
+    });
+    // bash_output_get — re-query the cached full output of a previous bash run.
+    // Designed to break the "re-run vitest with different pipe flags" loop by
+    // letting the agent slice cached stdout/stderr instead.
+    tools.bash_output_get = dynamicTool({
+        description: "Re-query the full (untruncated, ANSI-stripped) stdout+stderr of a previous bash run by run_id. " +
+            "Use this INSTEAD of re-running the same command with different `| tail`, `| head`, `| grep`, or " +
+            "`> file` flags. Modes: head/tail (first/last N lines), grep (regex filter), lines (range N-M).",
+        inputSchema: jsonSchema({
+            type: "object",
+            properties: {
+                run_id: { type: "string", description: "Run ID from a previous bash result, e.g. 'bash-42'" },
+                mode: { type: "string", enum: ["head", "tail", "grep", "lines", "full"] },
+                lines: { type: "number", description: "Line count for head/tail (default 50)" },
+                pattern: { type: "string", description: "Regex pattern for grep mode" },
+                range: { type: "string", description: "Line range 'N-M' (1-based, inclusive) for lines mode" },
+                case_insensitive: { type: "boolean", description: "Case-insensitive grep (default false)" },
+            },
+            required: ["run_id", "mode"],
+        }),
+        execute: async (input) => {
+            const record = getBashRun(input.run_id);
+            if (!record) {
+                return truncateOutput(`ERROR: No cached bash run with id '${input.run_id}'. Cache holds up to 50 runs.`);
+            }
+            const slice = sliceBashOutput(record, {
+                mode: input.mode,
+                lines: input.lines,
+                pattern: input.pattern,
+                range: input.range,
+                caseInsensitive: input.case_insensitive,
+            });
+            if (!slice.ok) {
+                return truncateOutput(`ERROR: ${slice.text}`);
+            }
+            const meta = `[${input.run_id} mode=${input.mode} total_lines=${slice.totalLines}${slice.matchedLines !== undefined ? ` matched=${slice.matchedLines}` : ""} exit=${record.exitCode ?? "?"}]`;
+            return truncateOutput(`${meta}\n${slice.text}`);
         },
     });
     // process_logs
@@ -173,7 +296,7 @@ export function createBuiltinTools(bash, mode, opts) {
         });
         // edit_file
         tools.edit_file = dynamicTool({
-            description: "Replace a unique string in a file with new content. The old_string must appear exactly once. SAFETY: you must call read_file on the target in the same session before editing; if the file changed on disk after your read, re-read it first.",
+            description: "Replace a unique string in a file with new content. The old_string must appear exactly once. MANDATORY: call read_file on the same file_path EARLIER in this session before edit_file — the edit WILL fail with 'File must be read first' otherwise. Batch reads when editing multiple files (parallel tool calls), then issue edits. If the file changed on disk after your read, re-read it first.",
             inputSchema: jsonSchema({
                 type: "object",
                 properties: {
@@ -273,6 +396,83 @@ export function createBuiltinTools(bash, mode, opts) {
                 },
             });
         }
+        // ee_query — semantic recall over the Experience Engine brain. This is the
+        // in-CLI counterpart of the MCP `ee.query` tool (src/mcp/ee-tools.ts):
+        // without it, the Agent Operating Contract + checkpoint reminders instruct
+        // the agent to "Use ee_query tool with 'tool-artifact id=XXX'" to rehydrate
+        // compaction-elided tool outputs, but the in-CLI agent had no such tool in
+        // its loop (session d95113d3be09: the anti-mù rehydrate path was a dead
+        // reference). Elided outputs are persisted to EE (message-processor.ts,
+        // source="tool-artifact"); this tool retrieves them. Degrades gracefully:
+        // returns an ee_unavailable note when EE is down/unconfigured.
+        tools.ee_query = dynamicTool({
+            description: "Active recall over the Experience Engine brain (learned warnings/recipes + task checkpoints + " +
+                "compaction-elided tool outputs for this codebase). General queries run the recallMode pipeline " +
+                "(/api/recall — same path as exp-recall.js) and return a formatted index whose entries carry " +
+                '`[id col]` handles. Anti-mù rehydration: query="tool-artifact id=<id from a [... elided ...] stub>" ' +
+                'or "full tool result id=<id>" does an exact lookup. Also: query="recent compaction checkpoint ' +
+                'Progress DONE" to confirm finished work after a compaction. Returns hits, or an ee_unavailable note ' +
+                "when EE is down/unconfigured.",
+            inputSchema: jsonSchema({
+                type: "object",
+                properties: {
+                    query: { type: "string", description: "Natural-language recall query (or 'tool-artifact id=<id>')" },
+                    project: { type: "string", description: "Optional project slug to scope the recall (general queries only)" },
+                    collections: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Optional EE collections to scope an artifact lookup (e.g. ['experience-behavioral'])",
+                    },
+                    limit: { type: "number", description: "Max hits for an artifact lookup (1-50, default server-side)" },
+                    maxChars: {
+                        type: "number",
+                        description: "Max chars of the recall index to return (500-20000, default 6000; general queries only)",
+                    },
+                },
+                required: ["query"],
+            }),
+            execute: async (input) => {
+                const query = typeof input?.query === "string" ? input.query.trim() : "";
+                if (!query) {
+                    return 'ERROR: ee_query requires a non-empty "query" string (e.g. {"query":"tool-artifact id=abc123"}).';
+                }
+                try {
+                    if (isToolArtifactQuery(query)) {
+                        // Artifact rehydration → raw /api/search (exact-collection lookup).
+                        const { searchEE } = await import("../ee/search.js");
+                        const resp = await searchEE(query, {
+                            ...(Array.isArray(input?.collections) ? { collections: input.collections } : {}),
+                            ...(typeof input?.limit === "number" ? { limit: input.limit } : {}),
+                        });
+                        if (resp === null) {
+                            return "[ee_unavailable] Experience Engine returned no response (server down, timeout, circuit open, or unconfigured). Proceed without EE recall — re-read the source directly if you need the elided content.";
+                        }
+                        return truncateOutput(JSON.stringify(resp));
+                    }
+                    // General recall → /api/recall (recallMode, [id col] index + surface).
+                    const { recallEE, formatRecallForAgent } = await import("../ee/search.js");
+                    const resp = await recallEE(query, {
+                        ...(typeof input?.project === "string" ? { project: input.project } : {}),
+                    });
+                    if (resp === null) {
+                        return "[ee_unavailable] Experience Engine returned no response (server down, timeout, circuit open, or unconfigured). Proceed without EE recall — re-read the source directly if you need the elided content.";
+                    }
+                    // Compact ranked `[id col]` index, not a JSON dump — the recallMode text
+                    // is ~30k (wide net), so JSON.stringify wasted the budget on escaping.
+                    return truncateOutput(formatRecallForAgent(resp, {
+                        query,
+                        ...(typeof input?.maxChars === "number" ? { maxChars: input.maxChars } : {}),
+                    }));
+                }
+                catch (err) {
+                    console.error(`[tools:ee_query] EE recall failed: ${err?.message}`, {
+                        query: query.slice(0, 120),
+                        stack: err?.stack?.split("\n").slice(0, 3),
+                    });
+                    return `[ee_unavailable] EE recall threw: ${err?.message ?? String(err)}. Proceed without EE recall.`;
+                }
+            },
+        });
     }
     // Vision proxy tools — only for text-only models (DeepSeek, etc.)
     if (opts?.modelId && needsVisionProxy(opts.modelId)) {
@@ -340,6 +540,64 @@ export function createBuiltinTools(bash, mode, opts) {
                     .join("\n");
             },
         });
+        // todo_write — Claude-Code-style task list. Each call REPLACES the agent's
+        // current todo snapshot; the orchestrator post-processes this tool's args
+        // into a task_list_update StreamChunk that the UI renders as a sticky
+        // checklist panel. Status flow: pending → in_progress → completed; only
+        // ONE item should be in_progress at a time. Use this when the user asks
+        // for a multi-step task (≥3 distinct steps) so progress is visible.
+        tools.todo_write = dynamicTool({
+            description: "Write the full current todo list. Replaces the previous list entirely on every call (no partial updates). Use when a user request resolves into ≥3 discrete steps so the UI can show progress. Mark exactly one item as in_progress at a time. Always emit the FULL list, not just the changed items.",
+            inputSchema: jsonSchema({
+                type: "object",
+                properties: {
+                    todos: {
+                        type: "array",
+                        description: "The full ordered list of todo items. Replaces any prior list. Keep order stable across updates so the UI doesn't reshuffle on every call.",
+                        items: {
+                            type: "object",
+                            properties: {
+                                id: { type: "string", description: "Stable id across updates (e.g. '1','2', or a slug)." },
+                                subject: { type: "string", description: "Short imperative title shown in the list." },
+                                activeForm: {
+                                    type: "string",
+                                    description: "Present-continuous form shown while in_progress (e.g. 'Reading files'). Falls back to subject when absent.",
+                                },
+                                status: {
+                                    type: "string",
+                                    enum: ["pending", "in_progress", "completed"],
+                                    description: "Item status. Only ONE item should be in_progress at any time.",
+                                },
+                            },
+                            required: ["id", "subject", "status"],
+                        },
+                    },
+                },
+                required: ["todos"],
+            }),
+            execute: async (input) => {
+                const todos = Array.isArray(input?.todos)
+                    ? input.todos
+                    : [];
+                const counts = { completed: 0, inProgress: 0, pending: 0, total: todos.length };
+                for (const t of todos) {
+                    if (t.status === "completed")
+                        counts.completed++;
+                    else if (t.status === "in_progress")
+                        counts.inProgress++;
+                    else
+                        counts.pending++;
+                }
+                return `Tracking ${counts.total} todo${counts.total !== 1 ? "s" : ""}: ${counts.completed} done · ${counts.inProgress} in progress · ${counts.pending} queued.`;
+            },
+        });
+    }
+    // Vision-tool gate: drop the 3 vision-proxy tools on turns with no plausible
+    // image involvement. Built then deleted (closures are cheap) to avoid
+    // re-indenting the tool definitions above. todo_write + core tools untouched.
+    if (opts?.includeVisionTools === false) {
+        for (const name of VISION_TOOL_NAMES)
+            delete tools[name];
     }
     return tools;
 }

package/dist/src/tools/schedule.test.js

@@ -34,7 +34,7 @@ async function importScheduleModule(options = {}) {
 }
 afterEach(() => {
     for (const dir of tempDirs.splice(0)) {
-        fs.rmSync(dir, { recursive: true, force: true });
+        fs.rmSync(dir, { recursive: true, force: true, maxRetries: 10, retryDelay: 50 });
     }
     vi.restoreAllMocks();
     vi.resetModules();

package/dist/src/tools/todo-write-snapshot.d.ts

@@ -0,0 +1,18 @@
+/**
+ * src/tools/todo-write-snapshot.ts
+ *
+ * Parse the `todo_write` tool's arguments into a TaskListSnapshot the UI can
+ * render. Pure / total — invalid input collapses to an empty snapshot instead
+ * of throwing, so a malformed tool call never poisons the stream.
+ *
+ * The tool itself is registered in `src/tools/registry.ts`. This module is the
+ * bridge between the raw argument JSON and the typed snapshot the orchestrator
+ * yields as a `task_list_update` StreamChunk.
+ */
+import type { TaskListSnapshot } from "../types/index.js";
+/**
+ * Parse the JSON-encoded arguments string of a `todo_write` tool call.
+ * Returns null when the input is unparseable or contains zero valid items,
+ * so the orchestrator can skip emitting an empty chunk.
+ */
+export declare function snapshotFromTodoWriteArgs(argsJson: string): TaskListSnapshot | null;

package/dist/src/tools/todo-write-snapshot.js

@@ -0,0 +1,66 @@
+/**
+ * src/tools/todo-write-snapshot.ts
+ *
+ * Parse the `todo_write` tool's arguments into a TaskListSnapshot the UI can
+ * render. Pure / total — invalid input collapses to an empty snapshot instead
+ * of throwing, so a malformed tool call never poisons the stream.
+ *
+ * The tool itself is registered in `src/tools/registry.ts`. This module is the
+ * bridge between the raw argument JSON and the typed snapshot the orchestrator
+ * yields as a `task_list_update` StreamChunk.
+ */
+const VALID_STATUSES = ["pending", "in_progress", "completed"];
+function coerceStatus(raw) {
+    return typeof raw === "string" && VALID_STATUSES.includes(raw)
+        ? raw
+        : "pending";
+}
+function parseItem(raw, idx) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const obj = raw;
+    const id = typeof obj.id === "string" && obj.id ? obj.id : `t-${idx}`;
+    const subject = typeof obj.subject === "string" && obj.subject.trim() ? obj.subject : null;
+    if (!subject)
+        return null;
+    const activeForm = typeof obj.activeForm === "string" && obj.activeForm.trim() ? obj.activeForm.trim() : undefined;
+    return { id, subject, status: coerceStatus(obj.status), ...(activeForm ? { activeForm } : {}) };
+}
+/**
+ * Parse the JSON-encoded arguments string of a `todo_write` tool call.
+ * Returns null when the input is unparseable or contains zero valid items,
+ * so the orchestrator can skip emitting an empty chunk.
+ */
+export function snapshotFromTodoWriteArgs(argsJson) {
+    let parsed;
+    try {
+        parsed = JSON.parse(argsJson);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== "object")
+        return null;
+    const todos = parsed.todos;
+    if (!Array.isArray(todos) || todos.length === 0)
+        return null;
+    const items = [];
+    todos.forEach((t, i) => {
+        const item = parseItem(t, i);
+        if (item)
+            items.push(item);
+    });
+    if (items.length === 0)
+        return null;
+    const counts = { completed: 0, inProgress: 0, pending: 0, total: items.length };
+    for (const it of items) {
+        if (it.status === "completed")
+            counts.completed++;
+        else if (it.status === "in_progress")
+            counts.inProgress++;
+        else
+            counts.pending++;
+    }
+    return { items, counts, ts: Date.now() };
+}
+//# sourceMappingURL=todo-write-snapshot.js.map

package/dist/src/tools/todo-write-snapshot.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/tools/todo-write-snapshot.test.js

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import { snapshotFromTodoWriteArgs } from "./todo-write-snapshot.js";
+function args(todos) {
+    return JSON.stringify({ todos });
+}
+describe("snapshotFromTodoWriteArgs", () => {
+    it("returns null for unparseable JSON", () => {
+        expect(snapshotFromTodoWriteArgs("not-json")).toBeNull();
+    });
+    it("returns null when todos is missing or empty", () => {
+        expect(snapshotFromTodoWriteArgs("{}")).toBeNull();
+        expect(snapshotFromTodoWriteArgs(args([]))).toBeNull();
+    });
+    it("parses a well-formed list and computes counts", () => {
+        const snap = snapshotFromTodoWriteArgs(args([
+            { id: "1", subject: "Write tests", status: "completed" },
+            { id: "2", subject: "Wire UI", status: "in_progress", activeForm: "Wiring UI" },
+            { id: "3", subject: "Ship", status: "pending" },
+        ]));
+        expect(snap).not.toBeNull();
+        expect(snap.items).toHaveLength(3);
+        expect(snap.items[1].activeForm).toBe("Wiring UI");
+        expect(snap.counts).toMatchObject({ completed: 1, inProgress: 1, pending: 1, total: 3 });
+    });
+    it("coerces unknown status to 'pending'", () => {
+        const snap = snapshotFromTodoWriteArgs(args([{ id: "1", subject: "x", status: "weird" }]));
+        expect(snap.items[0].status).toBe("pending");
+    });
+    it("drops items missing a subject (preserves the rest)", () => {
+        const snap = snapshotFromTodoWriteArgs(args([
+            { id: "1", subject: "Keep me", status: "pending" },
+            { id: "2", status: "pending" }, // no subject → dropped
+            { id: "3", subject: "   ", status: "pending" }, // blank subject → dropped
+        ]));
+        expect(snap.items).toHaveLength(1);
+        expect(snap.items[0].subject).toBe("Keep me");
+    });
+    it("assigns synthetic ids when missing", () => {
+        const snap = snapshotFromTodoWriteArgs(args([{ subject: "no id here", status: "pending" }]));
+        expect(snap.items[0].id).toBe("t-0");
+    });
+});
+//# sourceMappingURL=todo-write-snapshot.test.js.map

package/dist/src/tools/vision-gate.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Vision-tool gating.
+ *
+ * For text-only models the registry adds 3 vision-proxy tools
+ * (analyze_image, ask_vision_proxy, list_vision_cache) so the model can "see"
+ * images through a proxy. Their schemas carry long descriptions (~500-700
+ * input tokens total) and load on EVERY turn for those models — including the
+ * overwhelming majority of turns that involve no image at all.
+ *
+ * This gate drops the 3 vision tools ONLY when the turn cannot possibly need
+ * them. The bias is deliberately KEEP-not-drop: vision tools are retained
+ * whenever there is any plausible image involvement, so we never strip a
+ * capability a real turn needs (the BUG-A failure mode). They are dropped only
+ * when ALL of these are false:
+ *   - the message text references an image (path/extension/data-uri/keyword),
+ *   - the turn's messages carry an actual image content part (attachment),
+ *   - there are cached images from earlier turns (a follow-up may query them),
+ *   - a prior turn already issued tool calls (conservative continuation guard).
+ *
+ * `todo_write` and all core code tools are NEVER affected by this gate.
+ */
+/** The exact tool ids this gate governs. Core/code/todo tools are excluded. */
+export declare const VISION_TOOL_NAMES: readonly ["analyze_image", "ask_vision_proxy", "list_vision_cache"];
+/** True if any message in the turn carries an image (or image-typed) content part. */
+export declare function messagesHaveImagePart(messages: unknown[] | undefined): boolean;
+export interface VisionGateInput {
+    /** The current user message text. */
+    userMessage: string;
+    /** The full message list for the turn (to detect image attachments). */
+    messages?: unknown[];
+    /** How many images are cached from earlier turns (ask_vision_proxy targets). */
+    cachedImageCount?: number;
+    /** Whether a prior turn already issued tool calls (continuation guard). */
+    priorTurnHadTools?: boolean;
+}
+/**
+ * Decide whether the 3 vision tools should be included this turn. Returns true
+ * (keep) on any plausible image involvement; false (drop) only for a pure-text
+ * turn with no image anywhere and no image/tool history.
+ */
+export declare function visionToolsNeeded(input: VisionGateInput): boolean;

package/dist/src/tools/vision-gate.js

@@ -0,0 +1,67 @@
+/**
+ * Vision-tool gating.
+ *
+ * For text-only models the registry adds 3 vision-proxy tools
+ * (analyze_image, ask_vision_proxy, list_vision_cache) so the model can "see"
+ * images through a proxy. Their schemas carry long descriptions (~500-700
+ * input tokens total) and load on EVERY turn for those models — including the
+ * overwhelming majority of turns that involve no image at all.
+ *
+ * This gate drops the 3 vision tools ONLY when the turn cannot possibly need
+ * them. The bias is deliberately KEEP-not-drop: vision tools are retained
+ * whenever there is any plausible image involvement, so we never strip a
+ * capability a real turn needs (the BUG-A failure mode). They are dropped only
+ * when ALL of these are false:
+ *   - the message text references an image (path/extension/data-uri/keyword),
+ *   - the turn's messages carry an actual image content part (attachment),
+ *   - there are cached images from earlier turns (a follow-up may query them),
+ *   - a prior turn already issued tool calls (conservative continuation guard).
+ *
+ * `todo_write` and all core code tools are NEVER affected by this gate.
+ */
+/** The exact tool ids this gate governs. Core/code/todo tools are excluded. */
+export const VISION_TOOL_NAMES = ["analyze_image", "ask_vision_proxy", "list_vision_cache"];
+/**
+ * Image references in free text: an image file extension, a data: image URI, or
+ * common image vocabulary (English + Vietnamese). Broad on purpose — a false
+ * positive merely KEEPS the vision tools (costs tokens), never drops a needed one.
+ */
+// Note: \b is ASCII-only, so Vietnamese diacritic terms (ảnh/hình) are matched
+// as bare substrings in a trailing alternation rather than inside \b(...)\b.
+const IMAGE_SIGNAL_RE = /\.(png|jpe?g|gif|webp|svg|bmp|tiff?|heic|avif|ico)\b|data:image\/|\b(image|images|screenshot|screenshots|screen-?shot|picture|photo|photos|diagram|mockup|wireframe|figma|canva|chart|graph|logo|icon|thumbnail)\b|ảnh|hình|hinh/i;
+/** True if any message in the turn carries an image (or image-typed) content part. */
+export function messagesHaveImagePart(messages) {
+    if (!Array.isArray(messages))
+        return false;
+    for (const m of messages) {
+        const content = m?.content;
+        if (!Array.isArray(content))
+            continue;
+        for (const part of content) {
+            if (!part || typeof part !== "object")
+                continue;
+            const type = part.type;
+            if (type === "image" || type === "image_url" || type === "file")
+                return true;
+            const mediaType = part.mediaType;
+            if (typeof mediaType === "string" && mediaType.startsWith("image/"))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * Decide whether the 3 vision tools should be included this turn. Returns true
+ * (keep) on any plausible image involvement; false (drop) only for a pure-text
+ * turn with no image anywhere and no image/tool history.
+ */
+export function visionToolsNeeded(input) {
+    if (input.priorTurnHadTools)
+        return true;
+    if ((input.cachedImageCount ?? 0) > 0)
+        return true;
+    if (messagesHaveImagePart(input.messages))
+        return true;
+    return IMAGE_SIGNAL_RE.test(input.userMessage ?? "");
+}
+//# sourceMappingURL=vision-gate.js.map