@burtson-labs/agent-core 1.6.13

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

@@ -0,0 +1,72 @@
+/**
+ * Per-iteration goal-anchor injector for ToolUseLoop.runWithMessages.
+ *
+ * Re-injects the original user goal into the conversation when the
+ * loop is at risk of drifting. Two observed drift modes the anchor
+ * defends against:
+ *
+ *   1. Recency bias — long tool-result chains push the goal down the
+ *      attention window; model answers about whatever was salient in
+ *      the most recent tool reads.
+ *   2. Multi-turn pivot — after a stretch of failed tool calls,
+ *      compaction cleans them up and the model re-answers an EARLIER
+ *      user prompt that's cleaner to address.
+ *
+ * Eligibility: `iterations >= 2 AND messageTokens > 4000`. Re-fire
+ * allowed after `GOAL_ANCHOR_REFIRE_GAP` (4) iterations on sticky turns.
+ *
+ * Aggressive compaction this iteration overrides BOTH the refire-gap
+ * AND the eligibility floor — it's the highest-risk drift trigger we
+ * have. Compaction stripped most of the file content the model was
+ * reasoning over; without an immediate re-anchor the model falls back
+ * to imitating tool-result formats from training (the 2026-05-06
+ * fabricated `read_file` envelope) or pivoting to a tangent that
+ * sounded plausible from the surviving tool names.
+ *
+ * Post-aggressive-compaction anchors also include:
+ * - a "context just compacted" preamble explaining what the
+ *   `[earlier run, N lines elided]` markers actually mean
+ * - the live tool list (MCP-namespaced first, capped at 40) so a
+ *   surviving "tool not registered" error doesn't convince the model
+ *   that real tools are unavailable
+ *
+ * The whole module returns the new `lastGoalAnchorIteration` so the
+ * orchestrator can update its mutable counter; no other state escapes.
+ */
+import type { ToolLoopMessage } from '../tool-types';
+import type { ToolRegistry } from '../tool-registry';
+export type AnchorEmit = (type: string, payload?: unknown) => void;
+export declare const GOAL_ANCHOR_REFIRE_GAP = 4;
+export interface ApplyGoalAnchorArgs {
+    /** The user's goal for THIS turn (the most-recent substantive prompt). */
+    originalGoal: string;
+    /** Number of earlier user prompts in the seed — used by the
+     * "ignore prior prompts" suffix that defends against the multi-turn
+     * pivot failure mode. */
+    priorUserPromptCount: number;
+    /** When true, no anchor injection (the loop is wrapping up). */
+    hitLimit: boolean;
+    /** Current iteration counter. */
+    iteration: number;
+    /** Iteration at which the anchor last fired (-1 if never). */
+    lastGoalAnchorIteration: number;
+    /** When true, compaction this iteration dropped >=25% of tokens OR
+     * >=10k absolute. Overrides eligibility floor and refire gap. */
+    aggressiveCompactionThisIteration: boolean;
+    /** Mutable message log — anchor is pushed in place when fired. */
+    messages: ToolLoopMessage[];
+    /** Tool registry — read for the tool-list block when compaction is
+     * aggressive. */
+    registry: ToolRegistry;
+    /** Event sink for `tool_loop:goal_anchor`. */
+    emit: AnchorEmit;
+}
+export interface ApplyGoalAnchorResult {
+    /** New value for `lastGoalAnchorIteration` (caller assigns it back).
+     * Unchanged when the anchor did not fire. */
+    lastGoalAnchorIteration: number;
+    /** True when the anchor message was appended. */
+    anchored: boolean;
+}
+export declare function applyGoalAnchorIfNeeded(args: ApplyGoalAnchorArgs): ApplyGoalAnchorResult;
+//# sourceMappingURL=goalAnchor.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"goalAnchor.d.ts","sourceRoot":"","sources":["../../../src/tools/loop/goalAnchor.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AACH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAErD,MAAM,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;AAEnE,eAAO,MAAM,sBAAsB,IAAI,CAAC;AAExC,MAAM,WAAW,mBAAmB;IAClC,0EAA0E;IAC1E,YAAY,EAAE,MAAM,CAAC;IACrB;;6BAEyB;IACzB,oBAAoB,EAAE,MAAM,CAAC;IAC7B,gEAAgE;IAChE,QAAQ,EAAE,OAAO,CAAC;IAClB,iCAAiC;IACjC,SAAS,EAAE,MAAM,CAAC;IAClB,8DAA8D;IAC9D,uBAAuB,EAAE,MAAM,CAAC;IAChC;qEACiE;IACjE,iCAAiC,EAAE,OAAO,CAAC;IAC3C,kEAAkE;IAClE,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B;qBACiB;IACjB,QAAQ,EAAE,YAAY,CAAC;IACvB,8CAA8C;IAC9C,IAAI,EAAE,UAAU,CAAC;CAClB;AAED,MAAM,WAAW,qBAAqB;IACpC;iDAC6C;IAC7C,uBAAuB,EAAE,MAAM,CAAC;IAChC,iDAAiD;IACjD,QAAQ,EAAE,OAAO,CAAC;CACnB;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,mBAAmB,GAAG,qBAAqB,CAyFxF"}

