@juspay/neurolink 9.80.2 → 9.80.4

package/dist/providers/googleVertex.js

@@ -7,6 +7,8 @@ import { 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 { 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";
@@ -932,7 +934,10 @@ export class GoogleVertexProvider extends BaseProvider {
                 this.emitStreamEnd(modelName, streamStartTime, false, error);
                 throw error;
             }
-        }, (r) => r.stream, (r, wrapped) => ({ ...r, stream: wrapped }));
+        }, (r) => r.stream, 
+        // Preserve live getters (finishReason/structuredOutput/…) that the
+        // spread would otherwise snapshot before the background loop resolves.
+        (r, wrapped) => this.preserveStreamResultAccessors(r, { ...r, stream: wrapped }));
     }
     /**
      * Emit `stream:end` so the Pipeline B observability listener creates a
@@ -2348,7 +2353,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);
                 }
             }
@@ -2582,9 +2605,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),
                     });
                 }
             }
@@ -2832,6 +2853,13 @@ export class GoogleVertexProvider extends BaseProvider {
         // while generation is still in progress. Mirrors the executeStream
         // pattern in googleAiStudio.ts.
         const maxSteps = options.maxSteps || DEFAULT_MAX_STEPS;
+        // Reserve the LAST step of the budget for a forced final_result call when
+        // structured output is active — see the generate twin for the full
+        // rationale (tool_choice:"any" makes the text exit unreachable, so an
+        // un-reserved budget deadlocks into an empty stream).
+        const agenticStepBudget = useFinalResultTool
+            ? Math.max(maxSteps - 1, 0)
+            : maxSteps;
         const allToolCalls = [];
         const toolExecutions = [];
         const channel = createTextChannel();
@@ -2847,6 +2875,10 @@ export class GoogleVertexProvider extends BaseProvider {
         };
         const toolsUsedRef = [];
         const structuredOutputRef = {};
+        // Resolved after the background loop finishes; the StreamResult exposes it
+        // via a getter (consumers read it after draining the stream), mirroring
+        // the Gemini stream path's finishReason field.
+        const finishReasonRef = {};
         // 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
@@ -2883,6 +2915,11 @@ export class GoogleVertexProvider extends BaseProvider {
         });
         const turnContext = otelTrace.setSpan(otelContext.active(), turnSpan);
         let aggregatedTurnText = "";
+        // Count of characters ALREADY delivered to the consumer via live text
+        // deltas. aggregatedTurnText only reflects completed finalMessage()
+        // responses, so an aborted mid-answer call would otherwise look "empty"
+        // to the terminal handling even though the consumer saw partial prose.
+        let liveTextPushedLength = 0;
         // Anthropic prompt-cache token accounting, aggregated across loop steps.
         const turnCacheUsage = {
             read: 0,
@@ -2913,10 +2950,23 @@ export class GoogleVertexProvider extends BaseProvider {
         const loopPromise = (async () => {
             let step = 0;
             const currentMessages = [...messages];
+            // Step-cap / abort bookkeeping (mirrors the generate twin): read by the
+            // terminal recovery block after the loop and by the finishReason
+            // mapping written into finishReasonRef.
+            let wasAborted = false;
+            let hitStepLimit = false;
+            let synthesizedFinalAnswer = false;
+            let modelFinished = false;
+            let lastStopReason;
             try {
-                while (step < maxSteps) {
+                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) {
-                        throw new Error("Stream aborted by caller");
+                        wasAborted = true;
+                        break;
                     }
                     step++;
                     // One generation observation per API call: request in, content + usage out.
@@ -2980,6 +3030,7 @@ export class GoogleVertexProvider extends BaseProvider {
                                     generationSpan.setAttribute(LANGFUSE_ATTR.OBSERVATION_COMPLETION_START_TIME, new Date().toISOString());
                                 }
                                 channel.push(delta);
+                                liveTextPushedLength += delta.length;
                             }
                         });
                         // finalMessage() resolves AFTER message_stop. By then the listener
@@ -2999,6 +3050,15 @@ 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)) {
+                            activeStream = undefined;
+                            wasAborted = true;
+                            break;
+                        }
                         throw modelCallError;
                     }
                     activeStream = undefined;
@@ -3016,6 +3076,7 @@ export class GoogleVertexProvider extends BaseProvider {
                         usage.input += response.usage?.input_tokens || 0;
                         usage.output += response.usage?.output_tokens || 0;
                         usage.total = usage.input + usage.output;
+                        lastStopReason = response.stop_reason;
                         for (const block of response.content) {
                             if (block.type === "text" && typeof block.text === "string") {
                                 aggregatedTurnText += block.text;
@@ -3057,6 +3118,7 @@ export class GoogleVertexProvider extends BaseProvider {
                         if (finalResultCall) {
                             structuredOutputRef.value = finalResultCall.input;
                             channel.push(JSON.stringify(finalResultCall.input));
+                            modelFinished = true;
                             logger.debug("[GoogleVertex] Extracted structured output from final_result tool (stream)", { keys: Object.keys(finalResultCall.input) });
                             break;
                         }
@@ -3064,11 +3126,14 @@ export class GoogleVertexProvider extends BaseProvider {
                     // No tools — pure text turn. Listener already pushed all deltas;
                     // loop terminates and channel.close() flushes the consumer.
                     if (toolUseBlocks.length === 0) {
+                        modelFinished = true;
                         break;
                     }
                     // Tool execution loop. tool:start / tool:end events fire from
                     // ToolsManager's wrapped execute (ToolsManager.ts:355) — no inline
-                    // emit needed.
+                    // emit needed. The array also carries the trailing soft-budget
+                    // nudge text block appended below (tool_result blocks stay first,
+                    // as the Anthropic API requires).
                     const toolResults = [];
                     // Per-step bookkeeping for conversation-memory storage.
                     const stepStorageCalls = [];
@@ -3143,7 +3208,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,
@@ -3156,6 +3221,23 @@ export class GoogleVertexProvider extends BaseProvider {
                                 });
                             }
                             catch (err) {
+                                // 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)) {
+                                    endToolSpan({ aborted: true });
+                                    // 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
+                                    // the next turn would be rejected by the Anthropic API.
+                                    stepStorageResults.push({
+                                        toolCallId: toolUse.id,
+                                        toolName: toolUse.name,
+                                        output: { aborted: true },
+                                    });
+                                    wasAborted = true;
+                                    break;
+                                }
                                 const errMsg = `Error executing tool "${toolUse.name}": ${err instanceof Error ? err.message : String(err)}`;
                                 const errorPayload = { error: errMsg };
                                 endToolSpan(errorPayload, errMsg);
@@ -3199,7 +3281,9 @@ export class GoogleVertexProvider extends BaseProvider {
                     }
                     // Persist this step's tool calls/results into conversation memory.
                     // Without this hook, tool rows never land in Redis and the
-                    // chat-history UI loses every tool invocation.
+                    // chat-history UI loses every tool invocation. Runs BEFORE the
+                    // abort break below so tools that DID complete in an aborted step
+                    // (real side effects) still reach the chat history.
                     if (stepStorageCalls.length > 0 || stepStorageResults.length > 0) {
                         withTimeout(this.handleToolExecutionStorage(stepStorageCalls.map((c) => ({ ...c, stepIndex: step })), stepStorageResults.map((r) => ({ ...r, stepIndex: step })), options, new Date()), TOOL_STORAGE_TIMEOUT_MS, "tool storage write timed out").catch((error) => {
                             logger.warn("[GoogleVertex] Failed to store native Anthropic stream tool executions", {
@@ -3207,6 +3291,26 @@ export class GoogleVertexProvider extends BaseProvider {
                             });
                         });
                     }
+                    // An abort inside the tool-exec loop only breaks that inner
+                    // for-loop. Break the while too so no further model call is issued
+                    // and control reaches the terminal step-cap handling below.
+                    if (wasAborted) {
+                        break;
+                    }
+                    // Soft budget nudge: with the step cap approaching, tell the model
+                    // 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).
+                    const stepsRemaining = agenticStepBudget - step;
+                    if (stepsRemaining > 0 && stepsRemaining <= 3) {
+                        toolResults.push({
+                            type: "text",
+                            text: `NOTE: Only ${stepsRemaining} tool step(s) remain. Consolidate what you have and ` +
+                                (useFinalResultTool
+                                    ? "call final_result with your best answer."
+                                    : "provide your final answer."),
+                        });
+                    }
                     // Continue the loop: assistant turn + tool_result user turn.
                     // Filter server_tool_use blocks (Anthropic API rejects them in
                     // subsequent message turns).
@@ -3220,6 +3324,220 @@ export class GoogleVertexProvider extends BaseProvider {
                         content: toolResults,
                     });
                 }
+                // Terminal handling — the loop exited without a model-initiated
+                // finish (step budget exhausted, or the turn was aborted). Never end
+                // the stream empty: force the reserved final_result step on
+                // structured-output turns, synthesize a plain-text answer on tool
+                // turns, or push one graceful cap chunk. Mirrors the generate twin
+                // and the Gemini paths (ed289b7 / PR #1123). The finalization and
+                // backstop calls emit no per-call generation span (matching the
+                // 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
+                    // 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) {
+                        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.");
+                        if (aggregatedTurnText.length === 0 &&
+                            liveTextPushedLength === 0 &&
+                            !structuredOutputRef.value) {
+                            const capMessage = buildToolLoopCapMessage(maxSteps, externalToolCallCount);
+                            channel.push(capMessage);
+                            aggregatedTurnText = capMessage;
+                        }
+                    }
+                    else if (useFinalResultTool) {
+                        hitStepLimit = true;
+                        logger.warn(`[GoogleVertex] Native Anthropic stream loop reached maxSteps (${maxSteps}) without final_result; forcing a finalization call.`);
+                        try {
+                            // Reserved finalization step: identical request except
+                            // tool_choice pins final_result — Anthropic guarantees a
+                            // final_result tool_use. Cache treatment is byte-identical to
+                            // loop steps. No text listener: forced tool calls stream no
+                            // text deltas, and the structured JSON is pushed once below.
+                            const cachedFinal = applyVertexAnthropicCacheBreakpoints({
+                                system: systemPromptWithSchema,
+                                tools,
+                                messages: currentMessages,
+                            });
+                            const finalizationStream = await client.messages.stream({
+                                ...requestParams,
+                                tool_choice: {
+                                    type: "tool",
+                                    name: "final_result",
+                                },
+                                ...(cachedFinal.system !== undefined && {
+                                    system: cachedFinal.system,
+                                }),
+                                ...(cachedFinal.tools &&
+                                    cachedFinal.tools.length > 0 && {
+                                    tools: cachedFinal.tools,
+                                }),
+                                messages: cachedFinal.messages,
+                            });
+                            // Mid-flight aborts are covered by the shared abortHandler via
+                            // activeStream; already-fired aborts were handled by the
+                            // terminal-entry re-check above.
+                            activeStream = finalizationStream;
+                            const response = await finalizationStream.finalMessage();
+                            activeStream = undefined;
+                            usage.input += response.usage?.input_tokens || 0;
+                            usage.output += response.usage?.output_tokens || 0;
+                            usage.total = usage.input + usage.output;
+                            turnCacheUsage.read +=
+                                response.usage?.cache_read_input_tokens ?? 0;
+                            turnCacheUsage.creation +=
+                                response.usage?.cache_creation_input_tokens ?? 0;
+                            turnCacheUsage.creation5m +=
+                                response.usage?.cache_creation?.ephemeral_5m_input_tokens ?? 0;
+                            turnCacheUsage.creation1h +=
+                                response.usage?.cache_creation?.ephemeral_1h_input_tokens ?? 0;
+                            lastStopReason = response.stop_reason;
+                            const forcedFinalResult = response.content.find((block) => block.type === "tool_use" && block.name === "final_result");
+                            if (forcedFinalResult) {
+                                structuredOutputRef.value = forcedFinalResult.input;
+                                channel.push(JSON.stringify(forcedFinalResult.input));
+                                synthesizedFinalAnswer = true;
+                                logger.debug("[GoogleVertex] Forced finalization returned structured output (stream)", { keys: Object.keys(forcedFinalResult.input) });
+                            }
+                            else {
+                                const capMessage = buildToolLoopCapMessage(maxSteps, externalToolCallCount);
+                                channel.push(capMessage);
+                                aggregatedTurnText += capMessage;
+                            }
+                        }
+                        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)) {
+                                hitStepLimit = false;
+                            }
+                            logger.warn("[GoogleVertex] Forced finalization call failed; falling back to cap message", {
+                                error: error instanceof Error ? error.message : String(error),
+                            });
+                            const capMessage = buildToolLoopCapMessage(maxSteps, externalToolCallCount);
+                            channel.push(capMessage);
+                            aggregatedTurnText += capMessage;
+                        }
+                    }
+                    else {
+                        hitStepLimit = true;
+                        if (aggregatedTurnText.length === 0) {
+                            // Pure tool-loop with no streamed text: one tools-disabled call
+                            // so the model answers from the gathered tool results, pushed
+                            // as a single chunk (matching the Gemini stream synth). NOTE:
+                            // the tools array must stay in the request — Anthropic rejects
+                            // histories containing tool_use/tool_result blocks without a
+                            // tools param — so "tools disabled" is tool_choice:"none",
+                            // which also keeps the cached tools prefix byte-identical.
+                            logger.warn(`[GoogleVertex] Native Anthropic stream loop reached maxSteps (${maxSteps}) with no text; synthesizing a final answer with tools disabled.`);
+                            try {
+                                const backstopSystem = (systemPromptWithSchema
+                                    ? systemPromptWithSchema + "\n\n"
+                                    : "") +
+                                    "Tool calling is no longer available for this turn. " +
+                                    "Provide your final answer directly as plain text now, " +
+                                    "using the information gathered so far.";
+                                const cachedBackstop = applyVertexAnthropicCacheBreakpoints({
+                                    system: backstopSystem,
+                                    tools,
+                                    messages: currentMessages,
+                                });
+                                const backstopStream = await client.messages.stream({
+                                    ...requestParams,
+                                    tool_choice: { type: "none" },
+                                    system: cachedBackstop.system,
+                                    ...(cachedBackstop.tools &&
+                                        cachedBackstop.tools.length > 0 && {
+                                        tools: cachedBackstop.tools,
+                                    }),
+                                    messages: cachedBackstop.messages,
+                                });
+                                activeStream = backstopStream;
+                                const response = await backstopStream.finalMessage();
+                                activeStream = undefined;
+                                usage.input += response.usage?.input_tokens || 0;
+                                usage.output += response.usage?.output_tokens || 0;
+                                usage.total = usage.input + usage.output;
+                                turnCacheUsage.read +=
+                                    response.usage?.cache_read_input_tokens ?? 0;
+                                turnCacheUsage.creation +=
+                                    response.usage?.cache_creation_input_tokens ?? 0;
+                                turnCacheUsage.creation5m +=
+                                    response.usage?.cache_creation?.ephemeral_5m_input_tokens ??
+                                        0;
+                                turnCacheUsage.creation1h +=
+                                    response.usage?.cache_creation?.ephemeral_1h_input_tokens ??
+                                        0;
+                                lastStopReason = response.stop_reason;
+                                const backstopText = response.content
+                                    .filter((block) => block.type === "text")
+                                    .map((b) => b.text)
+                                    .join("");
+                                if (backstopText) {
+                                    synthesizedFinalAnswer = true;
+                                    channel.push(backstopText);
+                                    aggregatedTurnText = backstopText;
+                                }
+                                else {
+                                    const capMessage = buildToolLoopCapMessage(maxSteps, externalToolCallCount);
+                                    channel.push(capMessage);
+                                    aggregatedTurnText = capMessage;
+                                }
+                            }
+                            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)) {
+                                    hitStepLimit = false;
+                                }
+                                logger.warn("[GoogleVertex] Tools-disabled backstop call failed; falling back to cap message", {
+                                    error: error instanceof Error ? error.message : String(error),
+                                });
+                                const capMessage = buildToolLoopCapMessage(maxSteps, externalToolCallCount);
+                                channel.push(capMessage);
+                                aggregatedTurnText = capMessage;
+                            }
+                        }
+                        // else: prose already streamed to the consumer across steps —
+                        // add nothing; finishReason "tool-calls" flags the capped turn.
+                    }
+                }
+                // Absolute backstop — never close the stream empty on a turn that
+                // ran tools (mirrors the generate twin's guard). Catches the
+                // model-finished-with-empty-content exit, which skips the terminal
+                // recovery above.
+                const deliveredNothing = aggregatedTurnText.length === 0 &&
+                    liveTextPushedLength === 0 &&
+                    !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;
+                }
+                // Honest finish reason (same mapping as the generate twin): "length"
+                // takes precedence, a capped turn without a clean/forced answer is
+                // "tool-calls", everything else is "stop". Mirrored onto metadata
+                // (a mutable reference) because wrapper spreads snapshot the
+                // top-level getter before this line runs.
+                finishReasonRef.value =
+                    lastStopReason === "max_tokens"
+                        ? "length"
+                        : hitStepLimit && !synthesizedFinalAnswer
+                            ? "tool-calls"
+                            : "stop";
+                metadata.finishReason = finishReasonRef.value;
                 metadata.responseTime = Date.now() - startTime;
                 metadata.totalToolExecutions = allToolCalls.filter((tc) => tc.toolName !== "final_result").length;
                 // Surface cache metrics once, after the agentic loop, from the
@@ -3315,6 +3633,13 @@ export class GoogleVertexProvider extends BaseProvider {
             configurable: true,
             get: () => structuredOutputRef.value,
         });
+        // Resolved by the background loop right before channel.close(); consumers
+        // read it after draining the stream (same contract as usage/metadata).
+        Object.defineProperty(result, "finishReason", {
+            enumerable: true,
+            configurable: true,
+            get: () => finishReasonRef.value,
+        });
         return result;
     }
     /**
@@ -3344,9 +3669,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),
                     });
                 }
             }
@@ -3578,8 +3901,21 @@ export class GoogleVertexProvider extends BaseProvider {
         };
         // Handle tool calling loop with max steps
         const maxSteps = options.maxSteps || DEFAULT_MAX_STEPS;
+        // Reserve the LAST step of the budget for a forced final_result call when
+        // structured output is active. tool_choice:"any" (set above) forces a tool
+        // call on every assistant turn, so the toolUseBlocks.length===0 text exit
+        // is structurally unreachable — without a reserved finalization step, a
+        // turn whose budget is consumed by other tool calls (runaway loop, or all
+        // tools failing) ends with content:"" and a masking finishReason "stop".
+        const agenticStepBudget = useFinalResultTool
+            ? Math.max(maxSteps - 1, 0)
+            : maxSteps;
         let step = 0;
         let finalText = "";
+        // Prose produced mid-loop alongside tool calls, accumulated across steps
+        // via appendStepText — surfaced if the step budget runs out (mirrors the
+        // Gemini paths' accumulatedText; last-step-only would drop earlier prose).
+        let accumulatedStepText = "";
         let structuredOutput;
         const allToolCalls = [];
         let totalInputTokens = 0;
@@ -3594,8 +3930,22 @@ export class GoogleVertexProvider extends BaseProvider {
         // (notably "length" on token truncation) — the legacy native path always
         // reported "stop", hiding truncation from callers.
         let lastStopReason;
+        // Step-cap / abort bookkeeping (mirrors the native Gemini loops): the
+        // terminal recovery block below and the finishReason mapping both read
+        // these to distinguish clean finishes, capped turns, and aborted turns.
+        let wasAborted = false;
+        let hitStepLimit = false;
+        let synthesizedFinalAnswer = false;
+        let modelFinished = false;
         const currentMessages = [...messages];
-        while (step < maxSteps) {
+        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) {
+                wasAborted = true;
+                break;
+            }
             step++;
             try {
                 // Bound the SDK wait so a stalled Vertex/Anthropic call can't hang
@@ -3612,6 +3962,9 @@ export class GoogleVertexProvider extends BaseProvider {
                     tools,
                     messages: currentMessages,
                 });
+                // The caller's abortSignal rides as an SDK request option so a
+                // mid-flight abort cancels the HTTP call itself (the SDK rejects with
+                // an abort-shaped error the per-step catch below turns into a break).
                 const response = await withTimeout(client.messages.create({
                     ...requestParams,
                     ...(cachedGenerate.system !== undefined && {
@@ -3622,7 +3975,7 @@ export class GoogleVertexProvider extends BaseProvider {
                         tools: cachedGenerate.tools,
                     }),
                     messages: cachedGenerate.messages,
-                }), generateTimeoutMs, "Anthropic generate timed out");
+                }, { signal: options.abortSignal }), 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.
@@ -3641,6 +3994,7 @@ export class GoogleVertexProvider extends BaseProvider {
                         // Extract structured output and convert to JSON string for finalText
                         structuredOutput = finalResultCall.input;
                         finalText = JSON.stringify(structuredOutput);
+                        modelFinished = true;
                         logger.debug("[GoogleVertex] Extracted structured output from final_result tool (generate)", { keys: Object.keys(structuredOutput) });
                         break; // We have the structured output, we're done
                     }
@@ -3650,10 +4004,13 @@ export class GoogleVertexProvider extends BaseProvider {
                 const responseText = textBlocks.map((b) => b.text).join("");
                 if (toolUseBlocks.length === 0) {
                     // No tool calls, we're done
-                    finalText = responseText || finalText;
+                    finalText = responseText || accumulatedStepText;
+                    modelFinished = true;
                     break;
                 }
-                // Handle tool calls
+                // Handle tool calls. The array also carries the trailing soft-budget
+                // nudge text block appended below (tool_result blocks stay first, as
+                // the Anthropic API requires).
                 const toolResults = [];
                 // Per-step bookkeeping for conversation-memory storage. Tracks calls
                 // and results for ONLY the tools fired in this step so the storage
@@ -3691,7 +4048,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,
@@ -3704,6 +4061,21 @@ 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)) {
+                                // 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
+                                // the next turn would be rejected by the Anthropic API.
+                                stepStorageResults.push({
+                                    toolCallId: toolUse.id,
+                                    toolName: toolUse.name,
+                                    output: { aborted: true },
+                                });
+                                wasAborted = true;
+                                break;
+                            }
                             const errMsg = `Error executing tool "${toolUse.name}": ${err instanceof Error ? err.message : String(err)}`;
                             const errorPayload = { error: errMsg };
                             toolExecutions.push({
@@ -3747,6 +4119,8 @@ export class GoogleVertexProvider extends BaseProvider {
                 // Without this, tool_call / tool_result rows never reach Redis and
                 // the chat-history UI loses every tool invocation.
                 // Fire-and-forget — storage failures must not break generation.
+                // Runs BEFORE the abort break below so tools that DID complete in an
+                // aborted step (real side effects) still reach the chat history.
                 if (stepStorageCalls.length > 0 || stepStorageResults.length > 0) {
                     withTimeout(this.handleToolExecutionStorage(stepStorageCalls.map((c) => ({ ...c, stepIndex: step })), stepStorageResults.map((r) => ({ ...r, stepIndex: step })), options, new Date()), TOOL_STORAGE_TIMEOUT_MS, "tool storage write timed out").catch((error) => {
                         logger.warn("[GoogleVertex] Failed to store native Anthropic generate tool executions", {
@@ -3754,6 +4128,26 @@ export class GoogleVertexProvider extends BaseProvider {
                         });
                     });
                 }
+                // An abort inside the tool-exec loop only breaks that inner for-loop.
+                // Break the while too so no further model call is issued and control
+                // reaches the terminal step-cap handling below.
+                if (wasAborted) {
+                    break;
+                }
+                // Soft budget nudge: with the step cap approaching, tell the model 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).
+                const stepsRemaining = agenticStepBudget - step;
+                if (stepsRemaining > 0 && stepsRemaining <= 3) {
+                    toolResults.push({
+                        type: "text",
+                        text: `NOTE: Only ${stepsRemaining} tool step(s) remain. Consolidate what you have and ` +
+                            (useFinalResultTool
+                                ? "call final_result with your best answer."
+                                : "provide your final answer."),
+                    });
+                }
                 // 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");
@@ -3765,25 +4159,208 @@ export class GoogleVertexProvider extends BaseProvider {
                     role: "user",
                     content: toolResults,
                 });
-                // Store last text in case we hit max steps
-                if (responseText) {
-                    finalText = responseText;
-                }
+                // Accumulate the step's prose so a capped turn can still surface it —
+                // finalText is reserved for model-initiated finishes.
+                accumulatedStepText = appendStepText(accumulatedStepText, responseText);
             }
             catch (error) {
-                logger.error("[GoogleVertex] Native Anthropic SDK generate error", error);
+                // A mid-request abort surfaces as an abort-shaped SDK rejection (we
+                // pass options.abortSignal as the request signal above). 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
+                // an abort-shaped error either way means "stop", not a real failure.
+                if (options.abortSignal?.aborted || isAbortError(error)) {
+                    wasAborted = true;
+                    break;
+                }
+                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 */
+                }
                 throw this.handleProviderError(error);
             }
         }
