@juspay/neurolink 9.81.2 → 9.82.0

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/GenerationHandler.js

@@ -26,6 +26,7 @@ import { coerceJsonToSchema } from "../../utils/json/coerce.js";
 import { NoObjectGeneratedError } from "../../utils/generationErrors.js";
 import { Output, stepCountIs } from "../../utils/tool.js";
 import { generateText } from "../../utils/generation.js";
+import { extractSystemMessages } from "../../utils/systemMessages.js";
 const genTracer = tracers.generation;
 /**
  * Safely preview-serialize a value for debug logging.
@@ -105,9 +106,14 @@ export class GenerationHandler {
             }
         }
         const prepareStep = options.prepareStep;
+        // Hoist system-role messages into generateText's top-level `system` option
+        // rather than passing them inside `messages` (deprecated by the AI SDK,
+        // rejected in v7). See extractSystemMessages for the rationale. (#1024)
+        const { system, messages: nonSystemMessages } = extractSystemMessages(messages);
         return await generateText({
             model,
-            messages,
+            ...(system && { system }),
+            messages: nonSystemMessages,
             ...(shouldUseTools &&
                 Object.keys(toolsWithCache).length > 0 && { tools: toolsWithCache }),
             stopWhen: stepCountIs(options.maxSteps ?? DEFAULT_MAX_STEPS),

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/index.d.ts

@@ -35,7 +35,12 @@ import { AIProviderFactory } from "./core/factory.js";
 export { AIProviderFactory };
 export { NeuroLinkConfigManager as ConfigManager } from "./config/configManager.js";
 export { BaseFactory, BaseRegistry, NeuroLinkFeatureError, createErrorFactory, withRetry, TypedEventEmitter, } from "./core/infrastructure/index.js";
-export { NeuroLinkClient, createClient, NeuroLinkApiError, NeuroLinkLanguageModel, NeuroLinkAIProvider, createNeuroLinkProvider, createNeuroLinkModel, createStreamingResponse, neurolink as neuroLinkAIInstance, createApiKeyAuthInterceptor, createBearerAuthInterceptor, createDynamicAuthInterceptor, createLoggingInterceptor, createRetryInterceptor, createRateLimitInterceptor, createRequestTransformInterceptor, createResponseTransformInterceptor, createCacheInterceptor, createTimeoutInterceptor, createErrorHandlerInterceptor, composeMiddleware, conditionalMiddleware, SSEClient, WebSocketStreamingClient, createStreamingClient, createAsyncStream, collectStream, OAuth2TokenManager, JWTTokenManager, createApiKeyMiddleware, createBearerTokenMiddleware, createTokenManagerMiddleware, createAuthWithRetryMiddleware, createMultiAuthMiddleware, OAuth2Error, OAuth2AuthError, TokenRefreshError, decodeJWTPayload, isJWTExpired, getJWTExpiry, getApiKeyFromEnv, ErrorCode as ClientErrorCode, NeuroLinkError as ClientNeuroLinkError, HttpError, ClientRateLimitError, ClientValidationError, ClientAuthenticationError, ClientAuthorizationError, NotFoundError, ClientNetworkError, ClientTimeoutError, ClientConnectionError, AbortError, ClientConfigurationError, StreamError, ClientProviderError, ContextLengthError, ContentFilterError, createErrorFromResponse, createErrorFromNative, mapStatusToErrorCode, isRetryableStatus, isRetryableError, isNeuroLinkError, isApiError, } from "./client/index.js";
+export { NeuroLinkClient, createClient, NeuroLinkApiError, } from "./client/httpClient.js";
+export { NeuroLinkLanguageModel, NeuroLinkProvider as NeuroLinkAIProvider, createNeuroLinkProvider, createNeuroLinkModel, createStreamingResponse, neurolink as neuroLinkAIInstance, } from "./client/aiSdkAdapter.js";
+export { createApiKeyAuthInterceptor, createBearerAuthInterceptor, createDynamicAuthInterceptor, createLoggingInterceptor, createRetryInterceptor, createRateLimitInterceptor, createRequestTransformInterceptor, createResponseTransformInterceptor, createCacheInterceptor, createTimeoutInterceptor, createErrorHandlerInterceptor, composeMiddleware, conditionalMiddleware, } from "./client/interceptors.js";
+export { SSEClient, WebSocketStreamingClient, createStreamingClient, createAsyncStream, collectStream, } from "./client/streamingClient.js";
+export { OAuth2TokenManager, JWTTokenManager, createApiKeyMiddleware, createBearerTokenMiddleware, createTokenManagerMiddleware, createAuthWithRetryMiddleware, createMultiAuthMiddleware, OAuth2Error, OAuth2AuthenticationError as OAuth2AuthError, TokenRefreshError, decodeJWTPayload, isJWTExpired, getJWTExpiry, getApiKeyFromEnv, } from "./client/auth.js";
+export { ErrorCode as ClientErrorCode, NeuroLinkError as ClientNeuroLinkError, HttpError, ClientRateLimitError, ClientValidationError, ClientAuthenticationError, ClientAuthorizationError, NotFoundError, ClientNetworkError, ClientTimeoutError, ClientConnectionError, AbortError, ClientConfigurationError, StreamError, ClientProviderError, ContextLengthError, ContentFilterError, createErrorFromResponse, createErrorFromNative, mapStatusToErrorCode, isRetryableStatus, isRetryableError, isNeuroLinkError, isApiError, } from "./client/errors.js";
 export { AIProviderName, BedrockModels, OpenAIModels, VertexModels, } from "./constants/enums.js";
 export { dynamicModelProvider } from "./core/dynamicModels.js";
 export { validateTool } from "./sdk/toolRegistration.js";

package/dist/lib/index.js

@@ -41,20 +41,28 @@ export { BaseFactory, BaseRegistry, NeuroLinkFeatureError, createErrorFactory, w
 // ============================================================================
 // CLIENT SDK EXPORTS - Type-safe API access for browser and Node.js
 // Note: React hooks are NOT re-exported here. Import from '@juspay/neurolink/client'.
+// These re-exports intentionally bypass ./client/index.js: that barrel statically
+// re-exports ./reactHooks.js, so routing through it makes the ROOT import require
+// `react` (an optional peer dep) and crash react-less installs at import time.
 // ============================================================================
 export { 
 // HTTP Client
-NeuroLinkClient, createClient, NeuroLinkApiError, 
+NeuroLinkClient, createClient, NeuroLinkApiError, } from "./client/httpClient.js";
+export { 
 // AI SDK Adapter
-NeuroLinkLanguageModel, NeuroLinkAIProvider, createNeuroLinkProvider, createNeuroLinkModel, createStreamingResponse, neurolink as neuroLinkAIInstance, 
+NeuroLinkLanguageModel, NeuroLinkProvider as NeuroLinkAIProvider, createNeuroLinkProvider, createNeuroLinkModel, createStreamingResponse, neurolink as neuroLinkAIInstance, } from "./client/aiSdkAdapter.js";
+export { 
 // Interceptors
-createApiKeyAuthInterceptor, createBearerAuthInterceptor, createDynamicAuthInterceptor, createLoggingInterceptor, createRetryInterceptor, createRateLimitInterceptor, createRequestTransformInterceptor, createResponseTransformInterceptor, createCacheInterceptor, createTimeoutInterceptor, createErrorHandlerInterceptor, composeMiddleware, conditionalMiddleware, 
+createApiKeyAuthInterceptor, createBearerAuthInterceptor, createDynamicAuthInterceptor, createLoggingInterceptor, createRetryInterceptor, createRateLimitInterceptor, createRequestTransformInterceptor, createResponseTransformInterceptor, createCacheInterceptor, createTimeoutInterceptor, createErrorHandlerInterceptor, composeMiddleware, conditionalMiddleware, } from "./client/interceptors.js";
+export { 
 // Streaming Client
-SSEClient, WebSocketStreamingClient, createStreamingClient, createAsyncStream, collectStream, 
+SSEClient, WebSocketStreamingClient, createStreamingClient, createAsyncStream, collectStream, } from "./client/streamingClient.js";
+export { 
 // Authentication
-OAuth2TokenManager, JWTTokenManager, createApiKeyMiddleware, createBearerTokenMiddleware, createTokenManagerMiddleware, createAuthWithRetryMiddleware, createMultiAuthMiddleware, OAuth2Error, OAuth2AuthError, TokenRefreshError, decodeJWTPayload, isJWTExpired, getJWTExpiry, getApiKeyFromEnv, 
+OAuth2TokenManager, JWTTokenManager, createApiKeyMiddleware, createBearerTokenMiddleware, createTokenManagerMiddleware, createAuthWithRetryMiddleware, createMultiAuthMiddleware, OAuth2Error, OAuth2AuthenticationError as OAuth2AuthError, TokenRefreshError, decodeJWTPayload, isJWTExpired, getJWTExpiry, getApiKeyFromEnv, } from "./client/auth.js";
+export { 
 // Errors
-ErrorCode as ClientErrorCode, NeuroLinkError as ClientNeuroLinkError, HttpError, ClientRateLimitError, ClientValidationError, ClientAuthenticationError, ClientAuthorizationError, NotFoundError, ClientNetworkError, ClientTimeoutError, ClientConnectionError, AbortError, ClientConfigurationError, StreamError, ClientProviderError, ContextLengthError, ContentFilterError, createErrorFromResponse, createErrorFromNative, mapStatusToErrorCode, isRetryableStatus, isRetryableError, isNeuroLinkError, isApiError, } from "./client/index.js";
+ErrorCode as ClientErrorCode, NeuroLinkError as ClientNeuroLinkError, HttpError, ClientRateLimitError, ClientValidationError, ClientAuthenticationError, ClientAuthorizationError, NotFoundError, ClientNetworkError, ClientTimeoutError, ClientConnectionError, AbortError, ClientConfigurationError, StreamError, ClientProviderError, ContextLengthError, ContentFilterError, createErrorFromResponse, createErrorFromNative, mapStatusToErrorCode, isRetryableStatus, isRetryableError, isNeuroLinkError, isApiError, } from "./client/errors.js";
 export { AIProviderName, BedrockModels, OpenAIModels, VertexModels, } from "./constants/enums.js";
 // Dynamic Models exports
 export { dynamicModelProvider } from "./core/dynamicModels.js";

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) {

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.