@juspay/neurolink 9.80.3 → 9.81.0

package/dist/lib/providers/googleVertex.js

@@ -5,8 +5,10 @@ import path from "path";
 import os from "os";
 import { AIProviderName, ErrorCategory, ErrorSeverity, } from "../constants/enums.js";
 import { BaseProvider } from "../core/baseProvider.js";
-import { DEFAULT_GEMINI_STREAM_TIMEOUT_MS, DEFAULT_MAX_STEPS, DEFAULT_TOOL_MAX_RETRIES, GLOBAL_LOCATION_MODELS, IMAGE_GENERATION_MODELS, TOOL_STORAGE_TIMEOUT_MS, } from "../core/constants.js";
+import { DEFAULT_GEMINI_STREAM_TIMEOUT_MS, DEFAULT_MAX_STEPS, DEFAULT_TOOL_EXECUTION_TIMEOUT_MS, DEFAULT_TOOL_MAX_RETRIES, GLOBAL_LOCATION_MODELS, IMAGE_GENERATION_MODELS, TOOL_STORAGE_TIMEOUT_MS, } from "../core/constants.js";
 import { ModelConfigurationManager } from "../core/modelConfiguration.js";
+import { isSchemaComplexityError } from "../core/modules/structuredOutputPolicy.js";
+import { stringifyContentSafe } from "../utils/logSanitize.js";
 import { createProxyFetch } from "../proxy/proxyFetch.js";
 import { AuthenticationError, InvalidModelError, NetworkError, ProviderError, RateLimitError, } from "../types/index.js";
 import { ERROR_CODES, NeuroLinkError } from "../utils/errorHandling.js";
@@ -22,7 +24,7 @@ import { convertZodToJsonSchema, inlineJsonSchema, ensureNestedSchemaTypes, } fr
 import { createNativeThinkingConfig } from "../utils/thinkingConfig.js";
 import { TimeoutError, withTimeout } from "../utils/async/index.js";
 import { parseTimeout } from "../utils/timeout.js";
-import { appendStepText, buildToolLoopCapMessage, createTextChannel, extractThoughtSignature, isAbortError, mapGeminiFinishReason, prependConversationMessages, } from "./googleNativeGemini3.js";
+import { appendStepText, buildAbortedTurnMessage, buildToolLoopCapMessage, buildTurnStalledMessage, buildTurnTimeoutMessage, buildWrapupNudgeText, createTextChannel, createTurnClock, extractThoughtSignature, isAbortError, mapGeminiFinishReason, prependConversationMessages, resolveTurnStopReason, } from "./googleNativeGemini3.js";
 import { ATTR, LANGFUSE_ATTR, spanJsonAttribute, tracers, withClientSpan, withClientStreamSpan, withSpan, } from "../telemetry/index.js";
 import { SpanKind, SpanStatusCode, context as otelContext, trace as otelTrace, } from "@opentelemetry/api";
 import { calculateCost } from "../utils/pricing.js";
