@juspay/neurolink 12.58.1 → 13.0.0

package/dist/neurolink.js

@@ -12,7 +12,9 @@ import { beginOllamaDiagnostic, captureOllamaDiagnosticContext, completeOllamaDi
 // each suppressed dotenv's banner — one conditional, one unconditional.
 import { loadProcessDotenv } from "./utils/dotenvBootstrap.js";
 await loadProcessDotenv();
-import { SpanKind, SpanStatusCode, context, trace } from "@opentelemetry/api";
+import { SpanKind, SpanStatusCode, context, trace, } from "@opentelemetry/api";
+import { getPropagatedAttributesFromContext } from "@langfuse/core";
+import { LangfuseOtelSpanAttributes } from "@langfuse/tracing";
 import { AsyncLocalStorage } from "async_hooks";
 import { EventEmitter } from "events";
 import pLimit from "p-limit";
@@ -73,15 +75,18 @@ import { SpanSerializer } from "./observability/utils/spanSerializer.js";
 import { withSpan } from "./telemetry/withSpan.js";
 import { getActiveTraceContext } from "./telemetry/traceContext.js";
 import { calculateCost } from "./utils/pricing.js";
-import { flushOpenTelemetry, getLangfuseContext, getLangfuseHealthStatus, initializeOpenTelemetry, isOpenTelemetryInitialized, runWithCurrentLangfuseContext, setLangfuseContext, shutdownOpenTelemetry, stampGuestRescueIdentity, } from "./services/server/ai/observability/instrumentation.js";
+import { acquireTelemetry, ensureTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, isOpenTelemetryInitialized, releaseTelemetry, setLangfuseContext, traceMetadataFromContext, } from "./services/server/ai/observability/instrumentation.js";
 import { clearChecklistState, createChecklistTools, getChecklistState, resolveChecklistSessionId, } from "./agent/taskChecklist.js";
 import { cancelDelegates as cancelBackgroundDelegates, collectDelegates as collectBackgroundDelegates, configureDelegation, createDelegationTools, spawnDelegate as spawnBackgroundDelegate, } from "./agent/backgroundDelegation.js";
 import { awaitBackgroundCommand as awaitCommand, createBackgroundCommandTools, getBackgroundCommandStatus as getCommandStatus, killAllBackgroundCommands as killAllCommands, killBackgroundCommand as killCommand, readBackgroundCommandOutput as readCommandOutput, setBackgroundCommandPolicy as setCommandPolicy, startBackgroundCommand as startCommand, } from "./agent/backgroundCommands.js";
 import { configureGitTools, createGitTools, runGitCommand as runGitArgs, } from "./agent/gitTools.js";
 import { TaskManager } from "./tasks/taskManager.js";
 import { createTaskTools } from "./tasks/tools/taskTools.js";
-import { ATTR, spanJsonAttribute } from "./telemetry/attributes.js";
-import { tracers } from "./telemetry/tracers.js";
+import { ATTR, spanJsonAttribute, spanModelRequestAttribute, } from "./telemetry/attributes.js";
+import { assistantMessages } from "./telemetry/chatMessages.js";
+import { observationLevel, observe, observeTrace, usageDetails, } from "./telemetry/observation.js";
+import { toolSpanName } from "./telemetry/observationNames.js";
+import { isNestedOperation, tracers } from "./telemetry/tracers.js";
 import { getConversationMessages, storeConversationTurn, } from "./utils/conversationMemory.js";
 // Enhanced error handling imports
 import { CircuitBreaker, ERROR_CODES, ErrorFactory, isAbortError, isRetriableError, logStructuredError, NeuroLinkError, withRetry, withTimeout, } from "./utils/errorHandling.js";
@@ -363,6 +368,147 @@ function createTypedEmitter() {
     const emitter = new EventEmitter();
     return emitter;
 }
+function turnInput(optionsOrPrompt) {
+    if (typeof optionsOrPrompt === "string") {
+        return spanModelRequestAttribute({ prompt: optionsOrPrompt });
+    }
+    const options = optionsOrPrompt;
+    return spanModelRequestAttribute({
+        messages: options.conversationMessages,
+        prompt: options.input?.text,
+    });
+}
+function observeTurn(span, attrs) {
+    observe(span, "agent", attrs);
+    if (!isNestedOperation(span)) {
+        observeTrace(span, { input: attrs.input, output: attrs.output });
+    }
+}
+function startTurn(span, optionsOrPrompt) {
+    observeTurn(span, { input: turnInput(optionsOrPrompt) });
+    if (typeof optionsOrPrompt !== "string") {
+        const name = optionsOrPrompt.context?.observationName;
+        if (name) {
+            span.updateName(name);
+        }
+    }
+    if (!isNestedOperation(span)) {
+        observeTrace(span, {
+            metadata: traceMetadataFromContext(context.active()),
+        });
+    }
+}
+function failTurnSpan(span, error) {
+    const message = error.message;
+    if (isAbortError(error)) {
+        observeTurn(span, {
+            output: message,
+            level: "WARNING",
+            statusMessage: message,
+        });
+        return;
+    }
+    span.recordException(error);
+    span.setStatus({ code: SpanStatusCode.ERROR, message });
+    observeTurn(span, {
+        output: message,
+        level: "ERROR",
+        statusMessage: message,
+    });
+}
+function traceTurnStream(result, span, turnContext) {
+    const iterator = result.stream[Symbol.asyncIterator]();
+    let output = "";
+    let ended = false;
+    let started = false;
+    const finish = () => {
+        ended = true;
+        span.end();
+    };
+    const end = (level, statusMessage) => {
+        observeTurn(span, {
+            output: output ? assistantMessages(output) : undefined,
+            metadata: { model: result.model },
+            level,
+            statusMessage,
+        });
+        finish();
+    };
+    const close = async () => {
+        if (ended) {
+            return;
+        }
+        try {
+            await context.with(turnContext, async () => {
+                await iterator.return?.();
+            });
+        }
+        finally {
+            end("WARNING", started
+                ? "stream closed by the consumer before it finished"
+                : "stream closed before first chunk");
+        }
+    };
+    const traced = {
+        async next() {
+            if (ended) {
+                return { done: true, value: undefined };
+            }
+            started = true;
+            try {
+                const step = await context.with(turnContext, () => iterator.next());
+                if (step.done) {
+                    span.setStatus({ code: SpanStatusCode.OK });
+                    end(observationLevel(result.finishReason));
+                    return { done: true, value: undefined };
+                }
+                const content = typeof step.value === "object" && step.value !== null
+                    ? step.value.content
+                    : undefined;
+                if (typeof content === "string") {
+                    output += content;
+                }
+                return step;
+            }
+            catch (error) {
+                failTurnSpan(span, error instanceof Error ? error : new Error(String(error)));
+                finish();
+                throw error;
+            }
+        },
+        async return() {
+            await close();
+            return { done: true, value: undefined };
+        },
+        async throw(error) {
+            await close();
+            throw error;
+        },
+        [Symbol.asyncIterator]() {
+            return traced;
+        },
+    };
+    return traced;
+}
+function drainInContext(stream, drainContext) {
+    return (async function* () {
+        const iterator = stream[Symbol.asyncIterator]();
+        try {
+            while (true) {
+                const step = await context.with(drainContext, () => iterator.next());
+                if (step.done) {
+                    return;
+                }
+                yield step.value;
+            }
+        }
+        finally {
+            await context.with(drainContext, async () => {
+                await iterator.return?.();
+            });
+        }
+    })();
+}
 /** Monotonic source for {@link NeuroLink.logInstanceId}. Process-local by design. */
 let neuroLinkInstanceCounter = 0;
 export class NeuroLink {
@@ -633,78 +779,28 @@ export class NeuroLink {
     // `undefined` = not yet attempted, `null` = init failed (stay disabled).
     skillsManagerInstance;
     skillsConfig;
-    /**
-     * Extract and set Langfuse context from options with proper async scoping
-     */
     async setLangfuseContextFromOptions(options, callback) {
-        if (options.context &&
-            typeof options.context === "object" &&
-            options.context !== null) {
-            let callbackExecuted = false;
-            try {
-                const ctx = options.context;
-                // Trigger context scoping if any meaningful Langfuse field is present
-                if (ctx.userId ||
-                    ctx.sessionId ||
-                    ctx.conversationId ||
-                    ctx.requestId ||
-                    ctx.traceName ||
-                    ctx.metadata) {
-                    // Build customAttributes from top-level metadata string/number/boolean fields
-                    let customAttributes;
-                    if (ctx.metadata && typeof ctx.metadata === "object") {
-                        const metaObj = ctx.metadata;
-                        const attrs = {};
-                        for (const [k, v] of Object.entries(metaObj)) {
-                            if (typeof v === "string" ||
-                                typeof v === "number" ||
-                                typeof v === "boolean") {
-                                attrs[k] = v;
-                            }
-                        }
-                        if (Object.keys(attrs).length > 0) {
-                            customAttributes = attrs;
-                        }
-                    }
-                    return await new Promise((resolve, reject) => {
-                        setLangfuseContext({
-                            userId: typeof ctx.userId === "string" ? ctx.userId : null,
-                            sessionId: typeof ctx.sessionId === "string" ? ctx.sessionId : null,
-                            conversationId: typeof ctx.conversationId === "string"
-                                ? ctx.conversationId
-                                : null,
-                            requestId: typeof ctx.requestId === "string" ? ctx.requestId : null,
-                            traceName: typeof ctx.traceName === "string" ? ctx.traceName : null,
-                            metadata: ctx.metadata && typeof ctx.metadata === "object"
-                                ? ctx.metadata
-                                : null,
-                            ...(customAttributes !== undefined && { customAttributes }),
-                        }, async () => {
-                            try {
-                                callbackExecuted = true;
-                                const result = await callback();
-                                resolve(result);
-                            }
-                            catch (error) {
-                                reject(error);
-                            }
-                        });
-                    });
-                }
-            }
-            catch (error) {
-                if (callbackExecuted) {
-                    // Callback was executed inside Langfuse context but failed — do NOT retry
-                    // Re-throw to avoid double API calls and preserve error context
-                    throw error;
-                }
-                // Langfuse context setup itself failed — graceful degradation, run without context
-                logger.warn("Failed to set Langfuse context from options", {
-                    error: error instanceof Error ? error.message : String(error),
-                });
-            }
-        }
-        return await callback();
+        if (!options.context || typeof options.context !== "object") {
+            return await callback();
+        }
+        const ctx = options.context;
+        const outer = getPropagatedAttributesFromContext(context.active());
+        const unset = (key, value) => typeof value === "string" && !outer[key] ? value : undefined;
+        return await setLangfuseContext({
+            userId: unset(LangfuseOtelSpanAttributes.TRACE_USER_ID, ctx.userId),
+            sessionId: unset(LangfuseOtelSpanAttributes.TRACE_SESSION_ID, ctx.sessionId),
+            conversationId: typeof ctx.conversationId === "string"
+                ? ctx.conversationId
+                : undefined,
+            requestId: typeof ctx.requestId === "string" ? ctx.requestId : undefined,
+            traceName: unset(LangfuseOtelSpanAttributes.TRACE_NAME, ctx.traceName),
+            tags: Array.isArray(ctx.tags)
+                ? ctx.tags.filter((tag) => typeof tag === "string")
+                : undefined,
+            metadata: ctx.metadata && typeof ctx.metadata === "object"
+                ? ctx.metadata
+                : undefined,
+        }, callback);
     }
     createMetricsTraceContext() {
         // Attempt to reuse the active OTel trace context so Pipeline B spans
@@ -981,26 +1077,12 @@ export class NeuroLink {
         const previousSink = logger.getEventEmitter();
         const credentials = this.conversationMemoryConfig?.conversationMemory?.memory?.neurolink
             ?.credentials ?? this.credentials;
-        const hostLangfuse = this.observabilityConfig?.langfuse;
         this.memoryCondenser = new NeuroLink({
             ...(credentials ? { credentials } : {}),
             conversationMemory: { enabled: false },
             enableOrchestration: false,
             ...(this.observabilityConfig
-                ? {
-                    observability: {
-                        ...this.observabilityConfig,
-                        ...(hostLangfuse
-                            ? {
-                                langfuse: {
-                                    ...hostLangfuse,
-                                    autoDetectExternalProvider: true,
-                                    skipLangfuseSpanProcessor: true,
-                                },
-                            }
-                            : {}),
-                    },
-                }
+                ? { observability: this.observabilityConfig }
                 : {}),
         });
         if (previousSink) {
@@ -1113,6 +1195,7 @@ export class NeuroLink {
      * @throws {Error} When HITL configuration is invalid (if enabled)
      */
     observabilityConfig;
+    telemetryHeld = false;
     metricsAggregator = new MetricsAggregator();
     analyticsService;
     /**
@@ -1135,6 +1218,9 @@ export class NeuroLink {
         }
         this.fileRegistry = new FileReferenceRegistry();
         this.observabilityConfig = config?.observability;
+        if (this.observabilityConfig) {
+            ensureTelemetry(this.observabilityConfig);
+        }
         this.analyticsService = new AnalyticsService();
         // Initialize orchestration setting
         this.enableOrchestration = config?.enableOrchestration ?? false;
@@ -1230,7 +1316,6 @@ export class NeuroLink {
             this.skillsConfig = config.skills;
             this.registerSkillTools();
         }
-        this.initializeLangfuse(constructorId, constructorStartTime, constructorHrTimeStart);
         this.initializeMetricsListeners();
         this.logConstructorComplete(constructorId, constructorStartTime, constructorHrTimeStart);
         // Store auth config for lazy initialization
@@ -2195,20 +2280,14 @@ Current user's request: ${currentInput}`;
                 logger.warn("Memory storage failed:", error);
             }
         };
-        // Carry the turn's identity across the setImmediate boundary so the
-        // condensation generate + redis spans don't orphan to "guest". Keep the
-        // ambient store when it survived (generate path — carries conversationId,
-        // metadata, …); re-establish from the caller only when it was lost (stream
-        // path, which fires after the caller consumed the stream).
-        const ambient = getLangfuseContext();
-        const wrappedMemoryWrite = !(ambient?.traceName || ambient?.userId) &&
-            (langfuseIdentity?.traceName || langfuseIdentity?.sessionId)
+        const identifiedMemoryWrite = langfuseIdentity?.traceName || langfuseIdentity?.sessionId
             ? () => setLangfuseContext({
                 userId,
-                sessionId: langfuseIdentity.sessionId ?? null,
-                traceName: langfuseIdentity.traceName ?? null,
+                sessionId: langfuseIdentity.sessionId ?? undefined,
+                traceName: langfuseIdentity.traceName ?? undefined,
             }, memoryWrite)
-            : runWithCurrentLangfuseContext(memoryWrite);
+            : memoryWrite;
+        const wrappedMemoryWrite = context.bind(context.active(), identifiedMemoryWrite);
         // Tracked from the moment it is scheduled, not from when setImmediate
         // fires: shutdown() typically runs in that gap, and a write it cannot
         // see is a write it cannot wait for. `memoryWrite` never rejects (it
@@ -2367,87 +2446,19 @@ Current user's request: ${currentInput}`;
             this.unregisterExternalMCPToolFromRegistry(event.toolName);
         });
     }
-    /**
-     * Initialize Langfuse observability for AI operations tracking
-     */
-    initializeLangfuse(constructorId, constructorStartTime, constructorHrTimeStart) {
-        const langfuseInitStartTime = process.hrtime.bigint();
-        try {
-            const langfuseConfig = this.observabilityConfig?.langfuse;
-            // Check if we should use external provider mode - bypass enabled check
-            const useExternalProvider = langfuseConfig?.autoDetectExternalProvider === true ||
-                langfuseConfig?.useExternalTracerProvider === true;
-            if (langfuseConfig?.enabled || useExternalProvider) {
-                logger.debug(`[NeuroLink] 📊 LOG_POINT_C019_LANGFUSE_INIT_START`, {
-                    logPoint: "C019_LANGFUSE_INIT_START",
-                    constructorId,
-                    timestamp: new Date().toISOString(),
-                    elapsedMs: Date.now() - constructorStartTime,
-                    elapsedNs: (process.hrtime.bigint() - constructorHrTimeStart).toString(),
-                    langfuseInitStartTimeNs: langfuseInitStartTime.toString(),
-                    message: "Starting Langfuse observability initialization",
-                });
-                // Initialize OpenTelemetry (sets defaults from config)
-                void initializeOpenTelemetry(langfuseConfig).catch((err) => {
-                    logger.error("[NeuroLink] OpenTelemetry initialization failed", {
-                        error: err instanceof Error ? err.message : String(err),
-                    });
-                });
-                const healthStatus = getLangfuseHealthStatus();
-                const langfuseInitDurationNs = process.hrtime.bigint() - langfuseInitStartTime;
-                if (healthStatus.initialized &&
-                    healthStatus.hasProcessor &&
-                    healthStatus.isHealthy) {
-                    logger.debug(`[NeuroLink] ✅ LOG_POINT_C020_LANGFUSE_INIT_SUCCESS`, {
-                        logPoint: "C020_LANGFUSE_INIT_SUCCESS",
-                        constructorId,
-                        timestamp: new Date().toISOString(),
-                        elapsedMs: Date.now() - constructorStartTime,
-                        elapsedNs: (process.hrtime.bigint() - constructorHrTimeStart).toString(),
-                        langfuseInitDurationNs: langfuseInitDurationNs.toString(),
-                        langfuseInitDurationMs: Number(langfuseInitDurationNs) / 1_000_000,
-                        healthStatus,
-                        message: "Langfuse observability initialized successfully",
-                    });
-                }
-                else {
-                    logger.warn(`[NeuroLink] ⚠️ LOG_POINT_C021_LANGFUSE_INIT_WARNING`, {
-                        logPoint: "C021_LANGFUSE_INIT_WARNING",
-                        constructorId,
-                        timestamp: new Date().toISOString(),
-                        elapsedMs: Date.now() - constructorStartTime,
-                        elapsedNs: (process.hrtime.bigint() - constructorHrTimeStart).toString(),
-                        langfuseInitDurationNs: langfuseInitDurationNs.toString(),
-                        healthStatus,
-                        message: "Langfuse initialized but not healthy",
-                    });
-                }
-            }
-            else {
-                logger.debug(`[NeuroLink] 🚫 LOG_POINT_C022_LANGFUSE_DISABLED`, {
-                    logPoint: "C022_LANGFUSE_DISABLED",
-                    constructorId,
-                    timestamp: new Date().toISOString(),
-                    elapsedMs: Date.now() - constructorStartTime,
-                    elapsedNs: (process.hrtime.bigint() - constructorHrTimeStart).toString(),
-                    message: "Langfuse observability not enabled - skipping initialization",
-                });
-            }
+    holdTelemetry() {
+        if (!this.telemetryHeld) {
+            this.telemetryHeld = true;
+            acquireTelemetry(this.observabilityConfig);
         }
-        catch (error) {
-            const langfuseInitErrorDurationNs = process.hrtime.bigint() - langfuseInitStartTime;
-            logger.error(`[NeuroLink] ❌ LOG_POINT_C023_LANGFUSE_INIT_ERROR`, {
-                logPoint: "C023_LANGFUSE_INIT_ERROR",
-                constructorId,
-                timestamp: new Date().toISOString(),
-                elapsedMs: Date.now() - constructorStartTime,
-                elapsedNs: (process.hrtime.bigint() - constructorHrTimeStart).toString(),
-                langfuseInitDurationNs: langfuseInitErrorDurationNs.toString(),
-                errorMessage: error instanceof Error ? error.message : String(error),
-                errorStack: error instanceof Error ? error.stack : undefined,
-                message: "Langfuse observability initialization failed",
-            });
+    }
+    async releaseTelemetryHold() {
+        if (!this.telemetryHeld) {
+            await flushOpenTelemetry();
+            return;
         }
+        this.telemetryHeld = false;
+        await releaseTelemetry();
     }
     /**
      * Log constructor completion with final state summary
@@ -3099,47 +3110,36 @@ Current user's request: ${currentInput}`;
         return this.observabilityConfig;
     }
     /**
-     * Check if Langfuse telemetry is enabled
-     * Centralized utility to avoid duplication across providers
+     * @description Reports whether any tracing backend is active.
+     * @returns {boolean} `true` when OpenTelemetry is initialized or a Langfuse exporter is running.
      */
     isTelemetryEnabled() {
-        // Check if observability config enables telemetry
-        if (this.observabilityConfig?.langfuse?.enabled) {
-            return true;
-        }
-        // Check if OpenTelemetry was initialized (by this or external app)
-        return isOpenTelemetryInitialized();
+        return (isOpenTelemetryInitialized() || getLangfuseHealthStatus().hasProcessor);
     }
     /**
-     * Get comprehensive telemetry status including Langfuse, OTel, and exporter health
+     * Get comprehensive telemetry status including Langfuse and OpenTelemetry state
      */
     getTelemetryStatus() {
         const langfuseConfig = this.observabilityConfig?.langfuse;
-        const otelConfig = this.observabilityConfig?.openTelemetry;
+        const langfuseOptions = typeof langfuseConfig === "object" ? langfuseConfig : undefined;
+        const { hasProcessor } = getLangfuseHealthStatus();
         return {
-            enabled: this.isTelemetryEnabled(),
-            langfuse: langfuseConfig
+            enabled: isOpenTelemetryInitialized(),
+            langfuse: langfuseConfig !== undefined || hasProcessor
                 ? {
-                    enabled: langfuseConfig.enabled ?? false,
-                    baseUrl: langfuseConfig.baseUrl,
-                    environment: langfuseConfig.environment,
+                    enabled: hasProcessor,
+                    baseUrl: langfuseOptions?.baseUrl ?? process.env.LANGFUSE_BASE_URL,
+                    environment: langfuseOptions?.environment ??
+                        process.env.LANGFUSE_TRACING_ENVIRONMENT,
                 }
                 : undefined,
-            openTelemetry: otelConfig
+            openTelemetry: isOpenTelemetryInitialized() || process.env.OTEL_EXPORTER_OTLP_ENDPOINT
                 ? {
-                    enabled: otelConfig.enabled ?? false,
-                    endpoint: otelConfig.endpoint,
-                    serviceName: otelConfig.serviceName,
+                    enabled: isOpenTelemetryInitialized(),
+                    endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
+                    serviceName: process.env.OTEL_SERVICE_NAME,
                 }
-                : isOpenTelemetryInitialized() ||
-                    process.env.OTEL_EXPORTER_OTLP_ENDPOINT
-                    ? {
-                        enabled: isOpenTelemetryInitialized(),
-                        endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
-                        serviceName: process.env.OTEL_SERVICE_NAME,
-                    }
-                    : undefined,
-            exporters: [],
+                : undefined,
         };
     }
     /**
@@ -3229,27 +3229,7 @@ Current user's request: ${currentInput}`;
      * This method can be called externally to ensure Langfuse is properly initialized
      */
     async initializeLangfuseObservability() {
-        try {
-            const langfuseConfig = this.observabilityConfig?.langfuse;
-            if (langfuseConfig?.enabled) {
-                try {
-                    await initializeOpenTelemetry(langfuseConfig);
-                }
-                catch (err) {
-                    logger.error("[NeuroLink] OpenTelemetry initialization failed", {
-                        error: err instanceof Error ? err.message : String(err),
-                    });
-                    return;
-                }
-                logger.debug("[NeuroLink] Langfuse observability initialized via public method");
-            }
-            else {
-                logger.debug("[NeuroLink] Langfuse not enabled, skipping initialization");
-            }
-        }
-        catch (error) {
-            logger.warn("[NeuroLink] Failed to initialize Langfuse observability:", error);
-        }
+        this.holdTelemetry();
     }
     /**
      * Gracefully shutdown NeuroLink and all MCP connections
@@ -3275,8 +3255,7 @@ Current user's request: ${currentInput}`;
                 logger.warn("[NeuroLink] Memory condenser shutdown failed:", error);
             }
             try {
-                await flushOpenTelemetry();
-                await shutdownOpenTelemetry();
+                await this.releaseTelemetryHold();
                 logger.debug("[NeuroLink] OpenTelemetry shutdown completed");
             }
             catch (error) {
@@ -3357,13 +3336,11 @@ Current user's request: ${currentInput}`;
         return totalCost > 0 ? totalCost : undefined;
     }
     /**
-     * Handle generation:end for Pipeline B spans + advanced analytics.
-     * When pipelineAHandled is set, skips Pipeline B spans but still tracks
-     * analytics so successful AI-SDK generate/stream calls are recorded.
-     * Stream analytics are owned here (not stream:complete) to avoid duplicates.
+     * Handle generation:end: records advanced analytics for every generation
+     * and the metrics span for a non-streamed one. A streamed generation gets
+     * its span from stream:complete / stream:error instead.
      */
     handleGenerationEndMetrics(data) {
-        const skipPipelineBSpan = data.pipelineAHandled === true;
         try {
             const result = data.result;
             const usage = result?.usage;
@@ -3375,10 +3352,16 @@ Current user's request: ${currentInput}`;
                 ? data.timestamp
                 : Date.now();
             const traceCtx = this._metricsTraceContext;
-            let computedCost = typeof analytics?.cost === "number" && Number.isFinite(analytics.cost)
+            const reportedCost = typeof analytics?.cost === "number" && Number.isFinite(analytics.cost)
                 ? analytics.cost
                 : undefined;
-            if (!skipPipelineBSpan) {
+            const cost = reportedCost !== undefined && reportedCost > 0
+                ? reportedCost
+                : (this.estimateCostFromUsage(provider, model, usage) ??
+                    reportedCost);
+            const aborted = data.aborted === true;
+            const failed = !aborted && (data.success === false || !!data.error);
+            if (data.streamed !== true) {
                 let span = SpanSerializer.createGenerationSpan({
                     provider,
                     model,
@@ -3424,18 +3407,8 @@ Current user's request: ${currentInput}`;
                         totalTokens: usage.total || (usage.input || 0) + (usage.output || 0),
                     });
                 }
-                if (analytics?.cost && analytics.cost > 0) {
-                    span = SpanSerializer.enrichWithCost(span, {
-                        totalCost: analytics.cost,
-                    });
-                }
-                else {
-                    const estimated = this.estimateCostFromUsage(provider, model, usage);
-                    if (estimated !== undefined) {
-                        span = SpanSerializer.enrichWithCost(span, {
-                            totalCost: estimated,
-                        });
-                    }
+                if (cost !== undefined && cost > 0) {
+                    span = SpanSerializer.enrichWithCost(span, { totalCost: cost });
                 }
                 const content = result?.content || result?.text;
                 if (content) {
@@ -3447,50 +3420,27 @@ Current user's request: ${currentInput}`;
                 }
                 this.metricsAggregator.recordSpan(span);
                 getMetricsAggregator().recordSpan(span);
-                const spanCost = span.attributes["ai.cost.total"];
-                if (typeof spanCost === "number" && spanCost > 0) {
-                    computedCost = spanCost;
-                }
-                this.enqueueAnalyticsTrackRequest({
-                    provider,
-                    model,
-                    userId: data.userId || data.user || undefined,
-                    teamId: data.teamId || undefined,
-                    department: data.department || undefined,
-                    timestamp: eventTimestamp,
-                    latency: responseTime,
-                    inputTokens: usage?.input || 0,
-                    outputTokens: usage?.output || 0,
-                    totalTokens: usage?.total || (usage?.input || 0) + (usage?.output || 0),
-                    cost: computedCost,
-                    isError: span.status === SpanStatus.ERROR,
-                    errorMessage: statusMessage,
-                    qualityScore: parseAnalyticsQualityScore(data.qualityScore),
-                });
-            }
-            else {
-                // Pipeline A handled the observation — still record analytics so
-                // successful AI-SDK generate()/stream() calls are not silently dropped.
-                if (computedCost === undefined) {
-                    computedCost = this.estimateCostFromUsage(provider, model, usage);
-                }
-                this.enqueueAnalyticsTrackRequest({
-                    provider,
-                    model,
-                    userId: data.userId || data.user || undefined,
-                    teamId: data.teamId || undefined,
-                    department: data.department || undefined,
-                    timestamp: eventTimestamp,
-                    latency: responseTime,
-                    inputTokens: usage?.input || 0,
-                    outputTokens: usage?.output || 0,
-                    totalTokens: usage?.total || (usage?.input || 0) + (usage?.output || 0),
-                    cost: computedCost,
-                    isError: data.success === false || Boolean(data.error),
-                    errorMessage: data.error ? String(data.error) : undefined,
-                    qualityScore: parseAnalyticsQualityScore(data.qualityScore),
-                });
             }
+            this.enqueueAnalyticsTrackRequest({
+                provider,
+                model,
+                userId: data.userId || data.user || undefined,
+                teamId: data.teamId || undefined,
+                department: data.department || undefined,
+                timestamp: eventTimestamp,
+                latency: responseTime,
+                inputTokens: usage?.input || 0,
+                outputTokens: usage?.output || 0,
+                totalTokens: usage?.total || (usage?.input || 0) + (usage?.output || 0),
+                cost,
+                isError: failed,
+                errorMessage: aborted
+                    ? "Generation aborted by client"
+                    : data.error
+                        ? String(data.error)
+                        : undefined,
+                qualityScore: parseAnalyticsQualityScore(data.qualityScore),
+            });
         }
         catch {
             // Non-blocking
@@ -3763,7 +3713,10 @@ Current user's request: ${currentInput}`;
      * @since 1.0.0
      */
     async generate(optionsOrPrompt) {
-        return logger.runInInstanceScope(this.logInstanceId, () => this.generateInInstanceScope(optionsOrPrompt));
+        return logger.runInInstanceScope(this.logInstanceId, async () => {
+            this.holdTelemetry();
+            return this.generateInInstanceScope(optionsOrPrompt);
+        });
     }
     /**
      * Body of {@link generate}, always entered through the instance log scope
@@ -3818,37 +3771,10 @@ Current user's request: ${currentInput}`;
                 };
             }
         }
-        // Retrieve once at the public call boundary so fallback attempts reuse the
-        // same grounding block and internal preparation cannot inject it twice.
-        const groundingOptions = typeof optionsOrPrompt === "string"
-            ? { input: { text: optionsOrPrompt } }
-            : optionsOrPrompt;
-        const knowledgeOutcome = await this.retrieveKnowledgeGrounding(groundingOptions);
-        if (knowledgeOutcome?.ephemeralContext) {
-            const block = knowledgeOutcome.ephemeralContext.content;
-            optionsOrPrompt = {
-                ...groundingOptions,
-                systemPrompt: this.appendKnowledgeGroundingBlockToSystemPrompt(groundingOptions.systemPrompt, block),
-            };
-        }
         const startedAt = Date.now();
+        const turnOptions = optionsOrPrompt;
         try {
-            const result = await this.runWithFallbackOrchestration(optionsOrPrompt, "generate", (opts) => {
-                // Capture root-ness before startActiveSpan makes generateSpan active.
-                // The actual guest-rescue stamp is deferred to executeGenerateRequest,
-                // AFTER prepareGenerateRequest merges auth/requestContext-derived
-                // identity into options.context — otherwise an auth:{token} caller
-                // with no pre-set context.userId would stamp the root span as guest.
-                const generateIsRoot = !trace.getSpan(context.active());
-                return tracers.sdk.startActiveSpan("neurolink.generate", { kind: SpanKind.INTERNAL }, (generateSpan) => this.executeGenerateWithMetricsContext(opts, generateSpan, generateIsRoot));
-            });
-            if (knowledgeOutcome) {
-                result.knowledge = knowledgeOutcome.metadata;
-            }
-            if (agentModeVersion) {
-                result.agentModeVersion = agentModeVersion;
-            }
-            return result;
+            return await this.setLangfuseContextFromOptions(typeof turnOptions === "string" ? {} : turnOptions, () => tracers.sdk.startActiveSpan("generate", { kind: SpanKind.INTERNAL }, (turnSpan) => this.runGenerateTurn(turnOptions, agentModeVersion, turnSpan)));
         }
         catch (error) {
             // Lifecycle middleware (wrapGenerate.catch in builtin/lifecycle.ts)
@@ -3863,6 +3789,49 @@ Current user's request: ${currentInput}`;
             throw error;
         }
     }
+    async runGenerateTurn(optionsOrPrompt, agentModeVersion, turnSpan) {
+        try {
+            const groundingOptions = typeof optionsOrPrompt === "string"
+                ? { input: { text: optionsOrPrompt } }
+                : optionsOrPrompt;
+            const knowledgeOutcome = await this.retrieveKnowledgeGrounding(groundingOptions);
+            if (knowledgeOutcome?.ephemeralContext) {
+                const block = knowledgeOutcome.ephemeralContext.content;
+                optionsOrPrompt = {
+                    ...groundingOptions,
+                    systemPrompt: this.appendKnowledgeGroundingBlockToSystemPrompt(groundingOptions.systemPrompt, block),
+                };
+            }
+            startTurn(turnSpan, optionsOrPrompt);
+            const result = await this.runWithFallbackOrchestration(optionsOrPrompt, "generate", (opts) => tracers.sdk.startActiveSpan("generate.attempt", { kind: SpanKind.INTERNAL }, (attemptSpan) => {
+                observe(attemptSpan, "span", {});
+                return this.executeGenerateWithMetricsContext(opts, attemptSpan);
+            }));
+            if (knowledgeOutcome) {
+                result.knowledge = knowledgeOutcome.metadata;
+            }
+            if (agentModeVersion) {
+                result.agentModeVersion = agentModeVersion;
+            }
+            observeTurn(turnSpan, {
+                output: assistantMessages({
+                    text: result.content,
+                    toolCalls: result.toolExecutions,
+                }),
+                metadata: { model: result.model },
+                level: observationLevel(result.finishReason),
+            });
+            turnSpan.setStatus({ code: SpanStatusCode.OK });
+            return result;
+        }
+        catch (error) {
+            failTurnSpan(turnSpan, error instanceof Error ? error : new Error(String(error)));
+            throw error;
+        }
+        finally {
+            turnSpan.end();
+        }
+    }
     async fireConsumerOnErrorIfNotFired(optionsOrPrompt, error, startedAt) {
         if (hasLifecycleErrorFired(error)) {
             return;
@@ -4053,17 +4022,14 @@ Current user's request: ${currentInput}`;
             return { error };
         }
     }
-    async executeGenerateWithMetricsContext(optionsOrPrompt, generateSpan, isRootSpan) {
-        return metricsTraceContextStorage.run(this.createMetricsTraceContext(), () => this.executeGenerateRequest(optionsOrPrompt, generateSpan, isRootSpan));
+    async executeGenerateWithMetricsContext(optionsOrPrompt, generateSpan) {
+        return metricsTraceContextStorage.run(this.createMetricsTraceContext(), () => this.executeGenerateRequest(optionsOrPrompt, generateSpan));
     }
-    async executeGenerateRequest(optionsOrPrompt, generateSpan, isRootSpan) {
+    async executeGenerateRequest(optionsOrPrompt, generateSpan) {
         let resolvedOptions;
         try {
             const { options, originalPrompt } = await this.prepareGenerateRequest(optionsOrPrompt, generateSpan);
             resolvedOptions = options;
-            // Stamp now that prepareGenerateRequest has merged any auth/requestContext
-            // identity into options.context (see capture of isRootSpan in generate()).
-            stampGuestRescueIdentity(generateSpan, options.context, isRootSpan);
             const earlyResult = await this.maybeHandleEarlyGenerateResult(options, generateSpan);
             if (earlyResult) {
                 generateSpan.setStatus({ code: SpanStatusCode.OK });
@@ -4081,14 +4047,9 @@ Current user's request: ${currentInput}`;
             return result;
         }
         catch (error) {
-            // Match the inner-span discrimination: client aborts are user-initiated
-            // cancellations, not faults. Mark with finishReason=aborted and skip
-            // ERROR status so ContextEnricher routes the outer trace to
-            // langfuse.level=WARNING (matches Curator telemetry-gaps Issue 5a). All
-            // other errors keep the existing ERROR status + recordException pair.
             if (isAbortError(error)) {
                 generateSpan.setAttribute("ai.finishReason", "aborted");
-                generateSpan.setAttribute("neurolink.aborted", true);
+                generateSpan.setAttribute("aborted", true);
             }
             else {
                 generateSpan.recordException(error instanceof Error ? error : new Error(String(error)));
@@ -4099,9 +4060,9 @@ Current user's request: ${currentInput}`;
             }
             // G7 fix: Distinguish context overflow errors with dedicated attributes
             if (error instanceof ContextBudgetExceededError) {
-                generateSpan.setAttribute("neurolink.error.type", "context_overflow");
-                generateSpan.setAttribute("neurolink.context.estimated_tokens", error.estimatedTokens);
-                generateSpan.setAttribute("neurolink.context.available_tokens", error.availableTokens);
+                generateSpan.setAttribute("error.type", "context_overflow");
+                generateSpan.setAttribute("context.estimated_tokens", error.estimatedTokens);
+                generateSpan.setAttribute("context.available_tokens", error.availableTokens);
             }
             this.emitGenerateErrorEvent((resolvedOptions ?? optionsOrPrompt), error);
             throw error;
@@ -4130,12 +4091,12 @@ Current user's request: ${currentInput}`;
         this._disableToolCacheForCurrentRequest = !!options.disableToolCache;
         this._toolCacheKeysServedThisRequest = new Set();
         this._generationTurnActive = true;
-        generateSpan.setAttribute("neurolink.provider", options.provider || "default");
-        generateSpan.setAttribute("neurolink.model", options.model || "default");
-        generateSpan.setAttribute("neurolink.input_length", typeof optionsOrPrompt === "string"
+        generateSpan.setAttribute("sdk.provider", options.provider || "default");
+        generateSpan.setAttribute("sdk.model", options.model || "default");
+        generateSpan.setAttribute("input_length", typeof optionsOrPrompt === "string"
             ? optionsOrPrompt.length
             : options.input?.text?.length || 0);
-        generateSpan.setAttribute("neurolink.has_tools", !!(options.tools && Object.keys(options.tools).length > 0));
+        generateSpan.setAttribute("has_tools", !!(options.tools && Object.keys(options.tools).length > 0));
         // Ensure options.input is always an object — callers may omit it for
         // media-only modes (avatar / music / video) or STT flows. Downstream code
         // accesses it unconditionally, so we guarantee a non-null object here and
@@ -4243,11 +4204,11 @@ Current user's request: ${currentInput}`;
             logger.warn("[NeuroLink] STT audio preprocessing is not supported with PPT mode; audio will be ignored");
         }
         const pptResult = await this.generateWithPPT(options);
-        generateSpan.setAttribute("neurolink.output_length", pptResult.content?.length ?? 0);
+        generateSpan.setAttribute("output_length", pptResult.content?.length ?? 0);
         if (pptResult.analytics) {
-            generateSpan.setAttribute("neurolink.tokens.input", pptResult.analytics.tokenUsage?.input ?? 0);
-            generateSpan.setAttribute("neurolink.tokens.output", pptResult.analytics.tokenUsage?.output ?? 0);
-            generateSpan.setAttribute("neurolink.cost", pptResult.analytics.cost ?? 0);
+            generateSpan.setAttribute("tokens.input", pptResult.analytics.tokenUsage?.input ?? 0);
+            generateSpan.setAttribute("tokens.output", pptResult.analytics.tokenUsage?.output ?? 0);
+            generateSpan.setAttribute("cost", pptResult.analytics.cost ?? 0);
         }
         generateSpan.setStatus({ code: SpanStatusCode.OK });
         return pptResult;
@@ -4802,10 +4763,6 @@ Current user's request: ${currentInput}`;
             // generate() today. Declaring them is a public-type decision and is
             // deliberately left out of this fix.
             thinkingConfig: options.thinkingConfig,
-            // Lifecycle callbacks must reach the provider so non-AI-SDK paths
-            // (Vertex's native @google/genai, native Bedrock, Ollama, etc.) can
-            // invoke them directly. Pipeline A also still receives them via the
-            // wrapped middleware config set by applyGenerateLifecycleMiddleware.
             onFinish: options.onFinish,
             onError: options.onError,
         };
@@ -4934,12 +4891,6 @@ Current user's request: ${currentInput}`;
                 });
             }
         }
-        // Skip the top-level `generation:end` emission when the provider already
-        // emitted it from its native generate path (Vertex / Google AI Studio).
-        // Without this guard, native-path providers would surface TWO events
-        // per generate call (Pipeline A path: 1 from provider native + 1 here;
-        // standard AI-SDK path: 1 here). The observability suite asserts on
-        // emission count and would (and did) fail.
         const nativeAlreadyEmitted = !!textResult._generationEndEmitted;
         if (!nativeAlreadyEmitted) {
             this.emitter.emit("generation:end", {
@@ -4957,10 +4908,6 @@ Current user's request: ${currentInput}`;
                     options.prompt,
                 temperature: textOptions.temperature,
                 maxTokens: textOptions.maxTokens,
-                // A2 fix: Signal that Pipeline A (AI SDK → @langfuse/otel) already
-                // creates a GENERATION observation for this call. The generation:end
-                // listener should skip creating a duplicate Pipeline B span.
-                pipelineAHandled: true,
             });
         }
         this.emitter.emit("response:end", textResult.content || "");
@@ -5068,18 +5015,18 @@ Current user's request: ${currentInput}`;
             this._sessionCostUsd += generateResult.analytics.cost;
         }
         this.scheduleGenerateMemoryStorage(options, originalPrompt, generateResult);
-        generateSpan.setAttribute("neurolink.output_length", generateResult.content?.length || 0);
-        generateSpan.setAttribute("neurolink.tokens.input", generateResult.usage?.input || 0);
-        generateSpan.setAttribute("neurolink.tokens.output", generateResult.usage?.output || 0);
-        generateSpan.setAttribute("neurolink.finish_reason", generateResult.finishReason || "unknown");
+        generateSpan.setAttribute("output_length", generateResult.content?.length || 0);
+        generateSpan.setAttribute("tokens.input", generateResult.usage?.input || 0);
+        generateSpan.setAttribute("tokens.output", generateResult.usage?.output || 0);
+        generateSpan.setAttribute("finish_reason", generateResult.finishReason || "unknown");
         // G3 fix: Record step count and whether max steps was reached
         // Read steps from the raw provider result (textResult), not the flattened DTO
         const stepCount = textResult?.steps?.length ?? 1;
         const maxSteps = options.maxSteps ?? 200; // DEFAULT_MAX_STEPS
-        generateSpan.setAttribute("neurolink.step_count", stepCount);
-        generateSpan.setAttribute("neurolink.max_steps_reached", stepCount >= maxSteps);
-        generateSpan.setAttribute("neurolink.result_provider", generateResult.provider || "unknown");
-        generateSpan.setAttribute("neurolink.result_model", generateResult.model || "unknown");
+        generateSpan.setAttribute("step_count", stepCount);
+        generateSpan.setAttribute("max_steps_reached", stepCount >= maxSteps);
+        generateSpan.setAttribute("result_provider", generateResult.provider || "unknown");
+        generateSpan.setAttribute("result_model", generateResult.model || "unknown");
         generateSpan.setAttribute("generate.retry_count", generateResult.retries?.count || 0);
         generateSpan.setStatus({ code: SpanStatusCode.OK });
         return generateResult;
@@ -5200,8 +5147,8 @@ Current user's request: ${currentInput}`;
             ...musicOptions,
             prompt: musicOptions.prompt ?? options.input?.text ?? "",
         });
-        generateSpan.setAttribute("neurolink.music.provider", providerName);
-        generateSpan.setAttribute("neurolink.music.bytes", musicResult.size);
+        generateSpan.setAttribute("music.provider", providerName);
+        generateSpan.setAttribute("music.bytes", musicResult.size);
         generateSpan.setStatus({ code: SpanStatusCode.OK });
         return {
             content: `Music generated (${providerName}, ${musicResult.size} bytes, ${musicResult.format}).`,
@@ -5234,8 +5181,8 @@ Current user's request: ${currentInput}`;
         registerDefaultAvatarHandlers();
         const { AvatarProcessor } = await import("./utils/avatarProcessor.js");
         const avatarResult = await AvatarProcessor.generate(providerName, avatarOptions);
-        generateSpan.setAttribute("neurolink.avatar.provider", providerName);
-        generateSpan.setAttribute("neurolink.avatar.bytes", avatarResult.size);
+        generateSpan.setAttribute("avatar.provider", providerName);
+        generateSpan.setAttribute("avatar.bytes", avatarResult.size);
         generateSpan.setStatus({ code: SpanStatusCode.OK });
         return {
             content: `Avatar generated (${providerName}, ${avatarResult.size} bytes, ${avatarResult.format}).`,
@@ -5537,7 +5484,10 @@ Current user's request: ${currentInput}`;
      * 5. Store conversation turn for future context
      */
     async generateTextInternal(options) {
-        return tracers.sdk.startActiveSpan("neurolink.generateTextInternal", { kind: SpanKind.INTERNAL }, (internalSpan) => this.executeGenerateTextInternalWithSpan(options, internalSpan));
+        const internalSpan = tracers.sdk.startSpan("generateTextInternal", {
+            kind: SpanKind.INTERNAL,
+        });
+        return this.executeGenerateTextInternalWithSpan(options, internalSpan);
     }
     async executeGenerateTextInternalWithSpan(options, internalSpan) {
         return this.conversationEventContext.run(Symbol("generate-conversation"), () => this.executeGenerateTextInternalInEventScope(options, internalSpan));
@@ -5549,24 +5499,19 @@ Current user's request: ${currentInput}`;
                 ...this.initializeGenerateTextInternalContext(options),
                 eventSequence,
             };
-            internalSpan.setAttribute("neurolink.request_id", context.requestId);
-            internalSpan.setAttribute("neurolink.has_conversation_memory", !!this.conversationMemory);
-            internalSpan.setAttribute("neurolink.provider", options.provider || "auto");
-            internalSpan.setAttribute("neurolink.model", options.model || "default");
+            internalSpan.setAttribute("request_id", context.requestId);
+            internalSpan.setAttribute("has_conversation_memory", !!this.conversationMemory);
+            internalSpan.setAttribute("sdk.provider", options.provider || "auto");
+            internalSpan.setAttribute("sdk.model", options.model || "default");
             this.logGenerateTextInternalStart(context.generateInternalId, context.generateInternalStartTime, context.generateInternalHrTimeStart, options, context.functionTag);
             this.emitGenerationStartEvents(options);
             return await this.runGenerateTextInternalFlow(options, internalSpan, context);
         }
         catch (error) {
             // Client aborts are user-initiated cancellations, not system faults.
-            // Setting status=ERROR forces Langfuse to level=ERROR (see
-            // ContextEnricher.onEnd → instrumentation.ts:691). Instead leave status
-            // unset and stamp ai.finishReason=aborted so applyNonErrorLangfuseLevel
-            // maps it to level=WARNING with the canonical "Generation aborted by
-            // client" status_message. Matches Curator telemetry-gaps Issue 5a.
             if (isAbortError(error)) {
                 internalSpan.setAttribute("ai.finishReason", "aborted");
-                internalSpan.setAttribute("neurolink.aborted", true);
+                internalSpan.setAttribute("aborted", true);
             }
             else {
                 internalSpan.recordException(error instanceof Error ? error : new Error(String(error)));
@@ -5688,10 +5633,10 @@ Current user's request: ${currentInput}`;
         if (path === "direct") {
             this.emitter.emit("message", "Text generation completed successfully");
         }
-        internalSpan.setAttribute("neurolink.path", path);
-        internalSpan.setAttribute("neurolink.tokens.input", result.usage?.input || 0);
-        internalSpan.setAttribute("neurolink.tokens.output", result.usage?.output || 0);
-        internalSpan.setAttribute("neurolink.result_provider", result.provider || "unknown");
+        internalSpan.setAttribute("path", path);
+        internalSpan.setAttribute("tokens.input", result.usage?.input || 0);
+        internalSpan.setAttribute("tokens.output", result.usage?.output || 0);
+        internalSpan.setAttribute("result_provider", result.provider || "unknown");
         internalSpan.setStatus({ code: SpanStatusCode.OK });
         return result;
     }
@@ -7417,6 +7362,7 @@ Current user's request: ${currentInput}`;
     async stream(options) {
         const eventScope = Symbol("stream-conversation");
         return this.conversationEventContext.run(eventScope, () => logger.runInInstanceScope(this.logInstanceId, async () => {
+            this.holdTelemetry();
             const result = await this.streamInInstanceScope(options);
             return preserveLiveStreamAccessors(result, {
                 ...result,
@@ -7427,24 +7373,22 @@ Current user's request: ${currentInput}`;
     /** Re-enter request ownership when the caller drives a deferred async iterator. */
     bindConversationEventStream(stream, eventScope) {
         const scope = this.conversationEventContext;
-        return (async function* () {
-            const iterator = stream[Symbol.asyncIterator]();
-            try {
-                while (true) {
-                    const next = await scope.run(eventScope, () => iterator.next());
-                    if (next.done) {
-                        return;
-                    }
-                    yield next.value;
-                }
-            }
-            finally {
-                const close = iterator.return?.bind(iterator);
-                if (close) {
-                    await scope.run(eventScope, () => close());
-                }
-            }
-        })();
+        const iterator = stream[Symbol.asyncIterator]();
+        const bound = {
+            next: () => scope.run(eventScope, () => iterator.next()),
+            async return() {
+                await scope.run(eventScope, async () => iterator.return?.());
+                return { done: true, value: undefined };
+            },
+            async throw(error) {
+                await scope.run(eventScope, async () => iterator.return?.());
+                throw error;
+            },
+            [Symbol.asyncIterator]() {
+                return bound;
+            },
+        };
+        return bound;
     }
     /**
      * Body of {@link stream}, always entered through the instance log scope.
@@ -7501,26 +7445,9 @@ Current user's request: ${currentInput}`;
         }
         bindFileToolRoots(options, this.resolveFileToolRoots(options.toolRoots));
         const startedAt = Date.now();
-        // Retrieve once before provider/model fallback orchestration. Every fallback
-        // receives the same explicitly enriched options, without the retrieval helper
-        // mutating its input or injecting the same block more than once.
-        const knowledgeOutcome = await this.retrieveKnowledgeGrounding(options);
-        if (knowledgeOutcome?.ephemeralContext) {
-            const block = knowledgeOutcome.ephemeralContext.content;
-            options = {
-                ...options,
-                systemPrompt: this.appendKnowledgeGroundingBlockToSystemPrompt(options.systemPrompt, block),
-            };
-        }
+        const turnOptions = options;
         try {
-            const result = await this.streamWithIterationFallback(options);
-            if (knowledgeOutcome) {
-                result.knowledge = knowledgeOutcome.metadata;
-            }
-            if (agentModeVersion) {
-                result.agentModeVersion = agentModeVersion;
-            }
-            return result;
+            return await this.setLangfuseContextFromOptions(turnOptions, () => this.runStreamTurn(turnOptions, agentModeVersion));
         }
         catch (error) {
             // Mirror generate(): fire consumer onError for failures that
@@ -7534,6 +7461,42 @@ Current user's request: ${currentInput}`;
             throw error;
         }
     }
+    async runStreamTurn(options, agentModeVersion) {
+        const turnSpan = tracers.sdk.startSpan("stream", {
+            kind: SpanKind.INTERNAL,
+        });
+        const turnContext = trace.setSpan(context.active(), turnSpan);
+        let result;
+        try {
+            result = await context.with(turnContext, async () => {
+                const knowledgeOutcome = await this.retrieveKnowledgeGrounding(options);
+                const grounded = knowledgeOutcome?.ephemeralContext
+                    ? {
+                        ...options,
+                        systemPrompt: this.appendKnowledgeGroundingBlockToSystemPrompt(options.systemPrompt, knowledgeOutcome.ephemeralContext.content),
+                    }
+                    : options;
+                startTurn(turnSpan, grounded);
+                const streamed = await this.streamWithIterationFallback(grounded);
+                if (knowledgeOutcome) {
+                    streamed.knowledge = knowledgeOutcome.metadata;
+                }
+                if (agentModeVersion) {
+                    streamed.agentModeVersion = agentModeVersion;
+                }
+                return streamed;
+            });
+        }
+        catch (error) {
+            failTurnSpan(turnSpan, error instanceof Error ? error : new Error(String(error)));
+            turnSpan.end();
+            throw error;
+        }
+        return preserveLiveStreamAccessors(result, {
+            ...result,
+            stream: traceTurnStream(result, turnSpan, turnContext),
+        });
+    }
     /**
      * Curator P2-3 / Reviewer Finding #2: stream-fallback that also covers
      * errors thrown during async iteration (e.g. LiteLLM throwing inside
@@ -7665,11 +7628,11 @@ Current user's request: ${currentInput}`;
     async executeStreamRequest(options) {
         // Dynamic argument resolution — resolve any function-valued options before downstream use
         await this.resolveDynamicOptions(options);
-        const streamSpan = tracers.sdk.startSpan("neurolink.stream", {
+        const streamSpan = tracers.sdk.startSpan("stream.attempt", {
             kind: SpanKind.INTERNAL,
             attributes: {
                 [ATTR.NL_PROVIDER]: options.provider || "default",
-                [ATTR.GEN_AI_MODEL]: options.model || "default",
+                ...(options.model && { [ATTR.NL_MODEL]: options.model }),
                 [ATTR.NL_INPUT_LENGTH]: options.input?.text?.length || 0,
                 // Count registered custom tools too — chat hosts put their MCP tools
                 // in the registry, so options.tools alone under-reports.
@@ -7679,12 +7642,7 @@ Current user's request: ${currentInput}`;
                 [ATTR.NL_STREAM_MODE]: true,
             },
         });
-        // streamSpan isn't active yet, so context.active() is its parent — empty =
-        // root. Capture root-ness here, but defer the actual guest-rescue stamp to
-        // after validateStreamRequestOptions merges auth/requestContext identity
-        // into options.context (below) — otherwise an auth:{token} caller with no
-        // pre-set context.userId would stamp the root span as guest.
-        const streamIsRoot = !trace.getSpan(context.active());
+        observe(streamSpan, "span", {});
         const spanStartTime = Date.now();
         this._disableToolCacheForCurrentRequest = !!options.disableToolCache;
         this._toolCacheKeysServedThisRequest = new Set();
@@ -7729,8 +7687,6 @@ Current user's request: ${currentInput}`;
             const originalPrompt = options.input?.text ?? "";
             options.fileRegistry = this.fileRegistry;
             await this.validateStreamRequestOptions(options, startTime);
-            // options.context now carries any auth/requestContext-derived identity.
-            stampGuestRescueIdentity(streamSpan, options.context, streamIsRoot);
             const workflowResult = await this.maybeHandleWorkflowStreamRequest({
                 options,
                 startTime,
@@ -7780,19 +7736,23 @@ Current user's request: ${currentInput}`;
                     resolveStreamTtsAudio = resolve;
                 })
                 : undefined;
-            const streamResult = await context.with(streamSpanContext, () => this.setLangfuseContextFromOptions(options, () => this.runStandardStreamRequest({
-                options,
-                streamSpan,
-                spanStartTime,
-                startTime,
-                hrTimeStart,
-                streamId,
-                originalPrompt,
-                ttsResolver: resolveStreamTtsAudio,
-                ttsMetadataSink: (metadata) => {
-                    streamTtsMetadata = metadata;
-                },
-            })));
+            const streamResult = await context.with(streamSpanContext, () => this.setLangfuseContextFromOptions(options, async () => {
+                const attempt = await this.runStandardStreamRequest({
+                    options,
+                    streamSpan,
+                    spanStartTime,
+                    startTime,
+                    hrTimeStart,
+                    streamId,
+                    originalPrompt,
+                    ttsResolver: resolveStreamTtsAudio,
+                    ttsMetadataSink: (metadata) => {
+                        streamTtsMetadata = metadata;
+                    },
+                });
+                attempt.stream = drainInContext(attempt.stream, context.active());
+                return attempt;
+            }));
             if (streamSttTranscription) {
                 streamResult.transcription = streamSttTranscription;
             }
@@ -8358,7 +8318,7 @@ Current user's request: ${currentInput}`;
                 self._disableToolCacheForCurrentRequest = false;
                 self._toolCacheKeysServedThisRequest = new Set();
                 self._generationTurnActive = false;
-                params.streamSpan.setAttribute("neurolink.response_time_ms", Date.now() - params.spanStartTime);
+                params.streamSpan.setAttribute("response_time_ms", Date.now() - params.spanStartTime);
                 params.streamSpan.end();
             }
         })();
@@ -8411,14 +8371,14 @@ Current user's request: ${currentInput}`;
             const mcpStreamOutcome = await this.createMCPStream(enhancedOptions);
             const { stream: mcpStream } = mcpStreamOutcome;
             const providerName = mcpStreamOutcome.provider ?? "unknown";
-            let streamedTTSResult;
+            const tts = {};
             const { stream: incrementalStream, ttsMetadata: streamTtsMetadata } = await this.createIncrementalTTSStream({
                 stream: mcpStream,
                 ttsOptions: enhancedOptions.tts,
                 providerName,
                 fallbackProvider: enhancedOptions.provider,
                 onComplete: (result) => {
-                    streamedTTSResult = result;
+                    tts.result = result;
                 },
             });
             ttsMetadataSink?.(streamTtsMetadata);
@@ -8450,8 +8410,6 @@ Current user's request: ${currentInput}`;
             const currentToolCalls = () => streamState.toolCalls ?? mcpStreamOutcome.toolCalls ?? [];
             const currentToolResults = () => streamState.toolResults ?? mcpStreamOutcome.toolResults ?? [];
             streamSpan.setAttribute(ATTR.NL_PROVIDER, providerName || "unknown");
-            let accumulatedContent = "";
-            let chunkCount = 0;
             const { eventSequence, cleanup: cleanupListeners } = this.setupStreamEventListeners();
             const metadata = {
                 fallbackAttempted: false,
@@ -8460,312 +8418,32 @@ Current user's request: ${currentInput}`;
                 fallbackProvider: undefined,
                 fallbackModel: undefined,
             };
-            const self = this;
             const streamStartTime = Date.now();
             const sessionId = enhancedOptions.context
                 ?.sessionId;
-            const processedStream = (async function* () {
-                let streamError;
-                // Curator P2-4: hoist `resolvedUsage` so the finally block can emit a
-                // single `generation:end` event with cost data. Cost listeners
-                // subscribe here; previously the stream path never fired it.
-                let resolvedUsage;
-                // Reviewer follow-up: track *non-sentinel output chunks* (text,
-                // audio, image — anything the SDK considers real output) so the
-                // fallback gate fires only when the stream produced nothing
-                // useful. Counting only text content here would have spuriously
-                // triggered fallback for valid audio-only (Google Live) and
-                // image-only streams. The sentinel is the only thing we exclude
-                // — that path can mask real provider failures (DNS, auth,
-                // retry-exhaustion) that AI SDK rejects with
-                // NoOutputGeneratedError, and we want fallback to fire there.
-                let realOutputChunks = 0;
-                try {
-                    for await (const chunk of incrementalStream) {
-                        chunkCount++;
-                        const isNoOutputSentinel = chunk !== null &&
-                            typeof chunk === "object" &&
-                            "metadata" in chunk &&
-                            chunk.metadata
-                                ?.noOutput === true;
-                        const hasTextContent = chunk &&
-                            "content" in chunk &&
-                            typeof chunk.content === "string" &&
-                            chunk.content.length > 0;
-                        const hasMediaPayload = chunk !== null &&
-                            typeof chunk === "object" &&
-                            "type" in chunk &&
-                            (chunk.type === "audio" ||
-                                chunk.type === "tts_audio" ||
-                                chunk.type === "image");
-                        if (!isNoOutputSentinel && (hasTextContent || hasMediaPayload)) {
-                            realOutputChunks++;
-                        }
-                        if (chunk &&
-                            "content" in chunk &&
-                            typeof chunk.content === "string") {
-                            accumulatedContent += chunk.content;
-                            self.emitter.emit("response:chunk", chunk.content);
-                            self.emitter.emit("stream:chunk", {
-                                type: "stream:chunk",
-                                content: chunk.content,
-                                metadata: {
-                                    chunkIndex: chunkCount,
-                                    totalLength: accumulatedContent.length,
-                                    ...(isNoOutputSentinel && { noOutput: true }),
-                                },
-                                timestamp: Date.now(),
-                            });
-                        }
-                        yield chunk;
-                    }
-                    // Reviewer follow-up: fire fallback when no *non-sentinel*
-                    // output was produced — sentinel-only and truly empty streams
-                    // both qualify, but media-only streams (audio/image) do not.
-                    //
-                    // fallbackOnMaxSteps: false exempts one no-output shape — a turn
-                    // the provider reports as ended at the caller's own maxSteps bound
-                    // (metadata.stopReason "step-cap", a mutable reference the native
-                    // loops fill by drain time). That bound is the caller's budget,
-                    // not a provider failure, and retrying it on another provider
-                    // spends that provider's tokens to exceed a budget the caller set.
-                    const cappedByCallerBudget = enhancedOptions.fallbackOnMaxSteps === false &&
-                        mcpStreamOutcome.metadata?.stopReason === "step-cap";
-                    if (realOutputChunks === 0 &&
-                        !cappedByCallerBudget &&
-                        !metadata.fallbackAttempted &&
-                        !enhancedOptions.disableInternalFallback &&
-                        currentToolCalls().length === 0 &&
-                        currentToolResults().length === 0) {
-                        const fallbackStream = self.handleStreamFallback(metadata, streamState, originalPrompt, enhancedOptions, providerName, (content) => {
-                            accumulatedContent += content;
-                        });
-                        const { stream: incrementalFallback } = await self.createIncrementalTTSStream({
-                            stream: fallbackStream,
-                            ttsOptions: enhancedOptions.tts,
-                            providerName,
-                            fallbackProvider: enhancedOptions.provider,
-                            ttsMetadata: streamTtsMetadata,
-                            onComplete: (result) => {
-                                streamedTTSResult = result;
-                            },
-                        });
-                        yield* incrementalFallback;
-                    }
-                    ttsResolver?.(streamedTTSResult);
-                    // `streamState.finishReason` starts as a "stop" placeholder, before a
-                    // single chunk exists. A provider that records how the turn really
-                    // ended in metadata (a token-limit cut, a content filter, a step cap
-                    // that left tool calls pending) has that adopted here, once the drain
-                    // is done. Only the three unified values count: a raw vendor string
-                    // or "stop" leaves the graded reason alone, and a fallback's own
-                    // value is never overwritten.
-                    const drainedFinishReason = mcpStreamOutcome.metadata?.finishReason;
-                    if (!metadata.fallbackAttempted &&
-                        (drainedFinishReason === "length" ||
-                            drainedFinishReason === "tool-calls" ||
-                            drainedFinishReason === "content-filter")) {
-                        streamState.finishReason = drainedFinishReason;
-                    }
-                    resolvedUsage = mcpStreamOutcome.usage;
-                    if (!resolvedUsage && mcpStreamOutcome.analytics) {
-                        try {
-                            const resolved = await Promise.resolve(mcpStreamOutcome.analytics);
-                            if (resolved?.tokenUsage) {
-                                resolvedUsage = resolved.tokenUsage;
-                            }
-                        }
-                        catch {
-                            // non-blocking
-                        }
-                    }
-                    if (resolvedUsage) {
-                        mcpStreamOutcome.usage = resolvedUsage;
-                    }
-                    self.emitter.emit("stream:complete", {
-                        type: "stream:complete",
-                        content: accumulatedContent,
-                        provider: metadata.fallbackProvider ?? providerName,
-                        model: metadata.fallbackModel ??
-                            mcpStreamOutcome.model ??
-                            enhancedOptions.model,
-                        finishReason: streamState.finishReason ?? "stop",
-                        prompt: enhancedOptions.input?.text ||
-                            enhancedOptions.prompt,
-                        metadata: {
-                            chunkCount,
-                            totalLength: accumulatedContent.length,
-                            durationMs: Date.now() - streamStartTime,
-                            sessionId,
-                            usage: resolvedUsage,
-                            finishReason: streamState.finishReason ?? "stop",
-                            ...(metadata.fallbackAttempted && {
-                                primaryProvider: providerName,
-                                primaryModel: enhancedOptions.model,
-                                fallback: true,
-                            }),
-                        },
-                        timestamp: Date.now(),
-                    });
-                }
-                catch (error) {
-                    logger.debug("[NeuroLink.stream] Stream error occurred", {
-                        error: error instanceof Error ? error.message : String(error),
-                        name: error instanceof Error ? error.name : "UnknownError",
-                        provider: providerName,
-                        model: enhancedOptions.model,
-                        chunkCount,
-                        totalLength: accumulatedContent.length,
-                        durationMs: Date.now() - streamStartTime,
-                        sessionId,
-                    });
-                    streamError = error;
-                    self.emitter.emit("stream:error", {
-                        type: "stream:error",
-                        content: error instanceof Error ? error.message : String(error),
-                        provider: providerName,
-                        model: enhancedOptions.model,
-                        metadata: {
-                            chunkCount,
-                            totalLength: accumulatedContent.length,
-                            durationMs: Date.now() - streamStartTime,
-                            errorName: error instanceof Error ? error.name : "UnknownError",
-                            sessionId,
-                        },
-                        timestamp: Date.now(),
-                    });
-                    throw error;
-                }
-                finally {
-                    // Belt-and-braces: if TTS Mode 2 was requested but synthesis never
-                    // ran (stream errored before reaching the TTS block, or Mode 2 path
-                    // was skipped), resolve the audio promise to undefined so callers
-                    // awaiting `streamResult.audio` never hang. Uses the explicit
-                    // `ttsResolver` param (M11), not a side-channel cast.
-                    // m4: a duplicate resolution is a silent no-op — Promise resolvers
-                    // never throw, so no try/catch needed here.
-                    ttsResolver?.(undefined);
-                    logger.debug("[NeuroLink.stream] Stream finished, performing cleanup", {
-                        provider: providerName,
-                        model: enhancedOptions.model,
-                        totalChunks: chunkCount,
-                        totalLength: accumulatedContent.length,
-                        durationMs: Date.now() - streamStartTime,
-                        fallbackAttempted: metadata.fallbackAttempted,
-                        guardrailsBlocked: metadata.guardrailsBlocked,
-                        error: metadata.error,
-                    });
-                    // Curator P2-4: emit `generation:end` exactly once per stream so
-                    // cost listeners receive the same contract as for `generate()`.
-                    // The previous implementation only fired `stream:complete`, leaving
-                    // any subscriber to `generation:end` with zero events.
-                    //
-                    // Dedup: native provider stream paths (Gemini 3 on Vertex / Google
-                    // AI Studio) already emit `generation:end` themselves so Pipeline B
-                    // (Langfuse) records a GENERATION observation. Skip our emit when
-                    // they already fired — preserves their Pipeline B observation
-                    // source and keeps the "exactly once" contract. Per-stream flag
-                    // is concurrency-safe because it's scoped via AsyncLocalStorage.
-                    if (!dedupContext.providerEmitted) {
-                        try {
-                            const finalProvider = metadata.fallbackProvider ?? providerName ?? "unknown";
-                            const finalModel = metadata.fallbackModel ??
-                                mcpStreamOutcome.model ??
-                                enhancedOptions.model ??
-                                "unknown";
-                            const finalFinishReason = streamError
-                                ? "error"
-                                : (streamState.finishReason ?? "stop");
-                            self.emitter.emit("generation:end", {
-                                provider: finalProvider,
-                                model: finalModel,
-                                responseTime: Date.now() - streamStartTime,
-                                toolsUsed: currentToolCalls().map((t) => t.toolName),
-                                timestamp: Date.now(),
-                                result: {
-                                    content: accumulatedContent,
-                                    usage: resolvedUsage,
-                                    model: finalModel,
-                                    provider: finalProvider,
-                                    finishReason: finalFinishReason,
-                                },
-                                prompt: enhancedOptions.input?.text ||
-                                    enhancedOptions.prompt,
-                                temperature: enhancedOptions.temperature,
-                                maxTokens: enhancedOptions.maxTokens,
-                                success: !streamError,
-                                error: streamError
-                                    ? streamError instanceof Error
-                                        ? streamError.message
-                                        : String(streamError)
-                                    : undefined,
-                                pipelineAHandled: true,
-                            });
-                        }
-                        catch (emitError) {
-                            logger.debug("[NeuroLink.stream] generation:end listener threw — ignored", {
-                                error: emitError instanceof Error
-                                    ? emitError.message
-                                    : String(emitError),
-                            });
-                        }
-                    }
-                    self._disableToolCacheForCurrentRequest = false;
-                    self._toolCacheKeysServedThisRequest = new Set();
-                    self._generationTurnActive = false;
-                    cleanupListeners();
-                    streamSpan.setAttribute("neurolink.response_time_ms", Date.now() - spanStartTime);
-                    streamSpan.setAttribute(ATTR.NL_OUTPUT_LENGTH, accumulatedContent.length);
-                    const primaryFailed = !!(metadata.error || streamError);
-                    streamSpan.setAttribute(ATTR.GEN_AI_FINISH_REASON, primaryFailed ? "error" : "stop");
-                    if (metadata.fallbackAttempted) {
-                        streamSpan.setAttribute("neurolink.fallback_triggered", true);
-                        if (metadata.fallbackProvider) {
-                            streamSpan.setAttribute("neurolink.fallback_provider", metadata.fallbackProvider);
-                        }
-                    }
-                    if (primaryFailed) {
-                        streamSpan.setStatus({
-                            code: SpanStatusCode.ERROR,
-                            message: metadata.error ||
-                                (streamError instanceof Error
-                                    ? streamError.message
-                                    : String(streamError)),
-                        });
-                    }
-                    else {
-                        streamSpan.setStatus({ code: SpanStatusCode.OK });
-                    }
-                    streamSpan.end();
-                    if (accumulatedContent.trim()) {
-                        logger.info(`[NeuroLink.stream] stream() - COMPLETE SUCCESS`, {
-                            provider: providerName,
-                            model: enhancedOptions.model,
-                            responseTimeMs: Date.now() - startTime,
-                            contentLength: accumulatedContent.length,
-                            fallback: metadata.fallbackAttempted,
-                        });
-                    }
-                    await self.storeStreamConversationMemory({
-                        enhancedOptions,
-                        providerName,
-                        originalPrompt,
-                        accumulatedContent,
-                        startTime,
-                        eventSequence,
-                        // Read only now, after the stream drained: the provider's
-                        // toolsUsed is a live getter that resolves as the loop runs.
-                        resultToolsUsed: (() => {
-                            const fromResult = mcpStreamOutcome.toolsUsed;
-                            if (Array.isArray(fromResult) && fromResult.length > 0) {
-                                return fromResult;
-                            }
-                            const fromCalls = currentToolCalls().map((t) => t.toolName);
-                            return fromCalls.length > 0 ? fromCalls : undefined;
-                        })(),
-                    });
-                }
-            })();
+            const drain = {
+                enhancedOptions,
+                originalPrompt,
+                startTime,
+                streamStartTime,
+                sessionId,
+                streamSpan,
+                spanStartTime,
+                ttsResolver,
+                incrementalStream,
+                streamTtsMetadata,
+                tts,
+                mcpStreamOutcome,
+                providerName,
+                dedupContext,
+                streamState,
+                currentToolCalls,
+                currentToolResults,
+                metadata,
+                eventSequence,
+                cleanupListeners,
+            };
+            const processedStream = this.drainStandardStreamOnce(drain);
             const streamResult = await this.processStreamResult(processedStream, enhancedOptions, factoryResult);
             streamState.finishReason =
                 streamState.finishReason || streamResult.finishReason;
@@ -8862,6 +8540,288 @@ Current user's request: ${currentInput}`;
             return this.handleStreamError(error, options, startTime, streamId, undefined, undefined);
         }
     }
+    drainStandardStreamOnce(drain) {
+        const stream = this.drainStandardStream(drain);
+        let started = false;
+        const guarded = {
+            next: () => {
+                started = true;
+                return stream.next();
+            },
+            return: async (value) => {
+                if (!started) {
+                    started = true;
+                    await this.settleStandardStreamDrain(drain, {
+                        accumulatedContent: "",
+                        chunkCount: 0,
+                        streamError: undefined,
+                        resolvedUsage: undefined,
+                    });
+                }
+                return stream.return(value);
+            },
+            throw: (error) => stream.throw(error),
+            [Symbol.asyncIterator]: () => guarded,
+        };
+        return guarded;
+    }
+    async *drainStandardStream(drain) {
+        const { enhancedOptions, originalPrompt, streamStartTime, sessionId, ttsResolver, incrementalStream, streamTtsMetadata, tts, mcpStreamOutcome, providerName, streamState, currentToolCalls, currentToolResults, metadata, } = drain;
+        let accumulatedContent = "";
+        let chunkCount = 0;
+        let streamError;
+        let resolvedUsage;
+        let realOutputChunks = 0;
+        try {
+            for await (const chunk of incrementalStream) {
+                chunkCount++;
+                const isNoOutputSentinel = chunk !== null &&
+                    typeof chunk === "object" &&
+                    "metadata" in chunk &&
+                    chunk.metadata
+                        ?.noOutput === true;
+                const hasTextContent = chunk &&
+                    "content" in chunk &&
+                    typeof chunk.content === "string" &&
+                    chunk.content.length > 0;
+                const hasMediaPayload = chunk !== null &&
+                    typeof chunk === "object" &&
+                    "type" in chunk &&
+                    (chunk.type === "audio" ||
+                        chunk.type === "tts_audio" ||
+                        chunk.type === "image");
+                if (!isNoOutputSentinel && (hasTextContent || hasMediaPayload)) {
+                    realOutputChunks++;
+                }
+                if (chunk && "content" in chunk && typeof chunk.content === "string") {
+                    accumulatedContent += chunk.content;
+                    this.emitter.emit("response:chunk", chunk.content);
+                    this.emitter.emit("stream:chunk", {
+                        type: "stream:chunk",
+                        content: chunk.content,
+                        metadata: {
+                            chunkIndex: chunkCount,
+                            totalLength: accumulatedContent.length,
+                            ...(isNoOutputSentinel && { noOutput: true }),
+                        },
+                        timestamp: Date.now(),
+                    });
+                }
+                yield chunk;
+            }
+            const cappedByCallerBudget = enhancedOptions.fallbackOnMaxSteps === false &&
+                mcpStreamOutcome.metadata?.stopReason === "step-cap";
+            if (realOutputChunks === 0 &&
+                !cappedByCallerBudget &&
+                !metadata.fallbackAttempted &&
+                !enhancedOptions.disableInternalFallback &&
+                currentToolCalls().length === 0 &&
+                currentToolResults().length === 0) {
+                const fallbackStream = this.handleStreamFallback(metadata, streamState, originalPrompt, enhancedOptions, providerName, (content) => {
+                    accumulatedContent += content;
+                });
+                const { stream: incrementalFallback } = await this.createIncrementalTTSStream({
+                    stream: fallbackStream,
+                    ttsOptions: enhancedOptions.tts,
+                    providerName,
+                    fallbackProvider: enhancedOptions.provider,
+                    ttsMetadata: streamTtsMetadata,
+                    onComplete: (result) => {
+                        tts.result = result;
+                    },
+                });
+                yield* incrementalFallback;
+            }
+            ttsResolver?.(tts.result);
+            const drainedFinishReason = mcpStreamOutcome.metadata?.finishReason;
+            if (!metadata.fallbackAttempted &&
+                (drainedFinishReason === "length" ||
+                    drainedFinishReason === "tool-calls" ||
+                    drainedFinishReason === "content-filter")) {
+                streamState.finishReason = drainedFinishReason;
+            }
+            resolvedUsage = mcpStreamOutcome.usage;
+            if (!resolvedUsage && mcpStreamOutcome.analytics) {
+                try {
+                    const resolved = await Promise.resolve(mcpStreamOutcome.analytics);
+                    if (resolved?.tokenUsage) {
+                        resolvedUsage = resolved.tokenUsage;
+                    }
+                }
+                catch {
+                    // non-blocking
+                }
+            }
+            if (resolvedUsage) {
+                mcpStreamOutcome.usage = resolvedUsage;
+            }
+            this.emitter.emit("stream:complete", {
+                type: "stream:complete",
+                content: accumulatedContent,
+                provider: metadata.fallbackProvider ?? providerName,
+                model: metadata.fallbackModel ??
+                    mcpStreamOutcome.model ??
+                    enhancedOptions.model,
+                finishReason: streamState.finishReason ?? "stop",
+                prompt: enhancedOptions.input?.text ||
+                    enhancedOptions.prompt,
+                metadata: {
+                    chunkCount,
+                    totalLength: accumulatedContent.length,
+                    durationMs: Date.now() - streamStartTime,
+                    sessionId,
+                    usage: resolvedUsage,
+                    finishReason: streamState.finishReason ?? "stop",
+                    ...(metadata.fallbackAttempted && {
+                        primaryProvider: providerName,
+                        primaryModel: enhancedOptions.model,
+                        fallback: true,
+                    }),
+                },
+                timestamp: Date.now(),
+            });
+        }
+        catch (error) {
+            logger.debug("[NeuroLink.stream] Stream error occurred", {
+                error: error instanceof Error ? error.message : String(error),
+                name: error instanceof Error ? error.name : "UnknownError",
+                provider: providerName,
+                model: enhancedOptions.model,
+                chunkCount,
+                totalLength: accumulatedContent.length,
+                durationMs: Date.now() - streamStartTime,
+                sessionId,
+            });
+            streamError = error instanceof Error ? error : new Error(String(error));
+            this.emitter.emit("stream:error", {
+                type: "stream:error",
+                content: error instanceof Error ? error.message : String(error),
+                provider: providerName,
+                model: enhancedOptions.model,
+                metadata: {
+                    chunkCount,
+                    totalLength: accumulatedContent.length,
+                    durationMs: Date.now() - streamStartTime,
+                    errorName: error instanceof Error ? error.name : "UnknownError",
+                    sessionId,
+                },
+                timestamp: Date.now(),
+            });
+            throw error;
+        }
+        finally {
+            await this.settleStandardStreamDrain(drain, {
+                accumulatedContent,
+                chunkCount,
+                streamError,
+                resolvedUsage,
+            });
+        }
+    }
+    async settleStandardStreamDrain(drain, outcome) {
+        const { enhancedOptions, originalPrompt, startTime, streamStartTime, streamSpan, spanStartTime, ttsResolver, mcpStreamOutcome, providerName, dedupContext, streamState, currentToolCalls, metadata, eventSequence, cleanupListeners, } = drain;
+        const { accumulatedContent, chunkCount, streamError, resolvedUsage } = outcome;
+        ttsResolver?.(undefined);
+        logger.debug("[NeuroLink.stream] Stream finished, performing cleanup", {
+            provider: providerName,
+            model: enhancedOptions.model,
+            totalChunks: chunkCount,
+            totalLength: accumulatedContent.length,
+            durationMs: Date.now() - streamStartTime,
+            fallbackAttempted: metadata.fallbackAttempted,
+            guardrailsBlocked: metadata.guardrailsBlocked,
+            error: metadata.error,
+        });
+        if (!dedupContext.providerEmitted) {
+            try {
+                const finalProvider = metadata.fallbackProvider ?? providerName ?? "unknown";
+                const finalModel = metadata.fallbackModel ??
+                    mcpStreamOutcome.model ??
+                    enhancedOptions.model ??
+                    "unknown";
+                const finalFinishReason = streamError
+                    ? "error"
+                    : (streamState.finishReason ?? "stop");
+                this.emitter.emit("generation:end", {
+                    provider: finalProvider,
+                    model: finalModel,
+                    responseTime: Date.now() - streamStartTime,
+                    toolsUsed: currentToolCalls().map((t) => t.toolName),
+                    timestamp: Date.now(),
+                    result: {
+                        content: accumulatedContent,
+                        usage: resolvedUsage,
+                        model: finalModel,
+                        provider: finalProvider,
+                        finishReason: finalFinishReason,
+                    },
+                    prompt: enhancedOptions.input?.text ||
+                        enhancedOptions.prompt,
+                    temperature: enhancedOptions.temperature,
+                    maxTokens: enhancedOptions.maxTokens,
+                    success: !streamError,
+                    error: streamError?.message,
+                    streamed: true,
+                });
+            }
+            catch (emitError) {
+                logger.debug("[NeuroLink.stream] generation:end listener threw — ignored", {
+                    error: emitError instanceof Error
+                        ? emitError.message
+                        : String(emitError),
+                });
+            }
+        }
+        this._disableToolCacheForCurrentRequest = false;
+        this._toolCacheKeysServedThisRequest = new Set();
+        this._generationTurnActive = false;
+        cleanupListeners();
+        streamSpan.setAttribute("response_time_ms", Date.now() - spanStartTime);
+        streamSpan.setAttribute(ATTR.NL_OUTPUT_LENGTH, accumulatedContent.length);
+        const primaryFailed = !!(metadata.error || streamError);
+        streamSpan.setAttribute(ATTR.GEN_AI_FINISH_REASON, primaryFailed ? "error" : "stop");
+        if (metadata.fallbackAttempted) {
+            streamSpan.setAttribute("fallback_triggered", true);
+            if (metadata.fallbackProvider) {
+                streamSpan.setAttribute("fallback_provider", metadata.fallbackProvider);
+            }
+        }
+        if (primaryFailed) {
+            streamSpan.setStatus({
+                code: SpanStatusCode.ERROR,
+                message: metadata.error || streamError?.message,
+            });
+        }
+        else {
+            streamSpan.setStatus({ code: SpanStatusCode.OK });
+        }
+        streamSpan.end();
+        if (accumulatedContent.trim()) {
+            logger.info(`[NeuroLink.stream] stream() - COMPLETE SUCCESS`, {
+                provider: providerName,
+                model: enhancedOptions.model,
+                responseTimeMs: Date.now() - startTime,
+                contentLength: accumulatedContent.length,
+                fallback: metadata.fallbackAttempted,
+            });
+        }
+        await this.storeStreamConversationMemory({
+            enhancedOptions,
+            providerName,
+            originalPrompt,
+            accumulatedContent,
+            startTime,
+            eventSequence,
+            resultToolsUsed: (() => {
+                const fromResult = mcpStreamOutcome.toolsUsed;
+                if (Array.isArray(fromResult) && fromResult.length > 0) {
+                    return fromResult;
+                }
+                const fromCalls = currentToolCalls().map((t) => t.toolName);
+                return fromCalls.length > 0 ? fromCalls : undefined;
+            })(),
+        });
+    }
     /** Wrap one provider stream with incremental TTS synthesis. */
     async createIncrementalTTSStream(params) {
         const { stream, ttsOptions, providerName, fallbackProvider, onComplete } = params;
@@ -10050,7 +10010,7 @@ Current user's request: ${currentInput}`;
                                 finishReason: "stop",
                             },
                             success: true,
-                            pipelineAHandled: true,
+                            streamed: true,
                         });
                     }
                     catch {
@@ -11097,21 +11057,16 @@ Current user's request: ${currentInput}`;
             return this.mcpToolBatcher.execute(toolName, params);
         }
         const executionContext = this.createToolExecutionContext(toolName, params, options);
-        return tracers.mcp.startActiveSpan("neurolink.tool.execute", {
+        return tracers.mcp.startActiveSpan(toolSpanName(toolName), {
             attributes: {
                 "tool.name": toolName,
                 "tool.type": executionContext.toolType,
                 "tool.input_size": executionContext.inputSize,
-                "tool.input_preview": executionContext.truncatedInput,
-                // NOT marked langfuse.internal: this is the public entrypoint for
-                // `NeuroLink.executeTool()`. Direct API callers (not going through
-                // the AI SDK) would otherwise produce zero Langfuse observations —
-                // the lower-level registry/discovery spans are internal wrappers.
-                // AI-SDK-initiated custom tools will produce both ai.toolCall and
-                // this span, which is the accepted tradeoff for keeping direct
-                // invocations observable.
             },
-        }, (toolSpan) => this.executeToolWithSpan(toolName, params, options, executionContext, toolSpan));
+        }, (toolSpan) => {
+            observe(toolSpan, "tool", { input: params });
+            return this.executeToolWithSpan(toolName, params, options, executionContext, toolSpan);
+        });
     }
     createToolExecutionContext(toolName, params, options) {
         const externalTool = this.externalServerManager
@@ -11136,7 +11091,6 @@ Current user's request: ${currentInput}`;
             externalTool,
             toolType,
             inputSize: inputStr.length,
-            truncatedInput: inputStr.length > 2048 ? inputStr.substring(0, 2048) : inputStr,
             options,
             hitlState: { triggered: false },
         };
@@ -11144,11 +11098,23 @@ Current user's request: ${currentInput}`;
     async executeToolWithSpan(toolName, params, options, executionContext, toolSpan) {
         try {
             const prepared = await this.prepareToolExecutionState(toolName, params, options, executionContext);
-            return await this.runPreparedToolExecution(toolName, params, prepared, executionContext, toolSpan);
+            const result = await this.runPreparedToolExecution(toolName, params, prepared, executionContext, toolSpan);
+            const failed = isNonNullObject(result) &&
+                "isError" in result &&
+                result.isError === true;
+            observe(toolSpan, "tool", {
+                output: result,
+                ...(failed && {
+                    level: "ERROR",
+                    statusMessage: extractMcpErrorText(result),
+                }),
+            });
+            return result;
         }
         catch (outerError) {
+            const errMsg = outerError instanceof Error ? outerError.message : String(outerError);
+            observe(toolSpan, "tool", { level: "ERROR", statusMessage: errMsg });
             if (!(outerError instanceof NeuroLinkError)) {
-                const errMsg = outerError instanceof Error ? outerError.message : String(outerError);
                 toolSpan.recordException(outerError instanceof Error ? outerError : new Error(errMsg));
                 toolSpan.setStatus({ code: SpanStatusCode.ERROR, message: errMsg });
             }
@@ -13345,7 +13311,7 @@ Current user's request: ${currentInput}`;
         // (widely consumed as-is, e.g. by createExternalMCPTool's execute()),
         // so wrapping it to carry resolution metadata would be a breaking
         // change for every existing direct caller.
-        tracers.mcp.startActiveSpan("neurolink.mcp.toolNameRepair", {
+        tracers.mcp.startActiveSpan("mcp.toolNameRepair", {
             attributes: {
                 "mcp.server_id": serverId,
                 "mcp.tool_name.requested": requestedName,
@@ -13882,7 +13848,13 @@ Current user's request: ${currentInput}`;
      * @throws when no decision provider is configured, or the call fails
      */
     async decide(options) {
-        return this.runDecide(options);
+        const { sessionId, requestId } = options;
+        this.holdTelemetry();
+        return setLangfuseContext({
+            ...options.context,
+            sessionId: sessionId ?? options.context?.sessionId,
+            requestId: requestId ?? options.context?.requestId,
+        }, () => this.runDecide(options));
     }
     /**
      * The provider a decision call will go to, resolved exactly as `decide()`
@@ -14052,7 +14024,7 @@ Current user's request: ${currentInput}`;
         // request path of a tenant that has no decision model to reach, and an
         // event for a call that could never be made would only mislead.
         if (!this.resolveDecisionProviderName(merged.provider, merged.credentials)) {
-            return null;
+            return this.tryRunDecide(merged);
         }
         // Wire id → the host's own id, so answers can be handed back under the
         // ids the host used, and NeuroLink's consumers never see a host id. A Map,
@@ -14230,16 +14202,20 @@ Current user's request: ${currentInput}`;
         // SDK config counts as much as the environment: credentials given to the
         // constructor or to this call can configure a provider on their own.
         const providerName = this.resolveDecisionProviderName(options.provider, options.credentials);
-        if (!providerName) {
-            throw new Error(`No decision provider is configured. Set ${describeDecisionProviderKeys()} (in the environment or in \`credentials\`), or pass \`provider\` explicitly.`);
-        }
         const questionIds = Object.keys(options.questions);
         const questionCount = questionIds.length;
+        const decisionDescriptor = providerName
+            ? PROVIDER_DESCRIPTORS_BY_NAME.get((PROVIDER_ALIAS_INDEX.get(providerName.toLowerCase()) ??
+                providerName))
+            : undefined;
+        const requestedModel = options.model ??
+            (decisionDescriptor && this.registeredDecisionModel(decisionDescriptor));
         const stamped = options;
+        const hostQuestionCount = questionIds.filter(isHostDecisionKey).length;
         const siteSpanAttributes = stamped.site
             ? {
                 "decision.site": stamped.site,
-                "decision.host_question_count": questionIds.filter(isHostDecisionKey).length,
+                "decision.host_question_count": hostQuestionCount,
             }
             : {};
         // Observability parity with generate()/stream(): an OTEL span for the
@@ -14249,8 +14225,9 @@ Current user's request: ${currentInput}`;
         // internal consumer is fail-open, so a decision path that has silently
         // stopped working looks exactly like one that was never configured.
         return withSpan({
-            name: `gen_ai.${providerName}.decide`,
+            name: "decide",
             tracer: tracers.decision,
+            expectedFailure: () => !providerName,
             attributes: {
                 "gen_ai.system": providerName,
                 "gen_ai.operation.name": "decide",
@@ -14260,6 +14237,25 @@ Current user's request: ${currentInput}`;
                 ...siteSpanAttributes,
             },
         }, async (otelSpan) => {
+            observe(otelSpan, "generation", {
+                model: requestedModel,
+                input: { state: options.state, questions: options.questions },
+                metadata: {
+                    provider: providerName,
+                    ...(stamped.site && {
+                        site: stamped.site,
+                        host_question_count: hostQuestionCount,
+                    }),
+                },
+            });
+            if (!providerName) {
+                const reason = `No decision provider is configured. Set ${describeDecisionProviderKeys()} (in the environment or in \`credentials\`), or pass \`provider\` explicitly.`;
+                observe(otelSpan, "generation", {
+                    level: "WARNING",
+                    statusMessage: reason,
+                });
+                throw new Error(reason);
+            }
             const { traceId, parentSpanId } = getActiveTraceContext();
             const startedAt = Date.now();
             let span = SpanSerializer.createSpan(SpanType.MODEL_DECISION, `decision.${providerName}`, {
@@ -14302,6 +14298,15 @@ Current user's request: ${currentInput}`;
                 if (result.requestId) {
                     otelSpan.setAttribute("gen_ai.response.id", result.requestId);
                 }
+                observe(otelSpan, "generation", {
+                    model: result.model,
+                    output: result.answers,
+                    usageDetails: usageDetails({
+                        input: result.usage.inputTokens,
+                        output: result.usage.outputTokens,
+                    }),
+                    costDetails: { total: cost },
+                });
                 span.durationMs = Date.now() - startedAt;
                 span = SpanSerializer.updateAttributes(span, {
                     // The key names the cost aggregator reads. `ai.model` is
@@ -14361,6 +14366,7 @@ Current user's request: ${currentInput}`;
      * `decisionHooks` and emits `decision:before` / `decision:after`.
      */
     async tryDecide(options) {
+        this.holdTelemetry();
         return this.siteDecide(options);
     }
     // ==========================================================================
@@ -14977,10 +14983,8 @@ Current user's request: ${currentInput}`;
      *
      * Worker mode is the framework-provided version of the config block every
      * consumer used to copy by hand: conversation memory OFF, orchestration
-     * OFF, observability inherited from this instance with
-     * `autoDetectExternalProvider: true` + `skipLangfuseSpanProcessor: true`
-     * (worker spans join the host's tracer without duplicate Langfuse
-     * exports), credentials inherited, the host's tool registry shared (so
+     * OFF, observability inherited from this instance (worker spans join the
+     * host's tracer provider), credentials inherited, the host's tool registry shared (so
      * worker tool calls reuse the host's connections), and an internal log
      * bridge attached with a caller-supplied tag.
      *
@@ -15001,14 +15005,7 @@ Current user's request: ${currentInput}`;
             // Worker-mode fields always win over the config merge.
             conversationMemory: { enabled: false },
             enableOrchestration: false,
-            observability: {
-                ...(this.observabilityConfig ?? {}),
-                langfuse: {
-                    ...(this.observabilityConfig?.langfuse ?? {}),
-                    autoDetectExternalProvider: true,
-                    skipLangfuseSpanProcessor: true,
-                },
-            },
+            observability: this.observabilityConfig,
             ...(options?.shareToolRegistry !== false && {
                 toolRegistry: this.toolRegistry,
             }),
@@ -15707,8 +15704,7 @@ Current user's request: ${currentInput}`;
             // 1. Flush and shutdown OpenTelemetry
             try {
                 logger.debug("[NeuroLink] Flushing and shutting down OpenTelemetry...");
-                await flushOpenTelemetry();
-                await shutdownOpenTelemetry();
+                await this.releaseTelemetryHold();
                 logger.debug("[NeuroLink] OpenTelemetry shutdown successfully");
             }
             catch (error) {