package/dist/tools/loop/goalAnchor.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GOAL_ANCHOR_REFIRE_GAP = void 0;
+exports.applyGoalAnchorIfNeeded = applyGoalAnchorIfNeeded;
+exports.GOAL_ANCHOR_REFIRE_GAP = 4;
+function applyGoalAnchorIfNeeded(args) {
+    const { originalGoal, priorUserPromptCount, hitLimit, iteration, lastGoalAnchorIteration, aggressiveCompactionThisIteration, messages, registry, emit } = args;
+    if (!originalGoal || hitLimit) {
+        return { lastGoalAnchorIteration, anchored: false };
+    }
+    const messageTokens = messages.reduce((acc, m) => acc + (m.content?.length ?? 0), 0);
+    const eligible = iteration >= 2 && messageTokens > 4000;
+    const canRefire = lastGoalAnchorIteration >= 0
+        && (iteration - lastGoalAnchorIteration) >= exports.GOAL_ANCHOR_REFIRE_GAP;
+    const shouldAnchor = aggressiveCompactionThisIteration
+        || (eligible && (lastGoalAnchorIteration < 0 || canRefire));
+    if (!shouldAnchor) {
+        return { lastGoalAnchorIteration, anchored: false };
+    }
+    emit('tool_loop:goal_anchor', {
+        iteration,
+        goalPreview: originalGoal.slice(0, 120),
+        priorUserPromptCount,
+        refire: canRefire,
+        postAggressiveCompaction: aggressiveCompactionThisIteration
+    });
+    // Multi-turn-aware anchor. When prior user prompts exist in history,
+    // explicitly tell the model to ignore them — that's the failure mode
+    // boolean recency-bias guards don't catch. Structured header +
+    // bullet so even small models can lock onto the format.
+    const ignoreEarlier = priorUserPromptCount > 0
+        ? `\n  - There ${priorUserPromptCount === 1 ? 'is 1 earlier user prompt' : `are ${priorUserPromptCount} earlier user prompts`} in this conversation. Do NOT answer ${priorUserPromptCount === 1 ? 'it' : 'them'}. They were settled in prior turns.`
+        : '';
+    // Re-inject the current tool list whenever compaction has been
+    // aggressive — defends against the failure mode where an earlier
+    // error message ("tool not registered" or "expected object received
+    // string") survives compaction while the success path doesn't, and
+    // the model concludes the tool doesn't exist. The model would
+    // normally see the tools in the native-tools schema sent on every
+    // call, but small/mid models trust prose history over schema, so we
+    // make the availability claim textual and authoritative.
+    let toolListBlock = '';
+    if (aggressiveCompactionThisIteration) {
+        const allNames = registry.getAll().map((t) => t.name);
+        if (allNames.length > 0) {
+            // Cap to keep the prompt budget bounded — surface MCP-namespaced
+            // tools (the ones most likely to be hallucinated as absent)
+            // first, then any remaining names, then truncate.
+            const mcpNames = allNames.filter((n) => n.includes('.') || n.startsWith('mcp__'));
+            const otherNames = allNames.filter((n) => !mcpNames.includes(n));
+            const ordered = [...mcpNames, ...otherNames];
+            const TOOL_LIST_CAP = 40;
+            const shown = ordered.slice(0, TOOL_LIST_CAP);
+            const more = ordered.length > TOOL_LIST_CAP ? ` (+${ordered.length - TOOL_LIST_CAP} more)` : '';
+            toolListBlock =
+                `## TOOLS CURRENTLY AVAILABLE THIS TURN${more}\n\n` +
+                    shown.map((n) => `  - ${n}`).join('\n') +
+                    '\n\nIf you think a tool is missing, re-check this list before saying so. ' +
+                    'The names above were sent to you in the native-tools schema on THIS call.\n\n';
+        }
+    }
+    const compactionPreamble = aggressiveCompactionThisIteration
+        ? '## CONTEXT JUST COMPACTED — read this first.\n\n' +
+            'Most of the tool-result content from this turn was just collapsed to one-line placeholders to fit the context window. ' +
+            'Those `[earlier run, N lines elided]` markers represent real reads whose content is no longer in front of you. ' +
+            'Do NOT fabricate `<tool_result>` blocks pretending to read files; do NOT pivot to a topic that looks salient based on which tool names survived in the placeholders. ' +
+            'Answer from what you ALREADY learned in this turn, owning honestly anything you cannot recall in detail.\n\n' +
+            toolListBlock
+        : '';
+    messages.push({
+        role: 'user',
+        content: `${compactionPreamble}## CURRENT GOAL — answer THIS, nothing else:\n\n  "${originalGoal.trim()}"\n\nRules:\n  - Use what you have gathered to answer the goal above.\n  - Do not pivot to a related topic that happens to be salient in recent tool results.${ignoreEarlier}\n  - If the available tools cannot finish the goal, own that honestly in your final answer — do NOT redirect to an easier question.`
+    });
+    return { lastGoalAnchorIteration: iteration, anchored: true };
+}
+//# sourceMappingURL=goalAnchor.js.map

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

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

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