+        // Terminal handling — the loop exited without a model-initiated finish
+        // (step budget exhausted, or the turn was aborted). Never return "":
+        // force the reserved final_result step on structured-output turns,
+        // 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
+            // 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) {
+                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.");
+                finalText =
+                    accumulatedStepText ||
+                        buildToolLoopCapMessage(maxSteps, externalToolCallCount);
+            }
+            else if (useFinalResultTool) {
+                hitStepLimit = true;
+                logger.warn(`[GoogleVertex] Native Anthropic generate loop reached maxSteps (${maxSteps}) without final_result; forcing a finalization call.`);
+                try {
+                    // Reserved finalization step: identical request except tool_choice
+                    // pins final_result, so Anthropic guarantees the response is a
+                    // final_result tool_use. Cache treatment is byte-identical to loop
+                    // steps (same applyVertexAnthropicCacheBreakpoints on the same
+                    // stable system/tools prefix), so caching is unaffected.
+                    const cachedFinal = applyVertexAnthropicCacheBreakpoints({
+                        system: systemPromptWithSchema,
+                        tools,
+                        messages: currentMessages,
+                    });
+                    const response = await withTimeout(client.messages.create({
+                        ...requestParams,
+                        tool_choice: {
+                            type: "tool",
+                            name: "final_result",
+                        },
+                        ...(cachedFinal.system !== undefined && {
+                            system: cachedFinal.system,
+                        }),
+                        ...(cachedFinal.tools &&
+                            cachedFinal.tools.length > 0 && {
+                            tools: cachedFinal.tools,
+                        }),
+                        messages: cachedFinal.messages,
+                    }, { signal: options.abortSignal }), 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;
+                    totalCacheCreationTokens +=
+                        response.usage?.cache_creation_input_tokens || 0;
+                    lastStopReason = response.stop_reason;
+                    const forcedFinalResult = response.content.find((block) => block.type === "tool_use" && block.name === "final_result");
+                    if (forcedFinalResult) {
+                        structuredOutput = forcedFinalResult.input;
+                        finalText = JSON.stringify(structuredOutput);
+                        synthesizedFinalAnswer = true;
+                        logger.debug("[GoogleVertex] Forced finalization returned structured output (generate)", { keys: Object.keys(structuredOutput) });
+                    }
+                    else {
+                        finalText = buildToolLoopCapMessage(maxSteps, externalToolCallCount);
+                    }
+                }
+                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)) {
+                        hitStepLimit = false;
+                    }
+                    logger.warn("[GoogleVertex] Forced finalization call failed; falling back to cap message", { error: error instanceof Error ? error.message : String(error) });
+                    finalText = buildToolLoopCapMessage(maxSteps, externalToolCallCount);
+                }
+            }
+            else {
+                hitStepLimit = true;
+                if (accumulatedStepText) {
+                    // Prefer the prose the model already produced across steps.
+                    logger.warn(`[GoogleVertex] Native Anthropic generate loop reached maxSteps (${maxSteps}); returning text already gathered from prior steps.`);
+                    finalText = accumulatedStepText;
+                }
+                else {
+                    // Pure tool-loop with no text: one tools-disabled call so the model
+                    // answers from the gathered tool results (Anthropic twin of the
+                    // Gemini synthesizeFinalAnswerWithoutTools). NOTE: the tools array
+                    // must stay in the request — Anthropic rejects requests whose
+                    // history contains tool_use/tool_result blocks without a tools
+                    // param — so "tools disabled" is expressed as tool_choice:"none",
+                    // which also keeps the cached tools prefix byte-identical.
+                    logger.warn(`[GoogleVertex] Native Anthropic generate loop reached maxSteps (${maxSteps}) with no text; synthesizing a final answer with tools disabled.`);
+                    try {
+                        const backstopSystem = (systemPromptWithSchema ? systemPromptWithSchema + "\n\n" : "") +
+                            "Tool calling is no longer available for this turn. Provide " +
+                            "your final answer directly as plain text now, using the " +
+                            "information gathered so far.";
+                        const cachedBackstop = applyVertexAnthropicCacheBreakpoints({
+                            system: backstopSystem,
+                            tools,
+                            messages: currentMessages,
+                        });
+                        const response = await withTimeout(client.messages.create({
+                            ...requestParams,
+                            tool_choice: { type: "none" },
+                            system: cachedBackstop.system,
+                            ...(cachedBackstop.tools &&
+                                cachedBackstop.tools.length > 0 && {
+                                tools: cachedBackstop.tools,
+                            }),
+                            messages: cachedBackstop.messages,
+                        }, { signal: options.abortSignal }), generateTimeoutMs, "Anthropic backstop call timed out");
+                        totalInputTokens += response.usage?.input_tokens || 0;
+                        totalOutputTokens += response.usage?.output_tokens || 0;
+                        totalCacheReadTokens +=
+                            response.usage?.cache_read_input_tokens || 0;
+                        totalCacheCreationTokens +=
+                            response.usage?.cache_creation_input_tokens || 0;
+                        lastStopReason = response.stop_reason;
+                        const backstopText = response.content
+                            .filter((block) => block.type === "text")
+                            .map((b) => b.text)
+                            .join("");
+                        if (backstopText) {
+                            synthesizedFinalAnswer = true;
+                            finalText = backstopText;
+                        }
+                        else {
+                            finalText = buildToolLoopCapMessage(maxSteps, externalToolCallCount);
+                        }
+                    }
+                    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)) {
+                            hitStepLimit = false;
+                        }
+                        logger.warn("[GoogleVertex] Tools-disabled backstop call failed; falling back to cap message", {
+                            error: error instanceof Error ? error.message : String(error),
+                        });
+                        finalText = buildToolLoopCapMessage(maxSteps, externalToolCallCount);
+                    }
+                }
+            }
+        }
         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).
