@burtson-labs/agent-core 1.6.13

package/dist/tools/loop/singleToolExecute.js

@@ -0,0 +1,139 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createToolDispatcher = createToolDispatcher;
+const tool_use_parser_1 = require("../tool-use-parser");
+function createToolDispatcher(deps) {
+    const { registry, ctx, beforeToolExecute, emit, recentCallKeys, repeatLimit, filesReadThisTurn, filesWrittenThisTurn, isFileEditTool, onEditToolSucceeded } = deps;
+    return async function dispatchOne(tc) {
+        // Build a coarse signature for repeat detection. For file-writing
+        // tools (write_file, apply_edit, replace_range) we key on path + a short hash of
+        // the find/replace/content so we catch "same edit retried with
+        // same payload" (the original target — model corrupted a write
+        // and is looping) WITHOUT flagging "8 different edits to the
+        // same file" (legitimate batch refactor — // on S3Api with gpt-oss commenting all methods in one .cs file).
+        // For other tools we fall back to a truncated JSON of the params
+        // so unrelated calls don't collide.
+        const pathish = tc.params.path ?? tc.params.file ?? tc.params.filepath;
+        const isEditTool = tc.name === 'apply_edit' || tc.name === 'replace_range' || tc.name === 'write_file';
+        let callKey;
+        if (pathish && isEditTool) {
+            // Cheap deterministic hash of the payload — enough to
+            // distinguish 8 different edits to the same file. Not
+            // crypto, just collision-resistant for a window of 3 calls.
+            const payload = `${tc.params.find ?? ''}::${tc.params.replace ?? ''}::${tc.params.content ?? ''}::${tc.params.start_line ?? ''}::${tc.params.end_line ?? ''}`;
+            let h = 0;
+            for (let i = 0; i < payload.length; i++) {
+                h = (h * 31 + payload.charCodeAt(i)) | 0;
+            }
+            callKey = `${tc.name}::${pathish}::${h.toString(36)}`;
+        }
+        else if (pathish) {
+            callKey = `${tc.name}::${pathish}`;
+        }
+        else {
+            callKey = `${tc.name}::${JSON.stringify(tc.params).slice(0, 160)}`;
+        }
+        recentCallKeys.push(callKey);
+        if (recentCallKeys.length > repeatLimit)
+            recentCallKeys.shift();
+        if (recentCallKeys.length === repeatLimit &&
+            recentCallKeys.every((k) => k === callKey)) {
+            emit('tool_loop:repeat_breaker', { name: tc.name, key: callKey });
+            return {
+                name: tc.name,
+                output: `Loop detected: ${tc.name} has been invoked ${repeatLimit} times in a row against the same target (${pathish ?? 'identical params'}) without progress. This usually means the last write landed malformed — most often an unescaped \`"\` inside the JSON content string truncated the file. STOP retrying. Either (a) produce a final answer that explains the issue to the user, or (b) break the content into smaller edits. Do not call ${tc.name} with these params again.`,
+                isError: true
+            };
+        }
+        const tool = registry.get(tc.name);
+        if (!tool) {
+            emit('tool_loop:tool_not_found', { name: tc.name });
+            return { name: tc.name, output: `Error: tool "${tc.name}" is not registered.`, isError: true };
+        }
+        // Also surface the RAW tool_call block (first 400 chars) so
+        // observers can diagnose parser-edge cases. When a param
+        // extraction goes wrong (unknown wrapper key, nested array,
+        // etc.) the isError result is the symptom; the raw block is
+        // the evidence. Without it, debugging an empty-params call
+        // requires re-running with extra instrumentation.
+        //
+        // NOTE: the edit-tool counter is incremented inside the try
+        // block below, AFTER the result returns and only when
+        // `!result.isError`. Counting attempts (which an earlier
+        // version did at this point) made the false-completion
+        // detector blind to the worst variant of the hallucination:
+        // model fires 8 apply_edits, every single one fails with
+        // "find not found", model produces a confident "I have
+        // fixed the bug" summary. The counter said 8, the detector
+        // saw a non-zero count, the user read the lie. Observed
+        // 2026-05-01 on the bandit website's plans.tsx grid bug.
+        emit('tool_loop:tool_execute', {
+            name: tc.name,
+            params: tc.params,
+            rawSnippet: tc.raw.slice(0, 400)
+        });
+        const gate = await beforeToolExecute({ name: tc.name, params: tc.params });
+        if (!gate.allow) {
+            const reason = gate.reason ?? 'blocked by pre-execute guard';
+            emit('tool_loop:tool_blocked', { name: tc.name, reason });
+            return { name: tc.name, output: `Blocked: ${reason}`, isError: true };
+        }
+        try {
+            const result = await tool.execute(tc.params, ctx);
+            // Only count edits that actually landed. A `find`-not-found
+            // or schema-rejected edit returns isError:true and changed
+            // nothing on disk; counting it would let the false-
+            // completion detector wave through "I have fixed the bug"
+            // claims that are false.
+            const normalizeFilePath = (raw) => {
+                if (typeof raw !== 'string' || !raw)
+                    return null;
+                // Use basename so `src/App.jsx` and `~/proj/src/App.jsx`
+                // collide — the user's goal text typically uses the bare
+                // filename so a basename comparison is the most forgiving
+                // way to ask "did we touch the file the user named?".
+                const parts = raw.split(/[/\\]/);
+                return parts[parts.length - 1].toLowerCase();
+            };
+            if (isFileEditTool(tc.name) && !result.isError) {
+                onEditToolSucceeded();
+                const p = tc.params?.path;
+                const norm = normalizeFilePath(p);
+                if (norm)
+                    filesWrittenThisTurn.add(norm);
+            }
+            if (tc.name === 'read_file' && !result.isError) {
+                const p = tc.params?.path;
+                const norm = normalizeFilePath(p);
+                if (norm)
+                    filesReadThisTurn.add(norm);
+            }
+            // Include a short output snippet in the event — critical for
+            // downstream observers (eval runner, turn log) to know WHY
+            // a tool errored rather than just THAT it did. Capped so long
+            // successful results don't flood the event bus.
+            //
+            // outputSnippet is rendered to the host UI (tool
+            // cards in the extension, dim recap in the CLI). Redact
+            // before emitting so the user's terminal scrollback doesn't
+            // capture raw secrets even when the model's context
+            // already has the redacted version. The model-facing path
+            // goes through buildToolResultsMessage → formatToolResult,
+            // which already applies the same redactor at the parser
+            // boundary, so both paths converge on the same masked text.
+            emit('tool_loop:tool_result', {
+                name: tc.name,
+                isError: result.isError,
+                outputLength: result.output.length,
+                outputSnippet: (0, tool_use_parser_1.applySecretRedactionIfEnabled)(result.output.slice(0, 280))
+            });
+            return { name: tc.name, output: result.output, isError: result.isError };
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            emit('tool_loop:tool_error', { name: tc.name, error: msg });
+            return { name: tc.name, output: `Error executing tool "${tc.name}": ${msg}`, isError: true };
+        }
+    };
+}
+//# sourceMappingURL=singleToolExecute.js.map

