@juspay/neurolink 9.80.4 → 9.81.1

package/dist/cli/loop/optionsSchema.js

@@ -49,6 +49,22 @@ export const textGenerationOptionsSchema = {
         type: "number",
         description: "Timeout for the generation request in milliseconds.",
     },
+    turnTimeoutMs: {
+        type: "number",
+        description: "Wall-clock cap for the whole agentic turn in milliseconds (all steps + tool executions).",
+    },
+    stallTimeoutMs: {
+        type: "number",
+        description: "Maximum time with no progress (no chunk, no tool activity) before the turn ends as stalled, in milliseconds.",
+    },
+    wrapupTimeLeadMs: {
+        type: "number",
+        description: "Remaining-turn-time threshold that triggers a wrap-up nudge to the model, in milliseconds.",
+    },
+    toolTimeoutMs: {
+        type: "number",
+        description: "Per-tool-execution timeout in milliseconds (default 300000). A timed-out tool fails that step; the turn continues.",
+    },
     disableTools: {
         type: "boolean",
         description: "Disable all tool usage for the AI.",

package/dist/core/analytics.js

@@ -18,6 +18,15 @@ export function createAnalytics(provider, model, result, responseTime, context)
         const tokens = extractTokenUsage(result);
         // Estimate cost based on provider and tokens
         const cost = estimateCost(provider, model, tokens);
+        // Turn-lifecycle telemetry from native agentic loops (Vertex
+        // Gemini/Claude): stopReason / rawFinishReason / stepsUsed ride the
+        // provider result; toolCallCount and elapsedMs derive from it.
+        const turnResult = result;
+        const toolCallCount = Array.isArray(turnResult.toolExecutions)
+            ? turnResult.toolExecutions.length
+            : Array.isArray(turnResult.toolsUsed)
+                ? turnResult.toolsUsed.length
+                : undefined;
         const analytics = {
             provider,
             model,
@@ -26,6 +35,19 @@ export function createAnalytics(provider, model, result, responseTime, context)
             requestDuration: responseTime,
             context: context,
             timestamp: new Date().toISOString(),
+            ...(typeof turnResult.stepsUsed === "number" && {
+                stepsUsed: turnResult.stepsUsed,
+            }),
+            ...(toolCallCount !== undefined && { toolCallCount }),
+            ...(typeof turnResult.stopReason === "string" && {
+                stopReason: turnResult.stopReason,
+            }),
+            ...(typeof turnResult.responseTime === "number" && {
+                elapsedMs: turnResult.responseTime,
+            }),
+            ...(typeof turnResult.rawFinishReason === "string" && {
+                rawFinishReason: turnResult.rawFinishReason,
+            }),
         };
         logger.debug(`[${functionTag}] Analytics created`, {
             provider,

package/dist/core/constants.d.ts

@@ -23,6 +23,19 @@ export declare const DEFAULT_MAX_STEPS = 200;
 export declare const DEFAULT_TOOL_MAX_RETRIES = 2;
 /** Defensive wall-clock ceiling for a native Gemini-3 agentic turn (generate + stream). */
 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`.
+ */
+export declare const DEFAULT_TOOL_EXECUTION_TIMEOUT_MS = 300000;
+/**
+ * Default wrap-up lead applied when `turnTimeoutMs` is set but
+ * `wrapupTimeLeadMs` is not: with less than this much turn time remaining,
+ * a wrap-up nudge rides the next tool-result turn.
+ */
+export declare const DEFAULT_WRAPUP_TIME_LEAD_MS = 120000;
 export declare const TOOL_STORAGE_TIMEOUT_MS = 5000;
 export declare const STEP_LIMITS: {
     min: number;

package/dist/core/constants.js

@@ -109,6 +109,19 @@ export const DEFAULT_MAX_STEPS = 200;
 export const DEFAULT_TOOL_MAX_RETRIES = 2; // Maximum retries per tool before permanently failing
 /** Defensive wall-clock ceiling for a native Gemini-3 agentic turn (generate + stream). */
 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`.
+ */
+export const DEFAULT_TOOL_EXECUTION_TIMEOUT_MS = 300_000;
+/**
+ * Default wrap-up lead applied when `turnTimeoutMs` is set but
+ * `wrapupTimeLeadMs` is not: with less than this much turn time remaining,
+ * a wrap-up nudge rides the next tool-result turn.
+ */
+export const DEFAULT_WRAPUP_TIME_LEAD_MS = 120_000;
 // Fire-and-forget tool storage writes (Redis). 5s is generous for a single
 // Redis write; if breached, the .catch logs a warning.
 export const TOOL_STORAGE_TIMEOUT_MS = 5000;

package/dist/lib/core/analytics.js

@@ -18,6 +18,15 @@ export function createAnalytics(provider, model, result, responseTime, context)
         const tokens = extractTokenUsage(result);
         // Estimate cost based on provider and tokens
         const cost = estimateCost(provider, model, tokens);
+        // Turn-lifecycle telemetry from native agentic loops (Vertex
+        // Gemini/Claude): stopReason / rawFinishReason / stepsUsed ride the
+        // provider result; toolCallCount and elapsedMs derive from it.
+        const turnResult = result;
+        const toolCallCount = Array.isArray(turnResult.toolExecutions)
+            ? turnResult.toolExecutions.length
+            : Array.isArray(turnResult.toolsUsed)
+                ? turnResult.toolsUsed.length
+                : undefined;
         const analytics = {
             provider,
             model,
@@ -26,6 +35,19 @@ export function createAnalytics(provider, model, result, responseTime, context)
             requestDuration: responseTime,
             context: context,
             timestamp: new Date().toISOString(),
+            ...(typeof turnResult.stepsUsed === "number" && {
+                stepsUsed: turnResult.stepsUsed,
+            }),
+            ...(toolCallCount !== undefined && { toolCallCount }),
+            ...(typeof turnResult.stopReason === "string" && {
+                stopReason: turnResult.stopReason,
+            }),
+            ...(typeof turnResult.responseTime === "number" && {
+                elapsedMs: turnResult.responseTime,
+            }),
+            ...(typeof turnResult.rawFinishReason === "string" && {
+                rawFinishReason: turnResult.rawFinishReason,
+            }),
         };
         logger.debug(`[${functionTag}] Analytics created`, {
             provider,

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

@@ -23,6 +23,19 @@ export declare const DEFAULT_MAX_STEPS = 200;
 export declare const DEFAULT_TOOL_MAX_RETRIES = 2;
 /** Defensive wall-clock ceiling for a native Gemini-3 agentic turn (generate + stream). */
 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`.
+ */
+export declare const DEFAULT_TOOL_EXECUTION_TIMEOUT_MS = 300000;
+/**
+ * Default wrap-up lead applied when `turnTimeoutMs` is set but
+ * `wrapupTimeLeadMs` is not: with less than this much turn time remaining,
+ * a wrap-up nudge rides the next tool-result turn.
+ */
+export declare const DEFAULT_WRAPUP_TIME_LEAD_MS = 120000;
 export declare const TOOL_STORAGE_TIMEOUT_MS = 5000;
 export declare const STEP_LIMITS: {
     min: number;

package/dist/lib/core/constants.js

@@ -109,6 +109,19 @@ export const DEFAULT_MAX_STEPS = 200;
 export const DEFAULT_TOOL_MAX_RETRIES = 2; // Maximum retries per tool before permanently failing
 /** Defensive wall-clock ceiling for a native Gemini-3 agentic turn (generate + stream). */
 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`.
+ */
+export const DEFAULT_TOOL_EXECUTION_TIMEOUT_MS = 300_000;
+/**
+ * Default wrap-up lead applied when `turnTimeoutMs` is set but
+ * `wrapupTimeLeadMs` is not: with less than this much turn time remaining,
+ * a wrap-up nudge rides the next tool-result turn.
+ */
+export const DEFAULT_WRAPUP_TIME_LEAD_MS = 120_000;
 // Fire-and-forget tool storage writes (Redis). 5s is generous for a single
 // Redis write; if breached, the .catch logs a warning.
 export const TOOL_STORAGE_TIMEOUT_MS = 5000;

package/dist/lib/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/lib/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/lib/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/lib/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