@juspay/neurolink 12.12.15 → 12.13.0

package/dist/providers/googleVertex/client.js

@@ -8,7 +8,7 @@ import { BaseProvider } from "../../core/baseProvider.js";
 import { unwrapImagePayload } from "../../adapters/imageFormatSupport.js";
 import { appendNativeAudioParts } from "../googleNativeGemini3/utils.js";
 import { getMimeTypeForExtension } from "../../processors/config/mimeConstants.js";
-import { DEFAULT_GEMINI_STREAM_TIMEOUT_MS, DEFAULT_MAX_STEPS, DEFAULT_TOOL_EXECUTION_TIMEOUT_MS, DEFAULT_TOOL_MAX_RETRIES, GLOBAL_LOCATION_MODELS, TOOL_STORAGE_TIMEOUT_MS, } from "../../core/constants.js";
+import { DEFAULT_GEMINI_STREAM_TIMEOUT_MS, DEFAULT_MAX_STEPS, DEFAULT_TOOL_MAX_RETRIES, GLOBAL_LOCATION_MODELS, resolveToolTimeoutMs, TOOL_STORAGE_TIMEOUT_MS, } from "../../core/constants.js";
 import { resolveRequestKind } from "../../core/resolveRequestKind.js";
 import { ModelConfigurationManager } from "../../core/modelConfiguration.js";
 import { isSchemaComplexityError } from "../../core/modules/structuredOutputPolicy.js";
@@ -1560,7 +1560,7 @@ export class GoogleVertexProvider extends BaseProvider {
         // (whole-turn deadline + optional stall detector) all trip it, and every
         // request/tool-exec receives effectiveSignal.
         const streamTimeoutMs = parseTimeout(options.timeout) ?? DEFAULT_GEMINI_STREAM_TIMEOUT_MS;
-        const toolExecTimeoutMs = options.toolTimeoutMs ?? DEFAULT_TOOL_EXECUTION_TIMEOUT_MS;
+        const toolExecTimeoutMs = resolveToolTimeoutMs(options.toolTimeoutMs);
         const effectiveTurnDeadlineMs = options.turnTimeoutMs ?? streamTimeoutMs;
         const internalAbort = new AbortController();
         const onCallerAbort = () => internalAbort.abort();
@@ -1790,6 +1790,10 @@ export class GoogleVertexProvider extends BaseProvider {
                     onProgress: () => turnClock.noteProgress(),
                 }),
                 abortSignal: effectiveSignal,
+                // The engine bounds every tool call itself. Passing the value this
+                // loop already gave `buildDedupedEngineTools` keeps the engine's
+                // backstop from being tighter than what the caller asked for.
+                toolTimeoutMs: toolExecTimeoutMs,
             });
             // Collected, NOT forwarded to the consumer here. This loop replays the
             // gathered text after the turn rather than streaming it live, and a
@@ -2356,7 +2360,7 @@ export class GoogleVertexProvider extends BaseProvider {
         // (whole-turn deadline + optional stall detector) all trip it, and every
         // request/tool-exec receives effectiveSignal.
         const streamTimeoutMs = parseTimeout(options.timeout) ?? DEFAULT_GEMINI_STREAM_TIMEOUT_MS;
-        const toolExecTimeoutMs = options.toolTimeoutMs ?? DEFAULT_TOOL_EXECUTION_TIMEOUT_MS;
+        const toolExecTimeoutMs = resolveToolTimeoutMs(options.toolTimeoutMs);
         const effectiveTurnDeadlineMs = options.turnTimeoutMs ?? streamTimeoutMs;
         const internalAbort = new AbortController();
         const onCallerAbort = () => internalAbort.abort();
@@ -2585,6 +2589,10 @@ export class GoogleVertexProvider extends BaseProvider {
                     onProgress: () => turnClock.noteProgress(),
                 }),
                 abortSignal: effectiveSignal,
+                // The engine bounds every tool call itself. Passing the value this
+                // loop already gave `buildDedupedEngineTools` keeps the engine's
+                // backstop from being tighter than what the caller asked for.
+                toolTimeoutMs: toolExecTimeoutMs,
             });
             // generate() returns one result rather than streaming, so the engine's
             // chunks are drained and discarded — the answer comes off the turn's