package/dist/tools/loop/singleToolExecute.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"singleToolExecute.js","sourceRoot":"","sources":["../../../src/tools/loop/singleToolExecute.ts"],"names":[],"mappings":"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"}

package/dist/tools/loop/toolCallNormalize.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Tool-call batch normalization for ToolUseLoop.runWithMessages.
+ *
+ * After parseToolCalls returns the raw list of `<tool_call>` blocks the
+ * model emitted in one iteration, the loop has to:
+ *
+ *   1. Drop byte-identical duplicate calls (panic-fanout mode emits the
+ *      same search multiple times — observed 2026-04-26 with gpt-oss:120b
+ *      on H100 fanning out 25 calls in one iteration, four of them
+ *      identical `search_code writeInsightsReport`s).
+ *   2. Keep at most ONE foreground (synchronous) `task` call per
+ *      iteration — the model can't make progress on three subagents
+ *      simultaneously and the wait time stacks.
+ *   3. Slice the batch to `maxParallelTools` so a 25-call fanout
+ *      doesn't drown the next iteration's tool-result payload.
+ *   4. Slice further to fit the remaining per-turn budget
+ *      (`maxTotalTools - totalToolsExecuted`).
+ *
+ * Each step emits a telemetry event on the loop's `emit` sink so hosts
+ * can surface "we dropped N duplicates" / "we capped at N parallel" in
+ * the UI. The caller updates `totalToolsExecuted` from the returned
+ * `accepted` count.
+ *
+ * Pure with respect to the loop's mutable state: input is a `ToolCall[]`,
+ * output is a new `ToolCall[]` plus drop counts plus the events emitted
+ * via the supplied callback. The original input list is not mutated.
+ */
+import type { ParsedToolCall } from '../tool-use-parser';
+export type ToolCallNormalizeEmit = (type: string, payload?: unknown) => void;
+export interface NormalizeToolCallBatchArgs {
+    /** The raw parsed list straight off this iteration's chat response. */
+    toolCalls: ReadonlyArray<ParsedToolCall>;
+    /** Iteration index — used as the event `iteration` field. */
+    iteration: number;
+    /** Max calls executed in parallel within a single iteration. */
+    maxParallelTools: number;
+    /** Hard cap on tool calls across the full turn. */
+    maxTotalTools: number;
+    /** Running total of tools executed prior to this iteration. */
+    totalToolsExecuted: number;
+    /** Event sink (typically the loop's `emit`). */
+    emit: ToolCallNormalizeEmit;
+}
+export interface NormalizeToolCallBatchResult {
+    /** The final list of calls to execute this iteration. */
+    accepted: ParsedToolCall[];
+    /** Byte-identical duplicates removed. */
+    dedupedCount: number;
+    /** Excess foreground `task` calls dropped (kept at most one). */
+    droppedForegroundTaskCalls: number;
+    /** Calls dropped because the batch exceeded `maxParallelTools`. */
+    droppedParallelCap: number;
+    /** Calls dropped because the batch would exceed the per-turn cap. */
+    droppedTotalCap: number;
+}
+export declare function normalizeToolCallBatch(args: NormalizeToolCallBatchArgs): NormalizeToolCallBatchResult;
+//# sourceMappingURL=toolCallNormalize.d.ts.map