+        if (!finalText && externalToolCalls.length > 0) {
+            finalText = buildToolLoopCapMessage(maxSteps, externalToolCalls.length);
+        }
         const result = {
             content: finalText,
-            // Surface truncation: Anthropic "max_tokens" → unified "length" so the
-            // SDK boundary can flag/observe incomplete structured output. Anything
-            // else (end_turn / stop_sequence / tool_use) is a normal stop.
-            finishReason: lastStopReason === "max_tokens" ? "length" : "stop",
+            // 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",
             provider: this.providerName,
             model: modelName,
             usage: {
@@ -4076,8 +4653,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;
@@ -4252,10 +4870,35 @@ export class GoogleVertexProvider extends BaseProvider {
                 }
             },
         };
-        return {
+        return this.preserveStreamResultAccessors(result, {
             ...result,
             stream: wrappedIterable,
-        };
+        });
+    }
+    /**
+     * Re-apply getter-based accessor properties from a source StreamResult onto
+     * a wrapper copy. Wrapper spreads (`{ ...result }`) invoke and SNAPSHOT
+     * enumerable getters at wrap time — for background-loop streams (the native
+     * Anthropic path) that resolve finishReason / structuredOutput / toolCalls
+     * only as the consumer drains, the snapshot is permanently undefined/empty.
+     * Copying the accessor descriptors keeps the wrapped result live. Results
+     * built from plain data properties (the buffered Gemini paths) have no
+     * getters and pass through untouched.
+     */
+    preserveStreamResultAccessors(source, wrapped) {
+        for (const key of [
+            "finishReason",
+            "structuredOutput",
+            "toolCalls",
+            "toolsUsed",
+            "toolExecutions",
+        ]) {
+            const descriptor = Object.getOwnPropertyDescriptor(source, key);
+            if (descriptor?.get) {
+                Object.defineProperty(wrapped, key, descriptor);
+            }
+        }
+        return wrapped;
     }
     /**
      * Attach `gen_ai.usage.*` and `neurolink.cost` attributes to a span.
@@ -4389,17 +5032,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") ||