@juspay/neurolink 9.81.2 → 9.82.0

package/dist/lib/proxy/proxyDispatcher.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Install the tuned global undici dispatcher. Idempotent — safe to call once at
+ * proxy startup. No-op when `NEUROLINK_PROXY_KEEPALIVE` is off/false/0.
+ */
+export declare function configureProxyKeepAliveDispatcher(): void;

package/dist/lib/proxy/proxyDispatcher.js

@@ -0,0 +1,61 @@
+/**
+ * Tuned global undici dispatcher for the proxy's upstream forwards.
+ *
+ * The Claude passthrough (`claudeProxyRoutes.ts`) forwards every request to
+ * Anthropic via the global `fetch` → undici global dispatcher. undici keep-alives
+ * by default, but with a ~4s idle timeout: between Claude Code turns (the user
+ * reads output, a tool runs, the model thinks) the idle socket closes, so the
+ * next request opens a brand-new TCP connection. Under sustained use that is a
+ * high rate of short-lived outbound flows.
+ *
+ * On hosts running a socket content-filter (CFIL) — e.g. SentinelOne or
+ * GlobalProtect network extensions — every new flow allocates per-flow kernel
+ * state, so a high flow rate amplifies any leak in that path. Reusing connections
+ * cuts the flow rate sharply, so we install a dispatcher with a longer keep-alive
+ * and a bounded, reused connection pool.
+ *
+ * Everything is overridable via env so it can be tuned (or disabled) per host:
+ *   NEUROLINK_PROXY_KEEPALIVE=off       disable; keep undici defaults
+ *   NEUROLINK_PROXY_KEEPALIVE_MS        idle keep-alive timeout (default 30000)
+ *   NEUROLINK_PROXY_KEEPALIVE_MAX_MS    keep-alive upper bound  (default 600000)
+ *   NEUROLINK_PROXY_MAX_CONNECTIONS     max pooled connections per origin (default 64)
+ */
+import { Agent, setGlobalDispatcher } from "undici";
+import { logger } from "../utils/logger.js";
+function readPositiveInt(name, fallback) {
+    const raw = process.env[name];
+    if (!raw) {
+        return fallback;
+    }
+    const parsed = Number.parseInt(raw, 10);
+    return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
+}
+let configured = false;
+/**
+ * Install the tuned global undici dispatcher. Idempotent — safe to call once at
+ * proxy startup. No-op when `NEUROLINK_PROXY_KEEPALIVE` is off/false/0.
+ */
+export function configureProxyKeepAliveDispatcher() {
+    if (configured) {
+        return;
+    }
+    configured = true;
+    const toggle = (process.env.NEUROLINK_PROXY_KEEPALIVE ?? "").toLowerCase();
+    if (toggle === "off" || toggle === "false" || toggle === "0") {
+        logger.debug("[proxy] keep-alive dispatcher disabled via env");
+        return;
+    }
+    const keepAliveTimeout = readPositiveInt("NEUROLINK_PROXY_KEEPALIVE_MS", 30_000);
+    const keepAliveMaxTimeout = readPositiveInt("NEUROLINK_PROXY_KEEPALIVE_MAX_MS", 600_000);
+    const connections = readPositiveInt("NEUROLINK_PROXY_MAX_CONNECTIONS", 64);
+    setGlobalDispatcher(new Agent({
+        keepAliveTimeout,
+        keepAliveMaxTimeout,
+        connections,
+        pipelining: 1,
+    }));
+    logger.debug(`[proxy] tuned undici dispatcher installed ` +
+        `(keepAliveTimeout=${keepAliveTimeout}ms, ` +
+        `keepAliveMaxTimeout=${keepAliveMaxTimeout}ms, connections=${connections})`);
+}
+//# sourceMappingURL=proxyDispatcher.js.map

package/dist/lib/types/generate.d.ts

@@ -602,13 +602,17 @@ export type AdditionalMemoryUser = {
  *
  * - `completed` — the model finished on its own (text answer or final_result)
  * - `step-cap` — the `maxSteps` budget ran out while the model still wanted tools
+ * - `context-cap` — the in-loop context guard stopped the tool loop because the
+ *   accumulated conversation approached the model's context window (and the
+ *   terminal synthesis could not produce an answer); without the guard these
+ *   turns died mid-loop on a provider 400 "prompt is too long"
  * - `time-limit` — the `turnTimeoutMs` wall-clock deadline passed
  * - `stalled` — no progress (no chunk, no tool start/finish) for `stallTimeoutMs`
  * - `aborted` — the caller's `abortSignal` ended the turn
  * - `provider-error` — the provider/model failed the turn (e.g. persistent
  *   MALFORMED_FUNCTION_CALL after retry); usually worth a caller-side retry
  */