package/dist/tools/loop/toolCallNormalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolCallNormalize.d.ts","sourceRoot":"","sources":["../../../src/tools/loop/toolCallNormalize.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAEzD,MAAM,MAAM,qBAAqB,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;AAE9E,MAAM,WAAW,0BAA0B;IACzC,uEAAuE;IACvE,SAAS,EAAE,aAAa,CAAC,cAAc,CAAC,CAAC;IACzC,6DAA6D;IAC7D,SAAS,EAAE,MAAM,CAAC;IAClB,gEAAgE;IAChE,gBAAgB,EAAE,MAAM,CAAC;IACzB,mDAAmD;IACnD,aAAa,EAAE,MAAM,CAAC;IACtB,+DAA+D;IAC/D,kBAAkB,EAAE,MAAM,CAAC;IAC3B,gDAAgD;IAChD,IAAI,EAAE,qBAAqB,CAAC;CAC7B;AAED,MAAM,WAAW,4BAA4B;IAC3C,yDAAyD;IACzD,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,yCAAyC;IACzC,YAAY,EAAE,MAAM,CAAC;IACrB,iEAAiE;IACjE,0BAA0B,EAAE,MAAM,CAAC;IACnC,mEAAmE;IACnE,kBAAkB,EAAE,MAAM,CAAC;IAC3B,qEAAqE;IACrE,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,wBAAgB,sBAAsB,CAAC,IAAI,EAAE,0BAA0B,GAAG,4BAA4B,CAoGrG"}

