@juspay/neurolink 9.80.3 → 9.81.0

package/dist/lib/neurolink.js

@@ -72,6 +72,7 @@ import { coerceJsonToSchema } from "./utils/json/coerce.js";
 // Factory processing imports
 import { createCleanStreamOptions, enhanceTextGenerationOptions, processFactoryOptions, processStreamingFactoryOptions, validateFactoryConfig, } from "./utils/factoryProcessing.js";
 import { logger, mcpLogger } from "./utils/logger.js";
+import { redactUrlCredentials, safeDebugSerialize, sanitizeRecord, stringifyContentSafe, } from "./utils/logSanitize.js";
 import { extractMcpErrorText } from "./utils/mcpErrorText.js";
 import { createCustomToolServerInfo, detectCategory, } from "./utils/mcpDefaults.js";
 import { resolveModel } from "./utils/modelAliasResolver.js";
@@ -2156,9 +2157,7 @@ Current user's request: ${currentInput}`;
         const anyOptions = optionsOrPrompt;
         if (anyOptions.messages && anyOptions.messages.length > 0) {
             const lastMessage = anyOptions.messages[anyOptions.messages.length - 1];
-            return typeof lastMessage.content === "string"
-                ? lastMessage.content
-                : JSON.stringify(lastMessage.content);
+            return stringifyContentSafe(lastMessage.content);
         }
         // Handle input.text format
         return optionsOrPrompt.input?.text || "";
@@ -3514,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,
@@ -3645,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,
@@ -3879,9 +3888,7 @@ Current user's request: ${currentInput}`;
                 ?.filter((m) => m.role === "user" || m.role === "assistant")
                 .map((m) => ({
                 role: m.role,
-                content: typeof m.content === "string"
-                    ? m.content
-                    : JSON.stringify(m.content),
+                content: stringifyContentSafe(m.content),
             })) ??
                 options.conversationHistory,
             timeout: options.timeout,
@@ -3978,9 +3985,7 @@ Current user's request: ${currentInput}`;
                 ?.filter((m) => m.role === "user" || m.role === "assistant")
                 .map((m) => ({
                 role: m.role,
-                content: typeof m.content === "string"
-                    ? m.content
-                    : JSON.stringify(m.content),
+                content: stringifyContentSafe(m.content),
             })) ??
                 options.conversationHistory,
             timeout: options.timeout,
@@ -4603,6 +4608,11 @@ Current user's request: ${currentInput}`;
      */
     async performMCPGenerationRetries(options, generateInternalId, generateInternalStartTime, generateInternalHrTimeStart, functionTag) {
         const maxMcpRetries = RETRY_ATTEMPTS.QUICK;
+        // Captured BEFORE the first attempt: ensureMCPGenerationBudget (inside
+        // tryMCPGeneration) auto-scales options.timeout for >100K-token contexts
+        // when the caller left it unset, so checking options.timeout inside the
+        // catch below could not tell caller-set apart from auto-scaled.
+        const callerSetTimeout = options.timeout !== undefined;
         // NL-007: Track retry metadata for observability
         const retryErrors = [];
         let retryCount = 0;
@@ -4645,6 +4655,20 @@ Current user's request: ${currentInput}`;
                     logger.debug(`[${functionTag}] AbortError detected on attempt ${attempt}, stopping retries`);
                     throw error;
                 }
+                // A TimeoutError against an explicit caller-set options.timeout is
+                // deterministic-by-construction: every remaining retry AND the
+                // direct-generation fallback would re-run the same provider+model
+                // under the same per-step budget. Observed in production as ~650s
+                // of doomed follow-ups after a 90s step timeout. Surface it now.
+                // Name check (not instanceof): two TimeoutError classes exist
+                // (utils/timeout.ts and utils/async/withTimeout.ts) and both stamp
+                // name = "TimeoutError".
+                if (callerSetTimeout &&
+                    error instanceof Error &&
+                    error.name === "TimeoutError") {
+                    logger.warn(`[${functionTag}] Per-step timeout (${String(options.timeout)}) exhausted on attempt ${attempt} — surfacing instead of retrying with the same budget`);
+                    throw error;
+                }
                 // NL-007: Record retry error for observability
                 retryCount++;
                 const errMsg = error instanceof Error ? error.message : String(error);
@@ -5049,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),
@@ -5184,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;
@@ -5460,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}).
@@ -6457,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,
@@ -6804,6 +6837,7 @@ Current user's request: ${currentInput}`;
                 guardrailsBlocked: metadata.guardrailsBlocked,
                 error: metadata.error,
                 events: eventSequence,