-export type GenerateStopReason = "completed" | "step-cap" | "time-limit" | "stalled" | "aborted" | "provider-error";
+export type GenerateStopReason = "completed" | "step-cap" | "context-cap" | "time-limit" | "stalled" | "aborted" | "provider-error";
 /**
  * Generate function result type - Primary output format
  * Future-ready for multi-modal outputs while maintaining text focus

package/dist/lib/utils/async/index.d.ts

@@ -20,4 +20,4 @@
  */
 export { delay, sleep } from "./delay.js";
 export { calculateBackoff, createRetry, DEFAULT_RETRY_OPTIONS, RetryExhaustedError, retry, } from "./retry.js";
-export { TimeoutError, withTimeout, withTimeoutFn } from "./withTimeout.js";
+export { TimeoutError, raceWithAbort, withTimeout, withTimeoutFn, } from "./withTimeout.js";

package/dist/lib/utils/async/index.js

@@ -20,5 +20,5 @@
  */
 export { delay, sleep } from "./delay.js";
 export { calculateBackoff, createRetry, DEFAULT_RETRY_OPTIONS, RetryExhaustedError, retry, } from "./retry.js";
-export { TimeoutError, withTimeout, withTimeoutFn } from "./withTimeout.js";
+export { TimeoutError, raceWithAbort, withTimeout, withTimeoutFn, } from "./withTimeout.js";
 //# sourceMappingURL=index.js.map

package/dist/lib/utils/async/withTimeout.d.ts

