@juspay/neurolink 9.80.4 → 9.81.1

package/dist/lib/types/analytics.d.ts

@@ -35,6 +35,16 @@ export type AnalyticsData = {
     timestamp: string;
     cost?: number;
     context?: JsonValue;
+    /** Number of agentic steps (model calls) the turn used. */
+    stepsUsed?: number;
+    /** Number of external tool calls the turn made (final_result excluded). */
+    toolCallCount?: number;
+    /** Why the turn ended — see GenerateStopReason. */
+    stopReason?: string;
+    /** Wall-clock duration of the turn in milliseconds. */
+    elapsedMs?: number;
+    /** Verbatim provider finish/stop reason for the terminal model call. */
+    rawFinishReason?: string;
 };
 /**
  * Stream Analytics Data - Enhanced for performance tracking

package/dist/lib/types/generate.d.ts

@@ -310,6 +310,38 @@ export type GenerateOptions = {
      * provider+model with the same doomed budget.
      */
     timeout?: number | string;
+    /**
+     * Hard wall-clock cap for the WHOLE agentic turn (all model calls + tool
+     * executions), in milliseconds. When the deadline passes the turn ends
+     * gracefully with `stopReason: "time-limit"` and an honest time message —
+     * never the step-cap text. Unset = no turn-level deadline (the library
+     * imposes no product policy).
+     *
+     * Enforced by the native Vertex loops (Gemini + Claude); AI-SDK-driven
+     * providers currently ignore it.
+     */
+    turnTimeoutMs?: number;
+    /**
+     * Maximum time with NO progress — no stream chunk received, no tool
+     * execution started or finished, no step started — before the turn ends
+     * with `stopReason: "stalled"`. Catches wedged tools and hung model calls
+     * that a whole-turn deadline would let run to the bitter end.
+     * Unset = disabled.
+     */
+    stallTimeoutMs?: number;
+    /**
+     * When the remaining turn time drops below this, a wrap-up nudge rides the
+     * next tool-result turn telling the model to consolidate what it has and
+     * produce its final answer. Defaults to 120_000 when `turnTimeoutMs` is
+     * set; ignored when it is not.
+     */
+    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;
     /** AbortSignal for external cancellation of the AI call */
     abortSignal?: AbortSignal;
     /**
@@ -562,6 +594,21 @@ export type AdditionalMemoryUser = {
     /** Max words for this user's condensed memory. Overrides the default maxWords. */
     maxWords?: number;
 };
+/**
+ * Why an agentic turn ended — the discriminator consumers should branch on
+ * instead of sniffing the provider-shaped `finishReason` (whose values are
+ * overloaded: e.g. "tool-calls" historically covered both step-cap exits and
+ * Gemini MALFORMED_FUNCTION_CALL provider errors).
+ *
+ * - `completed` — the model finished on its own (text answer or final_result)
+ * - `step-cap` — the `maxSteps` budget ran out while the model still wanted tools
+ * - `time-limit` — the `turnTimeoutMs` wall-clock deadline passed
+ * - `stalled` — no progress (no chunk, no tool start/finish) for `stallTimeoutMs`
+ * - `aborted` — the caller's `abortSignal` ended the turn
+ * - `provider-error` — the provider/model failed the turn (e.g. persistent
+ *   MALFORMED_FUNCTION_CALL after retry); usually worth a caller-side retry
+ */
+export type GenerateStopReason = "completed" | "step-cap" | "time-limit" | "stalled" | "aborted" | "provider-error";
 /**
  * Generate function result type - Primary output format
  * Future-ready for multi-modal outputs while maintaining text focus
@@ -662,6 +709,20 @@ export type GenerateResult = {
     provider?: string;
     model?: string;
     finishReason?: string;
+    /**
+     * Why the agentic turn ended, independent of the provider-shaped
+     * `finishReason`. Populated by the native Vertex loops (Gemini + Claude);
+     * undefined on providers that don't run a native loop — fall back to
+     * `finishReason` heuristics there.
+     */
+    stopReason?: GenerateStopReason;
+    /**
+     * Verbatim provider finish/stop reason for the turn's terminal model call
+     * (e.g. "MALFORMED_FUNCTION_CALL", "MAX_TOKENS", "max_tokens", "tool_use").
+     */
+    rawFinishReason?: string;
+    /** Number of agentic steps (model calls) the turn used. */
+    stepsUsed?: number;
     /**
      * True when the schema JSON in `content`/`structuredData` was repaired from
      * malformed model text (jsonrepair ran). The result is still valid JSON.
@@ -882,6 +943,14 @@ export type TextGenerationOptions = {
      */
     enabledToolNames?: string[];
     timeout?: number | string;