package/dist/tools/loop/toolCallNormalize.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeToolCallBatch = normalizeToolCallBatch;
+function normalizeToolCallBatch(args) {
+    const { iteration, maxParallelTools, maxTotalTools, totalToolsExecuted, emit } = args;
+    let accepted = [...args.toolCalls];
+    // 1. Byte-identical dedup. `${name}::${JSON.stringify(params)}` is the
+    // signature. Only runs when there are 2+ calls — single-call iterations
+    // can't contain a duplicate of themselves.
+    let dedupedCount = 0;
+    if (accepted.length > 1) {
+        const seen = new Set();
+        const deduped = [];
+        for (const tc of accepted) {
+            const sig = `${tc.name}::${JSON.stringify(tc.params)}`;
+            if (seen.has(sig)) {
+                dedupedCount++;
+                continue;
+            }
+            seen.add(sig);
+            deduped.push(tc);
+        }
+        if (dedupedCount > 0) {
+            emit('tool_loop:tool_call_deduped', {
+                iteration,
+                removed: dedupedCount,
+                kept: deduped.length
+            });
+        }
+        accepted = deduped;
+    }
+    // 2. Foreground-task fanout cap. A `task` call with
+    // run_in_background != 'true' blocks the parent iteration on the
+    // subagent's completion; running multiple in one iteration stacks
+    // serially. Keep the first foreground task, drop the rest. Background
+    // tasks are unaffected — they're fire-and-forget.
+    let droppedForegroundTaskCalls = 0;
+    if (accepted.length > 1) {
+        let keptForegroundTask = false;
+        const scoped = [];
+        for (const tc of accepted) {
+            const isForegroundTask = tc.name === 'task' &&
+                String(tc.params.run_in_background ?? '').toLowerCase() !== 'true';
+            if (!isForegroundTask) {
+                scoped.push(tc);
+                continue;
+            }
+            if (!keptForegroundTask) {
+                scoped.push(tc);
+                keptForegroundTask = true;
+                continue;
+            }
+            droppedForegroundTaskCalls++;
+        }
+        if (droppedForegroundTaskCalls > 0) {
+            emit('tool_loop:foreground_task_fanout_capped', {
+                iteration,
+                kept: 1,
+                dropped: droppedForegroundTaskCalls
+            });
+            accepted = scoped;
+        }
+    }
+    // 3. Per-iteration parallel cap.
+    let droppedParallelCap = 0;
+    if (accepted.length > maxParallelTools) {
+        droppedParallelCap = accepted.length - maxParallelTools;
+        emit('tool_loop:tool_call_capped', {
+            iteration,
+            requested: accepted.length + 0,
+            kept: maxParallelTools,
+            dropped: droppedParallelCap
+        });
+        accepted = accepted.slice(0, maxParallelTools);
+    }
+    // 4. Per-turn total cap. Slice to fit remaining budget; the next
+    // iteration short-circuits on the count check.
+    let droppedTotalCap = 0;
+    const remainingBudget = Math.max(0, maxTotalTools - totalToolsExecuted);
+    if (accepted.length > remainingBudget) {
+        droppedTotalCap = accepted.length - remainingBudget;
+        emit('tool_loop:tool_call_total_capped', {
+            iteration,
+            requested: accepted.length,
+            kept: remainingBudget,
+            totalSoFar: totalToolsExecuted,
+            maxTotalTools
+        });
+        accepted = accepted.slice(0, remainingBudget);
+    }
+    return {
+        accepted,
+        dedupedCount,
+        droppedForegroundTaskCalls,
+        droppedParallelCap,
+        droppedTotalCap
+    };
+}
+//# sourceMappingURL=toolCallNormalize.js.map

package/dist/tools/loop/toolCallNormalize.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toolCallNormalize.js","sourceRoot":"","sources":["../../../src/tools/loop/toolCallNormalize.ts"],"names":[],"mappings":"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"}

package/dist/tools/loop/turnSetup.d.ts

@@ -0,0 +1,43 @@
+/**
+ * One-shot setup helpers for ToolUseLoop.runWithMessages — work that
+ * runs once per turn BEFORE the iteration loop.
+ *
+ * Current contents: `resolveTurnGoal`. Future Session 1/2/3 extractions
+ * (system-prompt assembly, native-tools schema build, counter init)
+ * will land here too. Kept under `loop/` so the orchestrator imports
+ * stay grouped with the other Arc 3 modules.
+ */
+import type { ToolLoopMessage } from '../tool-types';
+export interface ResolveTurnGoalArgs {
+    seedMessages: ReadonlyArray<ToolLoopMessage>;
+}
+export interface ResolvedTurnGoal {
+    /** The user message that anchors THIS turn — what the model is being
+     * asked to do right now. Used by the goal-anchor reminder injected
+     * before final-answer iterations to defeat recency bias from long
+     * tool-result chains. Empty string when the seed has no user message. */
+    originalGoal: string;
+    /** Count of earlier user prompts in the seed history (everything
+     * before the most-recent substantive one). Used by the goal-anchor
+     * injection to add an "ignore prior prompts" note when there are
+     * earlier conversation turns the model might confuse for the goal. */
+    priorUserPromptCount: number;
+}
+/**
+ * Resolve the per-turn goal anchor from the seed message history.
+ *
+ * Walks the seed messages forward to find the most-recent user prompt.
+ * If that prompt is a bare continuation token ("keep going", "yes",
+ * "good lets keep going" — see CONTINUATION_PROMPT_PHRASES in
+ * tool-use-loop.ts), walks BACKWARD through history for the most
+ * recent SUBSTANTIVE prompt and anchors on that instead.
+ *
+ * Why the walkback: the original bug was a 60-iteration linter-fix
+ * turn that anchored every iteration on "good lets keep going"
+ * because that was the literal last user message. The recall block
+ * became "remind yourself to keep going" and gave the model zero
+ * useful steering. Walking back finds the real goal ("fix the
+ * remaining TS errors") and uses THAT as the anchor.
+ */
+export declare function resolveTurnGoal(args: ResolveTurnGoalArgs): ResolvedTurnGoal;
+//# sourceMappingURL=turnSetup.d.ts.map