@@ -49,6 +49,18 @@ export declare class TimeoutError extends Error {
  * ```
  */
 export declare function withTimeout<T>(promise: Promise<T>, ms: number, message?: string): Promise<T>;
+/**
+ * Race a promise against an AbortSignal so the caller observes an abort
+ * IMMEDIATELY instead of waiting for the operation to settle (or for a
+ * separate timeout to expire). Rejects with an abort-shaped error
+ * (`name === "AbortError"`) so provider loops route it to their existing
+ * cancellation handling.
+ *
+ * The underlying operation is NOT cancelled — it continues as a bounded
+ * ghost (the same tradeoff as {@link withTimeout}); its eventual settlement
+ * is swallowed so it can never surface as an unhandled rejection.
+ */
+export declare function raceWithAbort<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T>;
 /**
  * Execute a function with timeout protection.
  *

package/dist/lib/utils/async/withTimeout.js

@@ -72,6 +72,51 @@ export async function withTimeout(promise, ms, message) {
         }
     }
 }
+/**
+ * Race a promise against an AbortSignal so the caller observes an abort
+ * IMMEDIATELY instead of waiting for the operation to settle (or for a
+ * separate timeout to expire). Rejects with an abort-shaped error
+ * (`name === "AbortError"`) so provider loops route it to their existing
+ * cancellation handling.
+ *
+ * The underlying operation is NOT cancelled — it continues as a bounded
+ * ghost (the same tradeoff as {@link withTimeout}); its eventual settlement
+ * is swallowed so it can never surface as an unhandled rejection.
+ */
+export async function raceWithAbort(promise, signal) {
+    if (!signal || typeof signal.addEventListener !== "function") {
+        return promise;
+    }
+    const makeAbortError = () => {
+        const e = new Error("Operation aborted");
+        e.name = "AbortError";
+        return e;
+    };
+    if (signal.aborted) {
+        promise.catch(() => {
+            // Swallow the abandoned settlement — it must never surface as an
+            // unhandled rejection after the race has already been decided.
+        });
+        return Promise.reject(makeAbortError());
+    }
+    return new Promise((resolve, reject) => {
+        const onAbort = () => {
+            promise.catch(() => {
+                // Swallow the abandoned settlement — it must never surface as an
+                // unhandled rejection after the race has already been decided.
+            });
+            reject(makeAbortError());
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(error);
+        });
+    });
+}
 /**
  * Execute a function with timeout protection.
  *

package/dist/lib/utils/mcpErrorText.d.ts

@@ -24,3 +24,14 @@ export declare function extractMcpErrorText(raw: unknown): string;
  * but no readable text is present, falls back to a generic message.
  */
 export declare function extractMcpToolErrorMessage(result: unknown): string | undefined;
+/**
+ * Detect a tool result that REPORTS failure without throwing, for the native
+ * loops' consecutive-failure breaker. Covers the two shapes NeuroLink itself
+ * produces or forwards:
+ * - MCP CallToolResult with `isError: true` (e.g. proxy-blocked tools) —
+ *   delegated to {@link extractMcpToolErrorMessage}
+ * - our own `{ error: "..." }` payloads
+ * Plain strings are never classified (too false-positive-prone).
+ * Returns the error text, or null when the result looks like a success.
+ */
+export declare function extractToolFailureText(result: unknown): string | null;

package/dist/lib/utils/mcpErrorText.js

@@ -69,4 +69,27 @@ export function extractMcpToolErrorMessage(result) {
         ? `MCP tool returned isError: ${text}`
         : "MCP tool returned isError: true";
 }
+/**
+ * Detect a tool result that REPORTS failure without throwing, for the native
+ * loops' consecutive-failure breaker. Covers the two shapes NeuroLink itself
+ * produces or forwards:
+ * - MCP CallToolResult with `isError: true` (e.g. proxy-blocked tools) —
+ *   delegated to {@link extractMcpToolErrorMessage}
+ * - our own `{ error: "..." }` payloads
+ * Plain strings are never classified (too false-positive-prone).
+ * Returns the error text, or null when the result looks like a success.
+ */
+export function extractToolFailureText(result) {
+    const mcpError = extractMcpToolErrorMessage(result);
+    if (mcpError) {
+        return mcpError;
+    }
+    if (result !== null &&
+        typeof result === "object" &&
+        typeof result.error === "string" &&
+        result.error.length > 0) {
+        return result.error;
+    }
+    return null;
+}
 //# sourceMappingURL=mcpErrorText.js.map

package/dist/lib/utils/systemMessages.d.ts

@@ -0,0 +1,29 @@
+import type { ModelMessage, SystemModelMessage } from "../types/index.js";
+/**
+ * Partition a built message array into system messages and the rest, so the
+ * system prompt can ride `generateText`'s top-level `system` option instead of
+ * the `messages` array.
+ *
+ * The AI SDK deprecates system-role entries inside `messages` (warns by default
+ * from ai@6.0.170 via the `allowSystemInMessages` option, rejected by default
+ * in v7, flagged as a prompt-injection risk). The `system` option accepts full
+ * SystemModelMessage objects, so per-message providerOptions (e.g. the anthropic
+ * cacheControl breakpoint set by buildMessagesArray) survive the move. See
+ * issue #1024.
+ *
+ * Order is preserved within both partitions and the input is not mutated.
+ *
+ * Guard: the partition only runs when it leaves a non-empty `messages` array.
+ * If every message is a system message (a system-only priming call) — or there
+ * are no system messages at all — the original array is returned untouched with
+ * `system: undefined`. The AI SDK rejects an empty `messages` array, and a
+ * system-only call has no hoisted form (the SDK also requires a non-system
+ * message), so that degenerate case is deliberately left on the old
+ * system-in-`messages` path rather than made to throw — it keeps whatever
+ * behaviour it had before #1024. The normal system-plus-conversation path is
+ * always hoisted.
+ */
+export declare function extractSystemMessages(messages: ModelMessage[]): {
+    system: SystemModelMessage[] | undefined;
+    messages: ModelMessage[];
+};

package/dist/lib/utils/systemMessages.js

@@ -0,0 +1,45 @@
+/**
+ * Partition a built message array into system messages and the rest, so the
+ * system prompt can ride `generateText`'s top-level `system` option instead of
+ * the `messages` array.
+ *
+ * The AI SDK deprecates system-role entries inside `messages` (warns by default
+ * from ai@6.0.170 via the `allowSystemInMessages` option, rejected by default
+ * in v7, flagged as a prompt-injection risk). The `system` option accepts full
+ * SystemModelMessage objects, so per-message providerOptions (e.g. the anthropic
+ * cacheControl breakpoint set by buildMessagesArray) survive the move. See
+ * issue #1024.
+ *
+ * Order is preserved within both partitions and the input is not mutated.
+ *
+ * Guard: the partition only runs when it leaves a non-empty `messages` array.
+ * If every message is a system message (a system-only priming call) — or there
+ * are no system messages at all — the original array is returned untouched with
+ * `system: undefined`. The AI SDK rejects an empty `messages` array, and a
+ * system-only call has no hoisted form (the SDK also requires a non-system
+ * message), so that degenerate case is deliberately left on the old
+ * system-in-`messages` path rather than made to throw — it keeps whatever
+ * behaviour it had before #1024. The normal system-plus-conversation path is
+ * always hoisted.
+ */
+export function extractSystemMessages(messages) {
+    const system = [];
+    const rest = [];
+    for (const message of messages) {
+        if (message.role === "system") {
+            system.push(message);
+        }
+        else {
+            rest.push(message);
+        }
+    }
+    // Only hoist when a non-empty messages array remains. A system-only call (or
+    // a no-system array) passes through unchanged: hoisting would empty
+    // `messages`, which the SDK rejects, and a system-only call has no compliant
+    // hoisted form.
+    if (system.length === 0 || rest.length === 0) {
+        return { system: undefined, messages };
+    }
+    return { system, messages: rest };
+}
+//# sourceMappingURL=systemMessages.js.map

package/dist/neurolink.js

@@ -28,7 +28,7 @@ import { emergencyContentTruncation } from "./context/emergencyTruncation.js";
 import { getContextOverflowProvider, isContextOverflowError, parseProviderOverflowDetails, } from "./context/errorDetection.js";
 import { ContextBudgetExceededError } from "./context/errors.js";
 import { repairToolPairs } from "./context/toolPairRepair.js";
-import { SYSTEM_LIMITS, DEFAULT_TOOL_ROUTING_TIMEOUT_MS, } from "./core/constants.js";
+import { SYSTEM_LIMITS, DEFAULT_TOOL_ROUTING_TIMEOUT_MS, MIN_RECOVERY_TURN_BUDGET_MS, } from "./core/constants.js";
 import { ConversationMemoryManager } from "./core/conversationMemoryManager.js";
 import { buildToolRoutingCatalog, buildRoutingQueryFromHistory, resolveToolRoutingExclusions, } from "./core/toolRouting.js";
 import { ToolRoutingCache } from "./core/toolRoutingCache.js";
@@ -4277,7 +4277,7 @@ Current user's request: ${currentInput}`;
         return result;
     }
     async handleGenerateTextInternalFailure(options, context, error) {
-        const recoveredResult = await this.tryRecoverGenerateTextOverflow(options, context.functionTag, error);
+        const recoveredResult = await this.tryRecoverGenerateTextOverflow(options, context.functionTag, error, context.generateInternalStartTime);
         if (recoveredResult) {
             return recoveredResult;
         }
@@ -4317,7 +4317,7 @@ Current user's request: ${currentInput}`;
         }
         return null;
     }
