@juspay/neurolink 12.59.0 → 13.0.1

package/dist/providers/googleVertex/client.js

@@ -1,6 +1,7 @@
 /* eslint-disable max-lines-per-function */
 // Native SDK imports - no more @ai-sdk/google-vertex dependency
 import fs from "fs";
+import { LangfuseOtelSpanAttributes } from "@langfuse/tracing";
 import { guardToolExecutor } from "../../core/toolExecutionGuards.js";
 import path from "path";
 import { ErrorCategory, ErrorSeverity, } from "../../constants/enums.js";
@@ -35,17 +36,17 @@ import { createNativeThinkingConfig } from "../../utils/thinkingConfig.js";
 import { TimeoutError, withTimeout } from "../../utils/async/index.js";
 import { parseTimeout } from "../../utils/timeout.js";
 import { appendStepText, buildContextCapMessage, buildDedupedEngineTools, buildLoopExitMessage, buildToolLoopCapMessage, buildWrapupNudgeText, createContextGuard, createTurnClock, extractThoughtSignature, isAbortError, mapGeminiFinishReason, prependConversationMessages, resolveTurnStopReason, DedupExecuteMap, } from "../googleNativeGemini3/index.js";
-import { createGeminiLoopAdapter } from "../../core/geminiLoopAdapter.js";
+import { createGeminiLoopAdapter, describeGeminiRequest, } from "../../core/geminiLoopAdapter.js";
 import { runAgenticLoop } from "../../core/loopEngine.js";
 import { createAnthropicLoopAdapter } from "../anthropic/loopAdapter.js";
-import { extractMcpToolErrorMessage } from "../../utils/mcpErrorText.js";
 import { createStreamChannel } from "../../core/streamChannel.js";
 import { toNativeToolDeclarations } from "../../core/nativeToolFormat.js";
 import { getAvailableInputTokens, getContextWindowSize, } from "../../constants/contextWindows.js";
 import { resolveLiveTool } from "../../tools/toolDiscovery.js";
-import { ATTR, LANGFUSE_ATTR, spanContentAttribute, spanJsonAttribute, spanModelRequestAttribute, tracers, withClientSpan, withClientStreamSpan, withSpan, } from "../../telemetry/index.js";
-import { SpanKind, SpanStatusCode, context as otelContext, trace as otelTrace, } from "@opentelemetry/api";
-import { calculateCost } from "../../utils/pricing.js";
+import { ATTR, spanContentAttribute, spanModelRequestAttribute, tracers, withClientSpan, withClientStreamSpan, withSpan, } from "../../telemetry/index.js";
+import { observe, observeGeneration, observeTrace, } from "../../telemetry/observation.js";
+import { withGeneration, withStepSpan } from "../../telemetry/withSpan.js";
+import { context as otelContext, SpanKind, SpanStatusCode, trace as otelTrace, } from "@opentelemetry/api";
 import { transformToolExecutions } from "../../utils/transformationUtils.js";
 import { resolveToolExecutionRecords } from "../../core/toolExecutionRecorder.js";
 import { modelSupportsForcedToolChoice, resolveSamplingParams, } from "../../models/modelRegistry.js";