@@ -0,0 +1,70 @@
+/**
+ * LLM streaming with intra-response loop detection and same-channel
+ * transient-error retry. Extracted from ToolUseLoop.runWithMessages so
+ * the orchestrator only holds high-level control flow, not the chunk-
+ * level fingerprint accounting and the retry ladder.
+ *
+ * Behavior pinned by `packages/agent-core/test/llmStreamContract.test.ts`:
+ *
+ *  - Chunks emit through `tool_loop:llm_chunk` in arrival order; the
+ *    aggregated text is returned in full when no detector trips.
+ *  - HARD_MAX cap (24,000 chars) aborts the stream, marks it, and
+ *    appends a sentinel so the downstream prose-loop detector can route
+ *    to the nudge path. Real trace it caught: a single response of
+ *    24,663 chars of "Wait, I'll try X. Actually..." prose.
+ *  - Line-level fast path: 5 identical short lines (<= 120 chars,
+ *    non-empty, trimmed) in a row aborts the stream. Catches
+ *    "I can't install things." × 24 before the 800-char fingerprint
+ *    window can fire (24 short lines ≈ 550 chars, below CHECK_EVERY).
+ *  - Window-level fingerprint: every 800 chars, hash the last 400
+ *    (whitespace-normalized, numeric tokens collapsed to '#') and check
+ *    for 3 identical fingerprints in a row. Catches re-numbered list
+ *    repetition the line-level path misses.
+ *  - User abort: `signal.aborted` mid-stream emits `stream_abort` with
+ *    reason `cancelled` and breaks. No retry.
+ *  - Retryable error WITH zero text streamed AND (no native tools OR
+ *    not yet streamed): exponential backoff retry (1.2s × 2^n, two
+ *    attempts). Emits `tool_loop:llm_retry` per attempt.
+ *  - Non-retryable error OR partial text already streamed: re-throw
+ *    (tagged with `UPSTREAM_MODEL` code on retryable to preserve the
+ *    existing error-summarization contract for outer-layer handlers).
+ *
+ * Gate widening note (preserved from the in-class implementation):
+ * the original retry gate was `!tools || tools.length === 0` — only
+ * text-tools turns got the same-channel ladder. That meant native-tools
+ * turns hit a transient 500 once and jumped to the disruptive native→
+ * text envelope switch (a second hiccup hard-failed). Widening to
+ * `!tools || tools.length === 0 || safeToReplay` keeps the original
+ * guarantee (no duplicated tool_call deltas after partial output) but
+ * lets the native path retry transient infra blips before the envelope
+ * switch escalates.
+ */
+import type { ChatFn, ToolLoopMessage, ChatCallOptions, NativeToolSchema } from '../tool-types';
+export type StreamEmit = (type: string, payload?: unknown) => void;
+export interface StreamAndAggregateArgs {
+    chat: ChatFn;
+    messages: ToolLoopMessage[];
+    emit: StreamEmit;
+    iteration: number;
+    tools?: NativeToolSchema[];
+    signal?: AbortSignal;
+    callOptions?: ChatCallOptions;
+}
+/**
+ * Stream from the chat function and return the fully aggregated response
+ * string. Aborts early if we detect the model is trapped in a self-
+ * contradicting prose loop — repeating phrases like "Wait, I see X
+ * isn't listed. Let me check X. Actually, I'll try to read X." without
+ * ever emitting a tool call. This was observed Apr 2026 on
+ * bandit-core-1: a single stream produced 24k chars of such prose.
+ * Without this guard the turn terminates naturally (no tool calls →
+ * final response), but the user sees the entire wall of repetition.
+ *
+ * Detection is cheap: after every ~800 chars we compute a hash of the
+ * last ~400 chars and check if the same hash appeared recently. Three
+ * repeats in a row means we're looping — abort and return what we
+ * have. The upstream loop will then still call the prose-loop detector
+ * and apply its nudge on the next iteration.
+ */
+export declare function streamAndAggregate(args: StreamAndAggregateArgs): Promise<string>;
+//# sourceMappingURL=llmStream.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"llmStream.d.ts","sourceRoot":"","sources":["../../../src/tools/loop/llmStream.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,OAAO,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAGhG,MAAM,MAAM,UAAU,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;AAEnE,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,eAAe,EAAE,CAAC;IAC5B,IAAI,EAAE,UAAU,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,gBAAgB,EAAE,CAAC;IAC3B,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,WAAW,CAAC,EAAE,eAAe,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAsB,kBAAkB,CAAC,IAAI,EAAE,sBAAsB,GAAG,OAAO,CAAC,MAAM,CAAC,CAmKtF"}

