@juspay/neurolink 12.12.15 → 12.13.0

package/dist/core/baseProvider.d.ts

@@ -41,6 +41,16 @@ export declare abstract class BaseProvider implements AIProvider {
      * @returns the current model's registered capability, or true when unknown
      */
     supportsTools(): boolean;
+    /**
+     * Whether this provider implements the opt-in `executionControl` contract.
+     *
+     * Default false, and that default is load-bearing: a provider that has not
+     * implemented the contract must REJECT it, not ignore it. Silently dropping
+     * a caller-set execution policy is invisible until a long turn dies at a
+     * ceiling its owner believed had been removed. Overridden only where the
+     * control is genuinely honoured end to end.
+     */
+    supportsExecutionControl(): boolean;
     /**
      * Apply the shared tool gate and optionally report registry-backed
      * suppression at the request entry point.

package/dist/core/baseProvider.js

@@ -46,6 +46,7 @@ import { TelemetryHandler } from "./modules/TelemetryHandler.js";
 import { ToolsManager } from "./modules/ToolsManager.js";
 import { Utilities } from "./modules/Utilities.js";
 import { generateOnceNative } from "../utils/nativeSingleShot.js";
+import { validateExecutionControl } from "../utils/parameterValidation.js";
 import { extractTokenUsage } from "../utils/tokenUtils.js";
 /**
  * Read the consumer-facing lifecycle callbacks buried inside a request's
@@ -182,6 +183,18 @@ export class BaseProvider {
     supportsTools() {
         return modelSupports("functionCalling", this.providerName, this.modelName);
     }
+    /**
+     * Whether this provider implements the opt-in `executionControl` contract.
+     *
+     * Default false, and that default is load-bearing: a provider that has not
+     * implemented the contract must REJECT it, not ignore it. Silently dropping
+     * a caller-set execution policy is invisible until a long turn dies at a
+     * ceiling its owner believed had been removed. Overridden only where the
+     * control is genuinely honoured end to end.
+     */
+    supportsExecutionControl() {
+        return false;
+    }
     /**
      * Apply the shared tool gate and optionally report registry-backed
      * suppression at the request entry point.
@@ -211,6 +224,14 @@ export class BaseProvider {
         // maxTokens (getSafeMaxTokens consults the discovered output ceiling).
         await this.ensureModelLimits();
         let options = this.normalizeStreamOptions(optionsOrPrompt);
+        // Before anything else, and before a single byte leaves the process: an
+        // execution policy this provider cannot honour is an error, and a policy
+        // whose shape could be read two ways is an error. Both are silent bugs at
+        // the point they would otherwise matter.
+        validateExecutionControl(options.executionControl, this.providerName, this.supportsExecutionControl(), {
+            turnTimeoutMs: options.turnTimeoutMs,
+            toolTimeoutMs: options.toolTimeoutMs,
+        });
         logger.info(`Starting stream`, {
             provider: this.providerName,
             hasTools: !options.disableTools && this.supportsTools(),

package/dist/core/constants.d.ts

@@ -27,9 +27,22 @@ export declare const DEFAULT_GEMINI_STREAM_TIMEOUT_MS = 300000;
  * Default per-tool-execution timeout for native agentic loops. 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. Override per call with
- * `toolTimeoutMs`.
+ * `toolTimeoutMs`, or remove the bound entirely with `toolTimeoutMs: null`.
  */
 export declare const DEFAULT_TOOL_EXECUTION_TIMEOUT_MS = 300000;
+/**
+ * Resolve a caller's `toolTimeoutMs` into the bound a loop should actually
+ * apply: a number of milliseconds, or `null` for no bound at all.
+ *
+ * The three-way distinction is the whole point, and `??` cannot express it:
+ * `undefined` means "no opinion, take the default", while `null` is a stated
+ * choice to run tools unbounded — the pre-existing behaviour of the loops that
+ * never had a per-tool timer, and the only way to say it, since a finite
+ * number is always a ceiling and `Infinity` silently desugars to `setTimeout`'s
+ * ~24.9-day cap. Every loop resolves it through here so `null` cannot come to
+ * mean "the default" on one provider and "unbounded" on another.
+ */
+export declare function resolveToolTimeoutMs(toolTimeoutMs: number | null | undefined): number | null;
 /**
  * Default wrap-up lead applied when `turnTimeoutMs` is set but
  * `wrapupTimeLeadMs` is not: with less than this much turn time remaining,

package/dist/core/constants.js

@@ -122,9 +122,26 @@ export const DEFAULT_GEMINI_STREAM_TIMEOUT_MS = 300_000;
  * Default per-tool-execution timeout for native agentic loops. 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. Override per call with
- * `toolTimeoutMs`.
+ * `toolTimeoutMs`, or remove the bound entirely with `toolTimeoutMs: null`.
  */
 export const DEFAULT_TOOL_EXECUTION_TIMEOUT_MS = 300_000;
+/**
+ * Resolve a caller's `toolTimeoutMs` into the bound a loop should actually
+ * apply: a number of milliseconds, or `null` for no bound at all.
+ *
+ * The three-way distinction is the whole point, and `??` cannot express it:
+ * `undefined` means "no opinion, take the default", while `null` is a stated
+ * choice to run tools unbounded — the pre-existing behaviour of the loops that
+ * never had a per-tool timer, and the only way to say it, since a finite
+ * number is always a ceiling and `Infinity` silently desugars to `setTimeout`'s
+ * ~24.9-day cap. Every loop resolves it through here so `null` cannot come to
+ * mean "the default" on one provider and "unbounded" on another.
+ */
+export function resolveToolTimeoutMs(toolTimeoutMs) {
+    return toolTimeoutMs === null
+        ? null
+        : (toolTimeoutMs ?? DEFAULT_TOOL_EXECUTION_TIMEOUT_MS);
+}
 /**
  * Default wrap-up lead applied when `turnTimeoutMs` is set but
  * `wrapupTimeLeadMs` is not: with less than this much turn time remaining,

package/dist/core/loopEngine.js

@@ -1,6 +1,7 @@
 import { createStreamChannel } from "./streamChannel.js";
 import { logger } from "../utils/logger.js";
 import { withProviderRetry } from "../utils/providerRetry.js";
+import { resolveToolTimeoutMs } from "./constants.js";
 /**
  * Marks a step error that occurred AFTER at least one chunk had already
  * been streamed to the consumer for this step. Retrying at that point
@@ -32,6 +33,71 @@ function sumUsage(a, b) {
         cacheWrite1hTokens: (a.cacheWrite1hTokens ?? 0) + (b.cacheWrite1hTokens ?? 0) || undefined,
     };
 }
+/**
+ * Run one tool call under its deadline, cancelling it rather than abandoning it.
+ *
+ * The signal handed to `execute` is a controller owned by THIS call, not the
+ * turn's — the deadline aborts it. A tool that honours its signal is therefore
+ * told to stop when its time is up, instead of being left running while the
+ * loop records that it failed: a terminal outcome reported for something that
+ * has not terminated, still holding its resources and, for a side-effecting
+ * tool, still applying its effect after the model was told it did not. A retry
+ * would then start a second copy alongside the first.
+ *
+ * What this cannot do is stop a tool that ignores its signal. Nothing in this
+ * process can; the loop stops waiting and the call runs on. That limit is
+ * stated in `toolTimeoutMs`'s own documentation rather than left implied.
+ *
+ * The turn's abort is forwarded into the same controller, so cancelling a turn
+ * reaches an in-flight tool exactly as it did before. Only the deadline is
+ * raced — a turn-level abort still lets the call settle on its own terms.
+ *
+ * `null` means the caller opted out of the bound: the call is awaited
+ * unguarded, with the turn's own signal, which is what the loops that never
+ * had a per-tool timer did.
+ */
+async function executeToolCall(params) {
+    const { name, execute, args, toolCallId, turnSignal, toolTimeoutMs } = params;
+    if (toolTimeoutMs === null) {
+        return execute(args, { toolCallId, abortSignal: turnSignal });
+    }
+    const toolAbort = new AbortController();
+    const onTurnAbort = () => toolAbort.abort(turnSignal.reason);
+    if (turnSignal.aborted) {
+        toolAbort.abort(turnSignal.reason);
+    }
+    else {
+        turnSignal.addEventListener("abort", onTurnAbort, { once: true });
+    }
+    // One timer does both jobs — abort the tool, then stop waiting for it — so
+    // the two can never drift apart. That is why this is not `withTimeout`,
+    // which would need a second timer to reach the controller. It is
+    // deliberately NOT unref'd: while a tool is in flight this timer is the only
+    // thing that will ever end a wedged one, so it must be able to hold the
+    // event loop open long enough to fire. `finally` clears it the instant the
+    // call settles, so it never outlives its tool.
+    let timer;
+    const deadline = new Promise((_, reject) => {
+        timer = setTimeout(() => {
+            const error = new Error(`Tool "${name}" execution timed out after ${toolTimeoutMs}ms`);
+            toolAbort.abort(error);
+            reject(error);
+        }, toolTimeoutMs);
+    });
+    try {
+        // `Promise.race` subscribes to both, so a tool that eventually rejects
+        // after its deadline has already been reported cannot resurface as an
+        // unhandled rejection and kill the consumer's process.
+        return await Promise.race([
+            Promise.resolve(execute(args, { toolCallId, abortSignal: toolAbort.signal })),
+            deadline,
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+        turnSignal.removeEventListener("abort", onTurnAbort);
+    }
+}
 /**
  * Dispatch one step's tool calls.
  *
@@ -42,7 +108,7 @@ function sumUsage(a, b) {
  * what happened by returning it, so the turn's accumulators stay in one place.
  */
 async function dispatchStepTools(params) {
-    const { calls, adapter, tools, failedTools, abortSignal } = params;
+    const { calls, adapter, tools, failedTools, abortSignal, toolTimeoutMs } = params;
     const toolResults = [];
     const executions = [];
     const dispatched = [];
@@ -126,9 +192,24 @@ async function dispatchStepTools(params) {
             continue;
         }
         try {
-            const output = await tool.execute(call.args, {
+            // Bounded unless the caller opted out. `abortSignal` alone only ends a
+            // tool that honours it, and between two steps there is no other timer
+            // running: the step's request deadline was disposed when the step
+            // settled and the next one is not armed yet. A tool that neither returns
+            // nor watches its signal would otherwise hang the whole turn with
+            // nothing to end it — the case a turn that removed its lifetime ceiling
+            // has no defence against.
+            //
+            // A breach lands in the catch below and is recorded as an ordinary tool
+            // failure, so the turn spends one step and carries on, matching what
+            // `toolTimeoutMs` already means on the native generate path.
+            const output = await executeToolCall({
+                name: call.name,
+                execute: tool.execute,
+                args: call.args,
                 toolCallId: call.id,
-                abortSignal: abortSignal,
+                turnSignal: abortSignal,
+                toolTimeoutMs,
             });
             // A result can report failure without throwing — an MCP isError
             // payload, a proxy-blocked call resolving with `{ error }`. When
@@ -221,8 +302,13 @@ export function runAgenticLoop(adapter, initialConversation, options) {
         const allToolCalls = [];
         const allToolExecutions = [];
         let hadToolCallsAtCap = false;
+        // The cap is a variable, not `adapter.maxSteps` read in place, because a
+        // step-boundary callback may renew it mid-turn. With no callback nothing
+        // ever writes to it, so the loop is the same loop it was.
+        let stepCap = adapter.maxSteps;
+        const turnStartedAt = Date.now();
         try {
-            for (let step = 0; step < adapter.maxSteps; step++) {
+            for (let step = 0; step < stepCap; step++) {
                 if (internalAbort.signal.aborted) {
                     break;
                 }
@@ -292,7 +378,7 @@ export function runAgenticLoop(adapter, initialConversation, options) {
                     !malformedRetryUsed &&
                     !internalAbort.signal.aborted) {
                     malformedRetryUsed = true;
-                    logger.warn(`[${adapter.providerLabel}] Malformed function call at step ${step + 1}/${adapter.maxSteps}; retrying once.`);
+                    logger.warn(`[${adapter.providerLabel}] Malformed function call at step ${step + 1}/${stepCap}; retrying once.`);
                     conversation =
                         adapter.buildMalformedRetryNote?.(conversation, step) ??
                             conversation;
@@ -302,7 +388,7 @@ export function runAgenticLoop(adapter, initialConversation, options) {
                     finalText = stepResult.text || finalText;
                     break;
                 }
-                if (step === adapter.maxSteps - 1) {
+                if (step === stepCap - 1) {
                     hadToolCallsAtCap = true;
                 }
                 const dispatch = await dispatchStepTools({
@@ -311,6 +397,7 @@ export function runAgenticLoop(adapter, initialConversation, options) {
                     tools: options.tools,
                     failedTools,
                     abortSignal: internalAbort.signal,
+                    toolTimeoutMs: resolveToolTimeoutMs(options.toolTimeoutMs),
                 });
                 const toolResults = dispatch.toolResults;
                 allToolCalls.push(...dispatch.dispatched);
@@ -326,7 +413,55 @@ export function runAgenticLoop(adapter, initialConversation, options) {
                     break;
                 }
                 conversation = adapter.buildToolResultMessages(conversation, stepResult, toolResults, step);
+                // THE step boundary. Everything this step did has settled — tools ran,
+                // their results are in the conversation — and the cap has not yet been
+                // re-checked, so this is the only point where raising it changes what
+                // happens next without replaying anything. Deliberately not reached
+                // when the step asked for no tools (the turn ended on its own; renewing
+                // there would be a restart) or when the turn is already cancelled.
+                if (options.beforeStep && !internalAbort.signal.aborted) {
+                    const decision = await options.beforeStep({
+                        stepIndex: step,
+                        stepsCompleted: step + 1,
+                        maxSteps: stepCap,
+                        elapsedMs: Date.now() - turnStartedAt,
+                        toolNames: dispatch.dispatched.map((call) => call.name),
+                        signal: internalAbort.signal,
+                    });
+                    // Strictly larger and finite. A smaller number would end a turn the
+                    // engine has already committed steps to, and Infinity would remove
+                    // the bound entirely — the callback's job is to extend a budget, not
+                    // to delete it.
+                    //
+                    // Floored BEFORE the comparison, not after. A cap is a whole number
+                    // of steps, so `stepCap + 0.5` is not a renewal at all — it floors
+                    // back to the cap already in force. Comparing the raw value first
+                    // let it pass the guard, leave the cap where it was, and still clear
+                    // `hadToolCallsAtCap` below, which drops the turn's last-step-text
+                    // fallback and reports a capped turn as an uncapped one.
+                    const renewed = typeof decision?.maxSteps === "number" &&
+                        Number.isFinite(decision.maxSteps)
+                        ? Math.floor(decision.maxSteps)
+                        : undefined;
+                    if (renewed !== undefined && renewed > stepCap) {
+                        stepCap = renewed;
+                        // The step that just ran is no longer the last one, so the turn is
+                        // no longer capped. Left set, a renewed turn would report itself
+                        // as having run out of steps.
+                        hadToolCallsAtCap = false;
+                    }
+                    if (decision?.nudge && adapter.appendPlanningNudge) {
+                        conversation = adapter.appendPlanningNudge(conversation, decision.nudge);
+                    }
+                }
             }
+            // Read AFTER the loop, so it covers every way an abort can end a turn:
+            // the step-top check, a tool batch cut short, and an adapter whose
+            // provider SDK swallows the cancellation and returns what it had. The
+            // Anthropic SDK does exactly that last one — its stream iterator treats
+            // an aborted read as a clean end — so an interrupted turn arrives here
+            // indistinguishable from a completed one unless the signal is consulted.
+            const aborted = internalAbort.signal.aborted;
             const finishReason = adapter.mapFinishReason(rawStopReason, hadToolCallsAtCap);
             return {
                 // `finalText` is only set by a step that asked for no tools, so a turn
@@ -340,9 +475,17 @@ export function runAgenticLoop(adapter, initialConversation, options) {
                 toolCalls: allToolCalls,
                 toolExecutions: allToolExecutions,
                 usage,
-                finishReason,
+                // A turn that was cut short before any terminal event reached it has
+                // no provider stop reason to map, and `mapFinishReason`'s default
+                // branch reports "stop" for that absence — the same value a model
+                // that finished normally produces. "other" is the AI-SDK-shaped value
+                // for "ended for a reason outside this enum", which is the truth.
+                // When the provider DID report a stop reason before the abort, that
+                // reason is real and is kept.
+                finishReason: aborted && rawStopReason === undefined ? "other" : finishReason,
                 rawStopReason,
                 conversation,
+                aborted,
             };
         }
         catch (err) {

package/dist/core/toolExecutionGuards.js

@@ -47,7 +47,12 @@ export function guardToolExecutor(name, execute, guards) {
             const raced = guards.abortSignal
                 ? raceWithAbort(call(), guards.abortSignal)
                 : call();
-            return await (guards.toolTimeoutMs === undefined
+            // `== null` catches both an omitted bound and an explicit `null` — a
+            // caller that asked for unbounded tool execution. Testing only for
+            // `undefined` would send `null` into `withTimeout`, where it parses as
+            // no delay and fires the deadline immediately.
+            return await (guards.toolTimeoutMs === undefined ||
+                guards.toolTimeoutMs === null
                 ? raced
                 : withTimeout(raced, guards.toolTimeoutMs, `Tool "${name}" execution timed out after ${guards.toolTimeoutMs}ms`));
         }

package/dist/providers/amazonBedrock/client.js

@@ -287,6 +287,11 @@ export class AmazonBedrockProvider extends BaseProvider {
             const { resultPromise } = runAgenticLoop(adapter, this.conversationHistory, {
                 tools: this.toEngineTools(tools),
                 abortSignal: options.abortSignal,
+                // `toEngineTools` adds no deadline of its own, so this is the only
+                // per-tool bound on the turn. The engine defaults when it is absent.
+                ...(options.toolTimeoutMs !== undefined
+                    ? { toolTimeoutMs: options.toolTimeoutMs }
+                    : {}),
             });
             const result = await resultPromise;
             this.conversationHistory = result.conversation;
@@ -893,6 +898,11 @@ export class AmazonBedrockProvider extends BaseProvider {
         const { stream, resultPromise } = runAgenticLoop(adapter, this.conversationHistory, {
             tools: this.toEngineTools(tools),
             abortSignal: options.abortSignal,
+            // `toEngineTools` adds no deadline of its own, so this is the only
+            // per-tool bound on the turn. The engine defaults when it is absent.
+            ...(options.toolTimeoutMs !== undefined
+                ? { toolTimeoutMs: options.toolTimeoutMs }
+                : {}),
         });
         // The stream surfaces the same failure, so this settled view exists only
         // so the turn's outcome can be read without a second unhandled rejection.

package/dist/providers/anthropic/client.d.ts

@@ -152,6 +152,14 @@ export declare class AnthropicProvider extends BaseProvider {
      * that read it, were never populated by anything.
      */
     private recordLimitSnapshot;
+    /**
+     * The native stream loop below is the one implementation of the
+     * `executionControl` contract: it arms the lifetime policy, hands the
+     * per-request deadline and the terminal-event requirement to the loop
+     * adapter, and runs the step-boundary callback through the engine. Every
+     * other provider rejects the option rather than ignoring it.
+     */
+    supportsExecutionControl(): boolean;
     protected executeStream(options: StreamOptions, analysisSchema?: ValidationSchema): Promise<StreamResult>;
     private executeStreamInCaptureScope;
     isAvailable(): Promise<boolean>;

package/dist/providers/anthropic/client.js

@@ -24,6 +24,7 @@ import { ANTHROPIC_MAX_CACHE_BREAKPOINTS, applyAnthropicHistoryCacheBreakpoints,
 import { calculateCost } from "../../utils/pricing.js";
 import { stringifyAnthropicToolOutput } from "./toolOutput.js";
 import { createAnthropicLoopAdapter } from "./loopAdapter.js";
+import { DEFAULT_BEFORE_STEP_TIMEOUT_MS } from "../../utils/parameterValidation.js";
 import { runAgenticLoop } from "../../core/loopEngine.js";
 import { hasNativeDoGenerate, runNativeGenerateLoop, } from "../../core/nativeGenerateLoop.js";
 import { withProviderRetry } from "../../utils/providerRetry.js";
@@ -31,7 +32,8 @@ import { resolveRequestKind } from "../../core/resolveRequestKind.js";
 import { resolveToolExecutionRecords, toolCallsFromSummaries, } from "../../core/toolExecutionRecorder.js";
 import { transformToolExecutions } from "../../utils/transformationUtils.js";
 import { createAnthropicConfig, getProviderModel, validateApiKey, } from "../../utils/providerConfig.js";
-import { composeAbortSignals, createTimeoutController, mergeAbortSignals, TimeoutError, } from "../../utils/timeout.js";
+import { composeAbortSignals, composeAbortSignalsScoped, createTimeoutController, mergeAbortSignals, TimeoutError, } from "../../utils/timeout.js";
+import { raceWithAbort } from "../../utils/async/index.js";
 import { resolveToolChoice } from "../../utils/toolChoice.js";
 import { emitToolEndFromStepFinish } from "../../utils/toolEndEmitter.js";
 import { NoOutputGeneratedError } from "../../utils/generationErrors.js";
@@ -1504,6 +1506,16 @@ export class AnthropicProvider extends BaseProvider {
         setLimitSpanAttributes(snapshot);
         logClaudeLimitSnapshot(snapshot, this.modelName);
     }
+    /**
+     * The native stream loop below is the one implementation of the
+     * `executionControl` contract: it arms the lifetime policy, hands the
+     * per-request deadline and the terminal-event requirement to the loop
+     * adapter, and runs the step-boundary callback through the engine. Every
+     * other provider rejects the option rather than ignoring it.
+     */
+    supportsExecutionControl() {
+        return true;
+    }
     async executeStream(options, analysisSchema) {
         // The capture scope must outlive this call: the SSE loop keeps running in
         // the background after executeStream returns, and its per-step HTTP
@@ -1516,8 +1528,38 @@ export class AnthropicProvider extends BaseProvider {
         // Refresh OAuth token if needed before making any API request.
         await this.refreshAuthIfNeeded();
         this.validateStreamOptions(options);
-        const timeout = this.getTimeout(options);
-        const timeoutController = createTimeoutController(timeout, this.providerName, "stream");
+        // Validated in BaseProvider.stream() before this point, so the shape here
+        // is known good: requestTimeoutMs finite positive, lifetimeTimeoutMs null
+        // or finite positive or absent.
+        const control = options.executionControl;
+        // Same split the generate path already enforces in
+        // `BaseProvider.withTurnTimeout`: an explicit, valid `turnTimeoutMs` is
+        // the caller's whole-turn contract and owns this timer. Without it the
+        // native stream path armed only the provider's own `timeout`, so a caller
+        // asking for a 40-minute turn of 5-minute calls was killed at the shorter
+        // value — and a caller asking for a 200ms turn was not bounded at all.
+        const hasValidTurnTimeout = typeof options.turnTimeoutMs === "number" &&
+            Number.isFinite(options.turnTimeoutMs) &&
+            options.turnTimeoutMs > 0;
+        // `lifetimeTimeoutMs: null` means NO lifetime timer, which is why this
+        // resolves to undefined rather than to a large number:
+        // createTimeoutController arms nothing for a falsy duration, so the turn
+        // ends up bounded by its per-request deadline and its step cap alone.
+        //
+        // Tested with `!== undefined` rather than `"lifetimeTimeoutMs" in control`:
+        // `in` is true for `{ lifetimeTimeoutMs: undefined }`, which is the shape
+        // any programmatic construction produces — an optional field spread, a
+        // JSON round trip, a config object assembled field by field. Under `in`
+        // that shape removed the turn's ceiling entirely while the caller had said
+        // nothing at all about it, and TypeScript could not warn because the field
+        // is `?: number | null`. An absent value means "no opinion", and no
+        // opinion inherits the legacy handling below.
+        const lifetimeTimeoutMs = control && control.lifetimeTimeoutMs !== undefined
+            ? (control.lifetimeTimeoutMs ?? undefined)
+            : hasValidTurnTimeout
+                ? options.turnTimeoutMs
+                : this.getTimeout(options);
+        const timeoutController = createTimeoutController(lifetimeTimeoutMs, this.providerName, "stream");
         // Consumer-driven abort: fires when the async iterator is closed early
         // (caller breaks out of `for await`) so the background loop stops
         // reading SSE and running tools.
@@ -1807,6 +1849,14 @@ export class AnthropicProvider extends BaseProvider {
                 toolsRecord,
                 buildParams,
                 planReclaim,
+                // Both are opt-in with the control and absent without it, so a caller
+                // that never passed executionControl sees the turn it saw before.
+                ...(control
+                    ? {
+                        requestTimeoutMs: control.requestTimeoutMs,
+                        requireTerminalEvent: true,
+                    }
+                    : {}),
                 noteObservedPromptTokens: (tokens) => {
                     lastObservedPromptTokens = tokens;
                 },
@@ -1894,10 +1944,63 @@ export class AnthropicProvider extends BaseProvider {
             // The engine passed `undefined` in its place, so the attribute silently
             // stopped being emitted for every native Anthropic turn.
             const activeSpan = trace.getActiveSpan();
+            // The caller's step-boundary callback, made finite and cancellable
+            // before the engine ever sees it. The engine's contract is "already
+            // bounded", and this is the layer that knows the budget, because the
+            // budget is a field on the public option this layer validated.
+            //
+            // A callback that throws or outlives its budget declines the renewal
+            // rather than failing the turn: the cap it did not raise still stands,
+            // so the turn ends at the step limit the caller originally set. Failing
+            // instead would let a flaky budget service kill work already done.
+            const callerBeforeStep = control?.beforeStep;
+            const beforeStep = callerBeforeStep
+                ? async (context) => {
+                    const budgetMs = control?.beforeStepTimeoutMs ?? DEFAULT_BEFORE_STEP_TIMEOUT_MS;
+                    const callbackTimeout = createTimeoutController(budgetMs, this.providerName, "stream");
+                    const composed = composeAbortSignalsScoped(context.signal, callbackTimeout?.controller.signal);
+                    try {
+                        // One timer, not two. `callbackTimeout` already aborts the
+                        // composed signal at `budgetMs`, so the second `withTimeout`
+                        // that used to sit here armed a duplicate timer for the same
+                        // deadline. Racing the composed signal instead keeps the budget
+                        // COMPULSORY — a callback that ignores its signal must not be
+                        // able to park the turn at a step boundary, which is the one
+                        // place no other timer is watching — while arming nothing new.
+                        // It also ends the wait the moment the TURN is cancelled, which
+                        // the old duplicate timer did not do.
+                        return await raceWithAbort(Promise.resolve(callerBeforeStep({
+                            ...context,
+                            signal: composed.signal ?? context.signal,
+                        })), composed.signal ?? context.signal);
+                    }
+                    catch (callbackError) {
+                        logger.warn("[Anthropic] executionControl.beforeStep failed or timed out; the step cap stands", {
+                            error: callbackError instanceof Error
+                                ? callbackError.message
+                                : String(callbackError),
+                            stepsCompleted: context.stepsCompleted,
+                        });
+                        return undefined;
+                    }
+                    finally {
+                        composed.dispose();
+                        callbackTimeout?.cleanup();
+                    }
+                }
+                : undefined;
             const { stream, resultPromise } = runAgenticLoop(adapter, payload.messages.slice(), {
                 tools: engineTools,
                 ...(abortSignal ? { abortSignal } : {}),
                 ...(activeSpan ? { span: activeSpan } : {}),
+                ...(beforeStep ? { beforeStep } : {}),
+                // `engineTools` above only fixes the context object; it adds no
+                // deadline. The engine's per-tool bound is therefore the only thing
+                // watching a wedged tool on this path — which matters most when the
+                // caller asked for no lifetime ceiling at all.
+                ...(options.toolTimeoutMs !== undefined
+                    ? { toolTimeoutMs: options.toolTimeoutMs }
+                    : {}),
             });
             // Structured turns buffer their text rather than streaming it: a caller
             // that passed a schema needs parseable JSON, and deltas emitted before
@@ -1946,6 +2049,32 @@ export class AnthropicProvider extends BaseProvider {
             totalCacheRead += result.usage.cacheReadTokens ?? 0;
             totalCacheWrite += result.usage.cacheWriteTokens ?? 0;
             lastStop = result.rawStopReason ?? lastStop;
+            // An interrupted turn is not a stop. The Anthropic SDK's stream
+            // iterator exits WITHOUT throwing when its request is aborted, so a
+            // turn killed by the caller's signal or by the turn deadline drains
+            // through here carrying no terminal event — and the ordinary path below
+            // would report it with the same `finishReason` and the same resolved
+            // stop reason as a model that answered and stopped.
+            //
+            // The merged signal's reason is what separates the two causes: NeuroLink's
+            // own timers abort with a TimeoutError, and nothing else does.
+            // Everything the completed steps produced is still reported — the text
+            // was already pushed to the consumer, and the tokens were billed.
+            if (result.aborted) {
+                const reason = abortSignal?.aborted ? abortSignal.reason : undefined;
+                turnMetadata.stopReason =
+                    reason instanceof TimeoutError ? "time-limit" : "aborted";
+                turnMetadata.finishReason = "other";
+                if (result.rawStopReason) {
+                    turnMetadata.rawFinishReason = result.rawStopReason;
+                }
+                resolveUsage(buildDeferredUsage());
+                // Returns before the step-cap branch below: a turn aborted while the
+                // model still wanted tools carries stop_reason "tool_use", which that
+                // branch would read as the caller's own maxSteps bound.
+                resolveFinish("other");
+                return;
+            }
             turnMetadata.finishReason = result.finishReason;
             if (result.rawStopReason) {
                 turnMetadata.rawFinishReason = result.rawStopReason;