+                providerMetadata: providerStreamMetadata,
             });
         }
         catch (error) {
@@ -7220,11 +7254,18 @@ Current user's request: ${currentInput}`;
      */
     async storeStreamConversationMemory(params) {
         const { enhancedOptions, providerName, originalPrompt, accumulatedContent, startTime, eventSequence, } = params;
-        logger.debug("[NeuroLink.stream] Preparing to store conversation turn in memory", {
-            options: JSON.stringify(enhancedOptions),
-            sessionId: enhancedOptions.context
-                ?.sessionId,
-        });
+        // Logger Guard: the full options object (history + tool outputs) can be
+        // enormous — an eager JSON.stringify here threw RangeError: Invalid
+        // string length in production and killed the turn. Serialize lazily,
+        // bounded, and only when debug is actually enabled; sanitizeRecord
+        // redacts credentials/PII keys before anything reaches the sink.
+        if (logger.shouldLog("debug")) {
+            logger.debug("[NeuroLink.stream] Preparing to store conversation turn in memory", {
+                options: safeDebugSerialize(sanitizeRecord(enhancedOptions)),
+                sessionId: enhancedOptions.context
+                    ?.sessionId,
+            });
+        }
         // Guard: skip storing if no meaningful content was produced (no text AND no tool activity)
         const hasToolEvents = eventSequence.some((e) => e.type === "tool:start" || e.type === "tool:end");
         if (!accumulatedContent.trim() && !hasToolEvents) {
@@ -7234,12 +7275,16 @@ Current user's request: ${currentInput}`;
             });
             return;
         }
-        logger.debug("[NeuroLink.stream] Storing conversation turn in memory", {
-            options: JSON.stringify(enhancedOptions),
-            sessionId: enhancedOptions.context
-                ?.sessionId,
-            conversationMemoryExists: this.conversationMemory ? true : false,
-        });
+        // Logger Guard: see the matching block above — never eagerly stringify
+        // the full options object, and always redact before serializing.
+        if (logger.shouldLog("debug")) {
+            logger.debug("[NeuroLink.stream] Storing conversation turn in memory", {
+                options: safeDebugSerialize(sanitizeRecord(enhancedOptions)),
+                sessionId: enhancedOptions.context
+                    ?.sessionId,
+                conversationMemoryExists: this.conversationMemory ? true : false,
+            });
+        }
         // Store memory after stream consumption is complete
         if (this.conversationMemory && enhancedOptions.context?.sessionId) {
             const sessionId = enhancedOptions.context
@@ -7587,6 +7632,7 @@ Current user's request: ${currentInput}`;
                         toolCalls: poolStreamResult.toolCalls ?? [],
                         toolResults: poolStreamResult.toolResults ?? [],
                         analytics: poolStreamResult.analytics,
+                        metadata: poolStreamResult.metadata,
                     };
                 }
                 catch (poolStreamError) {
@@ -7640,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,
         };
     }
     /**
@@ -7682,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,
-            },
+            }),
         };
     }
     /**
@@ -8703,11 +8755,7 @@ Current user's request: ${currentInput}`;
             : this.getCustomTools().has(toolName)
                 ? "custom"
                 : "external";
-        const inputStr = typeof params === "string"
-            ? params
-            : params
-                ? JSON.stringify(params)
-                : "";
+        const inputStr = params ? stringifyContentSafe(params) : "";
         const executionStartTime = Date.now();
         // Per-invocation id so consumers can correlate a tool:start with its matching
         // tool:end even when the same tool runs multiple times concurrently.
@@ -10271,8 +10319,15 @@ Current user's request: ${currentInput}`;
                 });
             }
             else {
+                // Single ERROR record for a failed registration — the inner layers
+                // (client factory, server manager) log at debug so one root cause no
+                // longer fans out into 5 ERROR lines. Carry enough context here to
+                // diagnose without the inner lines.
                 mcpLogger.error(`[NeuroLink] Failed to add external MCP server: ${serverId}`, {
                     error: result.error,
+                    transport: config.transport,
+                    command: config.command,
+                    url: config.url ? redactUrlCredentials(config.url) : undefined,
                 });
             }
             return result;
@@ -10304,6 +10359,11 @@ Current user's request: ${currentInput}`;
                     timestamp: Date.now(),
                 });
             }
+            else if (result.error?.includes("not found")) {
+                // Expected no-op: consumers commonly call remove as cleanup after a
+                // failed add, when the server never registered. Not an error.
+                mcpLogger.debug(`[NeuroLink] Remove skipped — external MCP server not registered: ${serverId}`);
+            }
             else {
                 mcpLogger.error(`[NeuroLink] Failed to remove external MCP server: ${serverId}`, {
                     error: result.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