package/dist/tools/loop/llmStream.js

@@ -0,0 +1,181 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.streamAndAggregate = streamAndAggregate;
+const tool_use_loop_1 = require("../tool-use-loop");
+/**
+ * Stream from the chat function and return the fully aggregated response
+ * string. Aborts early if we detect the model is trapped in a self-
+ * contradicting prose loop — repeating phrases like "Wait, I see X
+ * isn't listed. Let me check X. Actually, I'll try to read X." without
+ * ever emitting a tool call. This was observed Apr 2026 on
+ * bandit-core-1: a single stream produced 24k chars of such prose.
+ * Without this guard the turn terminates naturally (no tool calls →
+ * final response), but the user sees the entire wall of repetition.
+ *
+ * Detection is cheap: after every ~800 chars we compute a hash of the
+ * last ~400 chars and check if the same hash appeared recently. Three
+ * repeats in a row means we're looping — abort and return what we
+ * have. The upstream loop will then still call the prose-loop detector
+ * and apply its nudge on the next iteration.
+ */
+async function streamAndAggregate(args) {
+    const { chat, messages, emit, iteration, tools, signal, callOptions } = args;
+    let text = '';
+    // Intra-response loop guard. Tuned by observation, not theory:
+    // - CHECK_EVERY=800: a single "Actually, I'll try to read X." cycle
+    // in the real trace was ~120-180 chars, so we want multiple
+    // samples per cycle but not one per chunk (that would be slow).
+    // - WINDOW=400: the tail chunk used to build the fingerprint.
+    // - THRESHOLD=3: three identical fingerprints in a row is
+    // overwhelmingly a loop; two could be a natural repetition
+    // (e.g. a code block shown twice).
+    // - HARD_MAX=24000: a soft upper bound so a runaway generation
+    // doesn't burn unbounded tokens even if the fingerprint shifts
+    // slightly each cycle. The real trace was 24663 chars.
+    const CHECK_EVERY = 800;
+    const WINDOW = 400;
+    const THRESHOLD = 3;
+    const HARD_MAX = 24000;
+    const recentFingerprints = [];
+    let nextCheckAt = CHECK_EVERY;
+    let aborted = false;
+    // Line-level repetition guard. Catches "I can't install things." × 24
+    // long before the 800-char fingerprint check fires (24 short lines is
+    // ~550 chars, below CHECK_EVERY). Tracks the last completed line
+    // (text up to the most recent \n) and counts consecutive identical
+    // non-empty short lines. Five in a row is a clear loop; trips
+    // earlier than the full-fingerprint detector ever can.
+    const REPEAT_LINE_THRESHOLD = 5;
+    const REPEAT_LINE_MAXLEN = 120; // only short lines — long paragraphs aren't loops
+    let lastLine = '';
+    let repeatCount = 1;
+    let lastEmittedLineLength = 0;
+    const MAX_TRANSIENT_RETRIES = 2;
+    const BASE_RETRY_MS = 1200;
+    let transientRetries = 0;
+    while (true) {
+        try {
+            for await (const chunk of chat(messages, tools, callOptions)) {
+                if (signal?.aborted) {
+                    aborted = true;
+                    emit('tool_loop:stream_abort', { iteration, reason: 'cancelled', length: text.length });
+                    break;
+                }
+                text += chunk;
+                emit('tool_loop:llm_chunk', { iteration, chunk });
+                if (text.length >= HARD_MAX) {
+                    aborted = true;
+                    emit('tool_loop:stream_abort', { iteration, reason: 'hard_max', length: text.length });
+                    break;
+                }
+                // Line-repetition fast path. Walk newly-completed lines (between
+                // lastEmittedLineLength and the most recent \n) and bump a
+                // consecutive-identical counter. Trips faster than the
+                // 800-char fingerprint window for short-phrase loops.
+                const lastNewline = text.lastIndexOf('\n');
+                if (lastNewline > lastEmittedLineLength) {
+                    const newSegment = text.slice(lastEmittedLineLength, lastNewline);
+                    for (const rawLine of newSegment.split('\n')) {
+                        const line = rawLine.trim();
+                        if (!line || line.length > REPEAT_LINE_MAXLEN) {
+                            lastLine = line;
+                            repeatCount = 1;
+                            continue;
+                        }
+                        if (line === lastLine) {
+                            repeatCount += 1;
+                            if (repeatCount >= REPEAT_LINE_THRESHOLD) {
+                                aborted = true;
+                                emit('tool_loop:stream_abort', {
+                                    iteration,
+                                    reason: 'line_repetition_loop',
+                                    length: text.length,
+                                    fingerprintPreview: line.slice(0, 120),
+                                    repeatCount
+                                });
+                                break;
+                            }
+                        }
+                        else {
+                            lastLine = line;
+                            repeatCount = 1;
+                        }
+                    }
+                    lastEmittedLineLength = lastNewline + 1;
+                    if (aborted)
+                        break;
+                }
+                if (text.length >= nextCheckAt) {
+                    nextCheckAt = text.length + CHECK_EVERY;
+                    const tail = text.slice(Math.max(0, text.length - WINDOW));
+                    // Normalize whitespace + drop numeric noise so "3." vs "4." don't
+                    // defeat the comparison when a model re-numbers each attempt.
+                    const fingerprint = tail
+                        .toLowerCase()
+                        .replace(/\s+/g, ' ')
+                        .replace(/\d+/g, '#')
+                        .trim();
+                    recentFingerprints.push(fingerprint);
+                    if (recentFingerprints.length > THRESHOLD)
+                        recentFingerprints.shift();
+                    if (recentFingerprints.length === THRESHOLD &&
+                        recentFingerprints.every(f => f === fingerprint)) {
+                        aborted = true;
+                        emit('tool_loop:stream_abort', {
+                            iteration,
+                            reason: 'intra_response_loop',
+                            length: text.length,
+                            fingerprintPreview: fingerprint.slice(0, 120)
+                        });
+                        break;
+                    }
+                }
+            }
+            break;
+        }
+        catch (error) {
+            const retryable = (0, tool_use_loop_1.isRetryableLlmError)(error);
+            const safeToReplay = text.length === 0;
+            // Original gate was `!tools || tools.length === 0` — i.e. only
+            // text-tools turns got the same-channel backoff ladder. Native-tools
+            // turns hit a transient 500 once and jumped straight to the
+            // disruptive native→text envelope switch (and a second hiccup
+            // hard-failed). The gate exists to prevent re-emitting tool-call
+            // deltas after partial output was already streamed; when
+            // `safeToReplay` is true NO chunks have arrived yet, so there are
+            // no deltas to duplicate. Widening the gate to allow retry when
+            // safeToReplay holds catches transient infra blips (gateway load
+            // shedding, ollama restart, brief network glitches) on the native
+            // path without risking duplicated tool calls.
+            const sameTransportRetryAllowed = !tools || tools.length === 0 || safeToReplay;
+            if (retryable && safeToReplay && sameTransportRetryAllowed && !signal?.aborted && transientRetries < MAX_TRANSIENT_RETRIES) {
+                transientRetries++;
+                const delayMs = BASE_RETRY_MS * Math.pow(2, transientRetries - 1);
+                emit('tool_loop:llm_retry', {
+                    iteration,
+                    attempt: transientRetries + 1,
+                    maxAttempts: MAX_TRANSIENT_RETRIES + 1,
+                    delayMs,
+                    reason: (0, tool_use_loop_1.summarizeLlmError)(error)
+                });
+                await (0, tool_use_loop_1.sleep)(delayMs);
+                continue;
+            }
+            if (retryable)
+                (0, tool_use_loop_1.tagRetryableLlmError)(error);
+            throw error;
+        }
+    }
+    // If we aborted a runaway stream, trim trailing garbage and append
+    // a sentinel so the downstream final-response detector can recognize
+    // this and route to the prose-loop nudge (or a clean termination).
+    if (aborted) {
+        // Drop the last (likely-truncated) repetition cycle from the
+        // output — cleaner to end at a previous paragraph boundary than
+        // mid-sentence.
+        const trimmed = text.replace(/\s+$/, '');
+        text = trimmed + '\n\n[stream aborted: self-contradicting prose loop detected]';
+    }
+    return text;
+}
+//# sourceMappingURL=llmStream.js.map

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

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

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

