@juspay/neurolink 9.81.1 → 9.81.3

package/dist/constants/contextWindows.js

@@ -154,6 +154,8 @@ export const MODEL_CONTEXT_WINDOWS = {
     },
     anthropic: {
         _default: 200_000,
+        // Claude 5 (mid 2026) — 1M context window
+        "claude-sonnet-5": 1_000_000,
         // Claude 4.6 (Feb 2026) — 1M context window
         "claude-opus-4-6": 1_000_000,
         "claude-sonnet-4-6": 1_000_000,
@@ -243,6 +245,7 @@ export const MODEL_CONTEXT_WINDOWS = {
     vertex: {
         _default: 1_048_576,
         // Claude on Vertex
+        "claude-sonnet-5": 1_000_000,
         "claude-opus-4-6": 1_000_000,
         "claude-sonnet-4-6": 1_000_000,
         "claude-sonnet-4-5": 200_000,
@@ -252,6 +255,13 @@ export const MODEL_CONTEXT_WINDOWS = {
         "claude-sonnet-4-20250514": 200_000,
         "claude-opus-4-20250514": 200_000,
         "claude-opus-4": 200_000,
+        // Catch-all for UNKNOWN Claude models on Vertex (prefix match runs after
+        // the specific keys above). Without this, an unlisted Claude model falls
+        // to the Gemini-shaped _default (1,048,576) — ABOVE Anthropic's real 1M
+        // API cap — so the pre-dispatch budget check and the in-loop context
+        // guard both under-guard it (the claude-sonnet-5 1,005,647-token 400s).
+        // 200K is the conservative Anthropic floor; list real models explicitly.
+        "claude-": 200_000,
         // Gemini 3.1 on Vertex (all require -preview suffix)
         "gemini-3.1-pro-preview": 1_048_576,
         "gemini-3.1-flash-lite-preview": 1_048_576,

package/dist/core/constants.d.ts

@@ -36,6 +36,22 @@ export declare const DEFAULT_TOOL_EXECUTION_TIMEOUT_MS = 300000;
  * a wrap-up nudge rides the next tool-result turn.
  */
 export declare const DEFAULT_WRAPUP_TIME_LEAD_MS = 120000;
+/**
+ * In-loop context guard threshold for native agentic loops: when the last
+ * model call's actual prompt size (provider-reported usage) plus the
+ * estimated growth from this step's tool results crosses this fraction of
+ * the model's context window, the loop stops calling tools and synthesizes a
+ * final answer instead of stepping into a provider 400 ("prompt is too
+ * long") that would destroy the whole turn's work.
+ */
+export declare const DEFAULT_CONTEXT_GUARD_RATIO = 0.85;
+/**
+ * Floor for the turn budget handed to the post-overflow recovery retry.
+ * The retry inherits the REMAINING `turnTimeoutMs` (whole-turn semantics —
+ * one generate() must not stack two full budgets), but never less than this,
+ * so a compacted retry still gets a workable window.
+ */
+export declare const MIN_RECOVERY_TURN_BUDGET_MS = 30000;
 export declare const TOOL_STORAGE_TIMEOUT_MS = 5000;
 export declare const STEP_LIMITS: {
     min: number;

package/dist/core/constants.js

@@ -122,6 +122,22 @@ export const DEFAULT_TOOL_EXECUTION_TIMEOUT_MS = 300_000;
  * a wrap-up nudge rides the next tool-result turn.
  */
 export const DEFAULT_WRAPUP_TIME_LEAD_MS = 120_000;
+/**
+ * In-loop context guard threshold for native agentic loops: when the last
+ * model call's actual prompt size (provider-reported usage) plus the
+ * estimated growth from this step's tool results crosses this fraction of
+ * the model's context window, the loop stops calling tools and synthesizes a
+ * final answer instead of stepping into a provider 400 ("prompt is too
+ * long") that would destroy the whole turn's work.
+ */
+export const DEFAULT_CONTEXT_GUARD_RATIO = 0.85;
+/**
+ * Floor for the turn budget handed to the post-overflow recovery retry.
+ * The retry inherits the REMAINING `turnTimeoutMs` (whole-turn semantics —
+ * one generate() must not stack two full budgets), but never less than this,
+ * so a compacted retry still gets a workable window.
+ */
+export const MIN_RECOVERY_TURN_BUDGET_MS = 30_000;
 // Fire-and-forget tool storage writes (Redis). 5s is generous for a single
 // Redis write; if breached, the .catch logs a warning.
 export const TOOL_STORAGE_TIMEOUT_MS = 5000;

package/dist/core/modules/ToolsManager.d.ts

@@ -18,6 +18,11 @@ export declare class ToolsManager {
     /**
      * BZ-666: Wrap tool execute with output truncation to prevent
      * context overflow when large results flow into the AI SDK accumulator.
+     *
+     * Passes the AI-SDK second argument (execution options: abortSignal,
+     * toolCallId, messages) through to the inner execute — the native loops
+     * provide an abortSignal there, and dropping it at this wrapper made
+     * every tool uncancellable (deadline overshoot / ghost executions).
      */
     private wrapExecuteWithTruncation;
     /**

package/dist/core/modules/ToolsManager.js

@@ -7,6 +7,48 @@ import { getKeyCount } from "../../utils/transformationUtils.js";
 import { convertJsonSchemaToZod } from "../../utils/schemaConversion.js";
 import { generateToolOutputPreview } from "../../context/toolOutputLimits.js";
 import { tool as createAISDKTool, jsonSchema } from "../../utils/tool.js";
+/** Abort-shaped error so provider loops route it to their cancellation path. */
+function makeToolAbortError() {
+    const e = new Error("Tool execution aborted");
+    e.name = "AbortError";
+    return e;
+}
+/**
+ * Race a tool-execution promise against an AbortSignal so the calling loop
+ * observes a deadline/caller abort IMMEDIATELY instead of waiting for the
+ * tool to finish or its execution timeout to expire. The underlying call is
+ * not cancelled (bounded ghost execution — the same tradeoff as the tool
+ * timeout); real transport-level cancellation (executeExternalMCPTool → MCP
+ * client RequestOptions.signal) is tracked as a follow-up.
+ */
+function raceWithAbortSignal(promise, signal) {
+    if (signal.aborted) {
+        // Swallow the abandoned settlement so it can't become an unhandled
+        // rejection later.
+        promise.catch(() => {
+            // Swallow the abandoned settlement — it must never surface as an
+            // unhandled rejection after the race has already been decided.
+        });
+        return Promise.reject(makeToolAbortError());
+    }
+    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(makeToolAbortError());
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(error);
+        });
+    });
+}
 /**
  * ToolsManager class - Handles all tool management operations
  */
@@ -32,10 +74,24 @@ export class ToolsManager {
     /**
      * BZ-666: Wrap tool execute with output truncation to prevent
      * context overflow when large results flow into the AI SDK accumulator.
+     *
+     * Passes the AI-SDK second argument (execution options: abortSignal,
+     * toolCallId, messages) through to the inner execute — the native loops
+     * provide an abortSignal there, and dropping it at this wrapper made
+     * every tool uncancellable (deadline overshoot / ghost executions).
      */
     wrapExecuteWithTruncation(toolName, originalExecute) {
-        return async (params) => {
-            const result = await originalExecute(params);
+        return async (params, execOptions) => {
+            const signal = execOptions
+                ?.abortSignal;
+            const inner = originalExecute(params, execOptions);
+            // Inner executes that ignore the signal (external MCP / custom tools —
+            // the signal isn't plumbed to their transports yet) still return
+            // promptly on abort via the race; the loop's isAbortError handling
+            // treats the rejection as a cancellation, not a tool failure.
+            const result = signal && typeof signal.addEventListener === "function"
+                ? await raceWithAbortSignal(inner, signal)
+                : await inner;
             return this.truncateToolResult(toolName, result);
         };
     }
@@ -241,11 +297,11 @@ export class ToolsManager {
                 const guardedExecute = this.wrapExecuteWithTruncation(toolName, originalExecute);
                 tools[toolName] = {
                     ...directTool,
-                    execute: async (params) => {
+                    execute: async (params, execOptions) => {
                         const startTime = Date.now();
                         this.emitToolEvent("tool:start", toolName, { input: params });
                         try {
-                            const result = await guardedExecute(params);
+                            const result = await guardedExecute(params, execOptions);
                             this.emitToolEvent("tool:end", toolName, {
                                 result,
                                 success: true,
@@ -541,11 +597,11 @@ export class ToolsManager {
             return createAISDKTool({
                 description: tool.description || `External MCP tool ${tool.name}`,
                 inputSchema: finalSchema, // AI SDK v6 uses inputSchema (not parameters)
-                execute: async (params) => {
+                execute: async (params, execOptions) => {
                     const startTime = Date.now();
                     this.emitToolEvent("tool:start", tool.name, { input: params });
                     try {
-                        const result = await guardedExecute(params);
+                        const result = await guardedExecute(params, execOptions);
                         this.emitToolEvent("tool:end", tool.name, {
                             result,
                             success: true,

package/dist/lib/constants/contextWindows.js

@@ -154,6 +154,8 @@ export const MODEL_CONTEXT_WINDOWS = {
     },
     anthropic: {
         _default: 200_000,
+        // Claude 5 (mid 2026) — 1M context window
+        "claude-sonnet-5": 1_000_000,
         // Claude 4.6 (Feb 2026) — 1M context window
         "claude-opus-4-6": 1_000_000,
         "claude-sonnet-4-6": 1_000_000,
@@ -243,6 +245,7 @@ export const MODEL_CONTEXT_WINDOWS = {
     vertex: {
         _default: 1_048_576,
         // Claude on Vertex
+        "claude-sonnet-5": 1_000_000,
         "claude-opus-4-6": 1_000_000,
         "claude-sonnet-4-6": 1_000_000,
         "claude-sonnet-4-5": 200_000,
@@ -252,6 +255,13 @@ export const MODEL_CONTEXT_WINDOWS = {
         "claude-sonnet-4-20250514": 200_000,
         "claude-opus-4-20250514": 200_000,
         "claude-opus-4": 200_000,
+        // Catch-all for UNKNOWN Claude models on Vertex (prefix match runs after
+        // the specific keys above). Without this, an unlisted Claude model falls
+        // to the Gemini-shaped _default (1,048,576) — ABOVE Anthropic's real 1M
+        // API cap — so the pre-dispatch budget check and the in-loop context
+        // guard both under-guard it (the claude-sonnet-5 1,005,647-token 400s).
+        // 200K is the conservative Anthropic floor; list real models explicitly.
+        "claude-": 200_000,
         // Gemini 3.1 on Vertex (all require -preview suffix)
         "gemini-3.1-pro-preview": 1_048_576,
         "gemini-3.1-flash-lite-preview": 1_048_576,

package/dist/lib/core/constants.d.ts

@@ -36,6 +36,22 @@ export declare const DEFAULT_TOOL_EXECUTION_TIMEOUT_MS = 300000;
  * a wrap-up nudge rides the next tool-result turn.
  */
 export declare const DEFAULT_WRAPUP_TIME_LEAD_MS = 120000;
+/**
+ * In-loop context guard threshold for native agentic loops: when the last
+ * model call's actual prompt size (provider-reported usage) plus the
+ * estimated growth from this step's tool results crosses this fraction of
+ * the model's context window, the loop stops calling tools and synthesizes a
+ * final answer instead of stepping into a provider 400 ("prompt is too
+ * long") that would destroy the whole turn's work.
+ */
+export declare const DEFAULT_CONTEXT_GUARD_RATIO = 0.85;
+/**
+ * Floor for the turn budget handed to the post-overflow recovery retry.
+ * The retry inherits the REMAINING `turnTimeoutMs` (whole-turn semantics —
+ * one generate() must not stack two full budgets), but never less than this,
+ * so a compacted retry still gets a workable window.
+ */
+export declare const MIN_RECOVERY_TURN_BUDGET_MS = 30000;
 export declare const TOOL_STORAGE_TIMEOUT_MS = 5000;
 export declare const STEP_LIMITS: {
     min: number;

package/dist/lib/core/constants.js

@@ -122,6 +122,22 @@ export const DEFAULT_TOOL_EXECUTION_TIMEOUT_MS = 300_000;
  * a wrap-up nudge rides the next tool-result turn.
  */
 export const DEFAULT_WRAPUP_TIME_LEAD_MS = 120_000;
+/**
+ * In-loop context guard threshold for native agentic loops: when the last
+ * model call's actual prompt size (provider-reported usage) plus the
+ * estimated growth from this step's tool results crosses this fraction of
+ * the model's context window, the loop stops calling tools and synthesizes a
+ * final answer instead of stepping into a provider 400 ("prompt is too
+ * long") that would destroy the whole turn's work.
+ */
+export const DEFAULT_CONTEXT_GUARD_RATIO = 0.85;
+/**
+ * Floor for the turn budget handed to the post-overflow recovery retry.
+ * The retry inherits the REMAINING `turnTimeoutMs` (whole-turn semantics —
+ * one generate() must not stack two full budgets), but never less than this,
+ * so a compacted retry still gets a workable window.
+ */
+export const MIN_RECOVERY_TURN_BUDGET_MS = 30_000;
 // Fire-and-forget tool storage writes (Redis). 5s is generous for a single
 // Redis write; if breached, the .catch logs a warning.
 export const TOOL_STORAGE_TIMEOUT_MS = 5000;

package/dist/lib/core/modules/ToolsManager.d.ts

@@ -18,6 +18,11 @@ export declare class ToolsManager {
     /**
      * BZ-666: Wrap tool execute with output truncation to prevent
      * context overflow when large results flow into the AI SDK accumulator.
+     *
+     * Passes the AI-SDK second argument (execution options: abortSignal,
+     * toolCallId, messages) through to the inner execute — the native loops
+     * provide an abortSignal there, and dropping it at this wrapper made
+     * every tool uncancellable (deadline overshoot / ghost executions).
      */
     private wrapExecuteWithTruncation;
     /**

package/dist/lib/core/modules/ToolsManager.js

@@ -7,6 +7,48 @@ import { getKeyCount } from "../../utils/transformationUtils.js";
 import { convertJsonSchemaToZod } from "../../utils/schemaConversion.js";
 import { generateToolOutputPreview } from "../../context/toolOutputLimits.js";
 import { tool as createAISDKTool, jsonSchema } from "../../utils/tool.js";
+/** Abort-shaped error so provider loops route it to their cancellation path. */
+function makeToolAbortError() {
+    const e = new Error("Tool execution aborted");
+    e.name = "AbortError";
+    return e;
+}
+/**
+ * Race a tool-execution promise against an AbortSignal so the calling loop
+ * observes a deadline/caller abort IMMEDIATELY instead of waiting for the
+ * tool to finish or its execution timeout to expire. The underlying call is
+ * not cancelled (bounded ghost execution — the same tradeoff as the tool
+ * timeout); real transport-level cancellation (executeExternalMCPTool → MCP
+ * client RequestOptions.signal) is tracked as a follow-up.
+ */
+function raceWithAbortSignal(promise, signal) {
+    if (signal.aborted) {
+        // Swallow the abandoned settlement so it can't become an unhandled
+        // rejection later.
+        promise.catch(() => {
+            // Swallow the abandoned settlement — it must never surface as an
+            // unhandled rejection after the race has already been decided.
+        });
+        return Promise.reject(makeToolAbortError());
+    }
+    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(makeToolAbortError());
+        };
+        signal.addEventListener("abort", onAbort, { once: true });
+        promise.then((value) => {
+            signal.removeEventListener("abort", onAbort);
+            resolve(value);
+        }, (error) => {
+            signal.removeEventListener("abort", onAbort);
+            reject(error);
+        });
+    });
+}
 /**
  * ToolsManager class - Handles all tool management operations
  */
@@ -32,10 +74,24 @@ export class ToolsManager {
     /**
      * BZ-666: Wrap tool execute with output truncation to prevent
      * context overflow when large results flow into the AI SDK accumulator.
+     *
+     * Passes the AI-SDK second argument (execution options: abortSignal,
+     * toolCallId, messages) through to the inner execute — the native loops
+     * provide an abortSignal there, and dropping it at this wrapper made
+     * every tool uncancellable (deadline overshoot / ghost executions).
      */
     wrapExecuteWithTruncation(toolName, originalExecute) {
-        return async (params) => {
-            const result = await originalExecute(params);
+        return async (params, execOptions) => {
+            const signal = execOptions
+                ?.abortSignal;
+            const inner = originalExecute(params, execOptions);
+            // Inner executes that ignore the signal (external MCP / custom tools —
+            // the signal isn't plumbed to their transports yet) still return
+            // promptly on abort via the race; the loop's isAbortError handling
+            // treats the rejection as a cancellation, not a tool failure.
+            const result = signal && typeof signal.addEventListener === "function"
+                ? await raceWithAbortSignal(inner, signal)
+                : await inner;
             return this.truncateToolResult(toolName, result);
         };
     }
@@ -241,11 +297,11 @@ export class ToolsManager {
                 const guardedExecute = this.wrapExecuteWithTruncation(toolName, originalExecute);
                 tools[toolName] = {
                     ...directTool,
-                    execute: async (params) => {
+                    execute: async (params, execOptions) => {
                         const startTime = Date.now();
                         this.emitToolEvent("tool:start", toolName, { input: params });
                         try {
-                            const result = await guardedExecute(params);
+                            const result = await guardedExecute(params, execOptions);
                             this.emitToolEvent("tool:end", toolName, {
                                 result,
                                 success: true,
@@ -541,11 +597,11 @@ export class ToolsManager {
             return createAISDKTool({
                 description: tool.description || `External MCP tool ${tool.name}`,
                 inputSchema: finalSchema, // AI SDK v6 uses inputSchema (not parameters)
-                execute: async (params) => {
+                execute: async (params, execOptions) => {
                     const startTime = Date.now();
                     this.emitToolEvent("tool:start", tool.name, { input: params });
                     try {
-                        const result = await guardedExecute(params);
+                        const result = await guardedExecute(params, execOptions);
                         this.emitToolEvent("tool:end", tool.name, {
                             result,
                             success: true,

package/dist/lib/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) {
@@ -10440,11 +10458,29 @@ Current user's request: ${currentInput}`;
                 }
             }
             const result = await this.externalServerManager.executeTool(serverId, toolName, parameters, options);
-            // BZ-664: Store result in cache after successful execution
-            if (cacheEnabled && this.mcpToolResultCache) {
+            // BZ-664: Store result in cache after successful execution.
+            // Only cache SUCCESSFUL results. Caching an error result (isError:true /
+            // success:false — e.g. an upstream 403/timeout surfaced as a tool error)
+            // replays that identical failure to every caller with the same args for
+            // the whole TTL, turning a single transient upstream error into a storm
+            // of cached failures and preventing a retry from re-hitting the server
+            // once it recovers. Errors must always re-execute. (Detection mirrors the
+            // isToolError check used elsewhere in this file.)
+            const resultObj = result && typeof result === "object"
+                ? result
+                : undefined;
+            const isErrorResult = Boolean((resultObj && "isError" in resultObj && resultObj.isError === true) ||
+                (resultObj && "success" in resultObj && resultObj.success === false));
+            // Also skip an `undefined` result: the cache read side treats `undefined`
+            // as a miss (`cached !== undefined`), so storing it is a dead entry that can
+            // never be read back — keep write/read symmetric with the other cache sites.
+            if (cacheEnabled &&
+                this.mcpToolResultCache &&
+                !isErrorResult &&
+                result !== undefined) {
                 this.mcpToolResultCache.cacheResult(toolName, cacheKeyArgs, result);
             }
-            mcpLogger.debug(`[NeuroLink] External MCP tool executed successfully: ${toolName}`);
+            mcpLogger.debug(`[NeuroLink] External MCP tool ${isErrorResult ? "returned error" : "executed successfully"}: ${toolName}`);
             return result;
         }
         catch (error) {

package/dist/lib/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/lib/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.