@juspay/neurolink 12.41.5 → 12.41.7

package/dist/providers/googleVertex/client.js

@@ -22,6 +22,7 @@ import { FileDetector } from "../../utils/fileDetector.js";
 import { mergeMediaFileAliases, normalizeVisionImageFormats, processUnifiedFilesArray, } from "../../utils/messageBuilder.js";
 import { logger } from "../../utils/logger.js";
 import { drainDetachedPump } from "../../utils/drainDetachedPump.js";
+import { releaseIterator } from "../../utils/streamCancellation.js";
 import { fireOnErrorOnce, getLifecycleMiddlewareConfig, isLifecycleStreamCallbacksOwnedByBaseProvider, } from "../../utils/lifecycleCallbacks.js";
 import { GEMINI_ELISION_NOTE, planGeminiLoopReclaim, previewGeminiToolResponseText, } from "../../context/geminiLoopGuard.js";
 import { ANTHROPIC_ELISION_NOTE, planAnthropicLoopReclaim, previewAnthropicToolResultText, } from "../../context/anthropicLoopGuard.js";
@@ -426,6 +427,120 @@ const createVertexAnthropicSettings = async (region, timeoutMs, direct, baseURL)
 const isAnthropicModel = (modelName) => {
     return modelName.toLowerCase().includes("claude");
 };