@@ -0,0 +1,57 @@
+/**
+ * Output-budget-aware batch dispatch for ToolUseLoop.runWithMessages.
+ *
+ * Takes a normalized batch (already trimmed by maxParallelTools +
+ * dedup'd by `normalizeToolCallBatch`) and runs it. Two execution
+ * modes:
+ *
+ *   Parallel (default): `Promise.all(toolCalls.map(dispatchOne))`.
+ *
+ *   Serial: when the estimated combined output of the batch would
+ *   exceed `outputBudgetTokens * outputBudgetRatio`, the batch runs
+ *   one tool at a time. Each call short-circuits on `signal.aborted`.
+ *
+ * Why the serial mode exists: smaller models (4B–12B) generate
+ * malformed JSON in the tail of a multi-file emission once their
+ * effective output budget is exhausted. on a
+ * portfolio build — even a strong model produced a malformed
+ * `todo_write` after writing four files of ~7 KB each in one
+ * assistant turn. Serialising lets the model react to each result
+ * before committing further output, and gives the user one approval
+ * at a time instead of a queued pile.
+ *
+ * Single-call batches skip the threshold check entirely — there's no
+ * parallel/serial distinction with one call, and the gate's purpose
+ * is preventing a *batch* from overrunning the assistant turn.
+ *
+ * Token estimate is intentionally coarse (heavy payload fields × ¼).
+ * Reads and small calls never trip the gate; only writes/edits whose
+ * `content`/`replace`/`find`/`text` fields dominate the output budget.
+ * Accuracy isn't the goal — order-of-magnitude is enough to gate.
+ */
+import type { ParsedToolCall } from '../tool-use-parser';
+import type { ToolDispatchResult } from './singleToolExecute';
+export type BatchEmit = (type: string, payload?: unknown) => void;
+export interface ExecuteParallelBatchArgs {
+    toolCalls: ParsedToolCall[];
+    dispatchOne: (tc: ParsedToolCall) => Promise<ToolDispatchResult>;
+    outputBudgetTokens: number;
+    outputBudgetRatio: number;
+    emit: BatchEmit;
+    iteration: number;
+    signal?: AbortSignal;
+}
+/**
+ * Coarse token estimate for a single tool call's contribution to the
+ * assistant turn's output. Heavy fields (file content, edit
+ * replacements, apply_edit find/replace blocks) dominate; everything
+ * else is negligible. Uses chars/4 as a rough byte→token approximation
+ * — fast and good enough to gate batches; we don't need accuracy, just
+ * an order-of-magnitude check.
+ */
+export declare function estimateToolCallOutputTokens(tc: {
+    name: string;
+    params: Record<string, string>;
+}): number;
+export declare function executeParallelBatch(args: ExecuteParallelBatchArgs): Promise<ToolDispatchResult[]>;
+//# sourceMappingURL=parallelExecute.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"parallelExecute.d.ts","sourceRoot":"","sources":["../../../src/tools/loop/parallelExecute.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA8BG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAE9D,MAAM,MAAM,SAAS,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;AAElE,MAAM,WAAW,wBAAwB;IACvC,SAAS,EAAE,cAAc,EAAE,CAAC;IAC5B,WAAW,EAAE,CAAC,EAAE,EAAE,cAAc,KAAK,OAAO,CAAC,kBAAkB,CAAC,CAAC;IACjE,kBAAkB,EAAE,MAAM,CAAC;IAC3B,iBAAiB,EAAE,MAAM,CAAC;IAC1B,IAAI,EAAE,SAAS,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAgB,4BAA4B,CAAC,EAAE,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,GAAG,MAAM,CAMzG;AAED,wBAAsB,oBAAoB,CAAC,IAAI,EAAE,wBAAwB,GAAG,OAAO,CAAC,kBAAkB,EAAE,CAAC,CAmCxG"}