-    async tryRecoverGenerateTextOverflow(options, functionTag, error) {
+    async tryRecoverGenerateTextOverflow(options, functionTag, error, attemptStartTimeMs) {
         // Reviewer Finding #3: drop the `!this.conversationMemory` gate so
         // inline-conversationMessages callers also benefit from post-provider
         // recovery when their pre-dispatch estimate happens to undershoot
@@ -4467,16 +4467,34 @@ Current user's request: ${currentInput}`;
                     breakdown: verifiedBudget?.breakdown ?? {},
                 });
             }
+            // Whole-turn budget semantics: the retry inherits the REMAINING
+            // turnTimeoutMs, not a fresh clock — attempt 1 already spent part of
+            // the caller's budget, and a fresh clock let one generate() run ~2×
+            // the configured deadline (the 66-minute-turn incident shape).
+            // Floored so a compacted retry still gets a workable window — but the
+            // floor never exceeds the caller's own turnTimeoutMs (a 10s caller
+            // budget must not receive a 30s retry).
+            let retryTurnTimeoutMs = options.turnTimeoutMs;
+            if (typeof options.turnTimeoutMs === "number" &&
+                Number.isFinite(options.turnTimeoutMs) &&
+                attemptStartTimeMs !== undefined) {
+                const elapsedMs = Date.now() - attemptStartTimeMs;
+                retryTurnTimeoutMs = Math.max(options.turnTimeoutMs - elapsedMs, Math.min(MIN_RECOVERY_TURN_BUDGET_MS, options.turnTimeoutMs));
+            }
             logger.info(`[${functionTag}] Smart recovery verified, retrying generation`, {
                 tokensSaved: lastCompactionResult.tokensSaved,
                 compactionTarget,
                 verifiedTokens: verifiedBudget.estimatedInputTokens,
                 verifiedBudget: verifiedBudget.availableInputTokens,
                 recoveredFraction,
+                retryTurnTimeoutMs,
             });
             return this.directProviderGeneration({
                 ...options,
                 conversationMessages: compactedMessages,
+                ...(retryTurnTimeoutMs !== undefined && {
+                    turnTimeoutMs: retryTurnTimeoutMs,
+                }),
             });
         }
         catch (retryError) {

package/dist/providers/googleNativeGemini3.d.ts

@@ -230,6 +230,13 @@ export declare function isAbortError(error: unknown): boolean;
  * this text (a killed 23-step turn once claimed "reached the 200-step limit").
  */
 export declare function buildToolLoopCapMessage(maxSteps: number, toolCallCount: number): string;
+/**
+ * Honest message for a turn stopped by the in-loop context guard
+ * (stopReason "context-cap") without a synthesized answer. Sibling of
+ * {@link buildToolLoopCapMessage} — context exits must never claim a step
+ * limit was reached.
+ */
+export declare function buildContextCapMessage(toolCallCount: number): string;
 /**
  * Honest message for a turn ended by the `turnTimeoutMs` wall-clock deadline
  * (stopReason "time-limit"). Sibling of {@link buildToolLoopCapMessage} —
@@ -266,6 +273,8 @@ export declare function resolveTurnStopReason(params: {
     wasAborted: boolean;
     /** Step budget ran out AND no clean/forced answer was produced. */
     cappedWithoutAnswer: boolean;
+    /** Context guard stopped the loop AND no clean/forced answer was produced. */
+    contextCappedWithoutAnswer?: boolean;
     /** The turn's resolved unified finishReason. */
     finishReason?: string;
 }): GenerateStopReason;
