@juspay/neurolink 9.70.7 → 9.72.0

package/dist/providers/googleVertex.js

@@ -22,9 +22,12 @@ import { createNativeThinkingConfig } from "../utils/thinkingConfig.js";
 import { TimeoutError, withTimeout } from "../utils/async/index.js";
 import { parseTimeout } from "../utils/timeout.js";
 import { createTextChannel, extractThoughtSignature, prependConversationMessages, } from "./googleNativeGemini3.js";
-import { ATTR, tracers, withClientSpan, withClientStreamSpan, withSpan, } from "../telemetry/index.js";
+import { ATTR, LANGFUSE_ATTR, spanJsonAttribute, tracers, withClientSpan, withClientStreamSpan, withSpan, } from "../telemetry/index.js";
+import { SpanKind, SpanStatusCode, context as otelContext, trace as otelTrace, } from "@opentelemetry/api";
 import { calculateCost } from "../utils/pricing.js";
 import { transformToolExecutions } from "../utils/transformationUtils.js";
+import { sanitizeAnthropicMessagesForTrace } from "../utils/anthropicTraceSanitizer.js";
+import { extractMcpToolErrorMessage } from "../utils/mcpErrorText.js";
 // Import proper types for multimodal message handling
 // Dynamic import helper for native Anthropic Vertex SDK
 let anthropicVertexModule = null;
@@ -2390,6 +2393,49 @@ export class GoogleVertexProvider extends BaseProvider {
         };
         const toolsUsedRef = [];
         const structuredOutputRef = {};
+        // Langfuse/OTel: the native SDK bypasses the Vercel AI SDK's
+        // experimental_telemetry, so emit spans manually — one turn span, one
+        // generation span per API call, one tool span per execution — all carrying
+        // langfuse.* attributes the LangfuseSpanProcessor maps to observations.
+        // Usage lives ONLY on the generation spans (Langfuse sums usage across
+        // observations for trace totals, so repeating it on the turn double-counts).
+        const offeredToolNames = (tools ?? []).map((anthropicTool) => anthropicTool.name);
+        const turnInputAttribute = spanJsonAttribute({
+            system: systemPromptWithSchema,
+            messages: sanitizeAnthropicMessagesForTrace(messages),
+        });
+        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_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,
+                }),
+            },
+        });
+        const turnContext = otelTrace.setSpan(otelContext.active(), turnSpan);
+        let aggregatedTurnText = "";
+        // Anthropic prompt-cache token accounting, aggregated across loop steps.
+        const turnCacheUsage = {
+            read: 0,
+            creation: 0,
+            creation5m: 0,
+            creation1h: 0,
+        };
         // Track the active Anthropic stream so options.abortSignal can cancel it
         // mid-flight (pre-rewrite code had no abort handling — fixed for free).
         let activeStream;
@@ -2419,29 +2465,116 @@ export class GoogleVertexProvider extends BaseProvider {
                         throw new Error("Stream aborted by caller");
                     }
                     step++;