package/dist/tools/loop/parallelExecute.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.estimateToolCallOutputTokens = estimateToolCallOutputTokens;
+exports.executeParallelBatch = executeParallelBatch;
+/**
+ * Coarse token estimate for a single tool call's contribution to the
+ * assistant turn's output. Heavy fields (file content, edit
+ * replacements, apply_edit find/replace blocks) dominate; everything
+ * else is negligible. Uses chars/4 as a rough byte→token approximation
+ * — fast and good enough to gate batches; we don't need accuracy, just
+ * an order-of-magnitude check.
+ */
+function estimateToolCallOutputTokens(tc) {
+    const params = tc.params ?? {};
+    const heavy = [params.content, params.replace, params.find, params.text]
+        .filter((v) => typeof v === 'string' && v.length > 0)
+        .reduce((sum, s) => sum + s.length, 0);
+    return Math.ceil(heavy / 4);
+}
+async function executeParallelBatch(args) {
+    const { toolCalls, dispatchOne, outputBudgetTokens, outputBudgetRatio, emit, iteration, signal } = args;
+    // Output-budget gate. Only meaningful for multi-call batches —
+    // single-call iterations never have a parallel/serial choice.
+    let serializeBatch = false;
+    if (Number.isFinite(outputBudgetTokens) && toolCalls.length > 1) {
+        let estimatedBatchOutputTokens = 0;
+        for (const tc of toolCalls) {
+            estimatedBatchOutputTokens += estimateToolCallOutputTokens(tc);
+        }
+        const threshold = outputBudgetTokens * outputBudgetRatio;
+        if (estimatedBatchOutputTokens > threshold) {
+            serializeBatch = true;
+            emit('tool_loop:batch_serialized', {
+                iteration,
+                toolCount: toolCalls.length,
+                estimatedTokens: estimatedBatchOutputTokens,
+                budgetTokens: outputBudgetTokens,
+                threshold: Math.floor(threshold),
+                reason: 'output-budget-exceeded'
+            });
+        }
+    }
+    if (serializeBatch) {
+        const results = [];
+        for (const tc of toolCalls) {
+            if (signal?.aborted)
+                break;
+            results.push(await dispatchOne(tc));
+        }
+        return results;
+    }
+    return Promise.all(toolCalls.map(dispatchOne));
+}
+//# sourceMappingURL=parallelExecute.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"parallelExecute.js","sourceRoot":"","sources":["../../../src/tools/loop/parallelExecute.ts"],"names":[],"mappings":";;AAsDA,oEAMC;AAED,oDAmCC;AAnDD;;;;;;;GAOG;AACH,SAAgB,4BAA4B,CAAC,EAAoD;IAC/F,MAAM,MAAM,GAAG,EAAE,CAAC,MAAM,IAAI,EAAE,CAAC;IAC/B,MAAM,KAAK,GAAG,CAAC,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE,MAAM,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC;SACrE,MAAM,CAAC,CAAC,CAAC,EAAe,EAAE,CAAC,OAAO,CAAC,KAAK,QAAQ,IAAI,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;SACjE,MAAM,CAAC,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC,GAAG,GAAG,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,CAAC;IACzC,OAAO,IAAI,CAAC,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC;AAC9B,CAAC;AAEM,KAAK,UAAU,oBAAoB,CAAC,IAA8B;IACvE,MAAM,EAAE,SAAS,EAAE,WAAW,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,IAAI,CAAC;IAExG,+DAA+D;IAC/D,8DAA8D;IAC9D,IAAI,cAAc,GAAG,KAAK,CAAC;IAC3B,IAAI,MAAM,CAAC,QAAQ,CAAC,kBAAkB,CAAC,IAAI,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAChE,IAAI,0BAA0B,GAAG,CAAC,CAAC;QACnC,KAAK,MAAM,EAAE,IAAI,SAAS,EAAE,CAAC;YAC3B,0BAA0B,IAAI,4BAA4B,CAAC,EAAE,CAAC,CAAC;QACjE,CAAC;QACD,MAAM,SAAS,GAAG,kBAAkB,GAAG,iBAAiB,CAAC;QACzD,IAAI,0BAA0B,GAAG,SAAS,EAAE,CAAC;YAC3C,cAAc,GAAG,IAAI,CAAC;YACtB,IAAI,CAAC,4BAA4B,EAAE;gBACjC,SAAS;gBACT,SAAS,EAAE,SAAS,CAAC,MAAM;gBAC3B,eAAe,EAAE,0BAA0B;gBAC3C,YAAY,EAAE,kBAAkB;gBAChC,SAAS,EAAE,IAAI,CAAC,KAAK,CAAC,SAAS,CAAC;gBAChC,MAAM,EAAE,wBAAwB;aACjC,CAAC,CAAC;QACL,CAAC;IACH,CAAC;IAED,IAAI,cAAc,EAAE,CAAC;QACnB,MAAM,OAAO,GAAyB,EAAE,CAAC;QACzC,KAAK,MAAM,EAAE,IAAI,SAAS,EAAE,CAAC;YAC3B,IAAI,MAAM,EAAE,OAAO;gBAAE,MAAM;YAC3B,OAAO,CAAC,IAAI,CAAC,MAAM,WAAW,CAAC,EAAE,CAAC,CAAC,CAAC;QACtC,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,OAAO,OAAO,CAAC,GAAG,CAAC,SAAS,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC,CAAC;AACjD,CAAC"}

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