@@ -1000,15 +1001,14 @@ export class GoogleVertexProvider extends BaseProvider {
         // it sees for AI Studio. BaseProvider.stream does NOT emit this span
         // for any provider — each native provider has to add it itself.
         return withClientStreamSpan({
-            name: "neurolink.provider.stream",
+            name: "provider.stream",
             tracer: tracers.provider,
+            detached: true,
             attributes: {
-                [ATTR.GEN_AI_SYSTEM]: this.providerName,
-                [ATTR.GEN_AI_MODEL]: modelName,
-                [ATTR.GEN_AI_OPERATION]: "stream",
+                [ATTR.NL_MODEL]: modelName,
                 [ATTR.NL_PROVIDER]: this.providerName,
             },
-        }, async (streamSpan) => {
+        }, async () => {
             const streamStartTime = Date.now();
             // Tool filter (a0269210): trust options.tools — caller (BaseProvider.stream)
             // already merged MCP/built-in tools and applied any enabledToolNames filter.
@@ -1021,7 +1021,7 @@ export class GoogleVertexProvider extends BaseProvider {
             // Pipeline A. Without this, test:tracing's "Message Build Span"
             // assertion has to skip on every native-Vertex stream.
             const processedOptions = await withSpan({
-                name: "neurolink.message.build",
+                name: "message.build",
                 tracer: tracers.provider,
                 attributes: {
                     [ATTR.NL_PROVIDER]: this.providerName,
@@ -1059,10 +1059,6 @@ export class GoogleVertexProvider extends BaseProvider {
                     });
                     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
-                // `result.usage` is populated by the time we reach this point.
-                this.attachUsageAndCostAttributes(streamSpan, modelName, result?.usage);
                 // Wrap the result's async iterable to fire onChunk / onFinish
                 // lifecycle callbacks. Pipeline A gets these via the AI SDK
                 // wrapStream middleware; the native path has to fire them here.
@@ -1695,6 +1691,7 @@ export class GoogleVertexProvider extends BaseProvider {
             // nudge, and the terminal block below.
             const engineAdapter = createGeminiLoopAdapter({
                 providerLabel: "GoogleVertex",
+                provider: this.providerName,
                 maxSteps,
                 // Ported verbatim: the same DEFAULT_TOOL_MAX_RETRIES threshold, plus
                 // the two rules this loop has always had and the engine did not.
@@ -2473,7 +2470,7 @@ export class GoogleVertexProvider extends BaseProvider {
         // Cross-step text accumulation + last SDK finish reason, so the
         // maxSteps-exhaustion exit can surface real gathered text (Bug 1) and a
         // meaningful finishReason (Bug 2) instead of a placeholder / "unknown".
-        let accumulatedText = "";
+        const accumulatedText = "";
         let lastFinishReason;
         const allToolCalls = [];
         const toolExecutions = [];
@@ -2540,6 +2537,7 @@ export class GoogleVertexProvider extends BaseProvider {
             // nudge, and the terminal block below.
             const engineAdapter = createGeminiLoopAdapter({
                 providerLabel: "GoogleVertex",
+                provider: this.providerName,
                 maxSteps,
                 // Ported verbatim: the same DEFAULT_TOOL_MAX_RETRIES threshold, plus
                 // the two rules this loop has always had and the engine did not.
@@ -2992,57 +2990,76 @@ export class GoogleVertexProvider extends BaseProvider {
             // Vertex endpoint would hang the maxSteps recovery path indefinitely.
             // On timeout withTimeout rejects (TimeoutError) and the catch below
             // falls back to the placeholder — no new failure path is introduced.
-            return await withTimeout((async () => {
-                const stream = await client.models.generateContentStream({
-                    model: modelName,
-                    contents,
-                    config: synthConfig,
-                });
-                const parts = [];
-                let finishReason;
-                let inputTokens = 0;
-                let outputTokens = 0;
-                let reasoningTokens = 0;
-                for await (const chunk of stream) {
-                    const chunkRecord = chunk;
-                    const candidates = chunkRecord.candidates;
-                    const firstCandidate = candidates?.[0];
-                    const chunkFinishReason = firstCandidate?.finishReason;
-                    if (typeof chunkFinishReason === "string" && chunkFinishReason) {
-                        finishReason = chunkFinishReason;
-                    }
-                    const chunkContent = firstCandidate?.content;
-                    if (chunkContent && Array.isArray(chunkContent.parts)) {
-                        parts.push(...chunkContent.parts);
-                    }
-                    const usageMetadata = chunkRecord.usageMetadata;
-                    if (usageMetadata) {
-                        if (usageMetadata.promptTokenCount !== undefined &&
-                            usageMetadata.promptTokenCount > 0) {
-                            inputTokens = usageMetadata.promptTokenCount;
+            return await withGeneration(describeGeminiRequest(this.providerName, {
+                model: modelName,
+                contents,
+                config,
+            }), async (span) => {
+                const synth = await withTimeout((async () => {
+                    const stream = await client.models.generateContentStream({
+                        model: modelName,
+                        contents,
+                        config: synthConfig,
+                    });
+                    const parts = [];
+                    let finishReason;
+                    let inputTokens = 0;
+                    let outputTokens = 0;
+                    let reasoningTokens = 0;
+                    for await (const chunk of stream) {
+                        const chunkRecord = chunk;
+                        const candidates = chunkRecord.candidates;
+                        const firstCandidate = candidates?.[0];
+                        const chunkFinishReason = firstCandidate?.finishReason;
+                        if (typeof chunkFinishReason === "string" &&
+                            chunkFinishReason) {
+                            finishReason = chunkFinishReason;
                         }
-                        if (usageMetadata.candidatesTokenCount !== undefined &&
-                            usageMetadata.candidatesTokenCount > 0) {
-                            outputTokens = usageMetadata.candidatesTokenCount;
+                        const chunkContent = firstCandidate?.content;
+                        if (chunkContent && Array.isArray(chunkContent.parts)) {
+                            parts.push(...chunkContent.parts);
                         }
-                        if (usageMetadata.thoughtsTokenCount !== undefined &&
-                            usageMetadata.thoughtsTokenCount > 0) {
-                            reasoningTokens = usageMetadata.thoughtsTokenCount;
+                        const usageMetadata = chunkRecord.usageMetadata;
+                        if (usageMetadata) {
+                            if (usageMetadata.promptTokenCount !== undefined &&
+                                usageMetadata.promptTokenCount > 0) {
+                                inputTokens = usageMetadata.promptTokenCount;
+                            }
+                            if (usageMetadata.candidatesTokenCount !== undefined &&
+                                usageMetadata.candidatesTokenCount > 0) {
+                                outputTokens = usageMetadata.candidatesTokenCount;
+                            }
+                            if (usageMetadata.thoughtsTokenCount !== undefined &&
+                                usageMetadata.thoughtsTokenCount > 0) {
+                                reasoningTokens = usageMetadata.thoughtsTokenCount;
+                            }
                         }
                     }
-                }
-                const text = parts
-                    .filter((part) => typeof part.text === "string")
-                    .map((part) => part.text)
-                    .join("");
-                return {
-                    text,
-                    finishReason,
-                    inputTokens,
-                    outputTokens,
-                    reasoningTokens,
-                };
-            })(), timeoutMs, "Gemini synthesis call timed out");
+                    const text = parts
+                        .filter((part) => typeof part.text === "string")
+                        .map((part) => part.text)
+                        .join("");
+                    return {
+                        text,
+                        finishReason,
+                        inputTokens,
+                        outputTokens,
+                        reasoningTokens,
+                    };
+                })(), timeoutMs, "Gemini synthesis call timed out");
+                observeGeneration(span, {
+                    provider: this.providerName,
+                    model: modelName,
+                    output: synth.text,
+                    usage: {
+                        inputTokens: synth.inputTokens,
+                        outputTokens: synth.outputTokens,
+                        reasoningTokens: synth.reasoningTokens,
+                    },
+                    finishReason: synth.finishReason,
+                });
+                return synth;
+            });
         }
         catch (error) {
             logger.warn("[GoogleVertex] Tools-disabled synthesis call failed; falling back to placeholder", { error: error instanceof Error ? error.message : String(error) });
@@ -3466,24 +3483,18 @@ export class GoogleVertexProvider extends BaseProvider {
         const turnSpan = tracers.provider.startSpan("anthropic.vertex.stream", {
             kind: SpanKind.CLIENT,
             attributes: {
-                // Mark as span, not generation — without it Langfuse infers "generation"
-                // from the gen_ai.* attributes; the model calls live in child spans.
-                [LANGFUSE_ATTR.OBSERVATION_TYPE]: "span",
-                [ATTR.GEN_AI_SYSTEM]: "anthropic",
-                [ATTR.GEN_AI_MODEL]: modelName,
-                [ATTR.GEN_AI_OPERATION]: "stream",
+                [ATTR.NL_MODEL]: modelName,
                 [ATTR.NL_PROVIDER]: this.providerName,
                 [ATTR.NL_TOOL_COUNT]: offeredToolNames.length,
-                [LANGFUSE_ATTR.OBSERVATION_INPUT]: turnInputAttribute,
-                // Also lift IO to the trace — Langfuse reads trace input/output from
-                // langfuse.trace.* and the trace list is unreadable without it.
-                [LANGFUSE_ATTR.TRACE_INPUT]: turnInputAttribute,
-                [LANGFUSE_ATTR.OBSERVATION_METADATA]: spanJsonAttribute({
-                    toolsOffered: offeredToolNames,
-                    toolCount: offeredToolNames.length,
-                    maxSteps,
-                    structuredOutput: useFinalResultTool,
-                }),
+            },
+        });
+        observe(turnSpan, "span", {
+            input: turnInputAttribute,
+            metadata: {
+                toolsOffered: offeredToolNames,
+                toolCount: offeredToolNames.length,
+                maxSteps,
+                structuredOutput: useFinalResultTool,
             },
         });
         const turnContext = otelTrace.setSpan(otelContext.active(), turnSpan);
@@ -3543,7 +3554,6 @@ export class GoogleVertexProvider extends BaseProvider {
         const loopPromise = (async () => {
             let step = 0;
             const currentMessages = [...messages];
-            let stepConversation = currentMessages;
             // 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.
@@ -3558,71 +3568,6 @@ export class GoogleVertexProvider extends BaseProvider {
             const contextGuard = createContextGuard(getContextWindowSize("vertex", modelName));
             const failedTools = new Map();
             try {
-                // Restores the per-tool observation the hand-rolled dispatch had.
-                // The execution runs INSIDE the span's context so spans the tool opens
-                // itself nest under this call rather than dangling beside the turn, and
-                // the settled RESULT is inspected — an MCP tool reports failure in its
-                // payload, so an observation that only watches for throws records a
-                // failed call as successful.
-                //
-                // Stream path only: the generate twin never had per-tool spans, and
-                // giving it them here would be behaviour GAINED under cover of a
-                // migration. Shared with resolveToolOnMiss below: the old dispatch
-                // opened the span before the executor lookup, so a tool hydrated
-                // mid-turn was observed exactly like one declared up front.
-                const withToolSpan = (toolCallName, run, call) => {
-                    // Arguments are inputs: honour the same opt-out the AI SDK path uses.
-                    const argsAttribute = call?.args !== undefined &&
-                        process.env.NEUROLINK_RECORD_INPUTS?.trim().toLowerCase() !==
-                            "false"
-                        ? spanContentAttribute(call.args)
-                        : undefined;
-                    const toolSpan = tracers.mcp.startSpan("ai.toolCall", {
-                        kind: SpanKind.INTERNAL,
-                        attributes: {
-                            [LANGFUSE_ATTR.OBSERVATION_TYPE]: "tool",
-                            [ATTR.GEN_AI_TOOL_NAME]: toolCallName,
-                            "ai.toolCall.name": toolCallName,
-                            ...(call?.toolCallId
-                                ? { "ai.toolCall.id": call.toolCallId }
-                                : {}),
-                            ...(argsAttribute !== undefined
-                                ? {
-                                    "ai.toolCall.args": argsAttribute,
-                                    [LANGFUSE_ATTR.OBSERVATION_INPUT]: argsAttribute,
-                                }
-                                : {}),
-                        },
-                    }, turnContext);
-                    const finish = (output, errorMessage) => {
-                        const outputAttribute = spanContentAttribute(output);
-                        toolSpan.setAttribute("ai.toolCall.result", outputAttribute);
-                        toolSpan.setAttribute(LANGFUSE_ATTR.OBSERVATION_OUTPUT, outputAttribute);
-                        if (errorMessage) {
-                            toolSpan.setAttribute(LANGFUSE_ATTR.OBSERVATION_LEVEL, "ERROR");
-                            toolSpan.setAttribute(LANGFUSE_ATTR.OBSERVATION_STATUS_MESSAGE, errorMessage);
-                            toolSpan.setStatus({
-                                code: SpanStatusCode.ERROR,
-                                message: errorMessage,
-                            });
-                        }
-                        else {
-                            toolSpan.setStatus({ code: SpanStatusCode.OK });
-                        }
-                        toolSpan.end();
-                    };
-                    return otelContext.with(otelTrace.setSpan(turnContext, toolSpan), async () => {
-                        try {
-                            const result = await run();
-                            finish(result, extractMcpToolErrorMessage(result));
-                            return result;
-                        }
-                        catch (error) {
-                            finish({ error: true }, error instanceof Error ? error.message : String(error));
-                            throw error;
-                        }
-                    });
-                };
                 // Executors handed to the engine, taken through the turn's
                 // DedupExecuteMap so an identical repeated call is answered from the
                 // per-turn cache rather than run again (BZ-3327). `.get()` returns the
@@ -3644,17 +3589,9 @@ export class GoogleVertexProvider extends BaseProvider {
                             toolTimeoutMs: toolExecTimeoutMs,
                             abortSignal: internalAbort.signal,
                             onProgress: () => turnClock.noteProgress(),
-                            withToolSpan,
                         }),
                     };
                 }
-                // The turn runs on the shared engine. The step cap, tool dispatch, the
-                // failure breaker, per-step usage accumulation and the pre-first-chunk
-                // provider retry all live there now. What stays here is everything the
-                // engine has no opinion about: the turn clock, the context guard, the
-                // per-step Langfuse generation span, conversation-memory storage, the
-                // wrap-up nudge, and the reserved finalization in the terminal block.
-                //
                 // maxSteps is agenticStepBudget, NOT maxSteps: when structured output is
                 // active the last slot is reserved for the forced final_result call, and
                 // the engine must never spend it.
@@ -3662,6 +3599,7 @@ export class GoogleVertexProvider extends BaseProvider {
                 // MessageParam and every hook here is typed against the wrong shape.
                 const baseAdapter = createAnthropicLoopAdapter({
                     client,
+                    provider: this.providerName,
                     maxSteps: agenticStepBudget,
                     toolsRecord: options.tools ?? {},
                     // Set here and NOT for native Anthropic: these loops have always had
@@ -3751,15 +3689,10 @@ export class GoogleVertexProvider extends BaseProvider {
                         }
                         : {}),
                 });
-                // Wrapped rather than configured: both of these fire once PER STEP, and
-                // these are the only hooks that see a single step's request and results.
-                // Reading them off the turn's final result would batch every step into
-                // one late write and lose the per-step generation span entirely.
                 const adapter = {
                     ...baseAdapter,
                     buildStepRequest: (conversation, engineStep) => {
                         step = engineStep + 1;
-                        stepConversation = conversation;
                         turnClock.noteProgress();
                         return baseAdapter.buildStepRequest(conversation, engineStep);
                     },
@@ -3779,79 +3712,21 @@ export class GoogleVertexProvider extends BaseProvider {
                                 toolTimeoutMs: toolExecTimeoutMs,
                                 abortSignal: internalAbort.signal,
                                 onProgress: () => turnClock.noteProgress(),
-                                // Same observation as an up-front executor: the hand-rolled
-                                // dispatch spanned at the call, after the executor lookup, so
-                                // a hydrated tool was never the one unobserved call in a turn.
-                                withToolSpan,
                             }),
                         };
                     },
                     executeStep: async (request, stepChannel, signal) => {
-                        // One generation observation per API call: request in, content and
-                        // usage out. Started here rather than inside the adapter because the
-                        // attributes are this provider's, not the engine's.
-                        const generationSpan = tracers.generation.startSpan("anthropic.messages.stream", {
-                            kind: SpanKind.CLIENT,
-                            attributes: {
-                                [LANGFUSE_ATTR.OBSERVATION_TYPE]: "generation",
-                                [LANGFUSE_ATTR.OBSERVATION_MODEL_NAME]: modelName,
-                                [LANGFUSE_ATTR.OBSERVATION_MODEL_PARAMETERS]: spanJsonAttribute({
-                                    max_tokens: requestParams.max_tokens,
-                                    temperature: requestParams.temperature,
-                                    top_p: requestParams.top_p,
-                                }),
-                                [LANGFUSE_ATTR.OBSERVATION_INPUT]: spanModelRequestAttribute({
-                                    system: systemPromptWithSchema,
-                                    messages: sanitizeAnthropicMessagesForTrace(stepConversation),
-                                }),
-                                [LANGFUSE_ATTR.OBSERVATION_METADATA]: spanJsonAttribute({
-                                    step,
-                                    toolsOffered: offeredToolNames.length,
-                                }),
-                                [ATTR.GEN_AI_SYSTEM]: "anthropic",
-                                [ATTR.GEN_AI_MODEL]: modelName,
-                                [ATTR.GEN_AI_OPERATION]: "chat",
+                        const result = await baseAdapter.executeStep(request, {
+                            push: (chunk) => {
+                                turnClock.noteProgress();
+                                stepChannel.push(chunk);
                             },
-                        }, turnContext);
-                        let firstDeltaSeen = false;
-                        try {
-                            const result = await baseAdapter.executeStep(request, {
-                                push: (chunk) => {
-                                    turnClock.noteProgress();
-                                    if (chunk.content && !firstDeltaSeen) {
-                                        firstDeltaSeen = true;
-                                        // Time-to-first-token for this generation.
-                                        generationSpan.setAttribute(LANGFUSE_ATTR.OBSERVATION_COMPLETION_START_TIME, new Date().toISOString());
-                                    }
-                                    stepChannel.push(chunk);
-                                },
-                            }, signal);
-                            turnCacheUsage.read += result.usage.cacheReadTokens ?? 0;
-                            turnCacheUsage.creation += result.usage.cacheWriteTokens ?? 0;
-                            turnCacheUsage.creation5m += result.usage.cacheWrite5mTokens ?? 0;
-                            turnCacheUsage.creation1h += result.usage.cacheWrite1hTokens ?? 0;
-                            generationSpan.setAttribute(LANGFUSE_ATTR.OBSERVATION_OUTPUT, spanContentAttribute({
-                                text: result.text,
-                                ...(result.toolCalls.length > 0
-                                    ? { toolCalls: result.toolCalls }
-                                    : {}),
-                            }));
-                            generationSpan.setAttribute(`${LANGFUSE_ATTR.OBSERVATION_METADATA}.finishReason`, result.rawStopReason ?? "unknown");
-                            return result;
-                        }
-                        catch (error) {
-                            generationSpan.setStatus({
-                                code: SpanStatusCode.ERROR,
-                                message: error instanceof Error ? error.message : String(error),
-                            });
-                            if (error instanceof Error) {
-                                generationSpan.recordException(error);
-                            }
-                            throw error;
-                        }
-                        finally {
-                            generationSpan.end();
-                        }
+                        }, signal);
+                        turnCacheUsage.read += result.usage.cacheReadTokens ?? 0;
+                        turnCacheUsage.creation += result.usage.cacheWriteTokens ?? 0;
+                        turnCacheUsage.creation5m += result.usage.cacheWrite5mTokens ?? 0;
+                        turnCacheUsage.creation1h += result.usage.cacheWrite1hTokens ?? 0;
+                        return result;
                     },
                     buildToolResultMessages: (conversation, stepResult, toolResults, engineStep) => {
                         for (const result of toolResults) {
@@ -3905,15 +3780,14 @@ export class GoogleVertexProvider extends BaseProvider {
                         return next;
                     },
                 };
-                const activeSpan = otelTrace.getSpan(turnContext);
-                const { stream: engineStream, resultPromise } = runAgenticLoop(adapter, currentMessages.slice(), {
+                const { stream: engineStream, resultPromise } = otelContext.with(turnContext, () => runAgenticLoop(adapter, currentMessages.slice(), {
                     tools: engineTools,
                     abortSignal: internalAbort.signal,
-                    ...(activeSpan ? { span: activeSpan } : {}),
+                    span: turnSpan,
                     // Same value `guardToolExecutor` already received above, so the
                     // engine's own per-tool bound cannot undercut it.
                     toolTimeoutMs: toolExecTimeoutMs,
-                });
+                }));
                 const pump = (async () => {
                     for await (const chunk of engineStream) {
                         if (chunk.reasoning) {
@@ -4050,33 +3924,44 @@ export class GoogleVertexProvider extends BaseProvider {
                                 tools,
                                 messages: currentMessages,
                             });
-                            const finalizationStream = await client.messages.stream({
-                                ...requestParams,
-                                max_tokens: terminalMaxTokens,
-                                // Resized, not inherited: terminalMaxTokens can sit below the
-                                // budget requestParams' thinking was sized for.
-                                thinking: this.buildClaudeThinkingParam(options, terminalMaxTokens, forceFinalResult),
-                                ...(forceFinalResult && {
-                                    tool_choice: {
-                                        type: "tool",
-                                        name: "final_result",
-                                    },
-                                }),
-                                ...(cachedFinal.system !== undefined && {
-                                    system: cachedFinal.system,
-                                }),
-                                ...(cachedFinal.tools &&
-                                    cachedFinal.tools.length > 0 && {
-                                    tools: cachedFinal.tools,
-                                }),
+                            const response = await this.withClaudeGeneration({
+                                stepNumber: maxSteps + 1,
+                                model: requestParams.model,
+                                maxTokens: terminalMaxTokens,
+                                temperature: requestParams.temperature,
+                                topP: requestParams.top_p,
+                                system: cachedFinal.system,
                                 messages: cachedFinal.messages,
+                            }, async () => {
+                                const finalizationStream = await client.messages.stream({
+                                    ...requestParams,
+                                    max_tokens: terminalMaxTokens,
+                                    // Resized, not inherited: terminalMaxTokens can sit below the
+                                    // budget requestParams' thinking was sized for.
+                                    thinking: this.buildClaudeThinkingParam(options, terminalMaxTokens, forceFinalResult),
+                                    ...(forceFinalResult && {
+                                        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 message = await finalizationStream.finalMessage();
+                                activeStream = undefined;
+                                return message;
                             });
-                            // 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;
                             turnCacheUsage.read +=
@@ -4184,26 +4069,37 @@ export class GoogleVertexProvider extends BaseProvider {
                                 // is rebuilt for the shrunk limit rather than inherited
                                 // through the spread below.
                                 const backstopThinking = this.buildClaudeThinkingParam(options, terminalMaxTokens, false);
-                                const backstopStream = await client.messages.stream({
-                                    ...requestParams,
-                                    max_tokens: terminalMaxTokens,
-                                    // Assigned outright, never a conditional spread: spreading
-                                    // requestParams above may already carry a `thinking` sized
-                                    // for the original max_tokens, and only adding a key when
-                                    // backstopThinking is truthy would leave that stale value
-                                    // in place instead of clearing it.
-                                    thinking: backstopThinking,
-                                    tool_choice: { type: "none" },
+                                const response = await this.withClaudeGeneration({
+                                    stepNumber: maxSteps + 1,
+                                    model: requestParams.model,
+                                    maxTokens: terminalMaxTokens,
+                                    temperature: requestParams.temperature,
+                                    topP: requestParams.top_p,
                                     system: cachedBackstop.system,
-                                    ...(cachedBackstop.tools &&
-                                        cachedBackstop.tools.length > 0 && {
-                                        tools: cachedBackstop.tools,
-                                    }),
                                     messages: cachedBackstop.messages,
+                                }, async () => {
+                                    const backstopStream = await client.messages.stream({
+                                        ...requestParams,
+                                        max_tokens: terminalMaxTokens,
+                                        // Assigned outright, never a conditional spread: spreading
+                                        // requestParams above may already carry a `thinking` sized
+                                        // for the original max_tokens, and only adding a key when
+                                        // backstopThinking is truthy would leave that stale value
+                                        // in place instead of clearing it.
+                                        thinking: backstopThinking,
+                                        tool_choice: { type: "none" },
+                                        system: cachedBackstop.system,
+                                        ...(cachedBackstop.tools &&
+                                            cachedBackstop.tools.length > 0 && {
+                                            tools: cachedBackstop.tools,
+                                        }),
+                                        messages: cachedBackstop.messages,
+                                    });
+                                    activeStream = backstopStream;
+                                    const message = await backstopStream.finalMessage();
+                                    activeStream = undefined;
+                                    return message;
                                 });
-                                activeStream = backstopStream;
-                                const response = await backstopStream.finalMessage();
-                                activeStream = undefined;
                                 usage.input += response.usage?.input_tokens || 0;
                                 usage.output += response.usage?.output_tokens || 0;
                                 turnCacheUsage.read +=
@@ -4363,53 +4259,59 @@ export class GoogleVertexProvider extends BaseProvider {
                 if (turnCacheUsage.creation > 0) {
                     usage.cacheCreationTokens = turnCacheUsage.creation;
                 }
-                const turnOutputAttribute = spanContentAttribute({
-                    text: aggregatedTurnText,
-                    ...(structuredOutputRef.value
-                        ? { structuredOutput: structuredOutputRef.value }
-                        : {}),
-                });
-                turnSpan.setAttribute(LANGFUSE_ATTR.OBSERVATION_OUTPUT, turnOutputAttribute);
-                turnSpan.setAttribute(LANGFUSE_ATTR.TRACE_OUTPUT, turnOutputAttribute);
-                // Turn usage is metadata-only (not usage_details) — see the note at the
-                // top of this method on why it must not contribute to the cost rollup.
-                turnSpan.setAttribute(LANGFUSE_ATTR.OBSERVATION_METADATA, spanJsonAttribute({
-                    toolsOffered: offeredToolNames,
-                    toolCount: offeredToolNames.length,
-                    maxSteps,
-                    steps: step,
-                    toolCallCount: metadata.totalToolExecutions,
-                    toolsCalled: toolsUsedRef.filter((name) => name !== "final_result"),
-                    structuredOutput: useFinalResultTool,
-                    ...(stopReasonRef.value ? { stopReason: stopReasonRef.value } : {}),
-                    usage: {
-                        input: usage.input,
-                        output: usage.output,
-                        input_cached_tokens: turnCacheUsage.read,
-                        input_cache_creation: turnCacheUsage.creation,
-                        input_cache_creation_5m: turnCacheUsage.creation5m,
-                        input_cache_creation_1h: turnCacheUsage.creation1h,
+                observe(turnSpan, "span", {
+                    output: {
+                        text: aggregatedTurnText,
+                        ...(structuredOutputRef.value
+                            ? { structuredOutput: structuredOutputRef.value }
+                            : {}),
                     },
-                }));
+                    // Turn usage is metadata-only (not usage_details) — see the note at the
+                    // top of this method on why it must not contribute to the cost rollup.
+                    metadata: {
+                        toolsOffered: offeredToolNames,
+                        toolCount: offeredToolNames.length,
+                        maxSteps,
+                        steps: step,
+                        toolCallCount: metadata.totalToolExecutions,
+                        toolsCalled: toolsUsedRef.filter((name) => name !== "final_result"),
+                        structuredOutput: useFinalResultTool,
+                        ...(stopReasonRef.value ? { stopReason: stopReasonRef.value } : {}),
+                        usage: {
+                            input: usage.input,
+                            output: usage.output,
+                            input_cached_tokens: turnCacheUsage.read,
+                            input_cache_creation: turnCacheUsage.creation,
+                            input_cache_creation_5m: turnCacheUsage.creation5m,
+                            input_cache_creation_1h: turnCacheUsage.creation1h,
+                        },
+                    },
+                });
                 // How the turn ended, on the trace itself, so an evaluator can select
                 // only turns that finished ("completed") and skip capped, timed-out,
                 // aborted and failed ones. A trace holding several turns keeps the last
                 // one's; each turn's own is in its observation metadata above.
                 if (stopReasonRef.value) {
-                    turnSpan.setAttribute(`${LANGFUSE_ATTR.TRACE_METADATA}.stopReason`, stopReasonRef.value);
+                    observeTrace(turnSpan, {
+                        metadata: { stopReason: stopReasonRef.value },
+                    });
                 }
                 turnSpan.setStatus({ code: SpanStatusCode.OK });
                 channel.close();
             }
             catch (err) {
-                turnSpan.setAttribute(LANGFUSE_ATTR.OBSERVATION_METADATA, spanJsonAttribute({
-                    toolsOffered: offeredToolNames,
-                    toolCount: offeredToolNames.length,
-                    maxSteps,
-                    structuredOutput: useFinalResultTool,
-                    stopReason: "provider-error",
-                }));
-                turnSpan.setAttribute(`${LANGFUSE_ATTR.TRACE_METADATA}.stopReason`, "provider-error");
+                observe(turnSpan, "span", {
+                    level: "ERROR",
+                    statusMessage: err instanceof Error ? err.message : String(err),
+                    metadata: {
+                        toolsOffered: offeredToolNames,
+                        toolCount: offeredToolNames.length,
+                        maxSteps,
+                        structuredOutput: useFinalResultTool,
+                        stopReason: "provider-error",
+                    },
+                });
+                observeTrace(turnSpan, { metadata: { stopReason: "provider-error" } });
                 turnSpan.setStatus({
                     code: SpanStatusCode.ERROR,
                     message: err instanceof Error ? err.message : String(err),
@@ -4785,7 +4687,7 @@ export class GoogleVertexProvider extends BaseProvider {
         let hitStepLimit = false;
         let hitContextLimit = false;
         let synthesizedFinalAnswer = false;
-        let modelFinished = false;
+        const modelFinished = false;
         const currentMessages = [...messages];
         // In-loop context guard: stop calling tools when the accumulated
         // conversation approaches the model's real context window, instead of
@@ -4855,6 +4757,7 @@ export class GoogleVertexProvider extends BaseProvider {
         // engine must never spend it.
         const baseAdapter = createAnthropicLoopAdapter({
             client,
+            provider: this.providerName,
             maxSteps: agenticStepBudget,
             toolsRecord: options.tools ?? {},
             toolFailureBreaker: {
@@ -5130,7 +5033,15 @@ export class GoogleVertexProvider extends BaseProvider {
                         tools,
                         messages: currentMessages,
                     });
-                    const response = await withTimeout(client.messages.create({
+                    const response = await this.withClaudeGeneration({
+                        stepNumber: maxSteps + 1,
+                        model: requestParams.model,
+                        maxTokens: terminalMaxTokens,
+                        temperature: requestParams.temperature,
+                        topP: requestParams.top_p,
+                        system: cachedFinal.system,
+                        messages: cachedFinal.messages,
+                    }, () => withTimeout(client.messages.create({
                         ...requestParams,
                         max_tokens: terminalMaxTokens,
                         // Resized, not inherited: terminalMaxTokens can sit below the
@@ -5150,7 +5061,7 @@ export class GoogleVertexProvider extends BaseProvider {
                             tools: cachedFinal.tools,
                         }),
                         messages: cachedFinal.messages,
-                    }, { signal: internalAbort.signal }), generateTimeoutMs, "Anthropic finalization call timed out");
+                    }, { signal: internalAbort.signal }), generateTimeoutMs, "Anthropic finalization call timed out"));
                     totalInputTokens += response.usage?.input_tokens || 0;
                     totalOutputTokens += response.usage?.output_tokens || 0;
                     totalCacheReadTokens += response.usage?.cache_read_input_tokens || 0;
@@ -5242,7 +5153,15 @@ export class GoogleVertexProvider extends BaseProvider {
                         // rebuilt for the shrunk limit rather than inherited through the
                         // spread below.
                         const backstopThinking = this.buildClaudeThinkingParam(options, terminalMaxTokens, false);
-                        const response = await withTimeout(client.messages.create({
+                        const response = await this.withClaudeGeneration({
+                            stepNumber: maxSteps + 1,
+                            model: requestParams.model,
+                            maxTokens: terminalMaxTokens,
+                            temperature: requestParams.temperature,
+                            topP: requestParams.top_p,
+                            system: cachedBackstop.system,
+                            messages: cachedBackstop.messages,
+                        }, () => withTimeout(client.messages.create({
                             ...requestParams,
                             max_tokens: terminalMaxTokens,
                             // Assigned outright, never a conditional spread: spreading
@@ -5258,7 +5177,7 @@ export class GoogleVertexProvider extends BaseProvider {
                                 tools: cachedBackstop.tools,
                             }),
                             messages: cachedBackstop.messages,
-                        }, { signal: internalAbort.signal }), generateTimeoutMs, "Anthropic backstop call timed out");
+                        }, { signal: internalAbort.signal }), generateTimeoutMs, "Anthropic backstop call timed out"));
                         totalInputTokens += response.usage?.input_tokens || 0;
                         totalOutputTokens += response.usage?.output_tokens || 0;
                         totalCacheReadTokens +=
@@ -5569,6 +5488,14 @@ export class GoogleVertexProvider extends BaseProvider {
         // For non-image models, call the parent stream method
         return super.stream(optionsOrPrompt);
     }
+    observeMediaGeneration(model, run) {
+        const call = { provider: this.providerName, model };
+        return withGeneration(call, async (span) => {
+            const result = await run();
+            observeGeneration(span, { ...call, usage: result?.usage });
+            return result;
+        });
+    }
     /**
      * Override generate to route ALL models to native SDKs
      * No more @ai-sdk/google-vertex dependency
@@ -5585,12 +5512,11 @@ export class GoogleVertexProvider extends BaseProvider {
         // Vertex's generate() bypasses BaseProvider.generate entirely, so
         // without this wrapping the provider span never gets emitted.
         return withClientSpan({
-            name: "neurolink.provider.generate",
+            name: "provider.generate",
             tracer: tracers.provider,
+            detached: true,
             attributes: {
-                [ATTR.GEN_AI_SYSTEM]: this.providerName,
-                [ATTR.GEN_AI_MODEL]: modelName,
-                [ATTR.GEN_AI_OPERATION]: "generate",
+                [ATTR.NL_MODEL]: modelName,
                 [ATTR.NL_PROVIDER]: this.providerName,
             },
         }, async (generateSpan) => {
@@ -5610,8 +5536,7 @@ export class GoogleVertexProvider extends BaseProvider {
             // of producing video bytes.
             if (requestKind === "video") {
                 logger.info("[GoogleVertex] Routing video-mode generate to handleVideoGeneration", { model: modelName });
-                const videoResult = await this.handleVideoGeneration(options, generateStartTime);
-                this.attachUsageAndCostAttributes(generateSpan, modelName, videoResult?.usage);
+                const videoResult = await this.observeMediaGeneration(modelName, () => this.handleVideoGeneration(options, generateStartTime));
                 this.emitGenerationEnd(modelName, videoResult, generateStartTime, true);
                 return videoResult;
             }
@@ -5632,8 +5557,7 @@ export class GoogleVertexProvider extends BaseProvider {
             // gemini-3.1-flash-image-preview on the text path.
             if (requestKind === "image") {
                 logger.info("[GoogleVertex] Routing image generation model to executeImageGeneration", { model: modelName });
-                const imageResult = await this.executeImageGeneration(options);
-                this.attachUsageAndCostAttributes(generateSpan, modelName, imageResult?.usage);
+                const imageResult = await this.observeMediaGeneration(modelName, () => this.executeImageGeneration(options));
                 this.emitGenerationEnd(modelName, imageResult, generateStartTime, true);
                 return imageResult;
             }
@@ -5654,7 +5578,7 @@ export class GoogleVertexProvider extends BaseProvider {
             // span here. Without this the test:tracing "Message Build Span"
             // assertion has to skip on every native-Vertex run.
             const processedOptions = await withSpan({
-                name: "neurolink.message.build",
+                name: "message.build",
                 tracer: tracers.provider,
                 attributes: {
                     [ATTR.NL_PROVIDER]: this.providerName,
@@ -5681,7 +5605,7 @@ export class GoogleVertexProvider extends BaseProvider {
                     : {}),
                 prompt: inputPrompt,
             });
-            generateSpan.setAttribute(LANGFUSE_ATTR.OBSERVATION_INPUT, generationInputAttribute);
+            generateSpan.setAttribute(LangfuseOtelSpanAttributes.OBSERVATION_INPUT, generationInputAttribute);
             try {
                 let result;
                 // Wrap the actual native generate call in `neurolink.executeGeneration`
@@ -5690,15 +5614,15 @@ export class GoogleVertexProvider extends BaseProvider {
                 // native @google/genai / @anthropic-ai/vertex-sdk path. This
                 // provider overrides generate(), so the span is added here.
                 result = await withSpan({
-                    name: "neurolink.executeGeneration",
+                    name: "executeGeneration",
                     tracer: tracers.provider,
+                    detached: true,
                     attributes: {
-                        [ATTR.GEN_AI_SYSTEM]: this.providerName,
-                        [ATTR.GEN_AI_MODEL]: modelName,
-                        "neurolink.path": isAnthropicModel(modelName)
+                        [ATTR.NL_MODEL]: modelName,
+                        path: isAnthropicModel(modelName)
                             ? "native.anthropic"
                             : "native.google-genai",
-                        [LANGFUSE_ATTR.OBSERVATION_INPUT]: generationInputAttribute,
+                        [LangfuseOtelSpanAttributes.OBSERVATION_INPUT]: generationInputAttribute,
                     },
                 }, async (executionSpan) => {
                     let nativeResult;
@@ -5716,16 +5640,15 @@ export class GoogleVertexProvider extends BaseProvider {
                         });
                         nativeResult = await this.runNativeGenerateWithMiddleware(mergedOptions, modelName, (effectiveOptions) => this.executeNativeGemini3GenerateWithSchemaFallback(effectiveOptions, modelName));
                     }
-                    executionSpan.setAttribute(LANGFUSE_ATTR.OBSERVATION_OUTPUT, spanContentAttribute(nativeResult?.content ?? ""));
+                    executionSpan.setAttribute(LangfuseOtelSpanAttributes.OBSERVATION_OUTPUT, spanContentAttribute(nativeResult?.content ?? ""));
                     return nativeResult;
                 });
-                this.attachUsageAndCostAttributes(generateSpan, modelName, result?.usage);
                 // Pipe through TTS-of-AI-response when caller asks for it. The
                 // shared `synthesizeAIResponseIfNeeded` no-ops when tts is not
                 // enabled / useAiResponse is false, so the cost is zero on
                 // non-TTS paths.
                 result = await this.synthesizeAIResponseIfNeeded(result, options);
-                generateSpan.setAttribute(LANGFUSE_ATTR.OBSERVATION_OUTPUT, spanContentAttribute(result?.content ?? ""));
+                generateSpan.setAttribute(LangfuseOtelSpanAttributes.OBSERVATION_OUTPUT, spanContentAttribute(result?.content ?? ""));
                 // Fire onFinish lifecycle callback for the native generate path.
                 // Pipeline A providers get this for free via the AI SDK middleware
                 // wrapper (LifecycleMiddleware); native @google/genai bypasses
@@ -6389,54 +6312,35 @@ export class GoogleVertexProvider extends BaseProvider {
         }
         return wrapped;
     }
-    /**
-     * Attach `gen_ai.usage.*` and `neurolink.cost` attributes to a span.
-     * Pulled out so the generate / stream / image-gen paths share one
-     * implementation, and so observability/tracing tests find consistent
-     * attributes regardless of which native sub-route fulfilled the request.
-     */
-    attachUsageAndCostAttributes(span, modelName, usage) {
-        if (!span || !usage) {
-            return;
-        }
-        const inputTokens = usage.input ?? usage.inputTokens ?? 0;
-        const outputTokens = usage.output ?? usage.outputTokens ?? 0;
-        const totalTokens = usage.total ?? usage.totalTokens ?? inputTokens + outputTokens;
-        const cacheReadTokens = usage.cacheReadTokens ?? 0;
-        const cacheCreationTokens = usage.cacheCreationTokens ?? 0;
-        if (inputTokens > 0) {
-            span.setAttribute("gen_ai.usage.input_tokens", inputTokens);
-        }
-        if (outputTokens > 0) {
-            span.setAttribute("gen_ai.usage.output_tokens", outputTokens);
-        }
-        if (totalTokens > 0) {
-            span.setAttribute("gen_ai.usage.total_tokens", totalTokens);
-        }
-        if (cacheReadTokens > 0) {
-            span.setAttribute("gen_ai.usage.cache_read_input_tokens", cacheReadTokens);
-        }
-        if (cacheCreationTokens > 0) {
-            span.setAttribute("gen_ai.usage.cache_creation_input_tokens", cacheCreationTokens);
-        }
-        try {
-            // Pass cache tokens through so calculateCost prices the ~0.1x cache-read
-            // and ~1.25x cache-write tiers instead of billing cached content at the
-            // full input rate.
-            const cost = calculateCost(this.providerName, modelName, {
-                input: inputTokens,
-                output: outputTokens,
-                total: totalTokens,
-                cacheReadTokens,
-                cacheCreationTokens,
+    withClaudeGeneration(sent, send) {
+        const call = { provider: this.providerName, model: sent.model };
+        return withStepSpan(sent.stepNumber, () => withGeneration({
+            ...call,
+            modelParameters: {
+                temperature: sent.temperature,
+                maxTokens: sent.maxTokens,
+                topP: sent.topP,
+            },
+            input: {
+                system: sent.system,
+                messages: sanitizeAnthropicMessagesForTrace(sent.messages),
+            },
+        }, async (span) => {
+            const response = await send();
+            observeGeneration(span, {
+                ...call,
+                responseModel: response.model,
+                output: response.content,
+                usage: {
+                    inputTokens: response.usage?.input_tokens,
+                    outputTokens: response.usage?.output_tokens,
+                    cacheReadTokens: response.usage?.cache_read_input_tokens ?? undefined,
+                    cacheCreationTokens: response.usage?.cache_creation_input_tokens ?? undefined,
+                },
+                finishReason: response.stop_reason ?? undefined,
             });
-            if (typeof cost === "number" && cost > 0) {
-                span.setAttribute("neurolink.cost", cost);
-            }
-        }
-        catch {
-            // Pricing table miss is not fatal — leave the attribute unset.
-        }
+            return response;
+        }));
     }
     /**
      * Emit `generation:end` so the Pipeline B observability listener creates