@juspay/neurolink 10.3.0 → 10.3.1

package/dist/core/modules/GenerationHandler.js

@@ -19,8 +19,9 @@ import { logger } from "../../utils/logger.js";
 import { emitToolEndFromStepFinish } from "../../utils/toolEndEmitter.js";
 import { calculateCost } from "../../utils/pricing.js";
 import { withProviderRetry } from "../../utils/providerRetry.js";
+import { parseTimeout } from "../../utils/timeout.js";
 import { calculateCacheSavingsPercent, extractCacheCreationTokens, extractCacheReadTokens, extractTokenUsage, } from "../../utils/tokenUtils.js";
-import { DEFAULT_MAX_STEPS } from "../constants.js";
+import { DEFAULT_MAX_STEPS, DEFAULT_WRAPUP_TIME_LEAD_MS, } from "../constants.js";
 import { createStepBudgetGuard, estimateFixedOverheadTokens, } from "../../context/stepBudgetGuard.js";
 import { isTemperatureDeprecatedError, isSchemaComplexityError, isToolsSchemaConflictError, isToolsSchemaExclusionInForce, } from "./structuredOutputPolicy.js";
 import { coerceJsonToSchema } from "../../utils/json/coerce.js";
@@ -45,6 +46,94 @@ function safePreview(v) {
         return "[unserializable]";
     }
 }
+/**
+ * Turn budget + wrap-up deadline (parity with the googleVertex native loops).
+ * A deadline is engaged only when the caller expressed one: turnTimeoutMs
+ * wins, else an explicit generate timeout. Callers that set neither keep the
+ * pre-existing behaviour (no wrap-up; the outer defensive timeout in
+ * executeStandardGenerateFlow still applies). With `wrapupTimeLeadMs` left of
+ * the deadline, the loop stops offering tools (toolChoice: "none") so the
+ * model spends the remaining budget producing a final answer instead of being
+ * guillotined mid-tool-loop with all work discarded. The lead is clamped to a
+ * quarter of the budget so short explicit timeouts (e.g. 30s) don't trigger
+ * wrap-up on the very first step.
+ *
+ * `turnStartMs` anchors the deadline to the ORIGINAL generation start:
+ * callGenerateText re-runs on executeGeneration's fallback retries
+ * (structured-output conflict, temperature-deprecated) and provider retries,
+ * and a deadline computed from Date.now() per attempt would hand each retry
+ * a fresh budget — multiplying the caller's wall-clock cap.
+ */
+function resolveTurnBudget(options, turnStartMs) {
+    const callerTimeoutMs = parseTimeout(options.timeout);
+    const hasValidTurnTimeout = typeof options.turnTimeoutMs === "number" &&
+        Number.isFinite(options.turnTimeoutMs) &&
+        options.turnTimeoutMs > 0;
+    if (options.turnTimeoutMs !== undefined && !hasValidTurnTimeout) {
+        logger.warn("[GenerationHandler] Ignoring invalid turnTimeoutMs — expected a positive number of milliseconds; falling back to the timeout option", { turnTimeoutMs: options.turnTimeoutMs });
+    }
+    const turnBudgetMs = hasValidTurnTimeout
+        ? options.turnTimeoutMs
+        : callerTimeoutMs;
+    const wrapupLeadMs = turnBudgetMs
+        ? Math.min(options.wrapupTimeLeadMs ?? DEFAULT_WRAPUP_TIME_LEAD_MS, Math.floor(turnBudgetMs / 4))
+        : 0;
+    const turnDeadline = turnBudgetMs ? turnStartMs + turnBudgetMs : undefined;
+    return { callerTimeoutMs, turnBudgetMs, wrapupLeadMs, turnDeadline };
+}
+/**
+ * Merge the per-call providerOptions namespaces for generateText. Both the
+ * timeout forwarding (`neurolink.timeoutMs`, read by NeuroLink's delegating
+ * chat-completions models) and Gemini thinking (`google.thinkingConfig`) may
+ * apply on the same call — built here as ONE object because two conditional
+ * `providerOptions:` spreads in the args literal would silently clobber each
+ * other (object spread does not deep-merge).
+ */
+function buildProviderOptions(options, isGoogleProvider, callerTimeoutMs) {
+    const providerOptions = {};
+    if (callerTimeoutMs !== undefined) {
+        providerOptions.neurolink = { timeoutMs: callerTimeoutMs };
+    }
+    if (options.thinkingConfig?.enabled && isGoogleProvider) {
+        // Gemini 3 uses thinkingLevel; Gemini 2.5 uses thinkingBudget.
+        providerOptions.google = {
+            thinkingConfig: {
+                ...(options.thinkingConfig.thinkingLevel && {
+                    thinkingLevel: options.thinkingConfig.thinkingLevel,
+                }),
+                ...(options.thinkingConfig.budgetTokens &&
+                    !options.thinkingConfig.thinkingLevel && {
+                    thinkingBudget: options.thinkingConfig.budgetTokens,
+                }),
+                includeThoughts: true,
+            },
+        };
+    }
+    return Object.keys(providerOptions).length > 0
+        ? providerOptions
+        : undefined;
+}
+/**
+ * Build the prepareStep result for a forced wrap-up step: tools withdrawn
+ * (toolChoice: "none") plus an honest time message (native-loop parity) —
+ * without the message, weaker models keep trying to emit tool calls and leak
+ * raw tool-call tokens into the text answer.
+ */
+function buildWrapupStepResult(prepared, stepMessages) {
+    const baseMessages = prepared?.messages ??
+        stepMessages;
+    return {
+        ...(prepared ?? {}),
+        messages: [
+            ...baseMessages,
+            {
+                role: "user",
+                content: "The time budget for this task is nearly exhausted. Do not call any more tools. Give your best final answer NOW from the information already gathered, and note anything you could not verify in the remaining time.",
+            },
+        ],
+        toolChoice: "none",
+    };
+}
 /**
  * GenerationHandler class - Handles text generation operations for AI providers
  */