package/dist/tools/loop/turnSetup.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"turnSetup.d.ts","sourceRoot":"","sources":["../../../src/tools/loop/turnSetup.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAGrD,MAAM,WAAW,mBAAmB;IAClC,YAAY,EAAE,aAAa,CAAC,eAAe,CAAC,CAAC;CAC9C;AAED,MAAM,WAAW,gBAAgB;IAC/B;;;6EAGyE;IACzE,YAAY,EAAE,MAAM,CAAC;IACrB;;;0EAGsE;IACtE,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,mBAAmB,GAAG,gBAAgB,CAuB3E"}

package/dist/tools/loop/turnSetup.js

@@ -0,0 +1,48 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveTurnGoal = resolveTurnGoal;
+const tool_use_loop_1 = require("../tool-use-loop");
+/**
+ * Resolve the per-turn goal anchor from the seed message history.
+ *
+ * Walks the seed messages forward to find the most-recent user prompt.
+ * If that prompt is a bare continuation token ("keep going", "yes",
+ * "good lets keep going" — see CONTINUATION_PROMPT_PHRASES in
+ * tool-use-loop.ts), walks BACKWARD through history for the most
+ * recent SUBSTANTIVE prompt and anchors on that instead.
+ *
+ * Why the walkback: the original bug was a 60-iteration linter-fix
+ * turn that anchored every iteration on "good lets keep going"
+ * because that was the literal last user message. The recall block
+ * became "remind yourself to keep going" and gave the model zero
+ * useful steering. Walking back finds the real goal ("fix the
+ * remaining TS errors") and uses THAT as the anchor.
+ */
+function resolveTurnGoal(args) {
+    const { seedMessages } = args;
+    let originalGoal = '';
+    let priorUserPromptCount = 0;
+    for (const msg of seedMessages) {
+        if (msg.role === 'user' && typeof msg.content === 'string' && msg.content.trim()) {
+            if (originalGoal)
+                priorUserPromptCount++;
+            originalGoal = msg.content;
+        }
+    }
+    if (originalGoal && (0, tool_use_loop_1.isContinuationPrompt)(originalGoal)) {
+        for (let i = seedMessages.length - 1; i >= 0; i--) {
+            const m = seedMessages[i];
+            if (m.role !== 'user' || typeof m.content !== 'string')
+                continue;
+            const c = m.content.trim();
+            if (!c)
+                continue;
+            if (!(0, tool_use_loop_1.isContinuationPrompt)(c)) {
+                originalGoal = m.content;
+                break;
+            }
+        }
+    }
+    return { originalGoal, priorUserPromptCount };
+}
+//# sourceMappingURL=turnSetup.js.map

package/dist/tools/loop/turnSetup.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"turnSetup.js","sourceRoot":"","sources":["../../../src/tools/loop/turnSetup.ts"],"names":[],"mappings":";;AA6CA,0CAuBC;AA1DD,oDAAwD;AAmBxD;;;;;;;;;;;;;;;GAeG;AACH,SAAgB,eAAe,CAAC,IAAyB;IACvD,MAAM,EAAE,YAAY,EAAE,GAAG,IAAI,CAAC;IAC9B,IAAI,YAAY,GAAG,EAAE,CAAC;IACtB,IAAI,oBAAoB,GAAG,CAAC,CAAC;IAC7B,KAAK,MAAM,GAAG,IAAI,YAAY,EAAE,CAAC;QAC/B,IAAI,GAAG,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO,GAAG,CAAC,OAAO,KAAK,QAAQ,IAAI,GAAG,CAAC,OAAO,CAAC,IAAI,EAAE,EAAE,CAAC;YACjF,IAAI,YAAY;gBAAE,oBAAoB,EAAE,CAAC;YACzC,YAAY,GAAG,GAAG,CAAC,OAAO,CAAC;QAC7B,CAAC;IACH,CAAC;IACD,IAAI,YAAY,IAAI,IAAA,oCAAoB,EAAC,YAAY,CAAC,EAAE,CAAC;QACvD,KAAK,IAAI,CAAC,GAAG,YAAY,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAClD,MAAM,CAAC,GAAG,YAAY,CAAC,CAAC,CAAC,CAAC;YAC1B,IAAI,CAAC,CAAC,IAAI,KAAK,MAAM,IAAI,OAAO,CAAC,CAAC,OAAO,KAAK,QAAQ;gBAAE,SAAS;YACjE,MAAM,CAAC,GAAG,CAAC,CAAC,OAAO,CAAC,IAAI,EAAE,CAAC;YAC3B,IAAI,CAAC,CAAC;gBAAE,SAAS;YACjB,IAAI,CAAC,IAAA,oCAAoB,EAAC,CAAC,CAAC,EAAE,CAAC;gBAC7B,YAAY,GAAG,CAAC,CAAC,OAAO,CAAC;gBACzB,MAAM;YACR,CAAC;QACH,CAAC;IACH,CAAC;IACD,OAAO,EAAE,YAAY,EAAE,oBAAoB,EAAE,CAAC;AAChD,CAAC"}