@@ -307,6 +316,40 @@ export declare function createTurnClock(params: {
     shouldNudgeWrapup(): boolean;
     dispose(): void;
 };
+/**
+ * In-loop context guard for native agentic turns.
+ *
+ * The provider reports the ACTUAL prompt size of every model call
+ * (usage.input_tokens + cache reads/writes on Anthropic;
+ * usageMetadata.promptTokenCount on Gemini). The guard tracks that number
+ * plus an estimate of what the current step appends (assistant output, tool
+ * results), and tells the loop to stop calling tools once the projected next
+ * prompt crosses `thresholdRatio` of the model's context window — the turn
+ * then synthesizes a final answer from what it has instead of stepping into
+ * a provider 400 ("prompt is too long") that destroys all completed work.
+ *
+ * Fail-open: until the first usage report arrives, `shouldStop()` is false.
+ */
+export declare function createContextGuard(contextWindowTokens: number, thresholdRatio?: number): {
+    /** Tokens at which the guard trips (ratio × window). */
+    readonly thresholdTokens: number;
+    /** Last observed prompt size plus estimated growth since. */
+    readonly projectedNextPromptTokens: number;
+    /**
+     * Record a model call's reported usage. `promptTokens` must be the FULL
+     * prompt size (uncached input + cache read + cache creation for
+     * Anthropic). The response's own output is counted as growth — it is
+     * appended to the conversation for the next call.
+     */
+    noteUsage(promptTokens: number, outputTokens: number): void;
+    /**
+     * Add growth for content appended since the last model call (tool
+     * results, nudge text) using the ~4 chars/token heuristic.
+     */
+    noteAppendedChars(chars: number): void;
+    /** True when issuing another model call risks crossing the threshold. */
+    shouldStop(): boolean;
+};
 /**
  * Push model response parts to conversation history, preserving thoughtSignature
  * for Gemini 3 multi-turn tool calling.

package/dist/providers/googleNativeGemini3.js

@@ -11,7 +11,7 @@
 import { randomUUID } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { extname } from "node:path";
-import { DEFAULT_MAX_STEPS, DEFAULT_TOOL_MAX_RETRIES, DEFAULT_WRAPUP_TIME_LEAD_MS, } from "../core/constants.js";
+import { DEFAULT_CONTEXT_GUARD_RATIO, DEFAULT_MAX_STEPS, DEFAULT_TOOL_MAX_RETRIES, DEFAULT_WRAPUP_TIME_LEAD_MS, } from "../core/constants.js";
 import { logger } from "../utils/logger.js";
 import { convertZodToJsonSchema, ensureNestedSchemaTypes, inlineJsonSchema, isZodSchema, normalizeJsonSchemaObject, } from "../utils/schemaConversion.js";
 import { createNativeThinkingConfig } from "../utils/thinkingConfig.js";
@@ -853,6 +853,20 @@ export function buildToolLoopCapMessage(maxSteps, toolCallCount) {
     return (`${calls}reached the ${maxSteps}-step limit for a single turn before I could finish. ` +
         `Please narrow the request or break it into smaller asks and I'll continue.`);
 }
+/**
+ * Honest message for a turn stopped by the in-loop context guard
+ * (stopReason "context-cap") without a synthesized answer. Sibling of
+ * {@link buildToolLoopCapMessage} — context exits must never claim a step
+ * limit was reached.
+ */
+export function buildContextCapMessage(toolCallCount) {
+    const calls = toolCallCount > 0
+        ? `I gathered information across ${toolCallCount} tool call${toolCallCount === 1 ? "" : "s"} but `
+        : "I ";
+    return (`${calls}had to stop because the gathered material filled this turn's ` +
+        `context window before I could finish. Please narrow the request or ` +
+        `break it into smaller asks and I'll continue.`);
+}
 /** Format an elapsed duration as "Xm Ys" (or "Ys" under a minute). */
 function formatElapsed(elapsedMs) {
     const totalSeconds = Math.max(0, Math.round(elapsedMs / 1000));
@@ -923,6 +937,9 @@ export function resolveTurnStopReason(params) {
     if (params.wasAborted) {
         return "aborted";
     }
+    if (params.contextCappedWithoutAnswer) {
+        return "context-cap";
+    }
     if (params.cappedWithoutAnswer) {
         return "step-cap";
     }
@@ -1024,6 +1041,61 @@ export function createTurnClock(params) {
         },
     };
 }
+/**
+ * In-loop context guard for native agentic turns.
+ *
+ * The provider reports the ACTUAL prompt size of every model call
+ * (usage.input_tokens + cache reads/writes on Anthropic;
+ * usageMetadata.promptTokenCount on Gemini). The guard tracks that number
+ * plus an estimate of what the current step appends (assistant output, tool
+ * results), and tells the loop to stop calling tools once the projected next
+ * prompt crosses `thresholdRatio` of the model's context window — the turn
+ * then synthesizes a final answer from what it has instead of stepping into
+ * a provider 400 ("prompt is too long") that destroys all completed work.
+ *
+ * Fail-open: until the first usage report arrives, `shouldStop()` is false.
+ */
+export function createContextGuard(contextWindowTokens, thresholdRatio = DEFAULT_CONTEXT_GUARD_RATIO) {
+    const thresholdTokens = Math.floor(contextWindowTokens * thresholdRatio);
+    let observedPromptTokens = 0;
+    let projectedGrowthTokens = 0;
+    return {
+        /** Tokens at which the guard trips (ratio × window). */
+        get thresholdTokens() {
+            return thresholdTokens;
+        },
+        /** Last observed prompt size plus estimated growth since. */
+        get projectedNextPromptTokens() {
+            return observedPromptTokens + projectedGrowthTokens;
+        },
+        /**
+         * Record a model call's reported usage. `promptTokens` must be the FULL
+         * prompt size (uncached input + cache read + cache creation for
+         * Anthropic). The response's own output is counted as growth — it is
+         * appended to the conversation for the next call.
+         */
+        noteUsage(promptTokens, outputTokens) {
+            if (promptTokens > 0) {
+                observedPromptTokens = promptTokens;
+                projectedGrowthTokens = Math.max(0, outputTokens);
+            }
+        },
+        /**
+         * Add growth for content appended since the last model call (tool
+         * results, nudge text) using the ~4 chars/token heuristic.
+         */
+        noteAppendedChars(chars) {
+            if (chars > 0) {
+                projectedGrowthTokens += Math.ceil(chars / 4);
+            }
+        },
+        /** True when issuing another model call risks crossing the threshold. */
+        shouldStop() {
+            return (observedPromptTokens > 0 &&
+                observedPromptTokens + projectedGrowthTokens >= thresholdTokens);
+        },
+    };
+}
 /**
  * Push model response parts to conversation history, preserving thoughtSignature
  * for Gemini 3 multi-turn tool calling.