+    /** Wall-clock cap for the whole agentic turn (ms). See GenerateOptions.turnTimeoutMs. */
+    turnTimeoutMs?: number;
+    /** Max time with no progress before the turn ends as "stalled" (ms). 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;
     /** AbortSignal for external cancellation of the AI call */
     abortSignal?: AbortSignal;
     disableTools?: boolean;
@@ -1128,6 +1197,12 @@ export type TextGenerationResult = {
     /** Parsed structured object when a `schema` was requested (see GenerateResult.structuredData). */
     structuredData?: unknown;
     finishReason?: string;
+    /** Turn-exit discriminator from native agentic loops (see GenerateStopReason). */
+    stopReason?: GenerateStopReason;
+    /** Verbatim provider finish/stop reason for the turn's terminal model call. */
+    rawFinishReason?: string;
+    /** Number of agentic steps (model calls) the turn used. */
+    stepsUsed?: number;
     /** True when the schema JSON was repaired from malformed model text. */
     jsonRepaired?: boolean;
     /** True when the schema JSON appears truncated (output hit the token cap). */

package/dist/lib/types/stream.d.ts

@@ -8,7 +8,7 @@ import type { JsonValue, UnknownRecord } from "./common.js";
 import type { Content, ImageWithAltText } from "./content.js";
 import type { ChatMessage } from "./conversation.js";
 import type { StreamNoOutputSentinel } from "./noOutputSentinel.js";
-import type { AdditionalMemoryUser } from "./generate.js";
+import type { AdditionalMemoryUser, GenerateStopReason } from "./generate.js";
 import type { AIModelProviderConfig, NeurolinkCredentials } from "./providers.js";
 import type { TTSChunk, TTSOptions, TTSResult } from "./tts.js";
 import type { STTOptions, STTResult } from "./stt.js";
@@ -326,6 +326,14 @@ export type StreamOptions = {
     schema?: ValidationSchema;
     tools?: Record<string, Tool>;
     timeout?: number | string;
+    /** Wall-clock cap for the whole agentic turn (ms). See GenerateOptions.turnTimeoutMs. */
+    turnTimeoutMs?: number;
+    /** Max time with no progress before the turn ends as "stalled" (ms). 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;
     /** AbortSignal for external cancellation of the AI call */
     abortSignal?: AbortSignal;
     disableTools?: boolean;
@@ -518,6 +526,15 @@ export type StreamResult = {
     model?: string;
     usage?: TokenUsage;
     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.
+     */
+    stopReason?: GenerateStopReason;
+    /** Verbatim provider finish/stop reason for the turn's terminal model call. */
+    rawFinishReason?: string;
     toolCalls?: StreamToolCall[];
     toolResults?: StreamToolResult[];
     toolEvents?: AsyncIterable<ToolExecutionEvent>;
@@ -537,6 +554,9 @@ export type StreamResult = {
         guardrailsBlocked?: boolean;
         error?: string;
         finishReason?: string;
+        stopReason?: GenerateStopReason;
+        rawFinishReason?: string;
+        stepsUsed?: number;
         thoughtSignature?: string;
         thoughts?: Array<{
             id?: string;

package/dist/neurolink.js

@@ -3513,6 +3513,10 @@ Current user's request: ${currentInput}`;
             stt: options.stt,
             fileRegistry: this.fileRegistry,
             timeout: options.timeout,
+            turnTimeoutMs: options.turnTimeoutMs,
+            stallTimeoutMs: options.stallTimeoutMs,
+            wrapupTimeLeadMs: options.wrapupTimeLeadMs,
+            toolTimeoutMs: options.toolTimeoutMs,
             abortSignal: options.abortSignal,
             skipToolPromptInjection: options.skipToolPromptInjection,
             middleware: options.middleware,
@@ -3644,6 +3648,12 @@ Current user's request: ${currentInput}`;
             content: textResult.content,
             structuredData: textResult.structuredData,
             finishReason: textResult.finishReason,
+            // Turn-exit discriminator + raw provider stop reason + step count from
+            // native agentic loops — this DTO is an explicit field list, so new
+            // provider-result fields MUST be copied here or they silently vanish.
+            stopReason: textResult.stopReason,
+            rawFinishReason: textResult.rawFinishReason,
+            stepsUsed: textResult.stepsUsed,
             jsonRepaired: textResult.jsonRepaired,
             jsonTruncated: textResult.jsonTruncated,
             provider: textResult.provider,
@@ -5063,6 +5073,9 @@ Current user's request: ${currentInput}`;
             usage: result.usage,
             responseTime,
             finishReason: result.finishReason,
+            stopReason: result.stopReason,
+            rawFinishReason: result.rawFinishReason,
+            stepsUsed: result.stepsUsed,
             toolsUsed: result.toolsUsed || [],
             toolExecutions: transformedToolExecutions,
             enhancedWithTools: Boolean(hasToolExecutions),
@@ -5198,6 +5211,9 @@ Current user's request: ${currentInput}`;
                         usage: poolResult.usage,
                         responseTime,
                         finishReason: poolResult.finishReason,
+                        stopReason: poolResult.stopReason,
+                        rawFinishReason: poolResult.rawFinishReason,
+                        stepsUsed: poolResult.stepsUsed,
                         toolsUsed: poolResult.toolsUsed || [],
                         toolExecutions: poolResult.toolExecutions?.map((te) => {
                             const t = te;
@@ -5474,6 +5490,9 @@ Current user's request: ${currentInput}`;
                     usage: result.usage,
                     responseTime,
                     finishReason: result.finishReason,
+                    stopReason: result.stopReason,
+                    rawFinishReason: result.rawFinishReason,
+                    stepsUsed: result.stepsUsed,
                     toolsUsed: result.toolsUsed || [],
                     // Map toolExecutions from EnhancedGenerateResult shape ({name,input,output})
                     // to TextGenerationResult shape ({toolName,executionTime,success}).
@@ -6471,7 +6490,7 @@ Current user's request: ${currentInput}`;
                 factoryResult,
                 sessionId: enhancedOptions.context?.sessionId,
             });
-            const { stream: mcpStream, provider: providerName, usage: streamUsage, model: streamModel, finishReason: streamFinishReason, toolCalls: streamToolCalls, toolResults: streamToolResults, analytics: streamAnalytics, } = await this.createMCPStream(enhancedOptions);
+            const { stream: mcpStream, provider: providerName, usage: streamUsage, model: streamModel, finishReason: streamFinishReason, toolCalls: streamToolCalls, toolResults: streamToolResults, analytics: streamAnalytics, metadata: providerStreamMetadata, } = await this.createMCPStream(enhancedOptions);
             const streamState = {
                 finishReason: streamFinishReason ?? "stop",
                 toolCalls: streamToolCalls,
@@ -6818,6 +6837,7 @@ Current user's request: ${currentInput}`;
                 guardrailsBlocked: metadata.guardrailsBlocked,
                 error: metadata.error,
                 events: eventSequence,
+                providerMetadata: providerStreamMetadata,
             });
         }
         catch (error) {
@@ -7612,6 +7632,7 @@ Current user's request: ${currentInput}`;
                         toolCalls: poolStreamResult.toolCalls ?? [],
                         toolResults: poolStreamResult.toolResults ?? [],
                         analytics: poolStreamResult.analytics,
+                        metadata: poolStreamResult.metadata,
                     };
                 }
                 catch (poolStreamError) {
@@ -7665,6 +7686,12 @@ Current user's request: ${currentInput}`;
             toolCalls: streamResult.toolCalls ?? [],
             toolResults: streamResult.toolResults ?? [],
             analytics: streamResult.analytics,
+            // Pass the provider's metadata object THROUGH BY REFERENCE: native
+            // background-loop streams (Vertex Gemini/Claude) resolve
+            // finishReason/stopReason/rawFinishReason/stepsUsed onto it only when
+            // the loop finishes — snapshotting fields here would freeze them as
+            // undefined before the stream is drained.
+            metadata: streamResult.metadata,
         };
     }
     /**
@@ -7707,14 +7734,14 @@ Current user's request: ${currentInput}`;
             analytics: streamResult.analytics,
             evaluation: streamResult.evaluation,
             events: config.events && config.events.length > 0 ? config.events : undefined,
-            metadata: {
+            metadata: Object.assign(config.providerMetadata ?? {}, {
                 streamId: config.streamId,
                 startTime: config.startTime,
                 responseTime: config.responseTime,
                 fallback: config.fallback || false,
                 guardrailsBlocked: config.guardrailsBlocked,
                 error: config.error,
-            },
+            }),
         };
     }
     /**

package/dist/providers/googleNativeGemini3.d.ts

@@ -8,7 +8,7 @@
  * This module extracts the functions that are duplicated between the two
  * providers so they can share a single implementation.
  */
-import type { ThinkingConfig, ChatMessage, CollectedChunkResult, MinimalChatMessage, NativeFunctionCall, NativeFunctionResponse, NativeToolDeclarationsResult, NativeToolsConfig, TextChannel, VertexNativePart, GeminiMultimodalInput } from "../types/index.js";
+import type { GenerateStopReason, ThinkingConfig, ChatMessage, CollectedChunkResult, MinimalChatMessage, NativeFunctionCall, NativeFunctionResponse, NativeToolDeclarationsResult, NativeToolsConfig, TextChannel, VertexNativePart, GeminiMultimodalInput } from "../types/index.js";
 import type { Tool } from "../types/index.js";
 export declare function sanitizeForGoogleFunctionName(name: string): string;
 /**
@@ -109,8 +109,14 @@ export declare function computeMaxSteps(rawMaxSteps?: number): number;
  * Returns a plain string (not a `{ unified, raw }` object): the Vertex result
  * builders and the consuming layer (neurolink.ts `finishReason || "unknown"`
  * and `finishReason === "length"`) compare against plain strings.
+ *
+ * MALFORMED_FUNCTION_CALL / UNEXPECTED_TOOL_CALL map to "error", NOT
+ * "tool-calls": they are provider/model failures, while "tool-calls" is the
+ * exclusive contract for "step budget exhausted while the model still wanted
+ * tools" — consumers (e.g. curator's step-cap intercept) branch on it and
+ * were rendering fake step-limit messages for 2-4-step malformed-call turns.
  */
-export declare function mapGeminiFinishReason(raw: string | null | undefined): "stop" | "length" | "tool-calls" | "content-filter";
+export declare function mapGeminiFinishReason(raw: string | null | undefined): "stop" | "length" | "tool-calls" | "content-filter" | "error";
 /**
  * Append a step's text to a running cross-step accumulator, ignoring empty
  * steps and inserting a single newline between non-empty contributions.
@@ -215,10 +221,92 @@ export declare function handleMaxStepsTermination(logLabel: string, step: number
 export declare function isAbortError(error: unknown): boolean;
 /**
  * Build a graceful, user-facing message for when a single agentic turn hits
- * the step cap (or is aborted mid-turn) without producing a final answer.
- * Replaces the legacy bracketed "Tool execution limit reached" placeholder.
+ * the step cap without producing a final answer. Replaces the legacy
+ * bracketed "Tool execution limit reached" placeholder.
+ *
+ * Emit this ONLY when `step >= maxSteps` genuinely terminated the loop —
+ * aborted/timed-out/stalled turns must use {@link buildAbortedTurnMessage},
+ * {@link buildTurnTimeoutMessage}, or {@link buildTurnStalledMessage}, never
+ * this text (a killed 23-step turn once claimed "reached the 200-step limit").
  */
 export declare function buildToolLoopCapMessage(maxSteps: number, toolCallCount: number): string;
+/**
+ * Honest message for a turn ended by the `turnTimeoutMs` wall-clock deadline
+ * (stopReason "time-limit"). Sibling of {@link buildToolLoopCapMessage} —
+ * time exits must never claim a step limit was reached.
+ */
+export declare function buildTurnTimeoutMessage(elapsedMs: number, toolCallCount: number): string;
+/**
+ * Honest message for a turn ended by the `stallTimeoutMs` no-progress
+ * watchdog (stopReason "stalled") — typically a wedged tool or a hung
+ * model call.
+ */
+export declare function buildTurnStalledMessage(stallTimeoutMs: number, toolCallCount: number): string;
+/**
+ * Honest message for a caller-aborted turn (admin kill, coding-task
+ * short-circuit — stopReason "aborted").
+ */
+export declare function buildAbortedTurnMessage(toolCallCount: number): string;
+/**
+ * Wrap-up nudge injected when the remaining turn time drops inside the
+ * `wrapupTimeLeadMs` window — the time-budget twin of the soft step-budget
+ * nudge. Rides as a trailing text block on the tool-result user turn.
+ */
+export declare function buildWrapupNudgeText(useFinalResultTool: boolean): string;
+/**
+ * Resolve the turn's `stopReason` discriminator from the loop's exit
+ * bookkeeping. Precedence: time conditions beat the generic abort flag
+ * (the deadline/stall watchdogs abort through the same internal controller),
+ * abort beats step-cap, and a provider-error finishReason (e.g. persistent
+ * MALFORMED_FUNCTION_CALL) beats "completed".
+ */
+export declare function resolveTurnStopReason(params: {
+    timedOut: boolean;
+    stalled: boolean;
+    wasAborted: boolean;
+    /** Step budget ran out AND no clean/forced answer was produced. */
+    cappedWithoutAnswer: boolean;
+    /** The turn's resolved unified finishReason. */
+    finishReason?: string;
+}): GenerateStopReason;
+/**
+ * Wall-clock + progress watchdogs for a native agentic turn.
+ *
+ * - Deadline: `turnTimeoutMs` (caller knob) or `defaultTurnTimeoutMs` (the
+ *   loop's pre-existing defensive bound) arms a whole-turn timer.
+ * - Stall: when `stallTimeoutMs` is set, a low-frequency interval checks the
+ *   time since the last recorded progress (chunk received, tool started or
+ *   finished, step started).
+ *
+ * Both fire `onDeadline(kind)` exactly once each and latch a flag the loop's
+ * terminal handling reads to pick the honest exit message and `stopReason`.
+ * Timers are unref'd so they never hold the process open; call `dispose()`
+ * in the loop's finally.
+ */
+export declare function createTurnClock(params: {
+    /** Explicit whole-turn deadline (ms); wins over defaultTurnTimeoutMs. */
+    turnTimeoutMs?: number;
+    /** Loop-specific defensive default when turnTimeoutMs is unset (undefined = no deadline). */
+    defaultTurnTimeoutMs?: number;
+    /** No-progress watchdog (ms); undefined = disabled. */
+    stallTimeoutMs?: number;
+    /** Wrap-up lead (ms); only honored when turnTimeoutMs is explicitly set. */
+    wrapupTimeLeadMs?: number;
+    onDeadline: (kind: "timeout" | "stall") => void;
+}): {
+    readonly timedOut: boolean;
+    readonly stalled: boolean;
+    /** True when the turn ended on a time condition (deadline or stall). */
+    readonly expired: boolean;
+    /** The effective whole-turn deadline in ms (explicit or defensive default). */
+    readonly turnTimeoutMs: number | undefined;
+    elapsedMs(): number;
+    /** Record progress: chunk received, tool started/finished, step started. */
+    noteProgress(): void;
+    /** True when an explicit deadline exists and remaining time is inside the wrap-up lead. */
+    shouldNudgeWrapup(): boolean;
+    dispose(): void;
+};
 /**
  * Push model response parts to conversation history, preserving thoughtSignature
  * for Gemini 3 multi-turn tool calling.

package/dist/providers/googleNativeGemini3.js

@@ -11,7 +11,7 @@
 import { randomUUID } from "node:crypto";
 import { existsSync, readFileSync } from "node:fs";
 import { extname } from "node:path";
-import { DEFAULT_MAX_STEPS, DEFAULT_TOOL_MAX_RETRIES, } from "../core/constants.js";
+import { DEFAULT_MAX_STEPS, DEFAULT_TOOL_MAX_RETRIES, DEFAULT_WRAPUP_TIME_LEAD_MS, } from "../core/constants.js";
 import { logger } from "../utils/logger.js";
 import { convertZodToJsonSchema, ensureNestedSchemaTypes, inlineJsonSchema, isZodSchema, normalizeJsonSchemaObject, } from "../utils/schemaConversion.js";
 import { createNativeThinkingConfig } from "../utils/thinkingConfig.js";
@@ -463,6 +463,12 @@ export function computeMaxSteps(rawMaxSteps) {
  * Returns a plain string (not a `{ unified, raw }` object): the Vertex result
  * builders and the consuming layer (neurolink.ts `finishReason || "unknown"`
  * and `finishReason === "length"`) compare against plain strings.
+ *
+ * MALFORMED_FUNCTION_CALL / UNEXPECTED_TOOL_CALL map to "error", NOT
+ * "tool-calls": they are provider/model failures, while "tool-calls" is the
+ * exclusive contract for "step budget exhausted while the model still wanted
+ * tools" — consumers (e.g. curator's step-cap intercept) branch on it and
+ * were rendering fake step-limit messages for 2-4-step malformed-call turns.
  */
 export function mapGeminiFinishReason(raw) {
     switch (raw) {
@@ -470,7 +476,7 @@ export function mapGeminiFinishReason(raw) {
             return "length";
         case "MALFORMED_FUNCTION_CALL":
         case "UNEXPECTED_TOOL_CALL":
-            return "tool-calls";
+            return "error";
         case "SAFETY":
         case "RECITATION":
         case "BLOCKLIST":
@@ -832,8 +838,13 @@ export function isAbortError(error) {
 }
 /**
  * Build a graceful, user-facing message for when a single agentic turn hits
- * the step cap (or is aborted mid-turn) without producing a final answer.
- * Replaces the legacy bracketed "Tool execution limit reached" placeholder.
+ * the step cap without producing a final answer. Replaces the legacy
+ * bracketed "Tool execution limit reached" placeholder.
+ *
+ * Emit this ONLY when `step >= maxSteps` genuinely terminated the loop —
+ * aborted/timed-out/stalled turns must use {@link buildAbortedTurnMessage},
+ * {@link buildTurnTimeoutMessage}, or {@link buildTurnStalledMessage}, never
+ * this text (a killed 23-step turn once claimed "reached the 200-step limit").
  */
 export function buildToolLoopCapMessage(maxSteps, toolCallCount) {
     const calls = toolCallCount > 0
@@ -842,6 +853,177 @@ export function buildToolLoopCapMessage(maxSteps, toolCallCount) {
     return (`${calls}reached the ${maxSteps}-step limit for a single turn before I could finish. ` +
         `Please narrow the request or break it into smaller asks and I'll continue.`);
 }
+/** Format an elapsed duration as "Xm Ys" (or "Ys" under a minute). */
+function formatElapsed(elapsedMs) {
+    const totalSeconds = Math.max(0, Math.round(elapsedMs / 1000));
+    const minutes = Math.floor(totalSeconds / 60);
+    const seconds = totalSeconds % 60;
+    return minutes > 0 ? `${minutes}m ${seconds}s` : `${seconds}s`;
+}
+/**
+ * Honest message for a turn ended by the `turnTimeoutMs` wall-clock deadline
+ * (stopReason "time-limit"). Sibling of {@link buildToolLoopCapMessage} —
+ * time exits must never claim a step limit was reached.
+ */
+export function buildTurnTimeoutMessage(elapsedMs, toolCallCount) {
+    const calls = toolCallCount > 0
+        ? ` I completed ${toolCallCount} tool call${toolCallCount === 1 ? "" : "s"} before stopping;`
+        : "";
+    return (`I had to stop after ${formatElapsed(elapsedMs)} — this turn hit its ` +
+        `processing time limit.${calls} ask me to continue and I'll pick up from there.`);
+}
+/**
+ * Honest message for a turn ended by the `stallTimeoutMs` no-progress
+ * watchdog (stopReason "stalled") — typically a wedged tool or a hung
+ * model call.
+ */
+export function buildTurnStalledMessage(stallTimeoutMs, toolCallCount) {
+    const calls = toolCallCount > 0
+        ? ` I completed ${toolCallCount} tool call${toolCallCount === 1 ? "" : "s"} before stopping;`
+        : "";
+    return (`I had to stop because this turn made no progress for ` +
+        `${formatElapsed(stallTimeoutMs)} — a tool or model call appears to be stuck.` +
+        `${calls} ask me to continue and I'll pick up from there.`);
+}
+/**
+ * Honest message for a caller-aborted turn (admin kill, coding-task
+ * short-circuit — stopReason "aborted").
+ */
+export function buildAbortedTurnMessage(toolCallCount) {
+    const calls = toolCallCount > 0
+        ? ` I completed ${toolCallCount} tool call${toolCallCount === 1 ? "" : "s"} before stopping.`
+        : "";
+    return `This turn was stopped before I could finish.${calls}`;
+}
+/**
+ * Wrap-up nudge injected when the remaining turn time drops inside the
+ * `wrapupTimeLeadMs` window — the time-budget twin of the soft step-budget
+ * nudge. Rides as a trailing text block on the tool-result user turn.
+ */
+export function buildWrapupNudgeText(useFinalResultTool) {
+    return ("NOTE: processing time for this turn is nearly up. Consolidate what you have and " +
+        (useFinalResultTool
+            ? "call final_result with your best answer now."
+            : "provide your final answer now."));
+}
+/**
+ * Resolve the turn's `stopReason` discriminator from the loop's exit
+ * bookkeeping. Precedence: time conditions beat the generic abort flag
+ * (the deadline/stall watchdogs abort through the same internal controller),
+ * abort beats step-cap, and a provider-error finishReason (e.g. persistent
+ * MALFORMED_FUNCTION_CALL) beats "completed".
+ */
+export function resolveTurnStopReason(params) {
+    if (params.timedOut) {
+        return "time-limit";
+    }
+    if (params.stalled) {
+        return "stalled";
+    }
+    if (params.wasAborted) {
+        return "aborted";
+    }
+    if (params.cappedWithoutAnswer) {
+        return "step-cap";
+    }
+    if (params.finishReason === "error") {
+        return "provider-error";
+    }
+    return "completed";
+}
+/**
+ * Wall-clock + progress watchdogs for a native agentic turn.
+ *
+ * - Deadline: `turnTimeoutMs` (caller knob) or `defaultTurnTimeoutMs` (the
+ *   loop's pre-existing defensive bound) arms a whole-turn timer.
+ * - Stall: when `stallTimeoutMs` is set, a low-frequency interval checks the
+ *   time since the last recorded progress (chunk received, tool started or
+ *   finished, step started).
+ *
+ * Both fire `onDeadline(kind)` exactly once each and latch a flag the loop's
+ * terminal handling reads to pick the honest exit message and `stopReason`.
+ * Timers are unref'd so they never hold the process open; call `dispose()`
+ * in the loop's finally.
+ */
+export function createTurnClock(params) {
+    const startedAt = Date.now();
+    const isValidMs = (value) => value !== undefined && Number.isFinite(value) && value > 0;
+    const effectiveTurnTimeoutMs = isValidMs(params.turnTimeoutMs)
+        ? params.turnTimeoutMs
+        : isValidMs(params.defaultTurnTimeoutMs)
+            ? params.defaultTurnTimeoutMs
+            : undefined;
+    // Nudging against the loop's defensive default would inject prompt text
+    // into turns whose caller never opted into a time budget — only nudge
+    // against an explicit turnTimeoutMs.
+    const wrapupLeadMs = isValidMs(params.turnTimeoutMs)
+        ? (params.wrapupTimeLeadMs ?? DEFAULT_WRAPUP_TIME_LEAD_MS)
+        : undefined;
+    let timedOut = false;
+    let stalled = false;
+    let lastProgressAt = startedAt;
+    let deadlineTimer;
+    let stallTimer;
+    if (effectiveTurnTimeoutMs !== undefined) {
+        deadlineTimer = setTimeout(() => {
+            timedOut = true;
+            params.onDeadline("timeout");
+        }, effectiveTurnTimeoutMs);
+        deadlineTimer.unref?.();
+    }
+    if (isValidMs(params.stallTimeoutMs)) {
+        const stallTimeoutMs = params.stallTimeoutMs;
+        const checkEveryMs = Math.min(Math.max(1000, Math.floor(stallTimeoutMs / 4)), 15_000);
+        stallTimer = setInterval(() => {
+            if (!stalled &&
+                !timedOut &&
+                Date.now() - lastProgressAt >= stallTimeoutMs) {
+                stalled = true;
+                params.onDeadline("stall");
+            }
+        }, checkEveryMs);
+        stallTimer.unref?.();
+    }
+    return {
+        get timedOut() {
+            return timedOut;
+        },
+        get stalled() {
+            return stalled;
+        },
+        /** True when the turn ended on a time condition (deadline or stall). */
+        get expired() {
+            return timedOut || stalled;
+        },
+        /** The effective whole-turn deadline in ms (explicit or defensive default). */
+        get turnTimeoutMs() {
+            return effectiveTurnTimeoutMs;
+        },
+        elapsedMs() {
+            return Date.now() - startedAt;
+        },
+        /** Record progress: chunk received, tool started/finished, step started. */
+        noteProgress() {
+            lastProgressAt = Date.now();
+        },
+        /** True when an explicit deadline exists and remaining time is inside the wrap-up lead. */
+        shouldNudgeWrapup() {
+            if (effectiveTurnTimeoutMs === undefined || wrapupLeadMs === undefined) {
+                return false;
+            }
+            const remaining = effectiveTurnTimeoutMs - (Date.now() - startedAt);
+            return remaining > 0 && remaining <= wrapupLeadMs;
+        },
+        dispose() {
+            if (deadlineTimer) {
+                clearTimeout(deadlineTimer);
+            }
+            if (stallTimer) {
+                clearInterval(stallTimer);
+            }
+        },
+    };
+}
 /**
  * Push model response parts to conversation history, preserving thoughtSignature
  * for Gemini 3 multi-turn tool calling.

package/dist/providers/googleVertex.d.ts

@@ -256,6 +256,21 @@ export declare class GoogleVertexProvider extends BaseProvider {
      * exporters. Mirrors the Bedrock + Ollama pattern.
      */
     private emitGenerationEnd;
+    /**
+     * Emit a `turn:lifecycle` event on the SDK emitter (alongside
+     * tool:start/tool:end) so loop conditions that previously only reached
+     * process logs — step-cap, time-limit, stall, abort, tool timeouts,
+     * malformed-call retries — are observable by consumers' own pipelines.
+     */
+    private emitTurnEvent;
+    /**
+     * Pick the honest terminal message for a native-loop exit by its ACTUAL
+     * cause. The step-cap text is the fallback for genuine budget exhaustion
+     * only — time/stall/abort exits must never claim a step limit was reached
+     * (the 2026-07-03 "reached the 200-step limit" incident was a wall-clock
+     * abort wearing the cap message).
+     */
+    private buildLoopExitMessage;
     protected formatProviderError(error: unknown): Error;
     /**
      * Memory-safe cache management for model configurations