package/dist/tools/ocr.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Local OCR — extract printed text from an image file without an LLM.
+ *
+ * Dispatcher picks the best available engine for the platform:
+ *   macOS   → Apple Vision via `swift` running a VNRecognizeTextRequest
+ *             script. ~100-300ms per image, excellent on rendered text
+ *             (code, logs, stack traces, dialogs).
+ *   Linux   → tesseract CLI (`apt install tesseract-ocr`). ~500ms-2s.
+ *   Windows → tesseract CLI (PowerShell.Windows.Media.Ocr could be
+ *             added later; tesseract covers the common case today).
+ *
+ * Used by the extension/CLI on bandit-logic turns where a user paste
+ * an image. When OCR yields usable text, we inline it into the prompt
+ * as an `[Image text (OCR): …]` block and skip the model swap. When
+ * OCR returns nothing (diagrams, photos, blurry), we fall back to a
+ * vision-capable model for that turn.
+ *
+ * Binary OCR engines themselves are not bundled — we shell out to what
+ * the user's OS already ships. Linux/Windows users see a one-time
+ * install hint when tesseract is missing.
+ */
+export interface OcrResult {
+    /** Extracted text. May be empty if OCR produced no confident output. */
+    text: string;
+    /** Engine that produced the text. Useful for telemetry. */
+    engine: 'apple-vision' | 'tesseract' | 'windows-ocr' | 'none';
+    /** Wall-clock time the OCR call took. */
+    durationMs: number;
+}
+export interface OcrOptions {
+    /** Abort the OCR run after this many ms. Defaults to 8s — catches
+     *  a Vision hang without starving a long but legitimate recognition. */
+    timeoutMs?: number;
+}
+export declare function detectOcrAvailability(): {
+    apple: boolean;
+    tesseract: boolean;
+};
+/**
+ * Extract text from an image at `imagePath`. Returns an OcrResult with
+ * empty `.text` on failure rather than throwing — callers treat "empty
+ * text" as the signal to fall back to an LLM-vision path.
+ */
+export declare function extractImageText(imagePath: string, options?: OcrOptions): Promise<OcrResult>;
+/**
+ * Heuristic for "the OCR captured enough to be useful". Used by the
+ * image-handling path to decide between "inline OCR text + stay on
+ * current model" vs "fall back to a vision-capable model". Very cheap;
+ * runs once per image.
+ */
+export declare function ocrYieldedUsefulText(text: string): boolean;
+//# sourceMappingURL=ocr.d.ts.map

package/dist/tools/ocr.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ocr.d.ts","sourceRoot":"","sources":["../../src/tools/ocr.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAOH,MAAM,WAAW,SAAS;IACxB,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,2DAA2D;IAC3D,MAAM,EAAE,cAAc,GAAG,WAAW,GAAG,aAAa,GAAG,MAAM,CAAC;IAC9D,yCAAyC;IACzC,UAAU,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,UAAU;IACzB;4EACwE;IACxE,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AASD,wBAAgB,qBAAqB,IAAI;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,SAAS,EAAE,OAAO,CAAA;CAAE,CAM9E;AAWD;;;;GAIG;AACH,wBAAsB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,SAAS,CAAC,CAyBlG;AAwGD;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAS1D"}