@juspay/neurolink 9.81.1 → 9.81.3

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