@juspay/neurolink 12.12.16 → 12.14.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/proxy/clientAttribution.js

@@ -39,6 +39,9 @@ const CLIENT_PREFIXES = [
     // different token, and it is left unmapped until someone measures it rather
     // than pattern-matched on a guess.
     ["codex_exec/", "codex"],
+    // "grok-shell/1.0.30 (macos; aarch64)" — measured 2026-09-12 on
+    // POST /v1/messages from Grok Build 1.0.30.
+    ["grok-shell/", "grok"],
 ];
 /**
  * Deliberately NOT mapped, and why each was ruled out.

package/dist/proxy/proxyConfig.d.ts

@@ -11,6 +11,10 @@
  * falls back to JSON.parse.
  */
 import type { LoadProxyConfigOptions, ProxyConfigFile } from "../types/index.js";
+/** Default on-disk path used when `proxy start` is not given `--config`. */
+export declare function defaultProxyConfigPath(): string;
+/** Resolve `--config` the same way `proxy start` / `proxy install` do. */
+export declare function resolveProxyConfigPath(explicit?: string): string;
 /**
  * Replace all `${VAR}` / `${VAR:-default}` references in a string.
  *

package/dist/proxy/proxyConfig.js

@@ -11,9 +11,21 @@
  * falls back to JSON.parse.
  */
 import { readFile } from "node:fs/promises";
-import { extname } from "node:path";
+import { homedir } from "node:os";
+import { extname, join, resolve } from "node:path";
 import { MAX_MAX_INFLIGHT_PER_ACCOUNT, MIN_MAX_INFLIGHT_PER_ACCOUNT, } from "./modelRouter.js";
 import { logger } from "../utils/logger.js";
+/** Default on-disk path used when `proxy start` is not given `--config`. */
+export function defaultProxyConfigPath() {
+    return join(homedir(), ".neurolink", "proxy-config.yaml");
+}
+/** Resolve `--config` the same way `proxy start` / `proxy install` do. */
+export function resolveProxyConfigPath(explicit) {
+    const trimmed = explicit?.trim();
+    return trimmed && trimmed.length > 0
+        ? resolve(trimmed)
+        : defaultProxyConfigPath();
+}
 // ---------------------------------------------------------------------------
 // Environment variable resolution
 // ---------------------------------------------------------------------------

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

@@ -1,4 +1,14 @@
 import type { JsonObject } from "./common.js";
+/** Options forwarded through `applyAllClients` into a configurator's `apply`. */
+export type CliProxyClientApplyOptions = {
+    /**
+     * Absolute path of the proxy routing config this process loaded.
+     * The Grok writer reads `routing.model-mappings` from this file so a
+     * `proxy start --config` catalog matches `/v1/models`. Omit to use
+     * `~/.neurolink/proxy-config.yaml`.
+     */
+    configPath?: string;
+};
 /**
  * One AI coding CLI the proxy can point at itself.
  *
@@ -22,7 +32,7 @@ export type CliProxyClientConfigurator = {
      * suffix its CLI needs. Returns false when nothing was written, so callers
      * never print a success message for work that did not happen.
      */
-    apply: (proxyBaseUrl: string) => Promise<boolean>;
+    apply: (proxyBaseUrl: string, options?: CliProxyClientApplyOptions) => Promise<boolean>;
     /**
      * Restore the user's previous configuration. `proxyBaseUrl` is the same bare
      * origin; a configurator that finds a different URL configured must leave it
@@ -77,6 +87,29 @@ export type CliOpenCodeSnapshot = {
     /** What the writer last wrote, so apply() can recognise its own block. */
     written?: unknown;
 };
+/**
+ * One Grok Build picker entry the proxy writer emits under `[model.<id>]`.
+ *
+ * `contextWindow` is Grok's compaction limit and must be <= the upstream
+ * model's window. `supportsReasoningEffort` is false when Grok's `xhigh`
+ * would become Anthropic adaptive thinking that the model rejects.
+ */
+export type CliGrokProxyModelSpec = {
+    id: string;
+    name: string;
+    apiBackend: "messages" | "chat_completions";
+    contextWindow: number;
+    maxCompletionTokens: number;
+    supportsReasoningEffort: boolean;
+};
+/**
+ * Snapshot of whether `~/.grok/config.toml` existed before the proxy wrote
+ * its managed block. Persisted to `~/.neurolink/grok-proxy-snapshot.json`.
+ */
+export type CliGrokSnapshot = {
+    originalExisted: boolean;
+    writtenBaseUrl: string;
+};
 /**
  * Snapshot of the user's pre-existing Gemini CLI `~/.gemini/.env`.
  *

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;