-                    const stream = await client.messages.stream({
-                        ...requestParams,
-                        messages: currentMessages,
-                    });
-                    activeStream = stream;
-                    // Forward each text delta to the consumer as it arrives. The
-                    // Anthropic SDK fires this listener synchronously for every
-                    // content_block_delta SSE event, so the channel sees bytes at
-                    // the same cadence the wire delivers them.
-                    stream.on("text", (delta) => {
-                        if (delta.length > 0) {
-                            channel.push(delta);
+                    // One generation observation per API call: request in, content + usage out.
+                    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]: spanJsonAttribute({
+                                system: systemPromptWithSchema,
+                                messages: sanitizeAnthropicMessagesForTrace(currentMessages),
+                            }),
+                            [LANGFUSE_ATTR.OBSERVATION_METADATA]: spanJsonAttribute({
+                                step,
+                                toolsOffered: offeredToolNames.length,
+                            }),
+                            [ATTR.GEN_AI_SYSTEM]: "anthropic",
+                            [ATTR.GEN_AI_MODEL]: modelName,
+                            [ATTR.GEN_AI_OPERATION]: "chat",
+                        },
+                    }, turnContext);
+                    let response;
+                    try {
+                        const stream = await client.messages.stream({
+                            ...requestParams,
+                            messages: currentMessages,
+                        });
+                        activeStream = stream;
+                        // Forward each text delta as it arrives — the Anthropic SDK fires
+                        // this synchronously per content_block_delta, so the channel streams
+                        // at wire cadence. The first delta stamps completion_start_time,
+                        // giving Langfuse the generation's time-to-first-token.
+                        let firstDeltaSeen = false;
+                        stream.on("text", (delta) => {
+                            if (delta.length > 0) {
+                                if (!firstDeltaSeen) {
+                                    firstDeltaSeen = true;
+                                    generationSpan.setAttribute(LANGFUSE_ATTR.OBSERVATION_COMPLETION_START_TIME, new Date().toISOString());
+                                }
+                                channel.push(delta);
+                            }
+                        });
+                        // finalMessage() resolves AFTER message_stop. By then the listener
+                        // has already fired for every delta — awaiting here doesn't block
+                        // visible streaming, it just gives us the structured response
+                        // shape needed for tool_use block extraction.
+                        response = await stream.finalMessage();
+                    }
+                    catch (modelCallError) {
+                        generationSpan.setStatus({
+                            code: SpanStatusCode.ERROR,
+                            message: modelCallError instanceof Error
+                                ? modelCallError.message
+                                : String(modelCallError),
+                        });
+                        if (modelCallError instanceof Error) {
+                            generationSpan.recordException(modelCallError);
                         }
-                    });
-                    // finalMessage() resolves AFTER message_stop. By then the listener
-                    // has already fired for every delta — awaiting here doesn't block
-                    // visible streaming, it just gives us the structured response
-                    // shape needed for tool_use block extraction.
-                    const response = await stream.finalMessage();
+                        generationSpan.end();
+                        throw modelCallError;
+                    }
                     activeStream = undefined;
-                    usage.input += response.usage?.input_tokens || 0;
-                    usage.output += response.usage?.output_tokens || 0;
-                    usage.total = usage.input + usage.output;
+                    // End the generation span even if the bookkeeping below throws (else
+                    // it leaks). The model-call error path already ended it — no double-end.
+                    try {
+                        const stepCacheRead = response.usage?.cache_read_input_tokens ?? 0;
+                        const stepCacheCreation = response.usage?.cache_creation_input_tokens ?? 0;
+                        const stepCacheCreation5m = response.usage?.cache_creation?.ephemeral_5m_input_tokens ?? 0;
+                        const stepCacheCreation1h = response.usage?.cache_creation?.ephemeral_1h_input_tokens ?? 0;
+                        turnCacheUsage.read += stepCacheRead;
+                        turnCacheUsage.creation += stepCacheCreation;
+                        turnCacheUsage.creation5m += stepCacheCreation5m;
+                        turnCacheUsage.creation1h += stepCacheCreation1h;
+                        usage.input += response.usage?.input_tokens || 0;
+                        usage.output += response.usage?.output_tokens || 0;
+                        usage.total = usage.input + usage.output;
+                        for (const block of response.content) {
+                            if (block.type === "text" && typeof block.text === "string") {
+                                aggregatedTurnText += block.text;
+                            }
+                        }
+                        generationSpan.setAttribute(LANGFUSE_ATTR.OBSERVATION_OUTPUT, spanJsonAttribute(response.content));
+                        // 5m and 1h cache-creation are priced differently, so keep both;
+                        // drop the aggregate input_cache_creation (= 5m + 1h) that would
+                        // double-count. total sums the per-TTL keys shown here to match them.
+                        generationSpan.setAttribute(LANGFUSE_ATTR.OBSERVATION_USAGE_DETAILS, spanJsonAttribute({
+                            input: response.usage?.input_tokens ?? 0,
+                            output: response.usage?.output_tokens ?? 0,
+                            input_cached_tokens: stepCacheRead,
+                            input_cache_creation_5m: stepCacheCreation5m,
+                            input_cache_creation_1h: stepCacheCreation1h,
+                            total: (response.usage?.input_tokens ?? 0) +
+                                (response.usage?.output_tokens ?? 0) +
+                                stepCacheRead +
+                                stepCacheCreation5m +
+                                stepCacheCreation1h,
+                        }));
+                        generationSpan.setAttribute(ATTR.GEN_AI_INPUT_TOKENS, response.usage?.input_tokens ?? 0);
+                        generationSpan.setAttribute(ATTR.GEN_AI_OUTPUT_TOKENS, response.usage?.output_tokens ?? 0);
+                        if (response.stop_reason) {
+                            generationSpan.setAttribute(ATTR.GEN_AI_FINISH_REASON, response.stop_reason);
+                        }
+                        generationSpan.setStatus({ code: SpanStatusCode.OK });
+                    }
+                    finally {
+                        generationSpan.end();
+                    }
                     const toolUseBlocks = response.content.filter((block) => block.type === "tool_use");
                     // Structured-output pattern: when the model returns the
                     // final_result tool call, push its arguments as JSON and stop.