@@ -1326,21 +1328,37 @@ export class GoogleVertexProvider extends BaseProvider {
         const incrementalTextChunks = [];
         // Abort scaffolding (mirrors executeNativeAnthropicStream). The native
         // Gemini SDK cancels via config.abortSignal, so drive an internal
-        // AbortController: the caller's signal and a defensive wall-clock timer
-        // both trip it, and every request/tool-exec receives effectiveSignal.
+        // AbortController: the caller's signal and the turn clock's watchdogs
+        // (whole-turn deadline + optional stall detector) all trip it, and every
+        // request/tool-exec receives effectiveSignal.
         const streamTimeoutMs = parseTimeout(options.timeout) ?? DEFAULT_GEMINI_STREAM_TIMEOUT_MS;
+        const toolExecTimeoutMs = options.toolTimeoutMs ?? DEFAULT_TOOL_EXECUTION_TIMEOUT_MS;
+        const effectiveTurnDeadlineMs = options.turnTimeoutMs ?? streamTimeoutMs;
         const internalAbort = new AbortController();
         const onCallerAbort = () => internalAbort.abort();
         options.abortSignal?.addEventListener("abort", onCallerAbort);
-        const defensiveTimer = setTimeout(() => {
-            logger.warn(`[GoogleVertex] Native Gemini turn exceeded ${streamTimeoutMs}ms — aborting`);
-            internalAbort.abort();
-        }, streamTimeoutMs);
+        const turnClock = createTurnClock({
+            turnTimeoutMs: options.turnTimeoutMs,
+            // Preserve the pre-existing defensive whole-turn bound when the caller
+            // sets no explicit turn budget — a turn must never hang forever.
+            defaultTurnTimeoutMs: streamTimeoutMs,
+            stallTimeoutMs: options.stallTimeoutMs,
+            wrapupTimeLeadMs: options.wrapupTimeLeadMs,
+            onDeadline: (kind) => {
+                logger.warn(kind === "timeout"
+                    ? `[GoogleVertex] Native Gemini turn exceeded its ${effectiveTurnDeadlineMs}ms time budget — aborting`
+                    : `[GoogleVertex] Native Gemini turn made no progress for ${options.stallTimeoutMs}ms — aborting`);
+                internalAbort.abort();
+            },
+        });
         const effectiveSignal = internalAbort.signal;
         if (options.abortSignal?.aborted) {
             internalAbort.abort();
         }
         let wasAborted = false;
+        // One retry per turn for MALFORMED_FUNCTION_CALL steps (see the retry
+        // block after the step drain).
+        let malformedRetryCount = 0;
         // Step-cap flags declared in the outer scope so the terminal block (also
         // inside the try) and the finishReason mapping (after the finally) can
         // both read them.
@@ -1354,6 +1372,7 @@ export class GoogleVertexProvider extends BaseProvider {
                     break;
                 }
                 step++;
+                turnClock.noteProgress();
                 logger.debug(`[GoogleVertex] Native SDK step ${step}/${maxSteps}`);
                 try {
                     const stream = await client.models.generateContentStream({
@@ -1364,7 +1383,12 @@ export class GoogleVertexProvider extends BaseProvider {
                     const stepFunctionCalls = [];
                     // Capture raw response parts including thoughtSignature
                     const rawResponseParts = [];
+                    // This step's own finish reason (vs the cross-step
+                    // lastFinishReason) — drives the single MALFORMED_FUNCTION_CALL
+                    // retry below.
+                    let stepFinishReason;
                     for await (const chunk of stream) {
+                        turnClock.noteProgress();
                         // Extract raw parts from candidates FIRST
                         // This avoids using chunk.text which triggers SDK warning when
                         // non-text parts (thoughtSignature, functionCall) are present
@@ -1376,6 +1400,7 @@ export class GoogleVertexProvider extends BaseProvider {
                         const chunkFinishReason = firstCandidate?.finishReason;
                         if (typeof chunkFinishReason === "string" && chunkFinishReason) {
                             lastFinishReason = chunkFinishReason;
+                            stepFinishReason = chunkFinishReason;
                         }
                         const chunkContent = firstCandidate?.content;
                         if (chunkContent && Array.isArray(chunkContent.parts)) {
@@ -1411,6 +1436,37 @@ export class GoogleVertexProvider extends BaseProvider {
                         .filter((part) => typeof part.text === "string")
                         .map((part) => part.text)
                         .join("");
+                    // MALFORMED_FUNCTION_CALL is usually a transient formatting failure
+                    // (the model emitted an unparseable call): retry the step ONCE with
+                    // a corrective note instead of hard-ending the turn with empty
+                    // content — automated alert-RCA turns were dying at step 2-4 on
+                    // this, mislabeled as step-cap exits.
+                    if (stepFunctionCalls.length === 0 &&
+                        !stepText &&
+                        stepFinishReason === "MALFORMED_FUNCTION_CALL" &&
+                        malformedRetryCount < 1 &&
+                        !effectiveSignal.aborted) {
+                        malformedRetryCount++;
+                        logger.warn(`[GoogleVertex] Model returned MALFORMED_FUNCTION_CALL at step ${step}/${maxSteps}; retrying once with a corrective note.`);
+                        this.emitTurnEvent({ phase: "malformed-retry", step, maxSteps });
+                        if (rawResponseParts.length > 0) {
+                            currentContents.push({
+                                role: "model",
+                                parts: rawResponseParts,
+                            });
+                        }
+                        currentContents.push({
+                            role: "user",
+                            parts: [
+                                {
+                                    text: "Your previous function call was malformed and could not " +
+                                        "be parsed. Re-issue it as a single valid function call, " +
+                                        "or answer in plain text.",
+                                },
+                            ],
+                        });
+                        continue;
+                    }
                     // If no function calls, we're done
                     if (stepFunctionCalls.length === 0) {
                         finalText = stepText;
@@ -1487,7 +1543,11 @@ export class GoogleVertexProvider extends BaseProvider {
                                     messages: [],
                                     abortSignal: effectiveSignal,
                                 };
-                                const result = await execute(call.args, toolOptions);
+                                turnClock.noteProgress();
+                                // Bound the execute() await — a wedged tool costs one step
+                                // (error tool_result), not the whole turn.
+                                const result = await withTimeout(Promise.resolve(execute(call.args, toolOptions)), toolExecTimeoutMs, `Tool "${call.name}" execution timed out after ${toolExecTimeoutMs}ms`);
+                                turnClock.noteProgress();
                                 toolExecutions.push({
                                     name: call.name,
                                     input: call.args,
@@ -1512,6 +1572,15 @@ export class GoogleVertexProvider extends BaseProvider {
                                     wasAborted = true;
                                     break;
                                 }
+                                turnClock.noteProgress();
+                                if (error instanceof TimeoutError) {
+                                    this.emitTurnEvent({
+                                        phase: "tool-timeout",
+                                        step,
+                                        maxSteps,
+                                        toolName: call.name,
+                                    });
+                                }
                                 const errorMessage = error instanceof Error ? error.message : "Unknown error";
                                 // Track this failure
                                 const currentFailInfo = failedTools.get(call.name) || {
@@ -1601,6 +1670,15 @@ export class GoogleVertexProvider extends BaseProvider {
                             });
                         });
                     }
+                    // Time-budget wrap-up nudge (twin of the Anthropic loops' soft
+                    // step nudge): with the turn deadline approaching, tell the model
+                    // to consolidate. Rides as a trailing text part on the
+                    // tool-response user turn.
+                    if (turnClock.shouldNudgeWrapup()) {
+                        functionResponses.push({
+                            text: buildWrapupNudgeText(useFinalResultTool),
+                        });
+                    }
                     // The @google/genai SDK only accepts "user" and "model" as valid
                     // roles in contents — function/tool responses must use role: "user"
                     // (matching the SDK's automaticFunctionCalling implementation and
@@ -1645,11 +1723,21 @@ export class GoogleVertexProvider extends BaseProvider {
                         `returning text already gathered from prior steps.`);
                 }
                 else if (wasAborted) {
-                    // Aborted turn — skip synth entirely so it can never add +300s after
-                    // a blown budget. Deliver exactly one graceful cap chunk.
-                    logger.warn(`[GoogleVertex] Tool call loop aborted mid-turn; ` +
-                        `returning a graceful cap message.`);
-                    finalText = buildToolLoopCapMessage(maxSteps, toolCallCount);
+                    // Turn ended on a time condition or caller abort — skip synth
+                    // entirely so it can never add +300s after a blown budget, and
+                    // deliver exactly one HONEST terminal chunk matching the actual
+                    // exit cause (never the step-cap text — a killed healthy turn must
+                    // not claim it "reached the step limit").
+                    logger.warn(`[GoogleVertex] Tool call loop ended mid-turn ` +
+                        `(${turnClock.timedOut ? "turn time limit" : turnClock.stalled ? "stall watchdog" : "caller abort"}); ` +
+                        `returning an honest terminal message.`);
+                    finalText = this.buildLoopExitMessage({
+                        turnClock,
+                        wasAborted,
+                        stallTimeoutMs: options.stallTimeoutMs,
+                        maxSteps,
+                        toolCallCount,
+                    });
                 }
                 else {
                     logger.warn(`[GoogleVertex] Tool call loop terminated after reaching maxSteps (${maxSteps}) ` +
@@ -1675,7 +1763,7 @@ export class GoogleVertexProvider extends BaseProvider {
             }
         }
         finally {
-            clearTimeout(defensiveTimer);
+            turnClock.dispose();
             options.abortSignal?.removeEventListener("abort", onCallerAbort);
         }
         // Unified finish reason: a step-cap exhaustion that did NOT end in a clean
@@ -1686,6 +1774,24 @@ export class GoogleVertexProvider extends BaseProvider {
         const resolvedFinishReason = hitStepLimit && !synthesizedFinalAnswer
             ? "tool-calls"
             : mapGeminiFinishReason(lastFinishReason);
+        // Turn-exit discriminator, independent of the provider-shaped
+        // finishReason — consumers branch on this instead of sniffing strings.
+        const stopReason = resolveTurnStopReason({
+            timedOut: turnClock.timedOut,
+            stalled: turnClock.stalled,
+            wasAborted,
+            cappedWithoutAnswer: hitStepLimit && !synthesizedFinalAnswer,
+            finishReason: resolvedFinishReason,
+        });
+        if (stopReason !== "completed") {
+            this.emitTurnEvent({
+                phase: stopReason,
+                step,
+                maxSteps,
+                toolCallCount: allToolCalls.filter((tc) => tc.toolName !== "final_result").length,
+                elapsedMs: turnClock.elapsedMs(),
+            });
+        }
         const responseTime = Date.now() - startTime;
         // Yield each text part separately so the CLI receives multiple stream
         // chunks instead of a single coalesced buffer. The SDK already gave us
@@ -1713,6 +1819,8 @@ export class GoogleVertexProvider extends BaseProvider {
             provider: this.providerName,
             model: modelName,
             finishReason: resolvedFinishReason,
+            stopReason,
+            rawFinishReason: lastFinishReason,
             usage: {
                 input: totalInputTokens,
                 output: totalOutputTokens,
@@ -1733,6 +1841,9 @@ export class GoogleVertexProvider extends BaseProvider {
                 startTime,
                 responseTime,
                 totalToolExecutions: externalToolCalls.length,
+                stopReason,
+                rawFinishReason: lastFinishReason,
+                stepsUsed: step,
             },
         };
         // Add structured output if final_result tool was used
@@ -2063,21 +2174,37 @@ export class GoogleVertexProvider extends BaseProvider {
         let totalOutputTokens = 0;
         // Abort scaffolding (mirrors executeNativeAnthropicStream). The native
         // Gemini SDK cancels via config.abortSignal, so drive an internal
-        // AbortController: the caller's signal and a defensive wall-clock timer
-        // both trip it, and every request/tool-exec receives effectiveSignal.
+        // AbortController: the caller's signal and the turn clock's watchdogs
+        // (whole-turn deadline + optional stall detector) all trip it, and every
+        // request/tool-exec receives effectiveSignal.
         const streamTimeoutMs = parseTimeout(options.timeout) ?? DEFAULT_GEMINI_STREAM_TIMEOUT_MS;
+        const toolExecTimeoutMs = options.toolTimeoutMs ?? DEFAULT_TOOL_EXECUTION_TIMEOUT_MS;
+        const effectiveTurnDeadlineMs = options.turnTimeoutMs ?? streamTimeoutMs;
         const internalAbort = new AbortController();
         const onCallerAbort = () => internalAbort.abort();
         options.abortSignal?.addEventListener("abort", onCallerAbort);
-        const defensiveTimer = setTimeout(() => {
-            logger.warn(`[GoogleVertex] Native Gemini turn exceeded ${streamTimeoutMs}ms — aborting`);
-            internalAbort.abort();
-        }, streamTimeoutMs);
+        const turnClock = createTurnClock({
+            turnTimeoutMs: options.turnTimeoutMs,
+            // Preserve the pre-existing defensive whole-turn bound when the caller
+            // sets no explicit turn budget — a turn must never hang forever.
+            defaultTurnTimeoutMs: streamTimeoutMs,
+            stallTimeoutMs: options.stallTimeoutMs,
+            wrapupTimeLeadMs: options.wrapupTimeLeadMs,
+            onDeadline: (kind) => {
+                logger.warn(kind === "timeout"
+                    ? `[GoogleVertex] Native Gemini turn exceeded its ${effectiveTurnDeadlineMs}ms time budget — aborting`
+                    : `[GoogleVertex] Native Gemini turn made no progress for ${options.stallTimeoutMs}ms — aborting`);
+                internalAbort.abort();
+            },
+        });
         const effectiveSignal = internalAbort.signal;
         if (options.abortSignal?.aborted) {
             internalAbort.abort();
         }
         let wasAborted = false;
+        // One retry per turn for MALFORMED_FUNCTION_CALL steps (see the retry
+        // block after the step drain).
+        let malformedRetryCount = 0;
         // Step-cap flags declared in the outer scope so the terminal block (also
         // inside the try) and the finishReason mapping (after the finally) can
         // both read them.
@@ -2091,6 +2218,7 @@ export class GoogleVertexProvider extends BaseProvider {
                     break;
                 }
                 step++;
+                turnClock.noteProgress();
                 logger.debug(`[GoogleVertex] Native SDK generate step ${step}/${maxSteps}`);
                 try {
                     // Use generateContentStream and collect all chunks (same as GoogleAIStudio)
@@ -2102,8 +2230,13 @@ export class GoogleVertexProvider extends BaseProvider {
                     const stepFunctionCalls = [];
                     // Capture raw response parts including thoughtSignature
                     const rawResponseParts = [];
+                    // This step's own finish reason (vs the cross-step
+                    // lastFinishReason) — drives the single MALFORMED_FUNCTION_CALL
+                    // retry below.
+                    let stepFinishReason;
                     // Collect all chunks from stream
                     for await (const chunk of stream) {
+                        turnClock.noteProgress();
                         // Extract raw parts from candidates FIRST
                         // This avoids using chunk.text which triggers SDK warning when
                         // non-text parts (thoughtSignature, functionCall) are present
@@ -2115,6 +2248,7 @@ export class GoogleVertexProvider extends BaseProvider {
                         const chunkFinishReason = firstCandidate?.finishReason;
                         if (typeof chunkFinishReason === "string" && chunkFinishReason) {
                             lastFinishReason = chunkFinishReason;
+                            stepFinishReason = chunkFinishReason;
                         }
                         const chunkContent = firstCandidate?.content;
                         if (chunkContent && Array.isArray(chunkContent.parts)) {
@@ -2145,6 +2279,37 @@ export class GoogleVertexProvider extends BaseProvider {
                         .filter((part) => typeof part.text === "string")
                         .map((part) => part.text)
                         .join("");
+                    // MALFORMED_FUNCTION_CALL is usually a transient formatting failure
+                    // (the model emitted an unparseable call): retry the step ONCE with
+                    // a corrective note instead of hard-ending the turn with empty
+                    // content — automated alert-RCA turns were dying at step 2-4 on
+                    // this, mislabeled as step-cap exits.
+                    if (stepFunctionCalls.length === 0 &&
+                        !stepText &&
+                        stepFinishReason === "MALFORMED_FUNCTION_CALL" &&
+                        malformedRetryCount < 1 &&
+                        !effectiveSignal.aborted) {
+                        malformedRetryCount++;
+                        logger.warn(`[GoogleVertex] Model returned MALFORMED_FUNCTION_CALL at step ${step}/${maxSteps}; retrying once with a corrective note.`);
+                        this.emitTurnEvent({ phase: "malformed-retry", step, maxSteps });
+                        if (rawResponseParts.length > 0) {
+                            currentContents.push({
+                                role: "model",
+                                parts: rawResponseParts,
+                            });
+                        }
+                        currentContents.push({
+                            role: "user",
+                            parts: [
+                                {
+                                    text: "Your previous function call was malformed and could not " +
+                                        "be parsed. Re-issue it as a single valid function call, " +
+                                        "or answer in plain text.",
+                                },
+                            ],
+                        });
+                        continue;
+                    }
                     // If no function calls, we're done
                     if (stepFunctionCalls.length === 0) {
                         finalText = stepText;
@@ -2220,7 +2385,11 @@ export class GoogleVertexProvider extends BaseProvider {
                                     messages: [],
                                     abortSignal: effectiveSignal,
                                 };
-                                const execResult = await execute(call.args, toolOptions);
+                                turnClock.noteProgress();
+                                // Bound the execute() await — a wedged tool costs one step
+                                // (error tool_result), not the whole turn.
+                                const execResult = await withTimeout(Promise.resolve(execute(call.args, toolOptions)), toolExecTimeoutMs, `Tool "${call.name}" execution timed out after ${toolExecTimeoutMs}ms`);
+                                turnClock.noteProgress();
                                 // Track execution
                                 toolExecutions.push({
                                     name: call.name,
@@ -2245,6 +2414,15 @@ export class GoogleVertexProvider extends BaseProvider {
                                     wasAborted = true;
                                     break;
                                 }
+                                turnClock.noteProgress();
+                                if (error instanceof TimeoutError) {
+                                    this.emitTurnEvent({
+                                        phase: "tool-timeout",
+                                        step,
+                                        maxSteps,
+                                        toolName: call.name,
+                                    });
+                                }
                                 const errorMessage = error instanceof Error ? error.message : "Unknown error";
                                 // Track this failure
                                 const currentFailInfo = failedTools.get(call.name) || {
@@ -2331,6 +2509,15 @@ export class GoogleVertexProvider extends BaseProvider {
                             });
                         });
                     }
+                    // Time-budget wrap-up nudge (twin of the Anthropic loops' soft
+                    // step nudge): with the turn deadline approaching, tell the model
+                    // to consolidate. Rides as a trailing text part on the
+                    // tool-response user turn.
+                    if (turnClock.shouldNudgeWrapup()) {
+                        functionResponses.push({
+                            text: buildWrapupNudgeText(useFinalResultTool),
+                        });
+                    }
                     // The @google/genai SDK only accepts "user" and "model" as valid
                     // roles in contents — function/tool responses must use role: "user"
                     // (matching the SDK's automaticFunctionCalling implementation and
@@ -2351,7 +2538,25 @@ export class GoogleVertexProvider extends BaseProvider {
                         wasAborted = true;
                         break;
                     }
-                    logger.error("[GoogleVertex] Native SDK generate error", error);
+                    logger.error("[GoogleVertex] Native SDK generate error", {
+                        error,
+                        model: modelName,
+                        location: effectiveLocation,
+                        status: error?.status,
+                    });
+                    // Best-effort request context for formatProviderError —
+                    // this.modelName can be stale when options.model overrides the
+                    // instance default.
+                    try {
+                        if (error && typeof error === "object") {
+                            const e = error;
+                            e.requestModel = modelName;
+                            e.requestRegion = effectiveLocation;
+                        }
+                    }
+                    catch {
+                        /* frozen/sealed error — context stays best-effort */
+                    }
                     throw this.handleProviderError(error);
                 }
             }
@@ -2369,11 +2574,20 @@ export class GoogleVertexProvider extends BaseProvider {
                     finalText = accumulatedText;
                 }
                 else if (wasAborted) {
-                    // Aborted turn — skip synth entirely so it can never add +300s after
-                    // a blown budget. Deliver a graceful cap message as ordinary prose.
-                    logger.warn(`[GoogleVertex] Generate tool call loop aborted mid-turn; ` +
-                        `returning a graceful cap message.`);
-                    finalText = buildToolLoopCapMessage(maxSteps, toolCallCount);
+                    // Turn ended on a time condition or caller abort — skip synth
+                    // entirely so it can never add +300s after a blown budget, and
+                    // answer with an HONEST message matching the actual exit cause
+                    // (never the step-cap text).
+                    logger.warn(`[GoogleVertex] Generate tool call loop ended mid-turn ` +
+                        `(${turnClock.timedOut ? "turn time limit" : turnClock.stalled ? "stall watchdog" : "caller abort"}); ` +
+                        `returning an honest terminal message.`);
+                    finalText = this.buildLoopExitMessage({
+                        turnClock,
+                        wasAborted,
+                        stallTimeoutMs: options.stallTimeoutMs,
+                        maxSteps,
+                        toolCallCount,
+                    });
                 }
                 else {
                     // Pure functionCall turns leave no text — make one tools-disabled call
@@ -2401,7 +2615,7 @@ export class GoogleVertexProvider extends BaseProvider {
             }
         }
         finally {
-            clearTimeout(defensiveTimer);
+            turnClock.dispose();
             options.abortSignal?.removeEventListener("abort", onCallerAbort);
         }
         // Unified finish reason: a step-cap exhaustion that did NOT end in a clean
@@ -2412,6 +2626,24 @@ export class GoogleVertexProvider extends BaseProvider {
         const resolvedFinishReason = hitStepLimit && !synthesizedFinalAnswer
             ? "tool-calls"
             : mapGeminiFinishReason(lastFinishReason);
+        // Turn-exit discriminator, independent of the provider-shaped
+        // finishReason — consumers branch on this instead of sniffing strings.
+        const stopReason = resolveTurnStopReason({
+            timedOut: turnClock.timedOut,
+            stalled: turnClock.stalled,
+            wasAborted,
+            cappedWithoutAnswer: hitStepLimit && !synthesizedFinalAnswer,
+            finishReason: resolvedFinishReason,
+        });
+        if (stopReason !== "completed") {
+            this.emitTurnEvent({
+                phase: stopReason,
+                step,
+                maxSteps,
+                toolCallCount: allToolCalls.filter((tc) => tc.toolName !== "final_result").length,
+                elapsedMs: turnClock.elapsedMs(),
+            });
+        }
         const responseTime = Date.now() - startTime;
         // Filter out final_result from tool calls and executions as it's an internal pattern
         const externalToolCalls = allToolCalls.filter((tc) => tc.toolName !== "final_result");
@@ -2422,6 +2654,9 @@ export class GoogleVertexProvider extends BaseProvider {
             provider: this.providerName,
             model: modelName,
             finishReason: resolvedFinishReason,
+            stopReason,
+            rawFinishReason: lastFinishReason,
+            stepsUsed: step,
             usage: {
                 input: totalInputTokens,
                 output: totalOutputTokens,
@@ -2585,9 +2820,7 @@ export class GoogleVertexProvider extends BaseProvider {
                 if (msg.role === "user" || msg.role === "assistant") {
                     messages.push({
                         role: msg.role,
-                        content: typeof msg.content === "string"
-                            ? msg.content
-                            : JSON.stringify(msg.content),
+                        content: stringifyContentSafe(msg.content),
                     });
                 }
             }
@@ -2861,6 +3094,8 @@ export class GoogleVertexProvider extends BaseProvider {
         // via a getter (consumers read it after draining the stream), mirroring
         // the Gemini stream path's finishReason field.
         const finishReasonRef = {};
+        const stopReasonRef = {};
+        const rawFinishReasonRef = {};
         // Langfuse/OTel: the native SDK bypasses the Vercel AI SDK's
         // experimental_telemetry, so emit spans manually — one turn span, one
         // generation span per API call, one tool span per execution — all carrying
@@ -2909,8 +3144,8 @@ export class GoogleVertexProvider extends BaseProvider {
             creation5m: 0,
             creation1h: 0,
         };
-        // Track the active Anthropic stream so options.abortSignal can cancel it
-        // mid-flight (pre-rewrite code had no abort handling — fixed for free).
+        // Track the active Anthropic stream so aborts can cancel it mid-flight
+        // (pre-rewrite code had no abort handling — fixed for free).
         let activeStream;
         const abortHandler = () => {
             try {
@@ -2920,15 +3155,35 @@ export class GoogleVertexProvider extends BaseProvider {
                 /* ignore — stream may already be finalized */
             }
         };
-        options.abortSignal?.addEventListener("abort", abortHandler);
-        // Defensive upper bound: if neither the caller nor the SDK ever fires,
-        // abort the stream after the configured timeout so a stalled
-        // Vertex/Anthropic endpoint can't hang forever. options.timeout wins
-        // if set; otherwise 5 min — generous for tool-heavy turns.
-        const streamTimeoutHandle = setTimeout(() => {
-            logger.warn(`[GoogleVertex] Anthropic stream exceeded ${streamTimeoutMs}ms — aborting`);
-            abortHandler();
-        }, streamTimeoutMs);
+        // Internal abort fan-in: the caller's signal and the turn clock's
+        // watchdogs (whole-turn deadline + optional stall detector) all trip it;
+        // it cancels the in-flight SDK stream and is the signal tool executions
+        // receive.
+        const internalAbort = new AbortController();
+        internalAbort.signal.addEventListener("abort", abortHandler);
+        const onCallerAbort = () => internalAbort.abort();
+        options.abortSignal?.addEventListener("abort", onCallerAbort);
+        if (options.abortSignal?.aborted) {
+            internalAbort.abort();
+        }
+        const toolExecTimeoutMs = options.toolTimeoutMs ?? DEFAULT_TOOL_EXECUTION_TIMEOUT_MS;
+        const effectiveTurnDeadlineMs = options.turnTimeoutMs ?? streamTimeoutMs;
+        // Whole-turn deadline + optional stall watchdog. When the caller sets no
+        // explicit turn budget, keep the pre-existing defensive bound
+        // (options.timeout, else 5 min) so a stalled Vertex/Anthropic endpoint
+        // can't hang forever.
+        const turnClock = createTurnClock({
+            turnTimeoutMs: options.turnTimeoutMs,
+            defaultTurnTimeoutMs: streamTimeoutMs,
+            stallTimeoutMs: options.stallTimeoutMs,
+            wrapupTimeLeadMs: options.wrapupTimeLeadMs,
+            onDeadline: (kind) => {
+                logger.warn(kind === "timeout"
+                    ? `[GoogleVertex] Anthropic stream turn exceeded its ${effectiveTurnDeadlineMs}ms time budget — aborting`
+                    : `[GoogleVertex] Anthropic stream turn made no progress for ${options.stallTimeoutMs}ms — aborting`);
+                internalAbort.abort();
+            },
+        });
         const loopPromise = (async () => {
             let step = 0;
             const currentMessages = [...messages];
@@ -2942,15 +3197,17 @@ export class GoogleVertexProvider extends BaseProvider {
             let lastStopReason;
             try {
                 while (step < agenticStepBudget) {
-                    // Honor caller aborts BETWEEN steps: break into terminal handling
-                    // (one graceful cap chunk, clean close) instead of throwing —
-                    // channel.error would surface the caller's own abort as a stream
-                    // failure and route consumers into fallback retries.
-                    if (options.abortSignal?.aborted) {
+                    // Honor aborts BETWEEN steps (caller signal OR the turn clock's
+                    // watchdogs — all fan into internalAbort): break into terminal
+                    // handling (one honest terminal chunk, clean close) instead of
+                    // throwing — channel.error would surface the caller's own abort as
+                    // a stream failure and route consumers into fallback retries.
+                    if (internalAbort.signal.aborted) {
                         wasAborted = true;
                         break;
                     }
                     step++;
+                    turnClock.noteProgress();
                     // One generation observation per API call: request in, content + usage out.
                     const generationSpan = tracers.generation.startSpan("anthropic.messages.stream", {
                         kind: SpanKind.CLIENT,
@@ -3006,6 +3263,7 @@ export class GoogleVertexProvider extends BaseProvider {
                         // giving Langfuse the generation's time-to-first-token.
                         let firstDeltaSeen = false;
                         stream.on("text", (delta) => {
+                            turnClock.noteProgress();
                             if (delta.length > 0) {
                                 if (!firstDeltaSeen) {
                                     firstDeltaSeen = true;
@@ -3032,11 +3290,12 @@ export class GoogleVertexProvider extends BaseProvider {
                             generationSpan.recordException(modelCallError);
                         }
                         generationSpan.end();
-                        // A mid-flight abort (caller signal or the defensive timer
-                        // tripping abortHandler) rejects finalMessage() with an
-                        // abort-shaped error. Break gracefully into the terminal handling
-                        // instead of routing it through channel.error as a failure.
-                        if (options.abortSignal?.aborted || isAbortError(modelCallError)) {
+                        // A mid-flight abort (caller signal or a turn-clock watchdog
+                        // tripping internalAbort/abortHandler) rejects finalMessage()
+                        // with an abort-shaped error. Break gracefully into the terminal
+                        // handling instead of routing it through channel.error as a
+                        // failure.
+                        if (internalAbort.signal.aborted || isAbortError(modelCallError)) {
                             activeStream = undefined;
                             wasAborted = true;
                             break;
@@ -3171,12 +3430,16 @@ export class GoogleVertexProvider extends BaseProvider {
                                 const toolOptions = {
                                     toolCallId: toolUse.id,
                                     messages: [],
-                                    abortSignal: options.abortSignal,
+                                    abortSignal: internalAbort.signal,
                                 };
+                                turnClock.noteProgress();
                                 // Run with toolSpan active so spans inside execute
                                 // (neurolink.tool.execute) nest under this observation instead
-                                // of becoming disconnected siblings.
-                                const result = await otelContext.with(otelTrace.setSpan(turnContext, toolSpan), () => execute(toolUse.input, toolOptions));
+                                // of becoming disconnected siblings. Bound the await — a
+                                // wedged tool costs one step (error tool_result), not the
+                                // whole turn.
+                                const result = await withTimeout(otelContext.with(otelTrace.setSpan(turnContext, toolSpan), () => Promise.resolve(execute(toolUse.input, toolOptions))), toolExecTimeoutMs, `Tool "${toolUse.name}" execution timed out after ${toolExecTimeoutMs}ms`);
+                                turnClock.noteProgress();
                                 // MCP failures are returned, not thrown — surface them on
                                 // the span so failed calls show as ERROR in Langfuse.
                                 endToolSpan(result, extractMcpToolErrorMessage(result));
@@ -3190,7 +3453,7 @@ export class GoogleVertexProvider extends BaseProvider {
                                 // so coerce defensively to keep the follow-up turn valid.
                                 const resultContent = typeof result === "string"
                                     ? result
-                                    : (JSON.stringify(result ?? null) ?? String(result));
+                                    : stringifyContentSafe(result ?? null);
                                 toolResults.push({
                                     type: "tool_result",
                                     tool_use_id: toolUse.id,
@@ -3206,7 +3469,7 @@ export class GoogleVertexProvider extends BaseProvider {
                                 // An aborted tool call is a cancellation, not a tool failure —
                                 // end the span without recording an error execution/result and
                                 // break the turn.
-                                if (options.abortSignal?.aborted || isAbortError(err)) {
+                                if (internalAbort.signal.aborted || isAbortError(err)) {
                                     endToolSpan({ aborted: true });
                                     // Keep persisted tool history paired: the call row was
                                     // already pushed above, so record a neutral cancellation
@@ -3220,6 +3483,15 @@ export class GoogleVertexProvider extends BaseProvider {
                                     wasAborted = true;
                                     break;
                                 }
+                                turnClock.noteProgress();
+                                if (err instanceof TimeoutError) {
+                                    this.emitTurnEvent({
+                                        phase: "tool-timeout",
+                                        step,
+                                        maxSteps,
+                                        toolName: toolUse.name,
+                                    });
+                                }
                                 const errMsg = `Error executing tool "${toolUse.name}": ${err instanceof Error ? err.message : String(err)}`;
                                 const errorPayload = { error: errMsg };
                                 endToolSpan(errorPayload, errMsg);
@@ -3283,6 +3555,8 @@ export class GoogleVertexProvider extends BaseProvider {
                     // to wrap up so the reserved forced-finalization call below stays a
                     // fallback, not the norm. Rides as a trailing text block on the
                     // tool_result user turn (cache-safe: it lives in the growing tail).
+                    // The time-budget twin fires when the turn deadline is inside the
+                    // wrap-up lead window instead.
                     const stepsRemaining = agenticStepBudget - step;
                     if (stepsRemaining > 0 && stepsRemaining <= 3) {
                         toolResults.push({
@@ -3293,6 +3567,12 @@ export class GoogleVertexProvider extends BaseProvider {
                                     : "provide your final answer."),
                         });
                     }
+                    else if (turnClock.shouldNudgeWrapup()) {
+                        toolResults.push({
+                            type: "text",
+                            text: buildWrapupNudgeText(useFinalResultTool),
+                        });
+                    }
                     // Continue the loop: assistant turn + tool_result user turn.
                     // Filter server_tool_use blocks (Anthropic API rejects them in
                     // subsequent message turns).
@@ -3316,24 +3596,34 @@ export class GoogleVertexProvider extends BaseProvider {
                 // Gemini synthesizeFinalAnswerWithoutTools precedent); their tokens
                 // still land in `usage` and the turn-span metadata.
                 if (!modelFinished) {
-                    // A caller abort that landed during the FINAL budgeted step's tool
+                    // An abort that landed during the FINAL budgeted step's tool
                     // execution leaves wasAborted=false (no loop-entry check runs after
                     // a budget exit) — re-check before issuing any terminal model call.
-                    if (options.abortSignal?.aborted) {
+                    if (internalAbort.signal.aborted) {
                         wasAborted = true;
                     }
                     const externalToolCallCount = allToolCalls.filter((tc) => tc.toolName !== "final_result").length;
                     if (wasAborted) {
                         // Budget already blown — never issue another model call. Deliver
-                        // exactly one graceful cap chunk if nothing reached the consumer
-                        // (live deltas already delivered count as "something reached").
-                        logger.warn("[GoogleVertex] Native Anthropic stream loop aborted mid-turn; returning a graceful cap message.");
+                        // exactly one HONEST terminal chunk matching the actual exit
+                        // cause (time limit / stall / caller abort — never the step-cap
+                        // text) if nothing reached the consumer (live deltas already
+                        // delivered count as "something reached").
+                        logger.warn(`[GoogleVertex] Native Anthropic stream loop ended mid-turn ` +
+                            `(${turnClock.timedOut ? "turn time limit" : turnClock.stalled ? "stall watchdog" : "caller abort"}); ` +
+                            `returning an honest terminal message.`);
                         if (aggregatedTurnText.length === 0 &&
                             liveTextPushedLength === 0 &&
                             !structuredOutputRef.value) {
-                            const capMessage = buildToolLoopCapMessage(maxSteps, externalToolCallCount);
-                            channel.push(capMessage);
-                            aggregatedTurnText = capMessage;
+                            const exitMessage = this.buildLoopExitMessage({
+                                turnClock,
+                                wasAborted,
+                                stallTimeoutMs: options.stallTimeoutMs,
+                                maxSteps,
+                                toolCallCount: externalToolCallCount,
+                            });
+                            channel.push(exitMessage);
+                            aggregatedTurnText = exitMessage;
                         }
                     }
                     else if (useFinalResultTool) {
@@ -3398,17 +3688,26 @@ export class GoogleVertexProvider extends BaseProvider {
                         }
                         catch (error) {
                             activeStream = undefined;
-                            // An aborted finalization is a cancellation, not a step-cap
-                            // turn — keep finishReason mapping from lastStopReason.
-                            if (options.abortSignal?.aborted || isAbortError(error)) {
+                            // An aborted finalization is a cancellation (caller abort or a
+                            // turn-clock watchdog), not a step-cap turn — keep finishReason
+                            // mapping from lastStopReason and pick the exit message by the
+                            // actual cause.
+                            if (internalAbort.signal.aborted || isAbortError(error)) {
                                 hitStepLimit = false;
+                                wasAborted = true;
                             }
-                            logger.warn("[GoogleVertex] Forced finalization call failed; falling back to cap message", {
+                            logger.warn("[GoogleVertex] Forced finalization call failed; falling back to a terminal message", {
                                 error: error instanceof Error ? error.message : String(error),
                             });
-                            const capMessage = buildToolLoopCapMessage(maxSteps, externalToolCallCount);
-                            channel.push(capMessage);
-                            aggregatedTurnText += capMessage;
+                            const exitMessage = this.buildLoopExitMessage({
+                                turnClock,
+                                wasAborted,
+                                stallTimeoutMs: options.stallTimeoutMs,
+                                maxSteps,
+                                toolCallCount: externalToolCallCount,
+                            });
+                            channel.push(exitMessage);
+                            aggregatedTurnText += exitMessage;
                         }
                     }
                     else {
@@ -3478,17 +3777,26 @@ export class GoogleVertexProvider extends BaseProvider {
                             }
                             catch (error) {
                                 activeStream = undefined;
-                                // An aborted backstop is a cancellation, not a step-cap
-                                // turn — keep finishReason mapping from lastStopReason.
-                                if (options.abortSignal?.aborted || isAbortError(error)) {
+                                // An aborted backstop is a cancellation (caller abort or a
+                                // turn-clock watchdog), not a step-cap turn — keep
+                                // finishReason mapping from lastStopReason and pick the exit
+                                // message by the actual cause.
+                                if (internalAbort.signal.aborted || isAbortError(error)) {
                                     hitStepLimit = false;
+                                    wasAborted = true;
                                 }
-                                logger.warn("[GoogleVertex] Tools-disabled backstop call failed; falling back to cap message", {
+                                logger.warn("[GoogleVertex] Tools-disabled backstop call failed; falling back to a terminal message", {
                                     error: error instanceof Error ? error.message : String(error),
                                 });
-                                const capMessage = buildToolLoopCapMessage(maxSteps, externalToolCallCount);
-                                channel.push(capMessage);
-                                aggregatedTurnText = capMessage;
+                                const exitMessage = this.buildLoopExitMessage({
+                                    turnClock,
+                                    wasAborted,
+                                    stallTimeoutMs: options.stallTimeoutMs,
+                                    maxSteps,
+                                    toolCallCount: externalToolCallCount,
+                                });
+                                channel.push(exitMessage);
+                                aggregatedTurnText = exitMessage;
                             }
                         }
                         // else: prose already streamed to the consumer across steps —
@@ -3504,9 +3812,15 @@ export class GoogleVertexProvider extends BaseProvider {
                     !structuredOutputRef.value;
                 const externalToolCallTotal = allToolCalls.filter((tc) => tc.toolName !== "final_result").length;
                 if (deliveredNothing && externalToolCallTotal > 0) {
-                    const capMessage = buildToolLoopCapMessage(maxSteps, externalToolCallTotal);
-                    channel.push(capMessage);
-                    aggregatedTurnText = capMessage;
+                    const exitMessage = this.buildLoopExitMessage({
+                        turnClock,
+                        wasAborted,
+                        stallTimeoutMs: options.stallTimeoutMs,
+                        maxSteps,
+                        toolCallCount: externalToolCallTotal,
+                    });
+                    channel.push(exitMessage);
+                    aggregatedTurnText = exitMessage;
                 }
                 // Honest finish reason (same mapping as the generate twin): "length"
                 // takes precedence, a capped turn without a clean/forced answer is
@@ -3522,6 +3836,30 @@ export class GoogleVertexProvider extends BaseProvider {
                 metadata.finishReason = finishReasonRef.value;
                 metadata.responseTime = Date.now() - startTime;
                 metadata.totalToolExecutions = allToolCalls.filter((tc) => tc.toolName !== "final_result").length;
+                // Turn-exit discriminator + raw provider stop reason + step count —
+                // mirrored onto metadata (mutable reference) for wrapper spreads,
+                // like finishReason above.
+                const resolvedStopReason = resolveTurnStopReason({
+                    timedOut: turnClock.timedOut,
+                    stalled: turnClock.stalled,
+                    wasAborted,
+                    cappedWithoutAnswer: hitStepLimit && !synthesizedFinalAnswer,
+                    finishReason: finishReasonRef.value,
+                });
+                stopReasonRef.value = resolvedStopReason;
+                rawFinishReasonRef.value = lastStopReason ?? undefined;
+                metadata.stopReason = resolvedStopReason;
+                metadata.rawFinishReason = rawFinishReasonRef.value;
+                metadata.stepsUsed = step;
+                if (resolvedStopReason !== "completed") {
+                    this.emitTurnEvent({
+                        phase: resolvedStopReason,
+                        step,
+                        maxSteps,
+                        toolCallCount: metadata.totalToolExecutions,
+                        elapsedMs: turnClock.elapsedMs(),
+                    });
+                }
                 // Surface cache metrics once, after the agentic loop, from the
                 // cumulative turnCacheUsage running totals (accumulated via += on every
                 // step above). Assigned here — not per-iteration — so the final values
@@ -3576,8 +3914,9 @@ export class GoogleVertexProvider extends BaseProvider {
             }
             finally {
                 turnSpan.end();
-                options.abortSignal?.removeEventListener("abort", abortHandler);
-                clearTimeout(streamTimeoutHandle);
+                options.abortSignal?.removeEventListener("abort", onCallerAbort);
+                internalAbort.signal.removeEventListener("abort", abortHandler);
+                turnClock.dispose();
             }
         })();
         // Suppress unhandled-rejection: errors funnel through channel.error()
@@ -3622,6 +3961,16 @@ export class GoogleVertexProvider extends BaseProvider {
             configurable: true,
             get: () => finishReasonRef.value,
         });
+        Object.defineProperty(result, "stopReason", {
+            enumerable: true,
+            configurable: true,
+            get: () => stopReasonRef.value,
+        });
+        Object.defineProperty(result, "rawFinishReason", {
+            enumerable: true,
+            configurable: true,
+            get: () => rawFinishReasonRef.value,
+        });
         return result;
     }
     /**
@@ -3651,9 +4000,7 @@ export class GoogleVertexProvider extends BaseProvider {
                 if (msg.role === "user" || msg.role === "assistant") {
                     messages.push({
                         role: msg.role,
-                        content: typeof msg.content === "string"
-                            ? msg.content
-                            : JSON.stringify(msg.content),
+                        content: stringifyContentSafe(msg.content),
                     });
                 }
             }
@@ -3922,15 +4269,48 @@ export class GoogleVertexProvider extends BaseProvider {
         let synthesizedFinalAnswer = false;
         let modelFinished = false;
         const currentMessages = [...messages];
+        // Internal abort fan-in: the caller's signal and the turn clock's
+        // watchdogs all trip it; it rides every SDK request and tool execution.
+        const internalAbort = new AbortController();
+        const onCallerAbort = () => internalAbort.abort();
+        options.abortSignal?.addEventListener("abort", onCallerAbort);
+        if (options.abortSignal?.aborted) {
+            internalAbort.abort();
+        }
+        const toolExecTimeoutMs = options.toolTimeoutMs ?? DEFAULT_TOOL_EXECUTION_TIMEOUT_MS;
+        // Whole-turn deadline + optional stall watchdog. NOTE: unlike the stream
+        // twin, this path historically had NO whole-turn bound (only the per-call
+        // withTimeout) — so no defensive default is introduced here: without an
+        // explicit turnTimeoutMs, long multi-step turns keep running as before.
+        const turnClock = createTurnClock({
+            turnTimeoutMs: options.turnTimeoutMs,
+            stallTimeoutMs: options.stallTimeoutMs,
+            wrapupTimeLeadMs: options.wrapupTimeLeadMs,
+            onDeadline: (kind) => {
+                logger.warn(kind === "timeout"
+                    ? `[GoogleVertex] Anthropic generate turn exceeded its ${options.turnTimeoutMs}ms time budget — aborting`
+                    : `[GoogleVertex] Anthropic generate turn made no progress for ${options.stallTimeoutMs}ms — aborting`);
+                internalAbort.abort();
+            },
+        });
+        // No top-level try/finally wraps this loop (pre-existing shape); release
+        // watchdog timers + the caller-signal listener at both exits — the
+        // provider-error throw in the per-step catch and the normal return path.
+        const releaseTurnResources = () => {
+            turnClock.dispose();
+            options.abortSignal?.removeEventListener("abort", onCallerAbort);
+        };
         while (step < agenticStepBudget) {
-            // Honor caller aborts BETWEEN steps: break into terminal handling
-            // instead of throwing (a throw routes consumers into abortSignal-less
-            // fallback retries — observed in production as a 600s abort no-op).
-            if (options.abortSignal?.aborted) {
+            // Honor aborts BETWEEN steps (caller signal OR turn-clock watchdogs —
+            // all fan into internalAbort): break into terminal handling instead of
+            // throwing (a throw routes consumers into abortSignal-less fallback
+            // retries — observed in production as a 600s abort no-op).
+            if (internalAbort.signal.aborted) {
                 wasAborted = true;
                 break;
             }
             step++;
+            turnClock.noteProgress();
             try {
                 // Bound the SDK wait so a stalled Vertex/Anthropic call can't hang
                 // generate forever. options.timeout wins if set, otherwise default
@@ -3959,7 +4339,7 @@ export class GoogleVertexProvider extends BaseProvider {
                         tools: cachedGenerate.tools,
                     }),
                     messages: cachedGenerate.messages,
-                }, { signal: options.abortSignal }), generateTimeoutMs, "Anthropic generate timed out");
+                }, { signal: internalAbort.signal }), generateTimeoutMs, "Anthropic generate timed out");
                 // Update token counts. input_tokens is the uncached remainder; cache
                 // reads/writes are reported separately and accumulated here so the
                 // result reflects the full picture.
@@ -4019,9 +4399,13 @@ export class GoogleVertexProvider extends BaseProvider {
                             const toolOptions = {
                                 toolCallId: toolUse.id,
                                 messages: [],
-                                abortSignal: options.abortSignal,
+                                abortSignal: internalAbort.signal,
                             };
-                            const result = await execute(toolUse.input, toolOptions);
+                            turnClock.noteProgress();
+                            // Bound the execute() await — a wedged tool costs one step
+                            // (error tool_result), not the whole turn.
+                            const result = await withTimeout(Promise.resolve(execute(toolUse.input, toolOptions)), toolExecTimeoutMs, `Tool "${toolUse.name}" execution timed out after ${toolExecTimeoutMs}ms`);
+                            turnClock.noteProgress();
                             toolExecutions.push({
                                 name: toolUse.name,
                                 input: toolUse.input,
@@ -4032,7 +4416,7 @@ export class GoogleVertexProvider extends BaseProvider {
                             // so coerce defensively to keep the follow-up turn valid.
                             const resultContent = typeof result === "string"
                                 ? result
-                                : (JSON.stringify(result ?? null) ?? String(result));
+                                : stringifyContentSafe(result ?? null);
                             toolResults.push({
                                 type: "tool_result",
                                 tool_use_id: toolUse.id,
@@ -4047,7 +4431,7 @@ export class GoogleVertexProvider extends BaseProvider {
                         catch (err) {
                             // An aborted tool call is a cancellation, not a tool failure —
                             // break the turn without recording an error execution/result.
-                            if (options.abortSignal?.aborted || isAbortError(err)) {
+                            if (internalAbort.signal.aborted || isAbortError(err)) {
                                 // Keep persisted tool history paired: the call row was
                                 // already pushed above, so record a neutral cancellation
                                 // result (NOT an error) — an unpaired tool_use replayed on
@@ -4060,6 +4444,15 @@ export class GoogleVertexProvider extends BaseProvider {
                                 wasAborted = true;
                                 break;
                             }
+                            turnClock.noteProgress();
+                            if (err instanceof TimeoutError) {
+                                this.emitTurnEvent({
+                                    phase: "tool-timeout",
+                                    step,
+                                    maxSteps,
+                                    toolName: toolUse.name,
+                                });
+                            }
                             const errMsg = `Error executing tool "${toolUse.name}": ${err instanceof Error ? err.message : String(err)}`;
                             const errorPayload = { error: errMsg };
                             toolExecutions.push({
@@ -4122,6 +4515,8 @@ export class GoogleVertexProvider extends BaseProvider {
                 // wrap up so the reserved forced-finalization call below stays a
                 // fallback, not the norm. Rides as a trailing text block on the
                 // tool_result user turn (cache-safe: it lives in the growing tail).
+                // The time-budget twin fires when the turn deadline is inside the
+                // wrap-up lead window instead.
                 const stepsRemaining = agenticStepBudget - step;
                 if (stepsRemaining > 0 && stepsRemaining <= 3) {
                     toolResults.push({
@@ -4132,6 +4527,12 @@ export class GoogleVertexProvider extends BaseProvider {
                                 : "provide your final answer."),
                     });
                 }
+                else if (turnClock.shouldNudgeWrapup()) {
+                    toolResults.push({
+                        type: "text",
+                        text: buildWrapupNudgeText(useFinalResultTool),
+                    });
+                }
                 // Add assistant message and tool results to continue the loop
                 // Filter out server_tool_use blocks that the Anthropic API doesn't accept in messages
                 const assistantContent = response.content.filter((block) => block.type !== "server_tool_use");
@@ -4149,16 +4550,33 @@ export class GoogleVertexProvider extends BaseProvider {
             }
             catch (error) {
                 // A mid-request abort surfaces as an abort-shaped SDK rejection (we
-                // pass options.abortSignal as the request signal above). Break
+                // pass internalAbort.signal as the request signal above, and the
+                // caller's signal + turn-clock watchdogs all fan into it). Break
                 // gracefully into the terminal handling instead of re-throwing — a
                 // re-throw routes the caller's abort into abortSignal-less fallback
-                // retries. Dual check as in the Gemini loops: the caller's signal OR
+                // retries. Dual check as in the Gemini loops: the internal signal OR
                 // an abort-shaped error either way means "stop", not a real failure.
-                if (options.abortSignal?.aborted || isAbortError(error)) {
+                if (internalAbort.signal.aborted || isAbortError(error)) {
                     wasAborted = true;
                     break;
                 }
-                logger.error("[GoogleVertex] Native Anthropic SDK generate error", error);
+                logger.error("[GoogleVertex] Native Anthropic SDK generate error", {
+                    error,
+                    model: modelName,
+                    step,
+                    status: error?.status,
+                });
+                // Best-effort request context for formatProviderError — see the
+                // native Gemini catch for rationale.
+                try {
+                    if (error && typeof error === "object") {
+                        error.requestModel = modelName;
+                    }
+                }
+                catch {
+                    /* frozen/sealed error — context stays best-effort */
+                }
+                releaseTurnResources();
                 throw this.handleProviderError(error);
             }
         }
@@ -4168,22 +4586,32 @@ export class GoogleVertexProvider extends BaseProvider {
         // synthesize a plain-text answer on tool turns, or fall back to a
         // graceful cap message. Mirrors the Gemini paths (ed289b7 / PR #1123).
         if (!modelFinished && !finalText) {
-            // A caller abort that landed during the FINAL budgeted step's tool
+            // An abort that landed during the FINAL budgeted step's tool
             // execution leaves wasAborted=false (no loop-entry check runs after a
             // budget exit) — re-check before issuing any terminal model call.
-            if (options.abortSignal?.aborted) {
+            if (internalAbort.signal.aborted) {
                 wasAborted = true;
             }
             const externalToolCallCount = allToolCalls.filter((tc) => tc.toolName !== "final_result").length;
             if (wasAborted) {
                 // Budget already blown — never issue another model call; prefer the
                 // prose the model already produced (mirrors the Gemini abort path),
-                // else answer with a graceful cap message. finishReason keeps mapping
-                // from lastStopReason (an aborted turn is not a step-cap turn).
-                logger.warn("[GoogleVertex] Native Anthropic generate loop aborted mid-turn; returning gathered text or a graceful cap message.");
+                // else answer with an HONEST message matching the actual exit cause
+                // (time limit / stall / caller abort — never the step-cap text).
+                // finishReason keeps mapping from lastStopReason (an aborted turn is
+                // not a step-cap turn).
+                logger.warn(`[GoogleVertex] Native Anthropic generate loop ended mid-turn ` +
+                    `(${turnClock.timedOut ? "turn time limit" : turnClock.stalled ? "stall watchdog" : "caller abort"}); ` +
+                    `returning gathered text or an honest terminal message.`);
                 finalText =
                     accumulatedStepText ||
-                        buildToolLoopCapMessage(maxSteps, externalToolCallCount);
+                        this.buildLoopExitMessage({
+                            turnClock,
+                            wasAborted,
+                            stallTimeoutMs: options.stallTimeoutMs,
+                            maxSteps,
+                            toolCallCount: externalToolCallCount,
+                        });
             }
             else if (useFinalResultTool) {
                 hitStepLimit = true;
@@ -4213,7 +4641,7 @@ export class GoogleVertexProvider extends BaseProvider {
                             tools: cachedFinal.tools,
                         }),
                         messages: cachedFinal.messages,
-                    }, { signal: options.abortSignal }), generateTimeoutMs, "Anthropic finalization call timed out");
+                    }, { signal: internalAbort.signal }), generateTimeoutMs, "Anthropic finalization call timed out");
                     totalInputTokens += response.usage?.input_tokens || 0;
                     totalOutputTokens += response.usage?.output_tokens || 0;
                     totalCacheReadTokens += response.usage?.cache_read_input_tokens || 0;
@@ -4232,13 +4660,22 @@ export class GoogleVertexProvider extends BaseProvider {
                     }
                 }
                 catch (error) {
-                    // An aborted finalization is a cancellation, not a step-cap turn —
-                    // keep finishReason mapping from lastStopReason, not "tool-calls".
-                    if (options.abortSignal?.aborted || isAbortError(error)) {
+                    // An aborted finalization is a cancellation (caller abort or a
+                    // turn-clock watchdog), not a step-cap turn — keep finishReason
+                    // mapping from lastStopReason and pick the exit message by the
+                    // actual cause.
+                    if (internalAbort.signal.aborted || isAbortError(error)) {
                         hitStepLimit = false;
+                        wasAborted = true;
                     }
-                    logger.warn("[GoogleVertex] Forced finalization call failed; falling back to cap message", { error: error instanceof Error ? error.message : String(error) });
-                    finalText = buildToolLoopCapMessage(maxSteps, externalToolCallCount);
+                    logger.warn("[GoogleVertex] Forced finalization call failed; falling back to a terminal message", { error: error instanceof Error ? error.message : String(error) });
+                    finalText = this.buildLoopExitMessage({
+                        turnClock,
+                        wasAborted,
+                        stallTimeoutMs: options.stallTimeoutMs,
+                        maxSteps,
+                        toolCallCount: externalToolCallCount,
+                    });
                 }
             }
             else {
@@ -4276,7 +4713,7 @@ export class GoogleVertexProvider extends BaseProvider {
                                 tools: cachedBackstop.tools,
                             }),
                             messages: cachedBackstop.messages,
-                        }, { signal: options.abortSignal }), generateTimeoutMs, "Anthropic backstop call timed out");
+                        }, { signal: internalAbort.signal }), generateTimeoutMs, "Anthropic backstop call timed out");
                         totalInputTokens += response.usage?.input_tokens || 0;
                         totalOutputTokens += response.usage?.output_tokens || 0;
                         totalCacheReadTokens +=
@@ -4297,39 +4734,79 @@ export class GoogleVertexProvider extends BaseProvider {
                         }
                     }
                     catch (error) {
-                        // An aborted backstop is a cancellation, not a step-cap turn —
-                        // keep finishReason mapping from lastStopReason, not "tool-calls".
-                        if (options.abortSignal?.aborted || isAbortError(error)) {
+                        // An aborted backstop is a cancellation (caller abort or a
+                        // turn-clock watchdog), not a step-cap turn — keep finishReason
+                        // mapping from lastStopReason and pick the exit message by the
+                        // actual cause.
+                        if (internalAbort.signal.aborted || isAbortError(error)) {
                             hitStepLimit = false;
+                            wasAborted = true;
                         }
-                        logger.warn("[GoogleVertex] Tools-disabled backstop call failed; falling back to cap message", {
+                        logger.warn("[GoogleVertex] Tools-disabled backstop call failed; falling back to a terminal message", {
                             error: error instanceof Error ? error.message : String(error),
                         });
-                        finalText = buildToolLoopCapMessage(maxSteps, externalToolCallCount);
+                        finalText = this.buildLoopExitMessage({
+                            turnClock,
+                            wasAborted,
+                            stallTimeoutMs: options.stallTimeoutMs,
+                            maxSteps,
+                            toolCallCount: externalToolCallCount,
+                        });
                     }
                 }
             }
         }
+        releaseTurnResources();
         const responseTime = Date.now() - startTime;
         const externalToolCalls = allToolCalls.filter((tc) => tc.toolName !== "final_result");
         const externalToolExecutions = toolExecutions.filter((te) => te.name !== "final_result");
         // Absolute backstop — no code path may surface empty content on a turn
         // that ran tools (the consumer-facing "empty response" incident shape).
+        // Cause-aware: an aborted/timed-out turn gets the honest exit message,
+        // a genuine budget exhaustion gets the step-cap message.
         if (!finalText && externalToolCalls.length > 0) {
-            finalText = buildToolLoopCapMessage(maxSteps, externalToolCalls.length);
+            finalText = this.buildLoopExitMessage({
+                turnClock,
+                wasAborted,
+                stallTimeoutMs: options.stallTimeoutMs,
+                maxSteps,
+                toolCallCount: externalToolCalls.length,
+            });
+        }
+        // Honest finish reason. "length" (token truncation) takes precedence; a
+        // step-cap exhaustion without a clean/forced answer surfaces as
+        // "tool-calls" (aligned with the Gemini paths, so consumers detect
+        // capped turns uniformly); everything else — including a successful
+        // forced finalization or backstop synthesis — is a normal "stop".
+        const resolvedFinishReason = lastStopReason === "max_tokens"
+            ? "length"
+            : hitStepLimit && !synthesizedFinalAnswer
+                ? "tool-calls"
+                : "stop";
+        // Turn-exit discriminator, independent of the provider-shaped
+        // finishReason — consumers branch on this instead of sniffing strings.
+        const stopReason = resolveTurnStopReason({
+            timedOut: turnClock.timedOut,
+            stalled: turnClock.stalled,
+            wasAborted,
+            cappedWithoutAnswer: hitStepLimit && !synthesizedFinalAnswer,
+            finishReason: resolvedFinishReason,
+        });
+        if (stopReason !== "completed") {
+            this.emitTurnEvent({
+                phase: stopReason,
+                step,
+                maxSteps,
+                toolCallCount: externalToolCalls.length,
+                elapsedMs: turnClock.elapsedMs(),
+            });
         }
         const result = {
             content: finalText,
-            // Honest finish reason. "length" (token truncation) takes precedence; a
-            // step-cap exhaustion without a clean/forced answer surfaces as
-            // "tool-calls" (aligned with the Gemini paths, so consumers detect
-            // capped turns uniformly); everything else — including a successful
-            // forced finalization or backstop synthesis — is a normal "stop".
-            finishReason: lastStopReason === "max_tokens"
-                ? "length"
-                : hitStepLimit && !synthesizedFinalAnswer
-                    ? "tool-calls"
-                    : "stop",
+            finishReason: resolvedFinishReason,
+            stopReason,
+            rawFinishReason: lastStopReason ?? undefined,
+            stepsUsed: step,
             provider: this.providerName,
             model: modelName,
             usage: {
@@ -4622,8 +5099,49 @@ export class GoogleVertexProvider extends BaseProvider {
                             model: modelName,
                             totalToolCount: Object.keys(mergedOptions.tools).length,
                         });
-                        nativeResult =
-                            await this.executeNativeGemini3Generate(mergedOptions);
+                        try {
+                            nativeResult =
+                                await this.executeNativeGemini3Generate(mergedOptions);
+                        }
+                        catch (nativeError) {
+                            // Vertex rejects over-constrained responseSchemas with a
+                            // deterministic 400 ("too many states" — constrained-decoding
+                            // state explosion). Re-sending the same schema can never
+                            // succeed, so retry ONCE with the schema dropped but JSON
+                            // mode kept: output.format "json" still sets
+                            // responseMimeType application/json on the no-tools path,
+                            // so the model is forced to emit JSON — just without the
+                            // offending schema constraints. The NeuroLink layer then
+                            // coerces the JSON text into the caller's original schema
+                            // (generate({schema}) guarantee holds).
+                            const requestedStructured = mergedOptions.schema !== undefined ||
+                                mergedOptions.output?.format === "json";
+                            // Tools present → the executor skips responseMimeType, so a
+                            // schema-less retry would NOT actually run in JSON mode and
+                            // the structured-output contract would silently degrade to
+                            // prose. Only the no-tools case retries faithfully; with
+                            // tools, surface the 400 to the caller instead.
+                            const hasTools = !mergedOptions.disableTools &&
+                                Object.keys(mergedOptions.tools ?? {}).length > 0;
+                            if (requestedStructured &&
+                                !hasTools &&
+                                isSchemaComplexityError(nativeError)) {
+                                logger.warn("[GoogleVertex] responseSchema too complex for constrained decoding — retrying native generate in schema-less JSON mode", {
+                                    model: modelName,
+                                    error: nativeError instanceof Error
+                                        ? nativeError.message
+                                        : String(nativeError),
+                                });
+                                nativeResult = await this.executeNativeGemini3Generate({
+                                    ...mergedOptions,
+                                    schema: undefined,
+                                    output: { format: "json" },
+                                });
+                            }
+                            else {
+                                throw nativeError;
+                            }
+                        }
                     }
                     executionSpan.setAttribute(LANGFUSE_ATTR.OBSERVATION_OUTPUT, spanJsonAttribute(nativeResult?.content ?? ""));
                     return nativeResult;
@@ -4921,6 +5439,43 @@ export class GoogleVertexProvider extends BaseProvider {
                 true;
         }
     }
+    /**
+     * 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.
+     */
+    emitTurnEvent(payload) {
+        try {
+            this.neurolink?.getEventEmitter()?.emit("turn:lifecycle", {
+                provider: this.providerName,
+                timestamp: Date.now(),
+                ...payload,
+            });
+        }
+        catch {
+            /* listener errors are non-fatal */
+        }
+    }
+    /**
+     * 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).
+     */
+    buildLoopExitMessage(params) {
+        if (params.turnClock.timedOut) {
+            return buildTurnTimeoutMessage(params.turnClock.elapsedMs(), params.toolCallCount);
+        }
+        if (params.turnClock.stalled) {
+            return buildTurnStalledMessage(params.stallTimeoutMs ?? 0, params.toolCallCount);
+        }
+        if (params.wasAborted) {
+            return buildAbortedTurnMessage(params.toolCallCount);
+        }
+        return buildToolLoopCapMessage(params.maxSteps, params.toolCallCount);
+    }
     formatProviderError(error) {
         const errorRecord = error;
         if (typeof errorRecord?.name === "string" &&
@@ -4960,17 +5515,42 @@ export class GoogleVertexProvider extends BaseProvider {
                 `3. Ensure your project has access to the model ` +
                 `4. For Claude models, enable Anthropic integration in Google Cloud Console`, this.providerName);
         }
-        // Rate limit and quota errors
+        // Rate limit / quota / capacity errors. Anthropic-on-Vertex capacity
+        // exhaustion surfaces as overloaded_error (HTTP 529) — same operational
+        // meaning as a 429, so classify it here instead of the generic 5xx branch.
         if (message.includes("QUOTA_EXCEEDED") ||
             message.includes("RATE_LIMIT_EXCEEDED") ||
             message.includes("rate limit") ||
             message.includes("429") ||
-            statusCode === 429) {
-            return new RateLimitError(`Google Vertex AI quota/rate limit exceeded. ` +
-                `Solutions: 1. Check your Vertex AI quotas in Google Cloud Console ` +
-                `2. Request quota increase if needed ` +
-                `3. Try a different model or reduce request frequency ` +
-                `4. Consider using a different region`, this.providerName);
+            statusCode === 429 ||
+            statusCode === 529 ||
+            /overloaded/i.test(message)) {
+            // Surface retry guidance when the SDK error carries it. @google/genai
+            // ApiError nests RetryInfo inside the JSON error body's details array,
+            // so fall back to scraping retryDelay out of the raw message.
+            const retryDelay = typeof errorRecord?.retryDelay === "string"
+                ? errorRecord.retryDelay
+                : (/["']?retryDelay["']?\s*[:=]\s*["']?(\d+(?:\.\d+)?s)/.exec(message)?.[1] ?? undefined);
+            // Prefer the per-request context the native catches attach to the
+            // error (this.modelName can be stale when options.model overrides the
+            // instance default). Gemini models are force-routed to the "global"
+            // endpoint regardless of configured location — report the region the
+            // request actually hit.
+            const requestModel = typeof errorRecord?.requestModel === "string"
+                ? errorRecord.requestModel
+                : this.modelName;
+            const effectiveRegion = typeof errorRecord?.requestRegion === "string"
+                ? errorRecord.requestRegion
+                : resolveVertexRegionForModel(requestModel, this.location);
+            return new RateLimitError(`Google Vertex AI rate limit / shared-capacity exhausted (429 RESOURCE_EXHAUSTED / overloaded) ` +
+                `for model '${requestModel}' in region '${effectiveRegion}'.` +
+                (retryDelay
+                    ? ` Upstream suggests retrying after ${retryDelay}.`
+                    : "") +
+                ` Solutions: 1. Retry with backoff ` +
+                `2. Check your Vertex AI quotas in Google Cloud Console (shared-capacity 429s can occur below quota) ` +
+                `3. Try a different region or model ` +
+                `4. Request provisioned throughput for sustained load`, this.providerName);
         }
         // Network connectivity errors
         if (message.includes("ECONNRESET") ||