+/**
+ * Bridge a native Vertex stream loop's chunk iterable into a V3
+ * `ReadableStream`, so `wrapLanguageModel`'s `doStream` can drive it through
+ * the middleware chain. Lazy and pull-based — one native chunk in, one V3
+ * part out per `pull()` — because the native Anthropic loop
+ * (`executeNativeAnthropicStream`) is genuinely live: it returns its
+ * `StreamResult` while a background loop is still generating, with
+ * `usage`/`finishReason` as getters that settle only once the loop's
+ * channel closes. Eagerly draining the source here would silently turn that
+ * real-time stream into collect-then-replay. The Gemini3 loop's chunks are
+ * already fully resolved by the time this runs, so the same lazy pull is
+ * just as correct there — it has nothing left to wait on.
+ *
+ * Mirrors `chunksToV3Stream` in `openaiChatCompletionsBase.ts`, which is not
+ * exported, hence a local copy adapted to the native `{content, reasoning?}`
+ * chunk shape instead of `OpenAICompatStreamChunk`.
+ *
+ * `cancel()` releases the native iterator without awaiting it
+ * (`releaseIterator`), and the not-awaiting is what matters. The native
+ * `source` is `createStreamChannel`'s single-flight generator: `.return()`
+ * called while a `.next()` is in flight is queued behind it and only runs once
+ * that pending `.next()` settles (the next upstream frame, or the loop's own
+ * turn clock). A `ReadableStream` with the default `highWaterMark` calls
+ * `pull()` ahead of demand, so a `.next()` is routinely outstanding when the
+ * consumer breaks. Awaiting `iterator.return()` here would hold open
+ * `v3StreamToNativeChunks`'s `reader.cancel()`, and with it the `for await`
+ * exit inside `BaseProvider`'s lifecycle wrapper, whose `finally` is what runs
+ * `teardown()` — the abort of the call's own signal that actually releases the
+ * upstream connection. A held-open upstream would then keep the consumer's
+ * `break` parked until a frame or the turn clock arrived. Releasing without
+ * waiting lets `teardown()` run at once; the queued `.return()` then completes
+ * by itself once that abort settles the pending `.next()`.
+ */
+const nativeChunksToV3Stream = (source, completion) => {
+    const iterator = source[Symbol.asyncIterator]();
+    return new ReadableStream({
+        async pull(controller) {
+            try {
+                const next = await iterator.next();
+                if (next.done) {
+                    controller.enqueue(completion());
+                    controller.close();
+                    return;
+                }
+                const chunk = next.value;
+                if ("content" in chunk && typeof chunk.content === "string") {
+                    if ("reasoning" in chunk &&
+                        typeof chunk.reasoning === "string" &&
+                        chunk.reasoning.length > 0) {
+                        controller.enqueue({
+                            type: "reasoning-delta",
+                            delta: chunk.reasoning,
+                        });
+                    }
+                    if (chunk.content.length > 0) {
+                        controller.enqueue({ type: "text-delta", delta: chunk.content });
+                    }
+                }
+            }
+            catch (error) {
+                controller.error(error);
+            }
+        },
+        cancel() {
+            releaseIterator(iterator);
+        },
+    });
+};
+/**
+ * Drain a V3 `ReadableStream` (the middleware-wrapped native stream) back
+ * into the `{content, reasoning?}` chunk shape `StreamResult.stream`
+ * callers already iterate. `onFinish` captures the terminal `finish` part
+ * instead of yielding it — native chunk consumers have never seen a
+ * finish-shaped chunk and don't expect one.
+ *
+ * Mirrors `v3StreamToChunks` in `openaiChatCompletionsBase.ts` (also not
+ * exported).
+ */
+async function* v3StreamToNativeChunks(stream, onFinish) {
+    const reader = stream.getReader();
+    let done = false;
+    try {
+        while (true) {
+            const next = await reader.read();
+            if (next.done) {
+                done = true;
+                return;
+            }
+            const part = next.value;
+            if (part.type === "text-delta") {
+                yield { content: part.delta };
+            }
+            else if (part.type === "reasoning-delta") {
+                yield { content: "", reasoning: part.delta };
+            }
+            else if (part.type === "finish") {
+                onFinish(part);
+            }
+            else if (part.type === "error") {
+                throw part.error;
+            }
+        }
+    }
+    finally {
+        try {
+            if (!done) {
+                await reader.cancel();
+            }
+        }
+        finally {
+            reader.releaseLock();
+        }
+    }
+}
 /**
  * Google Vertex AI Provider v2 - BaseProvider Implementation
  *
@@ -934,7 +1049,7 @@ export class GoogleVertexProvider extends BaseProvider {
                         model: modelName,
                         totalToolCount: Object.keys(optionTools).length,
                     });
-                    result = await this.executeNativeAnthropicStream(mergedOptions);
+                    result = await this.runNativeStreamWithMiddleware(mergedOptions, modelName, (effectiveOptions) => this.executeNativeAnthropicStream(effectiveOptions));
                 }
                 else {
                     // ALL Gemini models use native @google/genai SDK
@@ -942,7 +1057,7 @@ export class GoogleVertexProvider extends BaseProvider {
                         model: modelName,
                         totalToolCount: Object.keys(optionTools).length,
                     });
-                    result = await this.executeNativeGemini3Stream(mergedOptions);
+                    result = await this.runNativeStreamWithMiddleware(mergedOptions, modelName, (effectiveOptions) => this.executeNativeGemini3Stream(effectiveOptions));
                 }
                 // Cost / token usage on the stream span. Native streams resolve
                 // usage synchronously (the stream loop has already drained), so
@@ -2012,6 +2127,44 @@ export class GoogleVertexProvider extends BaseProvider {
         }
         return result;
     }
+    /**
+     * Resolve the text a native Vertex *generate* call actually sends, for
+     * both `executeNativeGemini3Generate` and `executeNativeAnthropicGenerate`.
+     *
+     * The baseline here is the same `input.text || prompt || "Please
+     * respond."` chain both call sites have always used — `input.text` wins
+     * when set because the file preprocessors (`processUnifiedFilesArray`,
+     * `processCSVFilesForNativeSDK`) append attached-file content to it while
+     * `options.prompt` stays the pre-attachment snapshot; `prompt` is the
+     * fallback for the legacy prompt-only `generateText()` convention, which
+     * never sets `input` at all; the literal is the last resort when neither
+     * is set.
+     *
+     * That `||` chain alone has a gap model middleware falls into:
+     * `applyTurnParamsRewrite` writes every rewritten turn back onto
+     * `options.input.text`, including an *emptied* one (a redaction). `||`
+     * treats that empty string exactly like an unset `input.text` and falls
+     * through to `options.prompt` — which middleware never touched, since it
+     * is a plain snapshot taken before middleware ran — so a redaction a
+     * middleware applied is silently discarded and the ORIGINAL text still
+     * reaches Vertex.
+     *
+     * The fix is narrow: when `input.text` is *set* (not undefined) and
+     * differs from `prompt`, something deliberately changed it since the
+     * snapshot was taken — a middleware rewrite, or a file preprocessor's
+     * attachment-content append — and that divergence itself is the signal to
+     * trust `input.text` outright, empty string included. When the two agree
+     * (the untouched, no-middleware case, including the STT-silence
+     * `input.text === prompt === ""` placeholder) there is no divergence to
+     * trust, so the original fallback chain still applies unchanged.
+     */
+    resolveNativeGenerateText(options) {
+        if (options.input?.text !== undefined &&
+            options.input.text !== options.prompt) {
+            return options.input.text;
+        }
+        return options.input?.text || options.prompt || "Please respond.";
+    }
     /**
      * Execute generate using native @google/genai SDK for Gemini 3 models on Vertex AI
      * This bypasses @ai-sdk/google-vertex to properly handle thought_signature
@@ -2027,7 +2180,8 @@ export class GoogleVertexProvider extends BaseProvider {
         });
         // Build contents from input with multimodal support
         // Prioritize input.text over prompt since processCSVFilesForNativeSDK modifies input.text with CSV data
-        const inputText = options.input?.text || options.prompt || "Please respond.";
+        // (see resolveNativeGenerateText for the full precedence + middleware-redaction rationale)
+        const inputText = this.resolveNativeGenerateText(options);
         const contents = [];
         // Build user message parts - start with text
         const userParts = [{ text: inputText }];
@@ -4310,8 +4464,9 @@ export class GoogleVertexProvider extends BaseProvider {
         // attached file was silently dropped on the Claude generate path — the
         // model answered "no file attached" to a request that carried one. The
         // native Gemini path already reads input.text first for exactly this
-        // reason.
-        const inputText = options.input?.text || options.prompt || "Please respond.";
+        // reason. (See resolveNativeGenerateText for the full precedence +
+        // middleware-redaction rationale.)
+        const inputText = this.resolveNativeGenerateText(options);
         // Replay conversationMessages (with tool turns), else the legacy text-only conversationHistory.
         if (options.conversationMessages &&
             options.conversationMessages.length > 0) {
@@ -5513,57 +5668,14 @@ export class GoogleVertexProvider extends BaseProvider {
                             model: modelName,
                             totalToolCount: Object.keys(mergedOptions.tools).length,
                         });
-                        nativeResult =
-                            await this.executeNativeAnthropicGenerate(mergedOptions);
+                        nativeResult = await this.runNativeGenerateWithMiddleware(mergedOptions, modelName, (effectiveOptions) => this.executeNativeAnthropicGenerate(effectiveOptions));
                     }
                     else {
                         logger.info("[GoogleVertex] Routing Gemini generate to native @google/genai", {
                             model: modelName,
                             totalToolCount: Object.keys(mergedOptions.tools).length,
                         });
-                        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;
-                            }
-                        }
+                        nativeResult = await this.runNativeGenerateWithMiddleware(mergedOptions, modelName, (effectiveOptions) => this.executeNativeGemini3GenerateWithSchemaFallback(effectiveOptions, modelName));
                     }
                     executionSpan.setAttribute(LANGFUSE_ATTR.OBSERVATION_OUTPUT, spanJsonAttribute(nativeResult?.content ?? ""));
                     return nativeResult;
@@ -5731,15 +5843,484 @@ export class GoogleVertexProvider extends BaseProvider {
             stream: wrappedIterable,
         });
     }
+    /**
+     * The text a native Vertex turn is built from before any model middleware
+     * rewrite — `options.input.text` when the caller set it (the normal
+     * `generate()`/`stream()` convention), else `options.prompt` (the legacy
+     * prompt-only `generateText()` convention, where `input` is never
+     * populated — see `generateTextInInstanceScope` in `src/lib/neurolink.ts`,
+     * which validates `options.prompt` and never touches `options.input`).
+     *
+     * `buildTurnPromptForMiddleware` and `applyTurnParamsRewrite` both read
+     * this so they agree on one baseline: the first so a prompt-only caller
+     * shows middleware its real text instead of an empty turn, the second so
+     * a middleware-rewritten turn is compared against what middleware actually
+     * started from — not a baseline that ignores `prompt` entirely, which
+     * would make a prompt-only call look "unedited" no matter what middleware
+     * did to it. `StreamOptions` carries no top-level `prompt` field, hence
+     * the `"prompt" in options` guard instead of a cast.
+     */
+    vertexTurnBaselineText(options) {
+        if (options.input?.text !== undefined) {
+            return options.input.text;
+        }
+        return "prompt" in options && typeof options.prompt === "string"
+            ? options.prompt
+            : "";
+    }
+    /**
+     * Build the V3 entry-turn prompt middleware sees for a native call.
+     * Native Vertex loops build their own multi-turn conversation internally
+     * once they run — this is only the caller's system prompt + text input,
+     * the one turn middleware is given visibility into before that loop
+     * starts.
+     *
+     * The user turn is an array of text parts rather than a bare string. That
+     * is the V3 prompt shape, and prompt-editing middleware is written against
+     * it: one that spreads `content` into a longer array turns a string into
+     * one element per character, and one that calls `.map` / `.filter` on it
+     * throws. The AI Studio path already hands its middleware parts
+     * (`geminiContentsToV3Prompt`); this makes Vertex agree with it.
+     *
+     * The text itself comes from `vertexTurnBaselineText`, not
+     * `options.input?.text` alone — a prompt-only `generateText()` caller
+     * never sets `input`, and without the `options.prompt` fallback middleware
+     * would be shown an empty turn and have nothing of the caller's to inspect
+     * or build on.
+     */
+    buildTurnPromptForMiddleware(options) {
+        const prompt = [];
+        if (options.systemPrompt) {
+            prompt.push({ role: "system", content: options.systemPrompt });
+        }
+        prompt.push({
+            role: "user",
+            content: [{ type: "text", text: this.vertexTurnBaselineText(options) }],
+        });
+        return prompt;
+    }
+    /** Sampling params a native call already honors, carried onto the V3 view. */
+    buildTurnV3Params(options, prompt) {
+        return {
+            prompt,
+            ...(options.maxTokens !== undefined
+                ? { maxOutputTokens: options.maxTokens }
+                : {}),
+            ...(options.temperature !== undefined
+                ? { temperature: options.temperature }
+                : {}),
+            ...(options.topP !== undefined ? { topP: options.topP } : {}),
+            ...(options.abortSignal !== undefined
+                ? { abortSignal: options.abortSignal }
+                : {}),
+        };
+    }
+    /**
+     * Read a middleware-transformed prompt back into the two things a native
+     * Vertex turn can carry: one system instruction and one user text.
+     *
+     * Every system message counts (joined with a blank line, the way
+     * `v3PromptToGeminiContents` joins them for AI Studio) and so does every
+     * user message, not just the last. A middleware that appends or prepends
+     * context leaves the caller's own text in the prompt beside it; reading
+     * only the last user message would send the addition without the question
+     * it was meant to qualify, or drop it and send the question bare. Text
+     * blocks — across messages and across the parts of one message — are joined
+     * with a blank line for the same reason: they are separate blocks, and
+     * gluing them runs the last word of one into the first of the next.
+     *
+     * `unmapped` counts what a native turn has no place for — non-text user
+     * parts (files, images) and assistant or tool messages — so the caller can
+     * say it was dropped rather than drop it silently.
+     */
+    readTurnFromPrompt(prompt) {
+        const systemTexts = prompt.flatMap((message) => message.role === "system" ? [message.content] : []);
+        const userContents = prompt.flatMap((message) => message.role === "user" ? [message.content] : []);
+        const userTexts = userContents
+            .flatMap((content) => typeof content === "string"
+            ? [content]
+            : content.flatMap((part) => part.type === "text" ? [part.text] : []))
+            .filter((text) => text.length > 0);
+        const unmappedParts = userContents.reduce((count, content) => typeof content === "string"
+            ? count
+            : count + content.filter((part) => part.type !== "text").length, 0);
+        const unmappedMessages = prompt.filter((message) => message.role !== "system" && message.role !== "user").length;
+        return {
+            systemPrompt: systemTexts.length > 0 ? systemTexts.join("\n\n") : undefined,
+            text: userTexts.join("\n\n"),
+            unmapped: unmappedParts + unmappedMessages,
+        };
+    }
+    /**
+     * Apply a middleware-transformed turn back onto the native call options.
+     *
+     * The system instruction and the user text are each written back only when
+     * they differ from what middleware actually started from — `systemPrompt`
+     * against `options.systemPrompt`, user text against
+     * `vertexTurnBaselineText(options)`, not `options.input?.text` alone — so a
+     * middleware that touches neither leaves both exactly as they were. An
+     * edit is honoured in every direction — a changed, added or removed system
+     * message, an appended or prepended user message, a user message emptied
+     * outright (a redaction) — because every native generate/stream executor
+     * resolves its wire text through `options.input.text` once this write-back
+     * has run (`resolveNativeGenerateText` on the generate paths, which
+     * special-cases exactly this divergence so an emptied `input.text` is not
+     * mistaken for an unset one and does not fall back to the stale
+     * `options.prompt` snapshot; a direct `options.input.text` read on the
+     * stream paths, which have no such fallback to fall into). Comparing
+     * against `options.input?.text` alone — ignoring `options.prompt` — would
+     * make a prompt-only `generateText()` caller's untouched turn look
+     * "changed" the first time middleware ran (nothing to compare `turn.text`
+     * against but `""`), writing the real prompt into `input.text` as a
+     * spurious edit on every such call even when no middleware did anything.
+     *
+     * Sampling params are written back the same way and can be removed as well
+     * as changed: a middleware that drops `temperature` or `topP` from the
+     * params must reach the wire as "not sent", not as the caller's original
+     * value kept because the key went missing.
+     *
+     * `tools` is offered to middleware read-only — a middleware that rewrites
+     * it gets a WARN rather than a silent drop, matching the OpenAI-compatible
+     * streaming path's contract: native tool wiring is derived independently
+     * of this V3 view, and re-deriving it here would diverge from it.
+     */
+    applyTurnParamsRewrite(options, params) {
+        if (params.tools !== undefined) {
+            logger.warn("[GoogleVertex] middleware rewrote 'tools' on the native path; tool rewrites are not applied to the native request — the original tool list was sent.");
+        }
+        const turn = this.readTurnFromPrompt(params.prompt);
+        if (turn.unmapped > 0) {
+            logger.warn(`[GoogleVertex] middleware added ${turn.unmapped} prompt item(s) the native request cannot carry (non-text user parts, assistant or tool messages); only system and user text edits are applied — those items were not sent.`);
+        }
+        const maxTokens = typeof params.maxOutputTokens === "number"
+            ? params.maxOutputTokens
+            : undefined;
+        const temperature = typeof params.temperature === "number" ? params.temperature : undefined;
+        const topP = typeof params.topP === "number" ? params.topP : undefined;
+        return {
+            ...options,
+            ...(turn.systemPrompt !== (options.systemPrompt || undefined)
+                ? { systemPrompt: turn.systemPrompt }
+                : {}),
+            ...(turn.text !== this.vertexTurnBaselineText(options)
+                ? { input: { ...(options.input ?? {}), text: turn.text } }
+                : {}),
+            ...(maxTokens !== options.maxTokens ? { maxTokens } : {}),
+            ...(temperature !== options.temperature ? { temperature } : {}),
+            ...(topP !== options.topP ? { topP } : {}),
+        };
+    }
+    /**
+     * Strip the lifecycle middleware from the options handed to
+     * `applyMiddlewareToModel` for a native Vertex call, when something else is
+     * already firing the same callbacks.
+     *
+     * NeuroLink's `applyGenerateLifecycleMiddleware` /
+     * `applyStreamLifecycleMiddleware` (neurolink.ts) mirror a caller's
+     * top-level `onFinish` / `onError` / `onChunk` into
+     * `options.middleware.middlewareConfig.lifecycle.config` — the exact same
+     * callback references — before this provider sees `options`. Left enabled,
+     * the built-in lifecycle middleware would fire them again from inside the
+     * bridge, and with malformed payloads: it reads the legacy `textDelta` chunk
+     * field and a bare `finishReason`, neither of which a V3 model produces.
+     *
+     * Who else fires them differs by path, so the exclusion does too:
+     *
+     * - generate: only `fireGenerateOnFinish` / `fireGenerateOnError`, which read
+     *   the TOP-LEVEL callbacks. The entry is stripped only when one is present.
+     *   A caller who configures `middlewareConfig.lifecycle` directly has no
+     *   other firer here, so that middleware applies exactly once, unmodified.
+     * - stream: `BaseProvider.stream()` wraps every stream in
+     *   `wrapStreamWithLifecycleCallbacks`, which fires whatever sits in
+     *   `lifecycle.config` however it got there — top-level shorthand or direct
+     *   config. The entry is stripped whenever it exists, or a direct-config
+     *   caller would get every callback twice (and `onChunk` a third time, for
+     *   the `finish` part the middleware also reports).
+     *
+     * Only the `lifecycle` entry is disabled, so every other configured
+     * middleware (guardrails, transformParams, custom hooks, analytics, ...)
+     * applies normally.
+     */
+    excludeAutoLifecycleMiddleware(options, path) {
+        const opts = options;
+        const firedElsewhere = path === "stream" || !!(opts.onFinish || opts.onError || opts.onChunk);
+        if (!firedElsewhere) {
+            return options;
+        }
+        const lifecycle = opts.middleware?.middlewareConfig?.lifecycle;
+        if (!lifecycle) {
+            return options;
+        }
+        return {
+            ...options,
+            middleware: {
+                ...opts.middleware,
+                middlewareConfig: {
+                    ...opts.middleware?.middlewareConfig,
+                    lifecycle: { ...lifecycle, enabled: false },
+                },
+            },
+        };
+    }
+    /**
+     * Run the native Gemini generate loop and, when Vertex rejects an
+     * over-constrained `responseSchema`, retry once without it.
+     *
+     * The retry sits inside the function `runNativeGenerateWithMiddleware` hands
+     * to the model bridge rather than around the bridge, because it is
+     * provider-internal recovery: model middleware must see one `doGenerate`
+     * that succeeds. Retrying outside would show every middleware the failed
+     * first call — the lifecycle middleware would report an `onError` for a
+     * request that then succeeded, and `transformParams` would run twice.
+     */
+    async executeNativeGemini3GenerateWithSchemaFallback(options, modelName) {
+        try {
+            return await this.executeNativeGemini3Generate(options);
+        }
+        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 = options.schema !== undefined || options.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 = !options.disableTools && Object.keys(options.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),
+                });
+                return await this.executeNativeGemini3Generate({
+                    ...options,
+                    schema: undefined,
+                    output: { format: "json" },
+                });
+            }
+            throw nativeError;
+        }
+    }
+    /**
+     * Apply the configured middleware chain around a native Vertex generate
+     * loop. `callNative` is `executeNativeAnthropicGenerate` or
+     * `executeNativeGemini3Generate` — a self-contained black box that runs
+     * its own multi-step tool loop and returns a fully-resolved
+     * `EnhancedGenerateResult`. Wrapping happens around that call, not inside
+     * it: `transformParams` can rewrite the entry turn before the loop starts,
+     * and `wrapGenerate` can observe the result or replace it outright (a
+     * guardrail that blocks the call entirely never reaches `callNative`, so
+     * `nativeResult` stays unset and a settled result is synthesized purely
+     * from what middleware produced, then run through `enhanceResult` like any
+     * other result so `enableAnalytics` / `enableEvaluation` still apply).
+     */
+    async runNativeGenerateWithMiddleware(options, modelName, callNative) {
+        const startedAt = Date.now();
+        const originalPrompt = this.buildTurnPromptForMiddleware(options);
+        const providerName = this.providerName;
+        let nativeResult;
+        const baseModel = {
+            specificationVersion: "v3",
+            provider: providerName,
+            modelId: modelName,
+            supportedUrls: {},
+            doGenerate: async (params) => {
+                const effectiveOptions = this.applyTurnParamsRewrite(options, params);
+                const result = await callNative(effectiveOptions);
+                nativeResult = result;
+                return {
+                    content: [{ type: "text", text: result.content }],
+                    finishReason: { unified: result.finishReason ?? "stop" },
+                    usage: {
+                        inputTokens: { total: result.usage?.input ?? 0 },
+                        outputTokens: { total: result.usage?.output ?? 0 },
+                    },
+                };
+            },
+            doStream: () => {
+                throw new Error("[GoogleVertex] doStream is not implemented on the native generate middleware model — this path only drives doGenerate.");
+            },
+        };
+        const modelResult = await this.applyMiddlewareToModel(baseModel, this.excludeAutoLifecycleMiddleware(options, "generate"));
+        if (typeof modelResult === "string") {
+            throw new Error("[GoogleVertex] Native generate model handle required for middleware");
+        }
+        const wrappedModel = modelResult;
+        const v3Params = this.buildTurnV3Params(options, originalPrompt);
+        const v3Result = await wrappedModel.doGenerate(v3Params);
+        const v3Text = v3Result.content
+            .map((part) => (part.type === "text" ? part.text : ""))
+            .join("");
+        if (nativeResult) {
+            // Reference/value equality against what the native call itself
+            // returned is the "nothing changed" signal — return the native result
+            // untouched (structuredData, toolCalls, analytics and all) rather than
+            // a reconstruction that would drop fields this function doesn't know
+            // about. Only a middleware that actually rewrote the text pays for a
+            // merged object.
+            return v3Text === nativeResult.content
+                ? nativeResult
+                : { ...nativeResult, content: v3Text };
+        }
+        // Guardrails (or any middleware) blocked the call before `doGenerate`
+        // ran — synthesize a settled result purely from the V3 response
+        // middleware produced, the same "no native call, no content" contract
+        // the OpenAI-compatible path's blocking case already proves out. The
+        // turn bookkeeping a real loop would have filled in takes short-circuit
+        // defaults, and `enhanceResult` runs on it as on every unblocked result:
+        // without it a blocked call silently loses `analytics` / `evaluation`
+        // that the same call would have carried had the guardrail let it through.
+        return this.enhanceResult({
+            content: v3Text,
+            provider: providerName,
+            model: modelName,
+            finishReason: v3Result.finishReason.unified,
+            usage: {
+                input: v3Result.usage.inputTokens.total ?? 0,
+                output: v3Result.usage.outputTokens.total ?? 0,
+                total: (v3Result.usage.inputTokens.total ?? 0) +
+                    (v3Result.usage.outputTokens.total ?? 0),
+            },
+            toolCalls: [],
+            stopReason: resolveTurnStopReason({
+                timedOut: false,
+                stalled: false,
+                wasAborted: false,
+                cappedWithoutAnswer: false,
+                finishReason: v3Result.finishReason.unified,
+            }),
+            stepsUsed: 0,
+            responseTime: Date.now() - startedAt,
+            toolsUsed: [],
+            toolExecutions: [],
+            enhancedWithTools: false,
+        }, options, startedAt);
+    }
+    /**
+     * Apply the configured middleware chain around a native Vertex stream
+     * loop. `callNative` is `executeNativeAnthropicStream` or
+     * `executeNativeGemini3Stream`. Both are bridged through the same lazy V3
+     * `ReadableStream` (`nativeChunksToV3Stream` / `v3StreamToNativeChunks`)
+     * regardless of whether the underlying loop is genuinely live (Anthropic)
+     * or already fully resolved (Gemini3) by the time it returns — pulling one
+     * item at a time is correct for both, and never turns a live stream into
+     * collect-then-replay.
+     *
+     * A guardrail that blocks the call never invokes `doStream`, so
+     * `nativeResult` stays unset; a `StreamResult` is synthesized instead,
+     * with `usage` / `finishReason` resolving once the merged stream is fully
+     * drained (the same late-resolving-getter contract
+     * `preserveStreamResultAccessors` already exists for).
+     */
+    async runNativeStreamWithMiddleware(options, modelName, callNative) {
+        const originalPrompt = this.buildTurnPromptForMiddleware(options);
+        const providerName = this.providerName;
+        let nativeResult;
+        const baseModel = {
+            specificationVersion: "v3",
+            provider: providerName,
+            modelId: modelName,
+            supportedUrls: {},
+            doGenerate: () => {
+                throw new Error("[GoogleVertex] doGenerate is not implemented on the native stream middleware model — this path only drives doStream.");
+            },
+            doStream: async (params) => {
+                const effectiveOptions = this.applyTurnParamsRewrite(options, params);
+                const result = await callNative(effectiveOptions);
+                nativeResult = result;
+                return {
+                    stream: nativeChunksToV3Stream(result.stream, () => ({
+                        type: "finish",
+                        finishReason: { unified: result.finishReason ?? "stop" },
+                        usage: {
+                            inputTokens: { total: result.usage?.input ?? 0 },
+                            outputTokens: { total: result.usage?.output ?? 0 },
+                        },
+                    })),
+                };
+            },
+        };
+        const modelResult = await this.applyMiddlewareToModel(baseModel, this.excludeAutoLifecycleMiddleware(options, "stream"));
+        if (typeof modelResult === "string") {
+            throw new Error("[GoogleVertex] Native stream model handle required for middleware");
+        }
+        const wrappedModel = modelResult;
+        const v3Params = this.buildTurnV3Params(options, originalPrompt);
+        const { stream } = await wrappedModel.doStream(v3Params);
+        let finishPart;
+        const mergedStream = v3StreamToNativeChunks(stream, (part) => {
+            finishPart = part;
+        });
+        if (nativeResult) {
+            const settled = nativeResult;
+            return this.preserveStreamResultAccessors(settled, {
+                ...settled,
+                stream: mergedStream,
+            });
+        }
+        // Guardrails (or any middleware) blocked the call before `doStream`
+        // ran — synthesize a settled StreamResult purely from the V3 stream
+        // middleware produced. `usage` / `finishReason` are getters so a
+        // consumer who reads them before draining `stream` doesn't just see a
+        // permanent snapshot of "nothing yet" — same contract the native
+        // Anthropic path's own getters already rely on.
+        const blockedResult = {
+            stream: mergedStream,
+            provider: providerName,
+            model: modelName,
+        };
+        Object.defineProperty(blockedResult, "usage", {
+            enumerable: true,
+            configurable: true,
+            get: () => finishPart
+                ? {
+                    input: finishPart.usage.inputTokens.total ?? 0,
+                    output: finishPart.usage.outputTokens.total ?? 0,
+                    total: (finishPart.usage.inputTokens.total ?? 0) +
+                        (finishPart.usage.outputTokens.total ?? 0),
+                }
+                : undefined,
+        });
+        Object.defineProperty(blockedResult, "finishReason", {
+            enumerable: true,
+            configurable: true,
+            get: () => finishPart?.finishReason.unified,
+        });
+        return blockedResult;
+    }
     /**
      * 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.
+     * / usage 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, and the native Anthropic stream's own `usage` — a mutable
+     * object reference rather than a getter, so a spread keeps its identity
+     * and later mutations stay visible) have no matching getter here and pass
+     * through untouched.
+     *
+     * The re-applied property also accepts a direct write: NeuroLink.stream()
+     * backstops a missing `usage` from analytics once the outer stream drains
+     * by assigning `mcpStreamOutcome.usage = resolvedUsage` on whatever result
+     * object it was handed. Copying the bare getter-only descriptor verbatim
+     * would turn that assignment into a TypeError ("Cannot set property usage
+     * of #<Object> which has only a getter"), so each re-applied accessor is
+     * rebuilt with a setter that remembers an override and prefers it over the
+     * live source getter once one has been written.
      */
     preserveStreamResultAccessors(source, wrapped) {
         for (const key of [
@@ -5748,11 +6329,24 @@ export class GoogleVertexProvider extends BaseProvider {
             "toolCalls",
             "toolsUsed",
             "toolExecutions",
+            "usage",
         ]) {
             const descriptor = Object.getOwnPropertyDescriptor(source, key);
-            if (descriptor?.get) {
-                Object.defineProperty(wrapped, key, descriptor);
+            const liveGetter = descriptor?.get;
+            if (!liveGetter) {
+                continue;
             }
+            let overridden = false;
+            let overrideValue;
+            Object.defineProperty(wrapped, key, {
+                configurable: true,
+                enumerable: descriptor.enumerable ?? true,
+                get: () => (overridden ? overrideValue : liveGetter.call(source)),
+                set: (value) => {
+                    overridden = true;
+                    overrideValue = value;
+                },
+            });
         }
         return wrapped;
     }