@@ -2481,6 +2614,38 @@ export class GoogleVertexProvider extends BaseProvider {
                             toolName: toolUse.name,
                             args: toolUse.input,
                         });
+                        // One tool observation per execution. ai.toolCall.* names follow the
+                        // Vercel AI SDK convention so existing tooling keeps working.
+                        const toolSpan = tracers.mcp.startSpan("ai.toolCall", {
+                            kind: SpanKind.INTERNAL,
+                            attributes: {
+                                [LANGFUSE_ATTR.OBSERVATION_TYPE]: "tool",
+                                [ATTR.GEN_AI_TOOL_NAME]: toolUse.name,
+                                "ai.toolCall.name": toolUse.name,
+                                "ai.toolCall.id": toolUse.id,
+                                "ai.toolCall.args": spanJsonAttribute(toolUse.input, 20_000),
+                                [LANGFUSE_ATTR.OBSERVATION_INPUT]: spanJsonAttribute(toolUse.input, 20_000),
+                                [LANGFUSE_ATTR.OBSERVATION_METADATA]: spanJsonAttribute({
+                                    step,
+                                }),
+                            },
+                        }, turnContext);
+                        const endToolSpan = (output, errorMessage) => {
+                            toolSpan.setAttribute("ai.toolCall.result", spanJsonAttribute(output));
+                            toolSpan.setAttribute(LANGFUSE_ATTR.OBSERVATION_OUTPUT, spanJsonAttribute(output));
+                            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();
+                        };
                         const execute = executeMap.get(toolUse.name);
                         if (execute) {
                             try {
@@ -2489,7 +2654,13 @@ export class GoogleVertexProvider extends BaseProvider {
                                     messages: [],
                                     abortSignal: options.abortSignal,
                                 };
-                                const result = await execute(toolUse.input, toolOptions);
+                                // Run with toolSpan active so spans inside execute
+                                // (neurolink.tool.execute) nest under this observation instead
+                                // of becoming disconnected siblings.
+                                const result = await otelContext.with(otelTrace.setSpan(turnContext, toolSpan), () => execute(toolUse.input, toolOptions));
+                                // MCP failures are returned, not thrown — surface them on
+                                // the span so failed calls show as ERROR in Langfuse.
+                                endToolSpan(result, extractMcpToolErrorMessage(result));
                                 toolExecutions.push({
                                     name: toolUse.name,
                                     input: toolUse.input,
@@ -2515,6 +2686,7 @@ export class GoogleVertexProvider extends BaseProvider {
                             catch (err) {
                                 const errMsg = `Error executing tool "${toolUse.name}": ${err instanceof Error ? err.message : String(err)}`;
                                 const errorPayload = { error: errMsg };
+                                endToolSpan(errorPayload, errMsg);
                                 toolExecutions.push({
                                     name: toolUse.name,
                                     input: toolUse.input,
@@ -2535,6 +2707,7 @@ export class GoogleVertexProvider extends BaseProvider {
                         else {
                             const errMsg = `TOOL_NOT_FOUND: The tool "${toolUse.name}" does not exist.`;
                             const errorPayload = { error: errMsg };
+                            endToolSpan(errorPayload, errMsg);
                             toolExecutions.push({
                                 name: toolUse.name,
                                 input: toolUse.input,
@@ -2577,13 +2750,49 @@ export class GoogleVertexProvider extends BaseProvider {
                 }
                 metadata.responseTime = Date.now() - startTime;
                 metadata.totalToolExecutions = allToolCalls.filter((tc) => tc.toolName !== "final_result").length;
+                const turnOutputAttribute = spanJsonAttribute({
+                    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,
+                    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,
+                    },
+                }));
+                turnSpan.setStatus({ code: SpanStatusCode.OK });
                 channel.close();
             }
             catch (err) {
+                turnSpan.setStatus({
+                    code: SpanStatusCode.ERROR,
+                    message: err instanceof Error ? err.message : String(err),
+                });
+                if (err instanceof Error) {
+                    turnSpan.recordException(err);
+                }
                 logger.error("[GoogleVertex] Native Anthropic SDK stream error", err);
                 channel.error(this.handleProviderError(err));
             }
             finally {
+                turnSpan.end();
                 options.abortSignal?.removeEventListener("abort", abortHandler);
                 clearTimeout(streamTimeoutHandle);
             }
@@ -3316,6 +3525,15 @@ export class GoogleVertexProvider extends BaseProvider {
             const inputPrompt = mergedOptions.input?.text ||
                 mergedOptions.prompt ||
                 "";
+            // Set generation input before the call so error paths still carry the
+            // request; output is set after the native call resolves.
+            const generationInputAttribute = spanJsonAttribute({
+                ...(mergedOptions.systemPrompt
+                    ? { system: mergedOptions.systemPrompt }
+                    : {}),
+                prompt: inputPrompt,
+            });
+            generateSpan.setAttribute(LANGFUSE_ATTR.OBSERVATION_INPUT, generationInputAttribute);
             try {
                 let result;
                 // Wrap the actual native generate call in `neurolink.executeGeneration`
@@ -3332,20 +3550,28 @@ export class GoogleVertexProvider extends BaseProvider {
                         "neurolink.path": isAnthropicModel(modelName)
                             ? "native.anthropic"
                             : "native.google-genai",
+                        [LANGFUSE_ATTR.OBSERVATION_INPUT]: generationInputAttribute,
                     },
-                }, async () => {
+                }, async (executionSpan) => {
+                    let nativeResult;
                     if (isAnthropicModel(modelName)) {
                         logger.info("[GoogleVertex] Routing Claude generate to native @anthropic-ai/vertex-sdk", {
                             model: modelName,
                             totalToolCount: Object.keys(mergedOptions.tools).length,
                         });
-                        return this.executeNativeAnthropicGenerate(mergedOptions);
+                        nativeResult =
+                            await this.executeNativeAnthropicGenerate(mergedOptions);
                     }
-                    logger.info("[GoogleVertex] Routing Gemini generate to native @google/genai", {
-                        model: modelName,
-                        totalToolCount: Object.keys(mergedOptions.tools).length,
-                    });
-                    return this.executeNativeGemini3Generate(mergedOptions);
+                    else {
+                        logger.info("[GoogleVertex] Routing Gemini generate to native @google/genai", {
+                            model: modelName,
+                            totalToolCount: Object.keys(mergedOptions.tools).length,
+                        });
+                        nativeResult =
+                            await this.executeNativeGemini3Generate(mergedOptions);
+                    }
+                    executionSpan.setAttribute(LANGFUSE_ATTR.OBSERVATION_OUTPUT, spanJsonAttribute(nativeResult?.content ?? ""));
+                    return nativeResult;
                 });
                 this.attachUsageAndCostAttributes(generateSpan, modelName, result?.usage);
                 // Pipe through TTS-of-AI-response when caller asks for it. The
@@ -3353,6 +3579,7 @@ export class GoogleVertexProvider extends BaseProvider {
                 // 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, spanJsonAttribute(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

package/dist/services/server/ai/observability/instrumentation.d.ts

@@ -6,7 +6,7 @@
  *
  * Flow: Vercel AI SDK → OpenTelemetry Spans → LangfuseSpanProcessor → Langfuse Platform
  */
-import { trace } from "@opentelemetry/api";
+import { trace, type Span as ApiSpan } from "@opentelemetry/api";
 import { LoggerProvider } from "@opentelemetry/sdk-logs";
 import { type SpanProcessor } from "@opentelemetry/sdk-trace-base";
 import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
@@ -146,6 +146,15 @@ export declare function setLangfuseContext<T = void>(context: {
  * console.log(context?.userId, context?.sessionId);
  */
 export declare function getLangfuseContext(): LangfuseContext | undefined;
+/**
+ * Fill a span's Langfuse identity when the caller's context would otherwise
+ * fall back to "guest". Identity (user.id / session.id) is set additively —
+ * only fields ambient context didn't already provide, so a host's own context
+ * is never overridden. trace.name (the title) is rescued only when no ambient
+ * name source exists AND this span is the trace root, mirroring
+ * ContextEnricher.onStart so a host wrapper span isn't relabelled.
+ */
+export declare function stampGuestRescueIdentity(span: ApiSpan, callContext: unknown, isRootSpan: boolean): void;
 /**
  * Capture the current Langfuse AsyncLocalStorage context and return a wrapper
  * that re-enters that context when executing the provided callback.

package/dist/services/server/ai/observability/instrumentation.js

@@ -6,7 +6,7 @@
  *
  * Flow: Vercel AI SDK → OpenTelemetry Spans → LangfuseSpanProcessor → Langfuse Platform
  */
-import { metrics, SpanStatusCode, trace } from "@opentelemetry/api";
+import { metrics, SpanStatusCode, trace, } from "@opentelemetry/api";
 import { W3CTraceContextPropagator } from "@opentelemetry/core";
 import { OTLPLogExporter } from "@opentelemetry/exporter-logs-otlp-http";
 import { OTLPMetricExporter } from "@opentelemetry/exporter-metrics-otlp-http";
@@ -20,6 +20,7 @@ import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION, } from "@opentelemetry/semanti
 import { AsyncLocalStorage } from "async_hooks";
 import { extractMcpErrorText } from "../../../../utils/mcpErrorText.js";
 import { logger } from "../../../../utils/logger.js";
+import { LANGFUSE_ATTR } from "../../../../telemetry/attributes.js";
 const LOG_PREFIX = "[OpenTelemetry]";
 function createOtelResource(config, serviceName) {
     return resourceFromAttributes({
@@ -1117,6 +1118,40 @@ export async function setLangfuseContext(context, callback) {
 export function getLangfuseContext() {
     return contextStorage.getStore();
 }
+/**
+ * Fill a span's Langfuse identity when the caller's context would otherwise
+ * fall back to "guest". Identity (user.id / session.id) is set additively —
+ * only fields ambient context didn't already provide, so a host's own context
+ * is never overridden. trace.name (the title) is rescued only when no ambient
+ * name source exists AND this span is the trace root, mirroring
+ * ContextEnricher.onStart so a host wrapper span isn't relabelled.
+ */
+export function stampGuestRescueIdentity(span, callContext, isRootSpan) {
+    const ambient = getLangfuseContext();
+    const ctx = callContext;
+    const userId = typeof ctx?.userId === "string" && ctx.userId ? ctx.userId : undefined;
+    const sessionId = typeof ctx?.sessionId === "string" && ctx.sessionId
+        ? ctx.sessionId
+        : undefined;
+    // Title: the trace name comes from traceName ?? userId, so only rescue it
+    // from "guest" when ambient has neither, and only on the trace root.
+    if (isRootSpan && !ambient?.traceName && !ambient?.userId) {
+        const traceName = typeof ctx?.traceName === "string" && ctx.traceName
+            ? ctx.traceName
+            : userId;
+        if (traceName) {
+            span.setAttribute(LANGFUSE_ATTR.TRACE_NAME, traceName);
+            span.setAttribute("trace.name", traceName);
+        }
+    }
+    // Identity: additive — set each field only where ambient didn't.
+    if (userId && !ambient?.userId) {
+        span.setAttribute("user.id", userId);
+    }
+    if (sessionId && !ambient?.sessionId) {
+        span.setAttribute("session.id", sessionId);
+    }
+}
 /**
  * Capture the current Langfuse AsyncLocalStorage context and return a wrapper
  * that re-enters that context when executing the provided callback.

package/dist/telemetry/attributes.d.ts

@@ -103,3 +103,34 @@ export declare const ATTR: {
     readonly AR_DESCRIPTION: "autoresearch.description";
     readonly AR_ERROR_CODE: "autoresearch.error_code";
 };
+/**
+ * Langfuse observation/trace attribute names recognised by `@langfuse/otel`'s
+ * LangfuseSpanProcessor (already registered on the global TracerProvider). They
+ * let native (non-AI-SDK) provider paths emit spans that render as proper
+ * generation / tool observations — the same data the Vercel AI SDK's
+ * `experimental_telemetry` produced before providers moved to native SDKs.
+ */
+export declare const LANGFUSE_ATTR: {
+    readonly TRACE_NAME: "langfuse.trace.name";
+    readonly TRACE_INPUT: "langfuse.trace.input";
+    readonly TRACE_OUTPUT: "langfuse.trace.output";
+    readonly OBSERVATION_TYPE: "langfuse.observation.type";
+    readonly OBSERVATION_INPUT: "langfuse.observation.input";
+    readonly OBSERVATION_OUTPUT: "langfuse.observation.output";
+    readonly OBSERVATION_METADATA: "langfuse.observation.metadata";
+    readonly OBSERVATION_MODEL_NAME: "langfuse.observation.model.name";
+    readonly OBSERVATION_MODEL_PARAMETERS: "langfuse.observation.model.parameters";
+    readonly OBSERVATION_USAGE_DETAILS: "langfuse.observation.usage_details";
+    readonly OBSERVATION_LEVEL: "langfuse.observation.level";
+    readonly OBSERVATION_STATUS_MESSAGE: "langfuse.observation.status_message";
+    readonly OBSERVATION_COMPLETION_START_TIME: "langfuse.observation.completion_start_time";
+};
+/** Default ceiling for serialized span attribute values. */
+export declare const SPAN_ATTRIBUTE_MAX_CHARS = 40000;
+/**
+ * Serialize an arbitrary value for a span attribute, hard-capped at
+ * `maxChars` so a pathological prompt or tool result can't put megabytes
+ * on a single span. Strings pass through unserialized; everything else is
+ * JSON-stringified with a String() fallback for circular structures.
+ */
+export declare function spanJsonAttribute(value: unknown, maxChars?: number): string;

package/dist/telemetry/attributes.js

@@ -114,3 +114,51 @@ export const ATTR = {
     AR_DESCRIPTION: "autoresearch.description",
     AR_ERROR_CODE: "autoresearch.error_code",
 };
+/**
+ * Langfuse observation/trace attribute names recognised by `@langfuse/otel`'s
+ * LangfuseSpanProcessor (already registered on the global TracerProvider). They
+ * let native (non-AI-SDK) provider paths emit spans that render as proper
+ * generation / tool observations — the same data the Vercel AI SDK's
+ * `experimental_telemetry` produced before providers moved to native SDKs.
+ */
+export const LANGFUSE_ATTR = {
+    TRACE_NAME: "langfuse.trace.name",
+    TRACE_INPUT: "langfuse.trace.input",
+    TRACE_OUTPUT: "langfuse.trace.output",
+    OBSERVATION_TYPE: "langfuse.observation.type",
+    OBSERVATION_INPUT: "langfuse.observation.input",
+    OBSERVATION_OUTPUT: "langfuse.observation.output",
+    OBSERVATION_METADATA: "langfuse.observation.metadata",
+    OBSERVATION_MODEL_NAME: "langfuse.observation.model.name",
+    OBSERVATION_MODEL_PARAMETERS: "langfuse.observation.model.parameters",
+    OBSERVATION_USAGE_DETAILS: "langfuse.observation.usage_details",
+    OBSERVATION_LEVEL: "langfuse.observation.level",
+    OBSERVATION_STATUS_MESSAGE: "langfuse.observation.status_message",
+    OBSERVATION_COMPLETION_START_TIME: "langfuse.observation.completion_start_time",
+};
+/** Default ceiling for serialized span attribute values. */
+export const SPAN_ATTRIBUTE_MAX_CHARS = 40_000;
+/**
+ * Serialize an arbitrary value for a span attribute, hard-capped at
+ * `maxChars` so a pathological prompt or tool result can't put megabytes
+ * on a single span. Strings pass through unserialized; everything else is
+ * JSON-stringified with a String() fallback for circular structures.
+ */
+export function spanJsonAttribute(value, maxChars = SPAN_ATTRIBUTE_MAX_CHARS) {
+    let serialized;
+    try {
+        serialized =
+            typeof value === "string"
+                ? value
+                : (JSON.stringify(value) ?? String(value));
+    }
+    catch {
+        serialized = String(value);
+    }
+    if (serialized.length > maxChars) {
+        const truncationSuffix = `...[truncated ${serialized.length - maxChars} chars]`;
+        const keepLength = Math.max(0, maxChars - truncationSuffix.length);
+        return `${serialized.slice(0, keepLength)}${truncationSuffix}`;
+    }
+    return serialized;
+}

package/dist/telemetry/index.d.ts

@@ -1,7 +1,7 @@
 export { TelemetryService } from "./telemetryService.js";
 export { tracers } from "./tracers.js";
 export { withSpan, withClientSpan, withStreamSpan, withClientStreamSpan, } from "./withSpan.js";
-export { ATTR } from "./attributes.js";
+export { ATTR, LANGFUSE_ATTR, SPAN_ATTRIBUTE_MAX_CHARS, spanJsonAttribute, } from "./attributes.js";
 /**
  * Initialize telemetry for NeuroLink
  * Reuses an existing global TracerProvider when one is already registered,

package/dist/telemetry/index.js

@@ -2,7 +2,7 @@
 export { TelemetryService } from "./telemetryService.js";
 export { tracers } from "./tracers.js";
 export { withSpan, withClientSpan, withStreamSpan, withClientStreamSpan, } from "./withSpan.js";
-export { ATTR } from "./attributes.js";
+export { ATTR, LANGFUSE_ATTR, SPAN_ATTRIBUTE_MAX_CHARS, spanJsonAttribute, } from "./attributes.js";
 import { logger } from "../utils/logger.js";
 /**
  * Initialize telemetry for NeuroLink

package/dist/types/config.d.ts

@@ -9,6 +9,7 @@ import type { ConversationMemoryConfig } from "./conversation.js";
 import type { ObservabilityConfig } from "./observability.js";
 import type { AuthProvider, AuthProviderType, AuthProviderConfig, Auth0Config, ClerkConfig, FirebaseConfig, SupabaseConfig, WorkOSConfig, BetterAuthConfig, JWTConfig, OAuth2Config, CognitoConfig, KeycloakConfig, AuthenticatedContext } from "./auth.js";
 import type { NeurolinkCredentials } from "./providers.js";
+import type { ToolRoutingConfig } from "./toolRouting.js";
 /**
  * Main NeuroLink configuration type
  */
@@ -66,6 +67,13 @@ export type NeurolinkConstructorConfig = {
      * provider is preserved across the chain; only the model name changes.
      */
     modelChain?: string[];
+    /**
+     * Pre-call tool routing: a cheap router LLM picks the tool servers
+     * relevant to each stream() turn and the unpicked servers' tools are
+     * dropped from the request via `excludeTools`. Fails open (all tools) on
+     * any router failure. See {@link ToolRoutingConfig}.
+     */
+    toolRouting?: ToolRoutingConfig;
 };
 /**
  * Configuration for MCP enhancement modules wired into generate()/stream() paths.

package/dist/types/index.d.ts

@@ -50,6 +50,7 @@ export * from "./stream.js";
 export * from "./subscription.js";
 export * from "./task.js";
 export * from "./taskClassification.js";
+export * from "./toolRouting.js";
 export * from "./tools.js";
 export * from "./voice.js";
 export * from "./universalProviderOptions.js";

package/dist/types/index.js

@@ -51,6 +51,7 @@ export * from "./stream.js";
 export * from "./subscription.js";
 export * from "./task.js";
 export * from "./taskClassification.js";
+export * from "./toolRouting.js";
 export * from "./tools.js";
 export * from "./voice.js";
 export * from "./universalProviderOptions.js";