@@ -0,0 +1,71 @@
+/**
+ * Per-tool execution closure for ToolUseLoop.runWithMessages.
+ *
+ * The dispatcher takes one ParsedToolCall and runs it end-to-end:
+ *
+ *  - Build a coarse signature for the repeat-call breaker (the model's
+ *    "I'll just retry the same broken write 4 times in a row" failure
+ *    mode). The window is `repeatLimit` calls; once all entries are
+ *    identical, the dispatcher short-circuits with a stop-this-now error
+ *    instead of running the tool.
+ *  - Look up the tool in the registry. Unknown tool → error result.
+ *  - Run the host's `beforeToolExecute` gate. Blocked → error result.
+ *  - Execute the tool. On success: bump the success-only edit counter
+ *    via `onEditToolSucceeded()` for file-editing tools, and record the
+ *    touched file (normalized to basename) in `filesReadThisTurn` /
+ *    `filesWrittenThisTurn`. On exception: catch + emit `tool_error`.
+ *  - Emit `tool_execute` before invocation and `tool_result` (with a
+ *    redacted output snippet) after.
+ *
+ * The factory captures all the per-turn deps in a closure and returns
+ * a single async function. Mutable turn-state — `recentCallKeys`,
+ * `filesReadThisTurn`, `filesWrittenThisTurn` — is passed by reference
+ * so the dispatcher mutates the same objects the orchestrator (and the
+ * loop's detector pipeline) read.
+ *
+ * The success-only edit counter (`editToolsInvoked` in the orchestrator)
+ * has multiple downstream readers (false-completion detector, wrap-up
+ * template chooser), so it's routed through `onEditToolSucceeded` rather
+ * than incremented directly here.
+ */
+import type { ParsedToolCall } from '../tool-use-parser';
+import type { ToolExecutionContext } from '../tool-types';
+import type { ToolRegistry } from '../tool-registry';
+export type DispatchEmit = (type: string, payload?: unknown) => void;
+export type BeforeToolExecuteFn = (call: {
+    name: string;
+    params: Record<string, string>;
+}) => Promise<{
+    allow: boolean;
+    reason?: string;
+}> | {
+    allow: boolean;
+    reason?: string;
+};
+export interface ToolDispatchDeps {
+    registry: ToolRegistry;
+    ctx: ToolExecutionContext;
+    beforeToolExecute: BeforeToolExecuteFn;
+    emit: DispatchEmit;
+    /** Mutable turn-state — rolling window of recent call signatures. */
+    recentCallKeys: string[];
+    /** Cap on the rolling window; identical keys filling it trip the breaker. */
+    repeatLimit: number;
+    /** Mutable set of basenames read this turn (used by false-completion detector). */
+    filesReadThisTurn: Set<string>;
+    /** Mutable set of basenames written this turn. */
+    filesWrittenThisTurn: Set<string>;
+    /** Predicate identifying file-editing tools (write/apply_edit/replace_range). */
+    isFileEditTool: (name: string) => boolean;
+    /** Called once per successful file-editing tool result. Hosts use this
+     * to bump the `editToolsInvoked` counter that gates false-completion
+     * nudges and wrap-up template selection. */
+    onEditToolSucceeded: () => void;
+}
+export type ToolDispatchResult = {
+    name: string;
+    output: string;
+    isError?: boolean;
+};
+export declare function createToolDispatcher(deps: ToolDispatchDeps): (tc: ParsedToolCall) => Promise<ToolDispatchResult>;
+//# sourceMappingURL=singleToolExecute.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"singleToolExecute.d.ts","sourceRoot":"","sources":["../../../src/tools/loop/singleToolExecute.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,oBAAoB,EAAc,MAAM,eAAe,CAAC;AACtE,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAGrD,MAAM,MAAM,YAAY,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;AACrE,MAAM,MAAM,mBAAmB,GAAG,CAChC,IAAI,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,KACnD,OAAO,CAAC;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,GAAG;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC;AAExF,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,YAAY,CAAC;IACvB,GAAG,EAAE,oBAAoB,CAAC;IAC1B,iBAAiB,EAAE,mBAAmB,CAAC;IACvC,IAAI,EAAE,YAAY,CAAC;IACnB,qEAAqE;IACrE,cAAc,EAAE,MAAM,EAAE,CAAC;IACzB,6EAA6E;IAC7E,WAAW,EAAE,MAAM,CAAC;IACpB,mFAAmF;IACnF,iBAAiB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAC/B,kDAAkD;IAClD,oBAAoB,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;IAClC,iFAAiF;IACjF,cAAc,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC;IAC1C;;gDAE4C;IAC5C,mBAAmB,EAAE,MAAM,IAAI,CAAC;CACjC;AAED,MAAM,MAAM,kBAAkB,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,OAAO,CAAA;CAAE,CAAC;AAErF,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,gBAAgB,GAAG,CAAC,EAAE,EAAE,cAAc,KAAK,OAAO,CAAC,kBAAkB,CAAC,CA4IhH"}