@@ -67,7 +156,8 @@ export class GenerationHandler {
      * Helper method to call generateText with optional structured output
      * @private
      */
-    async callGenerateText(model, messages, tools, options, shouldUseTools, includeStructuredOutput) {
+    async callGenerateText(model, messages, tools, options, callConfig) {
+        const { shouldUseTools, includeStructuredOutput, turnStartMs } = callConfig;
         // Check if this is a Google provider (for provider-specific options)
         const isGoogleProvider = this.providerName === "google-ai" || this.providerName === "vertex";
         // Check if this is an Anthropic provider (includes Vertex+Claude)
@@ -113,6 +203,9 @@ export class GenerationHandler {
             }
         }
         const prepareStep = options.prepareStep;
+        const { callerTimeoutMs, turnBudgetMs, wrapupLeadMs, turnDeadline } = resolveTurnBudget(options, turnStartMs);
+        let wrapupForced = false;
+        const providerOptions = buildProviderOptions(options, isGoogleProvider, callerTimeoutMs);
         // 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)
@@ -148,7 +241,7 @@ export class GenerationHandler {
                 return cachedOverhead.tokens;
             },
         });
-        return await generateText({
+        const result = await generateText({
             model,
             ...(system && { system }),
             messages: nonSystemMessages,
@@ -173,52 +266,72 @@ export class GenerationHandler {
                 // the step's own messages. It never replaces a caller's content
                 // choices — it only reclaims budget from whatever was chosen.
                 const callerMessages = callerResult?.messages;
-                const compacted = stepBudgetGuard(callerMessages ?? stepOptions.messages);
-                if (!compacted) {
-                    return callerResult;
+                // Usage feedback: the provider's REAL prompt-token count for the
+                // previous step calibrates the guard's char-based estimator (see
+                // createStepBudgetGuard) — free precision, no tokenizer.
+                const previousStep = stepOptions.steps[stepOptions.steps.length - 1];
+                const compacted = stepBudgetGuard(callerMessages ?? stepOptions.messages, previousStep?.usage?.inputTokens);
+                const prepared = compacted
+                    ? { ...(callerResult ?? {}), messages: compacted }
+                    : callerResult;
+                // Wrap-up: inside the lead window before the turn deadline, stop
+                // offering tools so this step produces the final answer. Overrides
+                // any caller toolChoice — an honest partial beats a discarded turn.
+                if (turnDeadline !== undefined &&
+                    shouldUseTools &&
+                    Date.now() >= turnDeadline - wrapupLeadMs) {
+                    if (!wrapupForced) {
+                        wrapupForced = true;
+                        logger.warn("[GenerationHandler] Turn budget nearly exhausted — forcing wrap-up (toolChoice: none)", {
+                            provider: this.providerName,
+                            turnBudgetMs,
+                            wrapupLeadMs,
+                            stepNumber: stepOptions.stepNumber,
+                        });
+                    }
+                    return buildWrapupStepResult(prepared, stepOptions.messages);
                 }
-                return { ...(callerResult ?? {}), messages: compacted };
+                return prepared;
             }),
             temperature: options.temperature,
             maxOutputTokens: options.maxTokens,
             maxRetries: 0, // NL11: Disable AI SDK's invisible internal retries; we handle retries with OTel instrumentation
             abortSignal: options.abortSignal,
+            // Schema-driven tool-call repair (BZ-665): fixes near-miss tool names
+            // (case/substring/Levenshtein) and — for tools whose schema carries a
+            // validator — coerces mis-typed arguments ("123" → 123) and remaps
+            // near-miss parameter names before the call is marked invalid. Wired
+            // for every AI-SDK-loop provider; native loops have their own paths.
+            ...(shouldUseTools &&
+                !options.disableToolCallRepair && {
+                experimental_repairToolCall: (async (...repairArgs) => {
+                    // Lazy import to avoid a circular dependency at module load time
+                    const { createToolCallRepair } = await import("../../utils/toolCallRepair.js");
+                    return createToolCallRepair()(...repairArgs);
+                }),
+            }),
+            // Forward the caller's resolved timeout to the model layer: the AI-SDK
+            // V3 call options carry no `timeout`, so delegating chat-completions
+            // models (litellm & friends) could otherwise only ever apply their
+            // provider default per step — an explicit `timeout: "15m"` bounded the
+            // outer loop while each step stayed capped at the default.
+            // Merged namespaces (neurolink timeout forwarding + Gemini thinking) —
+            // built as ONE object; see buildProviderOptions.
+            ...(providerOptions && { providerOptions }),
             ...(useStructuredOutput &&
                 options.schema && {
                 experimental_output: Output.object({ schema: options.schema }),
             }),
-            // Add thinking configuration for extended reasoning
-            // Gemini 3 models use providerOptions.google.thinkingConfig with thinkingLevel
-            // Gemini 2.5 models use thinkingBudget
-            // Anthropic models use experimental_thinking with budgetTokens
-            ...(options.thinkingConfig?.enabled && {
-                // For Anthropic: experimental_thinking with budgetTokens
-                ...(isAnthropicProvider &&
-                    options.thinkingConfig.budgetTokens &&
-                    !options.thinkingConfig.thinkingLevel && {
-                    experimental_thinking: {
-                        type: "enabled",
-                        budgetTokens: options.thinkingConfig.budgetTokens,
-                    },
-                }),
-                // For Google Gemini 3: providerOptions with thinkingLevel
-                // For Gemini 2.5: providerOptions with thinkingBudget
-                ...(isGoogleProvider && {
-                    providerOptions: {
-                        google: {
-                            thinkingConfig: {
-                                ...(options.thinkingConfig.thinkingLevel && {
-                                    thinkingLevel: options.thinkingConfig.thinkingLevel,
-                                }),
-                                ...(options.thinkingConfig.budgetTokens &&
-                                    !options.thinkingConfig.thinkingLevel && {
-                                    thinkingBudget: options.thinkingConfig.budgetTokens,
-                                }),
-                                includeThoughts: true,
-                            },
-                        },
-                    },
-                }),
+            // Anthropic thinking: experimental_thinking with budgetTokens.
+            // (Gemini thinking rides providerOptions.google above.)
+            ...(options.thinkingConfig?.enabled &&
+                isAnthropicProvider &&
+                options.thinkingConfig.budgetTokens &&
+                !options.thinkingConfig.thinkingLevel && {
+                experimental_thinking: {
+                    type: "enabled",
+                    budgetTokens: options.thinkingConfig.budgetTokens,
+                },
             }),
             experimental_telemetry: this.getTelemetryConfigFn(options, "generate"),
             onStepFinish: ({ toolCalls, toolResults }) => {
@@ -237,6 +350,16 @@ export class GenerationHandler {
                 });
             },
         });
+        if (wrapupForced) {
+            // Non-enumerable marker read by formatEnhancedResult to report
+            // stopReason "time-limit" — the result object itself is the only
+            // artifact that travels from this call to result formatting.
+            Object.defineProperty(result, "__nlTurnWrapup", {
+                value: true,
+                enumerable: false,
+            });
+        }
+        return result;
     }
     /**
      * Execute the generation with AI SDK
@@ -293,7 +416,11 @@ export class GenerationHandler {
             }
             const genStartTime = Date.now();
             try {
-                const result = await withProviderRetry(() => this.callGenerateText(model, messages, tools, options, shouldUseTools, true), span, "generateText");
+                const result = await withProviderRetry(() => this.callGenerateText(model, messages, tools, options, {
+                    shouldUseTools,
+                    includeStructuredOutput: true,
+                    turnStartMs: genStartTime,
+                }), span, "generateText");
                 logger.info("[GenerationHandler] generateText returned", {
                     requestId,
                     durationMs: Date.now() - genStartTime,
@@ -388,7 +515,12 @@ export class GenerationHandler {
                     }
                     // Retry without experimental_output - the formatEnhancedResult method
                     // will extract JSON from the text response
-                    const result = await withProviderRetry(() => this.callGenerateText(model, messages, tools, options, shouldUseTools, false), span, "generateText(fallback)");
+                    const result = await withProviderRetry(() => this.callGenerateText(model, messages, tools, options, {
+                        shouldUseTools,
+                        // includeStructuredOutput intentionally omitted
+                        includeStructuredOutput: false,
+                        turnStartMs: genStartTime,
+                    }), span, "generateText(fallback)");
                     // NLK-GAP-007: Record recovery event after successful fallback
                     span.addEvent("retry.recovered", {
                         "retry.attempts": 2,
@@ -439,7 +571,12 @@ export class GenerationHandler {
                         model: this.modelName,
                         error: error instanceof Error ? error.message : String(error),
                     });
-                    const result = await withProviderRetry(() => this.callGenerateText(model, messages, tools, { ...options, temperature: undefined }, shouldUseTools, true), span, "generateText(no-temperature)");
+                    const result = await withProviderRetry(() => this.callGenerateText(model, messages, tools, { ...options, temperature: undefined }, {
+                        shouldUseTools,
+                        // mirror the initial call; the structured-output policy still applies
+                        includeStructuredOutput: true,
+                        turnStartMs: genStartTime,
+                    }), span, "generateText(no-temperature)");
                     span.addEvent("retry.recovered", {
                         "retry.attempts": 2,
                         "retry.strategy": "temperature_omitted",
@@ -722,11 +859,40 @@ export class GenerationHandler {
                     : String(rawReasoning)
             : undefined;
         const reasoningTokens = usage.reasoning ?? undefined;
+        // stopReason / stepsUsed parity with the native loops (Vertex Gemini /
+        // Claude / Bedrock): the AI-SDK loop path previously left both undefined,
+        // so consumers could not distinguish a completed turn from one truncated
+        // by the step cap or ended by the turn budget.
+        const steps = generateResult.steps;
+        const stepsUsed = Array.isArray(steps) ? steps.length : undefined;
+        const maxSteps = options.maxSteps ?? DEFAULT_MAX_STEPS;
+        let stopReason;
+        if (generateResult.__nlTurnWrapup === true) {
+            stopReason = "time-limit";
+        }
+        else if (stepsUsed !== undefined &&
+            stepsUsed >= maxSteps &&
+            generateResult.finishReason === "tool-calls") {
+            stopReason = "step-cap";
+        }
+        else if (generateResult.finishReason === "error") {
+            // Parity with resolveTurnStopReason (native loops): a turn that ended
+            // on a provider "error" finish is not a completion. length /
+            // content-filter DO map to "completed" — deliberately matching the
+            // native contract, where truncation is signaled via finishReason /
+            // rawFinishReason / jsonTruncated, never via stopReason.
+            stopReason = "provider-error";
+        }
+        else if (stepsUsed !== undefined) {
+            stopReason = "completed";
+        }
         return {
             content,
             structuredData,
             usage,
             finishReason: generateResult.finishReason,
+            stopReason,
+            stepsUsed,
             jsonRepaired: jsonRepaired || undefined,
             jsonTruncated: jsonTruncated || undefined,
             provider: this.providerName,

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

@@ -1,6 +1,23 @@
 import type { AIProviderName, ToolUtilities } from "../../types/index.js";
 import type { NeuroLink } from "../../neurolink.js";
 import type { Tool } from "../../types/index.js";
+/**
+ * Build an argument validator for an external MCP tool's JSON Schema, in the
+ * shape the AI SDK's `jsonSchema()` wrapper expects. Returns undefined when
+ * the schema can't be compiled (exotic dialect) — the tool then keeps the
+ * previous declarative-only behaviour instead of failing registration.
+ *
+ * The error message is written for the MODEL (it is fed back verbatim as the
+ * tool-error text): it names the offending fields and restates the contract
+ * (required properties + types) so the retry can succeed on the first attempt.
+ */
+export declare function buildMCPSchemaValidator(toolName: string, schema: Record<string, unknown>): Promise<((value: unknown) => {
+    success: true;
+    value: unknown;
+} | {
+    success: false;
+    error: Error;
+}) | undefined>;
 /**
  * ToolsManager class - Handles all tool management operations
  */

package/dist/core/modules/ToolsManager.js

@@ -13,6 +13,87 @@ function makeToolAbortError() {
     e.name = "AbortError";
     return e;
 }
+/**
+ * Compiled-validator cache, keyed by the ORIGINAL MCP tool inputSchema
+ * object. createExternalMCPTool runs once per external tool on EVERY
+ * getAllTools() (i.e. every generation call), and the schema object identity
+ * is stable for the lifetime of a server connection — without the cache the
+ * same JSON Schema is recompiled on every generate() (hot-path CPU for
+ * 50+-tool deployments). Rediscovery produces new schema objects, so stale
+ * entries fall out via WeakMap semantics. `undefined` values (schemas that
+ * failed to compile) are cached too — hence has()/get() rather than a
+ * get()-only check.
+ */
+const mcpValidatorCache = new WeakMap();
+/**
+ * Build an argument validator for an external MCP tool's JSON Schema, in the
+ * shape the AI SDK's `jsonSchema()` wrapper expects. Returns undefined when
+ * the schema can't be compiled (exotic dialect) — the tool then keeps the
+ * previous declarative-only behaviour instead of failing registration.
+ *
+ * The error message is written for the MODEL (it is fed back verbatim as the
+ * tool-error text): it names the offending fields and restates the contract
+ * (required properties + types) so the retry can succeed on the first attempt.
+ */
+export async function buildMCPSchemaValidator(toolName, schema) {
+    try {
+        const { Validator } = await import("@cfworker/json-schema");
+        // draft-07: the lingua franca of MCP server inputSchemas. shortCircuit
+        // false so the error lists every violation, not just the first.
+        const validator = new Validator(schema, "7", false);
+        const required = Array.isArray(schema.required)
+            ? schema.required
+            : [];
+        const properties = schema.properties && typeof schema.properties === "object"
+            ? schema.properties
+            : {};
+        const contract = Object.entries(properties)
+            .map(([key, prop]) => `${key}${required.includes(key) ? "" : "?"}: ${prop?.type ?? "any"}`)
+            .join(", ");
+        return (value) => {
+            try {
+                const result = validator.validate(value);
+                if (result.valid) {
+                    return { success: true, value };
+                }
+                // Root-level entries ("#") are mostly generic "instance does not
+                // match schema" noise — EXCEPT missing-required errors, which carry
+                // the offending property name and must reach the model.
+                const details = result.errors
+                    .filter((e) => e.instanceLocation !== "#" || /required property/i.test(e.error))
+                    .slice(0, 3)
+                    .map((e) => {
+                    const loc = e.instanceLocation.replace(/^#\/?/, "");
+                    return loc ? `${loc}: ${e.error}` : e.error;
+                })
+                    .join("; ");
+                return {
+                    success: false,
+                    error: new Error(`Invalid arguments for tool '${toolName}'${details ? ` — ${details}` : ""}. ` +
+                        `Expected: { ${contract} } (send every non-optional property with the exact name and JSON type).`),
+                };
+            }
+            catch (validationError) {
+                // Validator crashed on this instance — treat as valid rather than
+                // block the call; the MCP-layer validator still backstops execution.
+                logger.debug(`[ToolsManager] Schema validator failed for '${toolName}', passing through`, {
+                    error: validationError instanceof Error
+                        ? validationError.message
+                        : String(validationError),
+                });
+                return { success: true, value };
+            }
+        };
+    }
+    catch (compileError) {
+        logger.debug(`[ToolsManager] Could not compile schema validator for '${toolName}' — arguments will not be pre-validated`, {
+            error: compileError instanceof Error
+                ? compileError.message
+                : String(compileError),
+        });
+        return undefined;
+    }
+}
 /**
  * Race a tool-execution promise against an AbortSignal so the calling loop
  * observes a deadline/caller abort IMMEDIATELY instead of waiting for the
@@ -583,7 +664,24 @@ export class ToolsManager {
                 const fixedSchema = this.utilities?.fixSchemaForOpenAIStrictMode
                     ? this.utilities.fixSchemaForOpenAIStrictMode(originalSchema)
                     : originalSchema;
-                finalSchema = jsonSchema(fixedSchema);
+                // A jsonSchema() wrapper WITHOUT a validate function is declarative
+                // only — the AI SDK passes any parsed arguments straight through
+                // (safeValidateTypes short-circuits on `validate == null`). That let
+                // malformed calls (missing required params, "123" for a number)
+                // reach execution, where the MCP-layer validator rejected them at
+                // the cost of a full model round-trip. Attach a real validator so
+                // invalid calls fail at parse time, where experimental_repairToolCall
+                // can still fix them silently. Compiled once per schema object —
+                // see mcpValidatorCache.
+                let validate;
+                if (mcpValidatorCache.has(originalSchema)) {
+                    validate = mcpValidatorCache.get(originalSchema);
+                }
+                else {
+                    validate = await buildMCPSchemaValidator(tool.name, fixedSchema);
+                    mcpValidatorCache.set(originalSchema, validate);
+                }
+                finalSchema = jsonSchema(fixedSchema, validate ? { validate } : {});
             }
             else {
                 finalSchema = this.utilities?.createPermissiveZodSchema

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

@@ -30,6 +30,30 @@ export declare const MODEL_CONTEXT_WINDOWS: Record<string, Record<string, number
 export declare function registerRuntimeContextWindow(provider: string, model: string, contextWindow: number): void;
 /** Test hook: clear runtime-discovered windows (state is module-global). */
 export declare function clearRuntimeContextWindows(): void;
+/**
+ * Runtime-discovered window for an exact provider/model pair, or undefined.
+ *
+ * Unlike {@link getContextWindowSize} this NEVER falls back to static table
+ * values. Callers use it to distinguish "the serving infrastructure told us
+ * the real window" (safe to hard-enforce: clamp max_tokens, fail fast) from
+ * "static guess" (advisory only — hard-enforcing a guessed window would
+ * falsely reject requests that the real deployment accepts).
+ */
+export declare function getRuntimeContextWindow(provider: string, model?: string): number | undefined;
+/**
+ * Register a runtime-discovered output-token ceiling for a provider/model
+ * pair. Later registrations overwrite earlier ones (rediscovery refreshes
+ * values). Non-positive/non-finite ceilings are ignored so a malformed
+ * discovery source can never shrink an output budget to zero.
+ */
+export declare function registerRuntimeOutputCeiling(provider: string, model: string, maxOutputTokens: number): void;
+/**
+ * Runtime-discovered output ceiling for an exact provider/model pair, or
+ * undefined when the serving infrastructure has not advertised one.
+ */
+export declare function getRuntimeOutputCeiling(provider: string, model?: string): number | undefined;
+/** Test hook: clear runtime-discovered output ceilings (state is module-global). */
+export declare function clearRuntimeOutputCeilings(): void;
 /**
  * Resolve context window size for a provider/model combination.
  *

package/dist/lib/constants/contextWindows.js

@@ -420,6 +420,56 @@ export function registerRuntimeContextWindow(provider, model, contextWindow) {
 export function clearRuntimeContextWindows() {
     RUNTIME_CONTEXT_WINDOWS.clear();
 }
+/**
+ * Runtime-discovered window for an exact provider/model pair, or undefined.
+ *
+ * Unlike {@link getContextWindowSize} this NEVER falls back to static table
+ * values. Callers use it to distinguish "the serving infrastructure told us
+ * the real window" (safe to hard-enforce: clamp max_tokens, fail fast) from
+ * "static guess" (advisory only — hard-enforcing a guessed window would
+ * falsely reject requests that the real deployment accepts).
+ */
+export function getRuntimeContextWindow(provider, model) {
+    if (!model) {
+        return undefined;
+    }
+    return RUNTIME_CONTEXT_WINDOWS.get(`${provider}:${model}`);
+}
+/**
+ * Runtime-discovered output-token ceilings, keyed `${provider}:${model}` —
+ * the `max_output_tokens` the serving infrastructure advertises for a model
+ * (e.g. LiteLLM `/model/info`). Same async-populate/sync-read contract as
+ * {@link registerRuntimeContextWindow}. Consumed by `getSafeMaxTokens` so
+ * requested maxTokens is clamped to the deployed model's real cap instead of
+ * a static per-provider table value.
+ */
+const RUNTIME_OUTPUT_CEILINGS = new Map();
+/**
+ * Register a runtime-discovered output-token ceiling for a provider/model
+ * pair. Later registrations overwrite earlier ones (rediscovery refreshes
+ * values). Non-positive/non-finite ceilings are ignored so a malformed
+ * discovery source can never shrink an output budget to zero.
+ */
+export function registerRuntimeOutputCeiling(provider, model, maxOutputTokens) {
+    if (!Number.isFinite(maxOutputTokens) || maxOutputTokens <= 0) {
+        return;
+    }
+    RUNTIME_OUTPUT_CEILINGS.set(`${provider}:${model}`, maxOutputTokens);
+}
+/**
+ * Runtime-discovered output ceiling for an exact provider/model pair, or
+ * undefined when the serving infrastructure has not advertised one.
+ */
+export function getRuntimeOutputCeiling(provider, model) {
+    if (!model) {
+        return undefined;
+    }
+    return RUNTIME_OUTPUT_CEILINGS.get(`${provider}:${model}`);
+}
+/** Test hook: clear runtime-discovered output ceilings (state is module-global). */
+export function clearRuntimeOutputCeilings() {
+    RUNTIME_OUTPUT_CEILINGS.clear();
+}
 /**
  * Resolve context window size for a provider/model combination.
  *

package/dist/lib/context/errorDetection.d.ts

@@ -23,6 +23,12 @@ export declare function getContextOverflowProvider(error: unknown): string | nul
 export declare function parseProviderOverflowDetails(error: unknown): {
     actualTokens: number;
     budgetTokens: number;
+    /**
+     * Output tokens the rejected request asked for, when the message states
+     * them separately (vllm/LiteLLM phrasing). Lets recovery re-fit
+     * max_tokens instead of shrinking the input.
+     */
+    requestedOutputTokens?: number;
 } | null;
 /**
  * Extract error message from various error formats.

package/dist/lib/context/errorDetection.js

@@ -113,6 +113,24 @@ export function parseProviderOverflowDetails(error) {
             budgetTokens: parseInt(openaiMax[1].replace(/,/g, ""), 10),
         };
     }
+    // vllm / LiteLLM-proxied backends: "This model's maximum context length is
+    // N tokens. However, you requested X output tokens and your prompt contains
+    // at least Y input tokens..." — input and requested-output are stated
+    // separately (no "resulted in"), so recovery can re-fit max_tokens to
+    // N − Y instead of shrinking the input.
+    const vllmInput = message.match(/prompt\s+contains\s+at\s+least\s+(\d[\d,]{0,19})\s+input\s+tokens/i);
+    if (vllmInput && openaiMax) {
+        const requestedOutput = message.match(/requested\s+(\d[\d,]{0,19})\s+output\s+tokens/i);
+        return {
+            actualTokens: parseInt(vllmInput[1].replace(/,/g, ""), 10),
+            budgetTokens: parseInt(openaiMax[1].replace(/,/g, ""), 10),
+            ...(requestedOutput
+                ? {
+                    requestedOutputTokens: parseInt(requestedOutput[1].replace(/,/g, ""), 10),
+                }
+                : {}),
+        };
+    }
     // Anthropic pattern: "X tokens > Y token limit" or "X tokens, limit Y"
     // Use single character-class number groups to prevent ReDoS (CodeQL: js/polynomial-redos)
     const anthropicMatch = message.match(/(\d[\d,]{0,19})\s*tokens?\s*[>:]\s*(\d[\d,]{0,19})/i);

package/dist/lib/context/stepBudgetGuard.d.ts

@@ -41,7 +41,21 @@ export declare function estimateStepMessagesTokens(messages: readonly ModelMessa
 export declare function estimateFixedOverheadTokens(system: unknown, tools: Record<string, unknown> | undefined, provider?: string): number;
 /**
  * Create a per-step budget guard. Returns a function that, given the step's
- * messages, returns a compacted replacement array when the projected request
- * exceeds the threshold — or `undefined` when no change is needed.
+ * messages (and optionally the REAL input-token count the provider reported
+ * for the previous step), returns a compacted replacement array when the
+ * projected request exceeds the threshold — or `undefined` when no change is
+ * needed.
+ *
+ * Two dynamic behaviours:
+ *  - the available-input budget is re-resolved on EVERY invocation, so
+ *    runtime window discovery (`/model/info`, overflow self-healing) that
+ *    lands mid-loop takes effect immediately instead of the guard staying
+ *    frozen on the value captured at loop start;
+ *  - usage feedback calibrates the estimator: the ratio between the real
+ *    prompt tokens of the previous step and this guard's own estimate for
+ *    what that step sent scales later estimates (only UP — underestimates
+ *    overflow, overestimates merely compact earlier), eliminating the
+ *    char-based estimator's drift on dense code/diff content without
+ *    shipping a tokenizer.
  */
-export declare function createStepBudgetGuard(config: StepBudgetGuardConfig): (messages: readonly ModelMessage[]) => ModelMessage[] | undefined;
+export declare function createStepBudgetGuard(config: StepBudgetGuardConfig): (messages: readonly ModelMessage[], observedInputTokensLastStep?: number) => ModelMessage[] | undefined;