@@ -3304,7 +3312,7 @@ export class GoogleVertexProvider extends BaseProvider {
         if (options.abortSignal?.aborted) {
             internalAbort.abort();
         }
-        const toolExecTimeoutMs = options.toolTimeoutMs ?? DEFAULT_TOOL_EXECUTION_TIMEOUT_MS;
+        const toolExecTimeoutMs = resolveToolTimeoutMs(options.toolTimeoutMs);
         const effectiveTurnDeadlineMs = options.turnTimeoutMs ?? streamTimeoutMs;
         // Whole-turn deadline + optional stall watchdog. When the caller sets no
         // explicit turn budget, keep the pre-existing defensive bound
@@ -3668,6 +3676,9 @@ export class GoogleVertexProvider extends BaseProvider {
                     tools: engineTools,
                     abortSignal: internalAbort.signal,
                     ...(activeSpan ? { span: activeSpan } : {}),
+                    // Same value `guardToolExecutor` already received above, so the
+                    // engine's own per-tool bound cannot undercut it.
+                    toolTimeoutMs: toolExecTimeoutMs,
                 });
                 const pump = (async () => {
                     for await (const chunk of engineStream) {
@@ -4474,7 +4485,7 @@ export class GoogleVertexProvider extends BaseProvider {
         if (options.abortSignal?.aborted) {
             internalAbort.abort();
         }
-        const toolExecTimeoutMs = options.toolTimeoutMs ?? DEFAULT_TOOL_EXECUTION_TIMEOUT_MS;
+        const toolExecTimeoutMs = resolveToolTimeoutMs(options.toolTimeoutMs);
         // Whole-turn deadline + optional stall watchdog. NOTE: unlike the stream
         // twin, this path historically had NO whole-turn bound (only the per-call
         // withTimeout) — so no defensive default is introduced here: without an
@@ -4668,6 +4679,9 @@ export class GoogleVertexProvider extends BaseProvider {
         const { stream: engineStream, resultPromise } = runAgenticLoop(adapter, currentMessages.slice(), {
             tools: engineTools,
             abortSignal: internalAbort.signal,
+            // Same value `guardToolExecutor` already received above, so the
+            // engine's own per-tool bound cannot undercut it.
+            toolTimeoutMs: toolExecTimeoutMs,
         });
         // Drained and discarded: generate() returns one result rather than
         // streaming, and the per-step text is accumulated in

package/dist/types/generate.d.ts

@@ -410,11 +410,24 @@ export type GenerateOptions = {
      */
     wrapupTimeLeadMs?: number;
     /**
-     * Per-tool-execution timeout in milliseconds (default 300_000). A tool
-     * that exceeds it fails with an error tool_result and costs one step —
-     * the turn continues instead of hanging on a wedged tool.
-     */
-    toolTimeoutMs?: number;
+     * Per-tool-execution timeout in milliseconds (default 300_000), or `null`
+     * for no bound at all.
+     *
+     * A tool that exceeds it is told to stop — the AbortSignal it was handed is
+     * aborted — and then fails with an error tool_result costing one step, so
+     * the turn continues instead of hanging on a wedged tool. A tool that
+     * ignores its signal keeps running to completion in the background; nothing
+     * here can stop it, and its eventual result is discarded.
+     *
+     * `null` removes the bound and awaits `execute` unguarded, which is what the
+     * native loops did before they had a per-tool timer. It is the way to keep a
+     * legitimately long-running tool, since a finite number is always a ceiling
+     * and `Infinity` silently becomes `setTimeout`'s ~24.9-day cap. The one
+     * combination refused is `null` together with
+     * `executionControl.lifetimeTimeoutMs: null`, which would leave the turn
+     * with no bound anywhere.
+     */
+    toolTimeoutMs?: number | null;
     /** AbortSignal for external cancellation of the AI call */
     abortSignal?: AbortSignal;
     /**
@@ -1201,8 +1214,8 @@ export type TextGenerationOptions = {
     stallTimeoutMs?: number;
     /** Remaining-time threshold that triggers the wrap-up nudge (ms). See GenerateOptions.wrapupTimeLeadMs. */
     wrapupTimeLeadMs?: number;
-    /** Per-tool-execution timeout (ms, default 300_000). See GenerateOptions.toolTimeoutMs. */
-    toolTimeoutMs?: number;
+    /** Per-tool-execution timeout (ms, default 300_000; `null` for no bound). See GenerateOptions.toolTimeoutMs. */
+    toolTimeoutMs?: number | null;
     /** AbortSignal for external cancellation of the AI call */
     abortSignal?: AbortSignal;
     /** Bounds for tool execution capture. See GenerateOptions.toolExecutionCapture. */
@@ -1587,8 +1600,8 @@ export type NativeGenerateLoopArgs = {
     maxOutputTokens?: number;
     temperature?: number;
     abortSignal?: AbortSignal;
-    /** Per-tool-execution cap, forwarded into `guardToolExecutor`. */
-    toolTimeoutMs?: number;
+    /** Per-tool-execution cap, forwarded into `guardToolExecutor`. `null` for no bound. */
+    toolTimeoutMs?: number | null;
     /** Wraps one step: retry ladder plus provider error classification. */
     runStep: (call: () => Promise<Record<string, unknown>>) => Promise<Record<string, unknown>>;
 };

package/dist/types/loopEngine.d.ts

@@ -2,6 +2,7 @@ import type Anthropic from "@anthropic-ai/sdk";
 import type { Span } from "@opentelemetry/api";
 import type { Tool } from "./tools.js";
 import type { CollectedChunkResult, NativeFunctionCall, NativeToolDeclarationsResult } from "./providers.js";
+import type { ExecutionControlDecision, ExecutionControlStepContext } from "./stream.js";
 /**
  * One chunk on the engine's stream.
  *
@@ -163,6 +164,17 @@ export type AgenticLoopAdapter<TConversation = unknown, TRaw = unknown> = {
     readonly maxSteps: number;
     /** Set only for adapter instances whose client has the TOOL_NOT_FOUND strike breaker today: both Gemini adapters (AI Studio, Vertex+Gemini) AND the Vertex+Claude call to createAnthropicLoopAdapter — NOT the native-Anthropic call to that same factory, and not Bedrock. See Verified Fact 4. */
     readonly toolFailureBreaker?: AgenticLoopToolFailureBreaker;
+    /**
+     * Append a planning nudge to the conversation, in the provider's own message
+     * type. Supplied only by adapters whose caller can pass a step-boundary
+     * callback; the engine skips a nudge it has no way to write.
+     *
+     * Provider-supplied for the same reason `buildToolResultMessages` is: the
+     * engine does not know what a valid user turn looks like on this wire, and
+     * on Anthropic a nudge appended after a tool-result turn has to merge into
+     * that turn rather than open a second consecutive user message.
+     */
+    readonly appendPlanningNudge?: (conversation: TConversation, text: string) => TConversation;
     /**
      * Second lookup path, consulted when a tool call names nothing executable
      * in the caller's `options.tools` — used by adapters supporting mid-turn
@@ -265,6 +277,30 @@ export type AnthropicLoopAdapterConfig<TMessage = Anthropic.Messages.MessagePara
      * tell them apart would be guesswork, so the adapter says which happened.
      */
     onTerminalResult?: (text: string) => void;
+    /**
+     * Hard deadline for ONE `messages.create` request (ms). Composed with the
+     * engine's signal for the duration of that step only, so it bounds a stalled
+     * upstream even when the turn itself has no lifetime ceiling — and is armed
+     * fresh per step, which is why a step boundary can never extend a deadline
+     * already running.
+     *
+     * When the deadline fires, the step throws the timer's own TimeoutError
+     * rather than returning what it had: the Anthropic SDK's stream iterator
+     * exits WITHOUT throwing on an aborted read, so a truncated step would
+     * otherwise be reported as a model turn that simply said less.
+     */
+    requestTimeoutMs?: number;
+    /**
+     * Require the upstream terminal event (`message_stop`) before a step counts
+     * as complete.
+     *
+     * A response that ends early carries syntactically complete content blocks —
+     * including tool_use blocks — so without this the loop dispatches tools the
+     * model never finished asking for and reports the turn as a normal stop.
+     * Off by default: turning it on unconditionally would change what every
+     * existing caller sees from a flaky connection.
+     */
+    requireTerminalEvent?: boolean;
     toolFailureBreaker?: AgenticLoopToolFailureBreaker;
     /**
      * In-turn context reclaim, run once per step before the request is built.
@@ -305,8 +341,15 @@ export type AnthropicLoopAdapterConfig<TMessage = Anthropic.Messages.MessagePara
  * never had.
  */
 export type ToolExecutionGuards = {
-    /** Upper bound on a single execute(); omit for no bound. */
-    toolTimeoutMs?: number;
+    /**
+     * Upper bound on a single execute(). Omit, or pass `null`, for no bound.
+     *
+     * `null` is accepted as well as `undefined` because it is what a caller's
+     * own `toolTimeoutMs: null` resolves to, and the two must not diverge: a
+     * value that means "unbounded" at the public surface cannot arrive here
+     * meaning "0ms".
+     */
+    toolTimeoutMs?: number | null;
     /**
      * Turn-level abort, raced against the call so a deadline or caller cancel is
      * observed immediately instead of after the tool settles.
@@ -491,6 +534,44 @@ export type AgenticLoopOptions = {
      * because only they threaded a span before moving onto the engine.
      */
     span?: Span;
+    /**
+     * Upper bound on a single `tool.execute()` (ms), or `null` for no bound.
+     * Defaults to `DEFAULT_TOOL_EXECUTION_TIMEOUT_MS` (300_000) when omitted.
+     *
+     * The turn-level timers do not cover this: a per-request deadline bounds one
+     * model call and is disposed when the step settles, and the step cap only
+     * advances when a step completes. Between two steps, a tool that never
+     * returns has nothing watching it, and a turn that opted out of a lifetime
+     * ceiling then hangs forever. A tool that exceeds the bound is told to stop
+     * — the signal it was handed is aborted — and fails with an error tool
+     * result costing one step, exactly as it does on the native generate path.
+     *
+     * `null` restores the behaviour of a loop with no per-tool timer at all:
+     * `execute` is awaited unguarded, with the turn's own signal. Callers that
+     * relied on unbounded tool execution say so with it. The one combination
+     * refused is `null` together with `executionControl.lifetimeTimeoutMs: null`
+     * — that would leave the turn with no bound anywhere.
+     *
+     * Callers that already guard their executors (Vertex and the Gemini
+     * adapters, via `guardToolExecutor`) should pass the SAME value they gave
+     * those guards, so this backstop can never be tighter than what the caller
+     * asked for.
+     */
+    toolTimeoutMs?: number | null;
+    /**
+     * Step-boundary callback. Runs after a step's tool results have settled and
+     * been written into the conversation, and BEFORE the loop re-checks the step
+     * cap — the one point in a turn where raising the cap changes what happens
+     * next without replaying anything that already happened.
+     *
+     * Already bounded and cancellable by the time it reaches the engine: the
+     * caller owns the callback's own budget, because the caller is what the
+     * public option was validated against. The engine only calls it, applies a
+     * strictly-larger finite cap if one comes back, and asks the adapter to
+     * write the nudge. It never restarts a step, retries a request, or replays a
+     * tool.
+     */
+    beforeStep?: (context: ExecutionControlStepContext) => Promise<ExecutionControlDecision | undefined>;
 };
 export type AgenticLoopResult<TConversation> = {
     text: string;
@@ -518,4 +599,18 @@ export type AgenticLoopResult<TConversation> = {
     finishReason: string;
     rawStopReason: string | undefined;
     conversation: TConversation;
+    /**
+     * True when the turn ended because its abort signal fired rather than
+     * because the model finished.
+     *
+     * Not derivable from anything else on this result, which is why it is here.
+     * A turn cut short mid-stream never receives a terminal event, so
+     * `rawStopReason` is undefined and `mapFinishReason` lands on exactly the
+     * value a model that answered and stopped produces. Without this flag a
+     * caller reading the result cannot tell "the model finished" from "we
+     * stopped listening", and every consumer that branches on the outcome —
+     * fallback gates, retry policy, a UI that says why a turn ended — reads the
+     * interrupted turn as a success.
+     */
+    aborted: boolean;
 };

package/dist/types/stream.d.ts

@@ -184,6 +184,114 @@ export type ProviderStreamChunk = {
         base64: string;
     };
 };
+/**
+ * What a `beforeStep` callback is told at a step boundary.
+ *
+ * The boundary is reached only after that step's tool results have settled and
+ * been written into the conversation, and before the step cap is re-checked —
+ * so a decision taken here applies to the NEXT step of the SAME turn, never to
+ * a step already in flight.
+ */
+export type ExecutionControlStepContext = {
+    /** Zero-based index of the step that just settled. */
+    stepIndex: number;
+    /** Steps that have completed in this turn, including the one that just settled. */
+    stepsCompleted: number;
+    /** The step cap currently in force — the number a renewal must exceed. */
+    maxSteps: number;
+    /** Milliseconds since the turn's first request was built. */
+    elapsedMs: number;
+    /** Names of the tools dispatched on the step that just settled, in order. */
+    toolNames: string[];
+    /**
+     * Fires when the turn is cancelled or the callback outlives its own budget.
+     * A callback that does real work (reading a live budget, asking a service)
+     * must honour it — the turn does not wait for a callback that ignores it.
+     */
+    signal: AbortSignal;
+};
+/**
+ * What a `beforeStep` callback may change about the rest of the turn.
+ *
+ * Returning nothing is a decision too: it declines the renewal, so the
+ * existing cap stands and a turn that has reached it ends as a step-limit
+ * outcome exactly as it would with no callback at all.
+ */
+export type ExecutionControlDecision = {
+    /**
+     * A new absolute step cap. Must be finite and greater than the cap in force;
+     * anything else is ignored, so a callback cannot shorten a turn by returning
+     * a smaller number or unbound one by returning Infinity.
+     */
+    maxSteps?: number;
+    /**
+     * A planning nudge appended to the conversation before the next step, in the
+     * same loop and the same history — this is how a caller tells the model that
+     * its budget changed without restarting the turn.
+     */
+    nudge?: string;
+};
+/**
+ * Opt-in execution policy for one streamed turn. Supported only on the native
+ * Anthropic stream path today; any other provider REJECTS it rather than
+ * ignoring it, because silently dropping a policy the caller set is how a turn
+ * ends at a limit its owner believed it had removed.
+ *
+ * Absent, none of the turn-level policy here applies: the turn is bounded by
+ * `timeout` / `turnTimeoutMs` / `maxSteps` as it always was.
+ *
+ * One thing is NOT conditional on this option, and it is worth stating because
+ * it changed: the agentic engine bounds every tool call, at
+ * `toolTimeoutMs` or the 300s default, whether or not `executionControl` is
+ * present. Loops that previously ran tools with no per-tool timer at all — the
+ * Bedrock and Google AI Studio paths — therefore acquired one. A caller that
+ * relied on unbounded tool execution says so with `toolTimeoutMs: null`, which
+ * restores exactly the old behaviour.
+ */
+export type ExecutionControlOptions = {
+    /**
+     * Hard deadline for a single HTTP request (ms). Required, finite, positive.
+     *
+     * This is the floor that makes the rest of the contract safe: whatever the
+     * turn-level policy is — including no lifetime ceiling at all — a stalled
+     * upstream is always caught here, with the timer's own identity on the
+     * error. A step boundary cannot reset a deadline already running.
+     */
+    requestTimeoutMs: number;
+    /**
+     * The turn's wall-clock ceiling (ms).
+     *
+     * - `null` — no lifetime timer is armed at all. This is the case that cannot
+     *   be expressed any other way: a very large number is still a ceiling, and
+     *   it fires eventually, in the middle of work, dressed as a cancel. With no
+     *   lifetime timer the per-tool deadline is the turn's last bound, so
+     *   `toolTimeoutMs: null` is refused alongside it.
+     * - a finite positive number — an explicit cap, reported as `time-limit`.
+     * - `0`, negative, or non-finite — rejected.
+     * - absent — the legacy handling (`turnTimeoutMs`, else the provider
+     *   timeout) is inherited untouched.
+     *
+     * Set to anything other than absent, this OWNS the turn's lifetime timer, so
+     * a `turnTimeoutMs` on the same request would be read by nothing. That
+     * combination is rejected rather than silently resolved — set one or the
+     * other. Note that "absent" means the property is not there AND that it is
+     * present holding `undefined`: both say "no opinion", and both inherit.
+     */
+    lifetimeTimeoutMs?: number | null;
+    /**
+     * Runs at each step boundary. May renew the step cap and append a planning
+     * nudge. It is itself bounded by `beforeStepTimeoutMs` and cancelled with
+     * the turn; a callback that throws, or outlives its budget, is treated as
+     * declining to renew.
+     */
+    beforeStep?: (context: ExecutionControlStepContext) => ExecutionControlDecision | undefined | Promise<ExecutionControlDecision | undefined>;
+    /**
+     * Bound on `beforeStep` itself (ms, finite and positive; default 30_000).
+     * A boundary callback sits between two model calls, so an unbounded one
+     * stalls the turn in a place no other timer is watching.
+     */
+    beforeStepTimeoutMs?: number;
+};
 export type StreamOptions = {
     /**
      * Opt this stream call into the knowledge grounding configured on the
@@ -376,12 +484,39 @@ export type StreamOptions = {
     timeout?: number | string;
     /** Wall-clock cap for the whole agentic turn (ms). See GenerateOptions.turnTimeoutMs. */
     turnTimeoutMs?: number;
+    /**
+     * Opt-in execution policy for this turn (native Anthropic streaming only).
+     * See ExecutionControlOptions. Absent means the legacy bounds apply
+     * unchanged; present on any other provider is an error, not a no-op.
+     *
+     * Two consequences of that "error, not a no-op" stance are worth knowing
+     * before you set it:
+     *
+     * - **It is incompatible with provider fallback.** Only the native Anthropic
+     *   stream path implements the contract, so a turn that falls back to any
+     *   other provider — internal fallback, or a configured fallback chain —
+     *   fails there with a ValidationError instead of being served without the
+     *   policy. That is deliberate: a fallback that silently dropped the policy
+     *   would produce exactly the invisible ceiling this option exists to
+     *   remove. Pair it with `disableInternalFallback: true` when you want the
+     *   turn to stay on Anthropic, and handle the error if you do not.
+     * - **It cannot be combined with `turnTimeoutMs`** when it sets
+     *   `lifetimeTimeoutMs`, because both name the turn's wall-clock ceiling and
+     *   only one of them can win. Supplying both is rejected up front rather
+     *   than resolved in silence.
+     * - **`lifetimeTimeoutMs: null` cannot be combined with
+     *   `toolTimeoutMs: null`.** Removing the turn's ceiling leaves the per-tool
+     *   deadline as the only thing that will ever end a tool which never
+     *   returns; removing that as well leaves the turn with no bound anywhere.
+     *   Also rejected up front.
+     */
+    executionControl?: ExecutionControlOptions;
     /** Max time with no progress before the turn ends as "stalled" (ms). Native Vertex loops only — see GenerateOptions.stallTimeoutMs. */
     stallTimeoutMs?: number;
     /** Remaining-time threshold that triggers the wrap-up nudge (ms). See GenerateOptions.wrapupTimeLeadMs. */
     wrapupTimeLeadMs?: number;
-    /** Per-tool-execution timeout (ms, default 300_000). See GenerateOptions.toolTimeoutMs. */
-    toolTimeoutMs?: number;
+    /** Per-tool-execution timeout (ms, default 300_000; `null` for no bound). See GenerateOptions.toolTimeoutMs. */
+    toolTimeoutMs?: number | null;
     /** AbortSignal for external cancellation of the AI call */
     abortSignal?: AbortSignal;
     /** Bounds for tool execution capture. See GenerateOptions.toolExecutionCapture. */
@@ -641,9 +776,10 @@ export type StreamResult = {
     finishReason?: string;
     /**
      * Why the agentic turn ended (see GenerateStopReason). For background-loop
-     * streams (native Vertex paths) prefer `metadata.stopReason` after draining
-     * the stream — this top-level field may be a getter that resolves late, and
-     * wrapper spreads can snapshot it before the loop finishes.
+     * streams (the native Vertex paths and the native Anthropic stream path)
+     * prefer `metadata.stopReason` after draining the stream — this top-level
+     * field may be a getter that resolves late, and wrapper spreads can
+     * snapshot it before the loop finishes.
      */
     stopReason?: GenerateStopReason;
     /** Verbatim provider finish/stop reason for the turn's terminal model call. */

package/dist/utils/parameterValidation.d.ts

@@ -198,3 +198,33 @@ export declare function createValidationSummary(result: EnhancedValidationResult
  * Check if validation result has only warnings (no errors)
  */
 export declare function hasOnlyWarnings(result: EnhancedValidationResult): boolean;
+/**
+ * Default bound on a `beforeStep` callback (ms).
+ *
+ * A boundary callback sits between two model calls, in the one place no other
+ * timer in the turn is watching: the request deadline has been disposed and
+ * the next one is not armed yet. An unbounded callback therefore stalls the
+ * turn silently and indefinitely.
+ */
+export declare const DEFAULT_BEFORE_STEP_TIMEOUT_MS = 30000;
+/**
+ * Validate an opt-in `executionControl` object and its provider support.
+ *
+ * Rejecting rather than ignoring is the whole point. A caller that asked for
+ * no lifetime ceiling and got one anyway does not find out at call time — it
+ * finds out much later, when a long turn dies at a limit its owner believed it
+ * had removed, reported as an ordinary cancel. So an unsupported provider is an
+ * error here, and so is every shape that could be read two ways.
+ *
+ * Throws ValidationError; returns void when the control is absent or valid.
+ *
+ * @param request the sibling options on the SAME call that this control has to
+ *   be read together with. `turnTimeoutMs`, because a combination in which one
+ *   of the two ceilings would be silently discarded is rejected instead; and
+ *   `toolTimeoutMs`, because removing the turn's ceiling makes the per-tool
+ *   deadline the last thing watching a tool that never returns.
+ */
+export declare function validateExecutionControl(control: unknown, providerName: string, supported: boolean, request?: {
+    turnTimeoutMs?: unknown;
+    toolTimeoutMs?: unknown;
+}): void;

package/dist/utils/parameterValidation.js

@@ -978,3 +978,104 @@ export function createValidationSummary(result) {
 export function hasOnlyWarnings(result) {
     return result.errors.length === 0 && result.warnings.length > 0;
 }
+// ============================================================================
+// EXECUTION CONTROL
+// ============================================================================
+/**
+ * Default bound on a `beforeStep` callback (ms).
+ *
+ * A boundary callback sits between two model calls, in the one place no other
+ * timer in the turn is watching: the request deadline has been disposed and
+ * the next one is not armed yet. An unbounded callback therefore stalls the
+ * turn silently and indefinitely.
+ */
+export const DEFAULT_BEFORE_STEP_TIMEOUT_MS = 30_000;
+function isFinitePositive(value) {
+    return typeof value === "number" && Number.isFinite(value) && value > 0;
+}
+/**
+ * Validate an opt-in `executionControl` object and its provider support.
+ *
+ * Rejecting rather than ignoring is the whole point. A caller that asked for
+ * no lifetime ceiling and got one anyway does not find out at call time — it
+ * finds out much later, when a long turn dies at a limit its owner believed it
+ * had removed, reported as an ordinary cancel. So an unsupported provider is an
+ * error here, and so is every shape that could be read two ways.
+ *
+ * Throws ValidationError; returns void when the control is absent or valid.
+ *
+ * @param request the sibling options on the SAME call that this control has to
+ *   be read together with. `turnTimeoutMs`, because a combination in which one
+ *   of the two ceilings would be silently discarded is rejected instead; and
+ *   `toolTimeoutMs`, because removing the turn's ceiling makes the per-tool
+ *   deadline the last thing watching a tool that never returns.
+ */
+export function validateExecutionControl(control, providerName, supported, request = {}) {
+    const { turnTimeoutMs, toolTimeoutMs } = request;
+    if (control === undefined || control === null) {
+        return;
+    }
+    if (!isNonNullObject(control)) {
+        throw new ValidationError("executionControl must be an object", "executionControl", "INVALID_TYPE");
+    }
+    if (!supported) {
+        throw new ValidationError(`executionControl is not supported by provider "${providerName}" — it is implemented only on the native Anthropic stream path. Remove it, or route this turn to anthropic.`, "executionControl", "UNSUPPORTED_PROVIDER", [
+            "Use provider: 'anthropic' for turns that need executionControl",
+            "Use turnTimeoutMs / maxSteps for other providers",
+        ]);
+    }
+    const opts = control;
+    if (!isFinitePositive(opts.requestTimeoutMs)) {
+        throw new ValidationError(`executionControl.requestTimeoutMs is required and must be a finite positive number of milliseconds (received ${String(opts.requestTimeoutMs)}). It is the deadline that bounds a stalled upstream even when the turn has no lifetime ceiling, so there is no valid turn without it.`, "executionControl.requestTimeoutMs", "INVALID_VALUE");
+    }
+    // `null` is a value here, not an omission: it is the only way to say "no
+    // lifetime timer at all", which no number can express — a very large one is
+    // still a ceiling that fires mid-turn.
+    if (opts.lifetimeTimeoutMs !== undefined &&
+        opts.lifetimeTimeoutMs !== null &&
+        !isFinitePositive(opts.lifetimeTimeoutMs)) {
+        throw new ValidationError(`executionControl.lifetimeTimeoutMs must be null (no lifetime ceiling), a finite positive number of milliseconds, or absent (inherit the legacy timeout handling). Received ${String(opts.lifetimeTimeoutMs)}.`, "executionControl.lifetimeTimeoutMs", "INVALID_VALUE");
+    }
+    // Two whole-turn ceilings, one turn. An explicit `lifetimeTimeoutMs` — a
+    // number or `null` — takes over the turn's lifetime timer completely, so a
+    // `turnTimeoutMs` supplied alongside it was read by nothing at all. Dropping
+    // it silently is the same defect this contract exists to remove, one layer
+    // up: the caller's stated ceiling is discarded and it finds out when the
+    // turn ends somewhere it did not expect.
+    //
+    // Scoped deliberately to the case where the drop happens. `lifetimeTimeoutMs`
+    // ABSENT means "no opinion about the turn's lifetime", and that documented
+    // case inherits `turnTimeoutMs` and honours it — there is nothing to reject.
+    if (opts.lifetimeTimeoutMs !== undefined &&
+        typeof turnTimeoutMs === "number" &&
+        Number.isFinite(turnTimeoutMs) &&
+        turnTimeoutMs > 0) {
+        throw new ValidationError(`turnTimeoutMs (${turnTimeoutMs}) cannot be combined with executionControl.lifetimeTimeoutMs (${String(opts.lifetimeTimeoutMs)}): both set the turn's wall-clock ceiling, and executionControl wins, so the turnTimeoutMs would be ignored. Set exactly one of them.`, "executionControl.lifetimeTimeoutMs", "INVALID_VALUE", [
+            "Drop turnTimeoutMs and express the ceiling as executionControl.lifetimeTimeoutMs",
+            "Or drop executionControl.lifetimeTimeoutMs to inherit turnTimeoutMs unchanged",
+        ]);
+    }
+    // No ceiling, and no floor either. `lifetimeTimeoutMs: null` deliberately
+    // arms no turn-level timer, which leaves the per-tool deadline as the only
+    // thing that will ever end a tool that neither returns nor honours its
+    // signal — the step cap does not advance while a tool is in flight, and the
+    // request deadline was disposed when the step settled. `toolTimeoutMs: null`
+    // removes that too, and the turn then has nothing watching it anywhere.
+    //
+    // Refused rather than resolved, because there is no safe way to pick which
+    // of the two the caller meant to keep, and picking one silently is how a
+    // turn ends up bounded by a limit its owner did not choose.
+    if (opts.lifetimeTimeoutMs === null && toolTimeoutMs === null) {
+        throw new ValidationError("executionControl.lifetimeTimeoutMs: null removes the turn's wall-clock ceiling, which leaves toolTimeoutMs as the only bound on a tool that never returns — and toolTimeoutMs: null removes that one too, so the turn would have no bound anywhere. Keep one of them.", "executionControl.lifetimeTimeoutMs", "INVALID_VALUE", [
+            "Give toolTimeoutMs a finite bound, or omit it to take the 300000ms default",
+            "Or give executionControl.lifetimeTimeoutMs a finite ceiling instead of null",
+        ]);
+    }
+    if (opts.beforeStep !== undefined && typeof opts.beforeStep !== "function") {
+        throw new ValidationError("executionControl.beforeStep must be a function", "executionControl.beforeStep", "INVALID_TYPE");
+    }
+    if (opts.beforeStepTimeoutMs !== undefined &&
+        !isFinitePositive(opts.beforeStepTimeoutMs)) {
+        throw new ValidationError(`executionControl.beforeStepTimeoutMs must be a finite positive number of milliseconds when supplied. Received ${String(opts.beforeStepTimeoutMs)}.`, "executionControl.beforeStepTimeoutMs", "INVALID_VALUE");
+    }
+}

package/dist/utils/timeout.js

@@ -259,12 +259,35 @@ export async function withTimeout(promise, timeout, provider, operation) {
     if (!timeoutMs) {
         return promise;
     }
+    // The handle is captured, unref'd and cleared — the same shape
+    // `createTimeoutPromise` above already uses. `Promise.race` settles on the
+    // first outcome but cancels nothing, so an uncaptured timer stayed pending
+    // for its full duration after the wrapped promise had already resolved: one
+    // live timer per call, each holding the event loop open until it fired. The
+    // `finally` clears it the moment the race is decided, which is what makes
+    // this safe to wrap around something invoked once per tool call.
+    let timeoutHandle;
     const timeoutPromise = new Promise((_, reject) => {
-        setTimeout(() => {
+        const timer = setTimeout(() => {
             reject(new TimeoutError(`${provider} ${operation} operation timed out after ${timeoutMs}ms`, timeoutMs, provider, operation));
         }, timeoutMs);
+        timeoutHandle = timer;
+        // Unref the timer so it doesn't keep the process alive (Node.js only)
+        if (typeof timer === "object" &&
+            timer &&
+            "unref" in timer &&
+            typeof timer.unref === "function") {
+            timer.unref();
+        }
     });
-    return Promise.race([promise, timeoutPromise]);
+    try {
+        return await Promise.race([promise, timeoutPromise]);
+    }
+    finally {
+        if (timeoutHandle !== undefined) {
+            clearTimeout(timeoutHandle);
+        }
+    }
 }
 /**
  * Wrap a streaming async generator with timeout