@juspay/neurolink 9.55.10 → 9.56.0

package/dist/core/modules/StreamHandler.js

@@ -113,6 +113,18 @@ export class StreamHandler {
                 // rather than crashing the process with an unhandled rejection.
                 if (NoOutputGeneratedError.isInstance(error)) {
                     logger.warn(`${providerName}: Stream produced no output (NoOutputGeneratedError), returning empty stream`);
+                    // Curator P2-5: stamp the active OTel span so ContextEnricher.onEnd()
+                    // surfaces a WARNING-level Langfuse observation instead of defaulting
+                    // to DEFAULT with no status message.
+                    try {
+                        const activeSpan = trace.getSpan(otelContext.active());
+                        if (activeSpan) {
+                            activeSpan.setAttribute("neurolink.no_output", true);
+                        }
+                    }
+                    catch {
+                        // Tracing not initialized — ignore.
+                    }
                     // S4 fix: yield a sentinel chunk so Pipeline B can detect the empty stream
                     // and set the span to WARNING status instead of OK
                     yield {

package/dist/core/modules/ToolsManager.js

@@ -399,6 +399,10 @@ export class ToolsManager {
                         attributes: {
                             "tool.name": toolName,
                             "tool.type": "custom",
+                            // Curator P1-3: pure wrapper — duplicates the AI SDK's
+                            // ai.toolCall observation in Langfuse. Keep the OTel span
+                            // for internal metrics; filter from Langfuse export.
+                            "langfuse.internal": true,
                         },
                     });
                     const startTime = Date.now();

package/dist/core/redisConversationMemoryManager.js

@@ -631,6 +631,11 @@ export class RedisConversationMemoryManager {
      * Applies sendToolPreview toggle and hydrates result.result for backward compat
      */
     async buildContextMessages(sessionId, userId, enableSummarization, requestId) {
+        logger.debug("[RedisConversationMemoryManager] Building context messages", {
+            sessionId,
+            userId,
+            enableSummarization,
+        });
         await this.ensureInitialized();
         if (!this.redisClient) {
             logger.warn("[RedisConversationMemoryManager] Redis client not available in buildContextMessages");
@@ -654,6 +659,11 @@ export class RedisConversationMemoryManager {
                 const redisKey = getSessionKey(this.redisConfig, sessionId, userId);
                 const conversationData = await withTimeout(redisClient.get(redisKey), REDIS_TIMEOUT_MS);
                 const conversation = deserializeConversation(conversationData || null);
+                logger.debug("[RedisConversationMemoryManager] Retrieved conversation for context building", {
+                    sessionId,
+                    userId,
+                    conversationFound: !!conversation,
+                });
                 if (!conversation) {
                     span.setAttribute("session.found", false);
                     span.setStatus({ code: SpanStatusCode.OK });
@@ -672,6 +682,12 @@ export class RedisConversationMemoryManager {
                     lastActivity: new Date(conversation.updatedAt).getTime(),
                 };
                 const contextMessages = buildContextFromPointer(session, requestId);
+                logger.debug("[RedisConversationMemoryManager] Built context messages from pointer", {
+                    sessionId,
+                    userId,
+                    contextMessageCount: contextMessages.length,
+                    pointerMessageId: session.summarizedUpToMessageId || "none",
+                });
                 const sendToolPreview = this.config?.contextCompaction?.sendToolPreview === true;
                 // Map tool_result messages: apply preview toggle + hydrate result.result
                 const finalMessages = contextMessages.map((msg) => {
@@ -695,6 +711,15 @@ export class RedisConversationMemoryManager {
                         }
                         hydratedResult = { ...msg.result, result: parsedResult };
                     }
+                    logger.debug("[RedisConversationMemoryManager] Processing tool_result message for context", {
+                        sessionId,
+                        userId,
+                        messageId: msg.id,
+                        sendToolPreview,
+                        hasPreview: !!msg.metadata?.toolOutputPreview,
+                        contentLength: content ? String(content).length : 0,
+                        resultHydrated: hydratedResult !== msg.result,
+                    });
                     return { ...msg, content, result: hydratedResult };
                 });
                 // Tool messages now have real content and participate in context properly.

package/dist/index.d.ts

@@ -48,8 +48,8 @@ export { TTSProcessor } from "./utils/ttsProcessor.js";
 import { NeuroLink } from "./neurolink.js";
 export { NeuroLink };
 export { buildObservabilityConfigFromEnv } from "./utils/observabilityHelpers.js";
-import { createContextEnricher, flushOpenTelemetry, getLangfuseContext, getLangfuseHealthStatus, getLangfuseSpanProcessor, getSpanProcessors, getTracer, getTracerProvider, initializeOpenTelemetry, isOpenTelemetryInitialized, isUsingExternalTracerProvider, runWithCurrentLangfuseContext, setLangfuseContext, shutdownOpenTelemetry } from "./services/server/ai/observability/instrumentation.js";
-export { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, setLangfuseContext, getLangfuseSpanProcessor, getTracerProvider, isOpenTelemetryInitialized, getSpanProcessors, createContextEnricher, isUsingExternalTracerProvider, getLangfuseContext, getTracer, runWithCurrentLangfuseContext, };
+import { createContextEnricher, flushOpenTelemetry, getLangfuseContext, getLangfuseHealthStatus, getLangfuseSpanProcessor, getSpanProcessors, getTracer, getTracerProvider, initializeOpenTelemetry, isLangfuseInternalSpan, isOpenTelemetryInitialized, isUsingExternalTracerProvider, langfuseShouldExportSpan, runWithCurrentLangfuseContext, setLangfuseContext, shutdownOpenTelemetry } from "./services/server/ai/observability/instrumentation.js";
+export { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, setLangfuseContext, getLangfuseSpanProcessor, getTracerProvider, isOpenTelemetryInitialized, getSpanProcessors, createContextEnricher, isUsingExternalTracerProvider, isLangfuseInternalSpan, langfuseShouldExportSpan, getLangfuseContext, getTracer, runWithCurrentLangfuseContext, };
 export { clearAnalyticsMetrics, createAnalyticsMiddleware, getAnalyticsMetrics, } from "./middleware/builtin/analytics.js";
 export { createLifecycleMiddleware } from "./middleware/builtin/lifecycle.js";
 export { MiddlewareFactory } from "./middleware/factory.js";

package/dist/index.js

@@ -80,11 +80,14 @@ import { createContextEnricher, flushOpenTelemetry,
 // Enhanced context and tracing
 getLangfuseContext, getLangfuseHealthStatus, getLangfuseSpanProcessor, 
 // NEW EXPORTS - External TracerProvider Support
-getSpanProcessors, getTracer, getTracerProvider, initializeOpenTelemetry, isOpenTelemetryInitialized, isUsingExternalTracerProvider, runWithCurrentLangfuseContext, setLangfuseContext, shutdownOpenTelemetry, } from "./services/server/ai/observability/instrumentation.js";
+getSpanProcessors, getTracer, getTracerProvider, initializeOpenTelemetry, isLangfuseInternalSpan, isOpenTelemetryInitialized, isUsingExternalTracerProvider, langfuseShouldExportSpan, runWithCurrentLangfuseContext, setLangfuseContext, shutdownOpenTelemetry, } from "./services/server/ai/observability/instrumentation.js";
 import { getTelemetryStatus as getStatus, initializeTelemetry as init, } from "./telemetry/index.js";
 export { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, setLangfuseContext, getLangfuseSpanProcessor, getTracerProvider, isOpenTelemetryInitialized, 
 // NEW EXPORTS - External TracerProvider Support
 getSpanProcessors, createContextEnricher, isUsingExternalTracerProvider, 
+// Host-processor filter helpers — reuse NeuroLink's internal-span filtering
+// when the host app registers its own LangfuseSpanProcessor.
+isLangfuseInternalSpan, langfuseShouldExportSpan, 
 // Enhanced context and tracing
 getLangfuseContext, getTracer, 
 // ALS context propagation helper

package/dist/lib/core/modules/StreamHandler.js

@@ -113,6 +113,18 @@ export class StreamHandler {
                 // rather than crashing the process with an unhandled rejection.
                 if (NoOutputGeneratedError.isInstance(error)) {
                     logger.warn(`${providerName}: Stream produced no output (NoOutputGeneratedError), returning empty stream`);
+                    // Curator P2-5: stamp the active OTel span so ContextEnricher.onEnd()
+                    // surfaces a WARNING-level Langfuse observation instead of defaulting
+                    // to DEFAULT with no status message.
+                    try {
+                        const activeSpan = trace.getSpan(otelContext.active());
+                        if (activeSpan) {
+                            activeSpan.setAttribute("neurolink.no_output", true);
+                        }
+                    }
+                    catch {
+                        // Tracing not initialized — ignore.
+                    }
                     // S4 fix: yield a sentinel chunk so Pipeline B can detect the empty stream
                     // and set the span to WARNING status instead of OK
                     yield {

package/dist/lib/core/modules/ToolsManager.js

@@ -399,6 +399,10 @@ export class ToolsManager {
                         attributes: {
                             "tool.name": toolName,
                             "tool.type": "custom",
+                            // Curator P1-3: pure wrapper — duplicates the AI SDK's
+                            // ai.toolCall observation in Langfuse. Keep the OTel span
+                            // for internal metrics; filter from Langfuse export.
+                            "langfuse.internal": true,
                         },
                     });
                     const startTime = Date.now();

package/dist/lib/core/redisConversationMemoryManager.js

@@ -631,6 +631,11 @@ export class RedisConversationMemoryManager {
      * Applies sendToolPreview toggle and hydrates result.result for backward compat
      */
     async buildContextMessages(sessionId, userId, enableSummarization, requestId) {
+        logger.debug("[RedisConversationMemoryManager] Building context messages", {
+            sessionId,
+            userId,
+            enableSummarization,
+        });
         await this.ensureInitialized();
         if (!this.redisClient) {
             logger.warn("[RedisConversationMemoryManager] Redis client not available in buildContextMessages");
@@ -654,6 +659,11 @@ export class RedisConversationMemoryManager {
                 const redisKey = getSessionKey(this.redisConfig, sessionId, userId);
                 const conversationData = await withTimeout(redisClient.get(redisKey), REDIS_TIMEOUT_MS);
                 const conversation = deserializeConversation(conversationData || null);
+                logger.debug("[RedisConversationMemoryManager] Retrieved conversation for context building", {
+                    sessionId,
+                    userId,
+                    conversationFound: !!conversation,
+                });
                 if (!conversation) {
                     span.setAttribute("session.found", false);
                     span.setStatus({ code: SpanStatusCode.OK });
@@ -672,6 +682,12 @@ export class RedisConversationMemoryManager {
                     lastActivity: new Date(conversation.updatedAt).getTime(),
                 };
                 const contextMessages = buildContextFromPointer(session, requestId);
+                logger.debug("[RedisConversationMemoryManager] Built context messages from pointer", {
+                    sessionId,
+                    userId,
+                    contextMessageCount: contextMessages.length,
+                    pointerMessageId: session.summarizedUpToMessageId || "none",
+                });
                 const sendToolPreview = this.config?.contextCompaction?.sendToolPreview === true;
                 // Map tool_result messages: apply preview toggle + hydrate result.result
                 const finalMessages = contextMessages.map((msg) => {
@@ -695,6 +711,15 @@ export class RedisConversationMemoryManager {
                         }
                         hydratedResult = { ...msg.result, result: parsedResult };
                     }
+                    logger.debug("[RedisConversationMemoryManager] Processing tool_result message for context", {
+                        sessionId,
+                        userId,
+                        messageId: msg.id,
+                        sendToolPreview,
+                        hasPreview: !!msg.metadata?.toolOutputPreview,
+                        contentLength: content ? String(content).length : 0,
+                        resultHydrated: hydratedResult !== msg.result,
+                    });
                     return { ...msg, content, result: hydratedResult };
                 });
                 // Tool messages now have real content and participate in context properly.

package/dist/lib/index.d.ts

@@ -48,8 +48,8 @@ export { TTSProcessor } from "./utils/ttsProcessor.js";
 import { NeuroLink } from "./neurolink.js";
 export { NeuroLink };
 export { buildObservabilityConfigFromEnv } from "./utils/observabilityHelpers.js";
-import { createContextEnricher, flushOpenTelemetry, getLangfuseContext, getLangfuseHealthStatus, getLangfuseSpanProcessor, getSpanProcessors, getTracer, getTracerProvider, initializeOpenTelemetry, isOpenTelemetryInitialized, isUsingExternalTracerProvider, runWithCurrentLangfuseContext, setLangfuseContext, shutdownOpenTelemetry } from "./services/server/ai/observability/instrumentation.js";
-export { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, setLangfuseContext, getLangfuseSpanProcessor, getTracerProvider, isOpenTelemetryInitialized, getSpanProcessors, createContextEnricher, isUsingExternalTracerProvider, getLangfuseContext, getTracer, runWithCurrentLangfuseContext, };
+import { createContextEnricher, flushOpenTelemetry, getLangfuseContext, getLangfuseHealthStatus, getLangfuseSpanProcessor, getSpanProcessors, getTracer, getTracerProvider, initializeOpenTelemetry, isLangfuseInternalSpan, isOpenTelemetryInitialized, isUsingExternalTracerProvider, langfuseShouldExportSpan, runWithCurrentLangfuseContext, setLangfuseContext, shutdownOpenTelemetry } from "./services/server/ai/observability/instrumentation.js";
+export { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, setLangfuseContext, getLangfuseSpanProcessor, getTracerProvider, isOpenTelemetryInitialized, getSpanProcessors, createContextEnricher, isUsingExternalTracerProvider, isLangfuseInternalSpan, langfuseShouldExportSpan, getLangfuseContext, getTracer, runWithCurrentLangfuseContext, };
 export { clearAnalyticsMetrics, createAnalyticsMiddleware, getAnalyticsMetrics, } from "./middleware/builtin/analytics.js";
 export { createLifecycleMiddleware } from "./middleware/builtin/lifecycle.js";
 export { MiddlewareFactory } from "./middleware/factory.js";

package/dist/lib/index.js

@@ -80,11 +80,14 @@ import { createContextEnricher, flushOpenTelemetry,
 // Enhanced context and tracing
 getLangfuseContext, getLangfuseHealthStatus, getLangfuseSpanProcessor, 
 // NEW EXPORTS - External TracerProvider Support
-getSpanProcessors, getTracer, getTracerProvider, initializeOpenTelemetry, isOpenTelemetryInitialized, isUsingExternalTracerProvider, runWithCurrentLangfuseContext, setLangfuseContext, shutdownOpenTelemetry, } from "./services/server/ai/observability/instrumentation.js";
+getSpanProcessors, getTracer, getTracerProvider, initializeOpenTelemetry, isLangfuseInternalSpan, isOpenTelemetryInitialized, isUsingExternalTracerProvider, langfuseShouldExportSpan, runWithCurrentLangfuseContext, setLangfuseContext, shutdownOpenTelemetry, } from "./services/server/ai/observability/instrumentation.js";
 import { getTelemetryStatus as getStatus, initializeTelemetry as init, } from "./telemetry/index.js";
 export { initializeOpenTelemetry, shutdownOpenTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, setLangfuseContext, getLangfuseSpanProcessor, getTracerProvider, isOpenTelemetryInitialized, 
 // NEW EXPORTS - External TracerProvider Support
 getSpanProcessors, createContextEnricher, isUsingExternalTracerProvider, 
+// Host-processor filter helpers — reuse NeuroLink's internal-span filtering
+// when the host app registers its own LangfuseSpanProcessor.
+isLangfuseInternalSpan, langfuseShouldExportSpan, 
 // Enhanced context and tracing
 getLangfuseContext, getTracer, 
 // ALS context propagation helper

package/dist/lib/mcp/toolDiscoveryService.js

@@ -9,10 +9,72 @@ import { globalCircuitBreakerManager, CircuitBreakerOpenError, } from "./mcpCirc
 import { isObject, isNullish } from "../utils/typeUtils.js";
 import { validateToolName, validateToolDescription, } from "../utils/parameterValidation.js";
 import { withTimeout } from "../utils/errorHandling.js";
+import { extractMcpErrorText } from "../utils/mcpErrorText.js";
 import { SpanKind, SpanStatusCode } from "@opentelemetry/api";
 import { tracers } from "../telemetry/tracers.js";
 import { withSpan } from "../telemetry/withSpan.js";
 const mcpTracer = tracers.mcp;
+/**
+ * JSON-stringify a value for a Langfuse input/output preview attribute,
+ * truncated to a hard cap to stay under span attribute size limits. The
+ * returned string is guaranteed to be ≤ maxLen characters; when truncated,
+ * the last character is replaced with an ellipsis.
+ */
+function safeJsonStringify(value, maxLen) {
+    if (maxLen <= 0) {
+        return "";
+    }
+    try {
+        const str = JSON.stringify(value);
+        if (typeof str !== "string") {
+            return "";
+        }
+        if (str.length <= maxLen) {
+            return str;
+        }
+        return str.slice(0, Math.max(0, maxLen - 1)) + "…";
+    }
+    catch {
+        return "";
+    }
+}
+/**
+ * Match property names that commonly hold secrets. Values under these keys
+ * are replaced with `[REDACTED]` before serialization. Case-insensitive.
+ * Conservative list — anything matching *here* is masked; the rest of the
+ * structure is preserved so Langfuse still gets a meaningful preview.
+ */
+const SENSITIVE_KEY_PATTERN = /^(password|passwd|secret|token|api[_-]?key|apikey|access[_-]?key|authorization|auth|bearer|credential|cookie|session[_-]?id|private[_-]?key|client[_-]?secret|refresh[_-]?token|x-api-key)$/i;
+/**
+ * Walk a value, producing a structurally-equivalent copy with sensitive-key
+ * values masked. Unlike `transformParamsForLogging` (which collapses objects
+ * to a "N params" string), this preserves non-sensitive content so Langfuse
+ * input/output previews stay useful. Bounded depth guards against cycles.
+ */
+function redactForPreview(value, depth = 0) {
+    if (depth > 10) {
+        return "[...]";
+    }
+    if (value === null || value === undefined) {
+        return value;
+    }
+    if (typeof value !== "object") {
+        return value;
+    }
+    if (Array.isArray(value)) {
+        return value.map((v) => redactForPreview(v, depth + 1));
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        if (SENSITIVE_KEY_PATTERN.test(k)) {
+            out[k] = "[REDACTED]";
+        }
+        else {
+            out[k] = redactForPreview(v, depth + 1);
+        }
+    }
+    return out;
+}
 /**
  * Default timeout for MCP tool execution operations in milliseconds.
  * Configurable via MCP_TOOL_TIMEOUT env var.
@@ -376,6 +438,18 @@ export class ToolDiscoveryService extends EventEmitter {
                         "mcp.server_id": serverId,
                         "mcp.tool_name": toolName,
                         "mcp.timeout_ms": effectiveTimeout,
+                        // Curator P1-4: Langfuse observations rely on ai.*/gen_ai.*
+                        // attributes for tool name and I/O previews. Provide them so
+                        // the SPAN observation in Langfuse is legible without
+                        // timestamp-joining against the parent ai.toolCall. Redact
+                        // parameters via the existing secret-stripping helper so
+                        // tokens/credentials/paths don't leave the process.
+                        "ai.tool.name": toolName,
+                        "gen_ai.tool.name": toolName,
+                        "gen_ai.request": safeJsonStringify({
+                            name: toolName,
+                            arguments: redactForPreview(parameters),
+                        }, 2048),
                     },
                 }, async (callSpan) => {
                     try {
@@ -384,11 +458,26 @@ export class ToolDiscoveryService extends EventEmitter {
                             name: toolName,
                             arguments: parameters,
                         }), timeout, new Error(`Tool execution timeout: ${toolName}`));
-                        callSpan.setStatus({ code: SpanStatusCode.OK });
+                        // Curator P0-1/P0-2: the MCP client does NOT throw on protocol
+                        // errors — it returns { isError: true, content: [...] }. Detect
+                        // that pattern so the span status reflects reality.
+                        const resultObj = callResult;
+                        if (resultObj && resultObj.isError === true) {
+                            const errorText = extractMcpErrorText(resultObj);
+                            callSpan.setStatus({
+                                code: SpanStatusCode.ERROR,
+                                message: errorText || `Tool ${toolName} returned isError`,
+                            });
+                        }
+                        else {
+                            callSpan.setStatus({ code: SpanStatusCode.OK });
+                        }
                         // ── MCP output normalization ──────────────────────────────────
                         // Intercept here — after receive, before cache, before memory,
                         // before LLM context injection. Returns a compact surrogate when
                         // the payload exceeds mcp.outputLimits.maxBytes.
+                        let resultForPreview = callResult;
+                        let resultForReturn = callResult;
                         if (this.outputNormalizer) {
                             try {
                                 const normalized = await this.outputNormalizer.normalize(callResult, { toolName, serverId });
@@ -396,7 +485,8 @@ export class ToolDiscoveryService extends EventEmitter {
                                 if (normalized.isExternalized) {
                                     callSpan.setAttribute("mcp.output.original_bytes", normalized.originalBytes);
                                 }
-                                return normalized.result;
+                                resultForPreview = normalized.result;
+                                resultForReturn = normalized.result;
                             }
                             catch (normErr) {
                                 mcpLogger.warn(`[ToolDiscoveryService] McpOutputNormalizer failed for ` +
@@ -405,7 +495,13 @@ export class ToolDiscoveryService extends EventEmitter {
                             }
                         }
                         // ── end normalization ─────────────────────────────────────────
-                        return callResult;
+                        // Curator P1-4: build gen_ai.response AFTER normalization so
+                        // large payloads use the compact surrogate instead of the raw
+                        // result (avoids redundant stringify + memory hit on payloads
+                        // that were specifically externalized to Redis). Redact via the
+                        // same secret-stripping path used for request parameters.
+                        callSpan.setAttribute("gen_ai.response", safeJsonStringify(redactForPreview(resultForPreview), 2048));
+                        return resultForReturn;
                     }
                     catch (err) {
                         callSpan.setStatus({

package/dist/lib/mcp/toolRegistry.js

@@ -257,6 +257,9 @@ export class MCPToolRegistry extends MCPRegistry {
             attributes: {
                 [ATTR.GEN_AI_TOOL_NAME]: toolName,
                 [ATTR.MCP_SERVER_ID]: preResolvedServerId || "builtin",
+                // Curator P1-3: registry-level wrapper — duplicates ai.toolCall in
+                // Langfuse. Retained for OTel/metrics; skipped for Langfuse export.
+                "langfuse.internal": true,
             },
         }, async (span) => {
             try {

package/dist/lib/neurolink.js

@@ -64,6 +64,7 @@ import { CircuitBreaker, ERROR_CODES, ErrorFactory, isAbortError, isRetriableErr
 // Factory processing imports
 import { createCleanStreamOptions, enhanceTextGenerationOptions, processFactoryOptions, processStreamingFactoryOptions, validateFactoryConfig, } from "./utils/factoryProcessing.js";
 import { logger, mcpLogger } from "./utils/logger.js";
+import { extractMcpErrorText } from "./utils/mcpErrorText.js";
 import { createCustomToolServerInfo, detectCategory, } from "./utils/mcpDefaults.js";
 import { resolveModel } from "./utils/modelAliasResolver.js";
 // Import orchestration components
@@ -133,29 +134,6 @@ function mcpCategoryToErrorCategory(mcpCategory) {
             return ErrorCategory.EXECUTION;
     }
 }
-/**
- * Extract a human-readable error string from an MCP isError result object.
- * Returns an empty string if nothing useful can be extracted.
- */
-function extractMcpErrorText(raw) {
-    try {
-        const resultObj = typeof raw === "string" ? JSON.parse(raw) : raw;
-        if (!resultObj || typeof resultObj !== "object") {
-            return "";
-        }
-        const content = resultObj.content;
-        if (!Array.isArray(content)) {
-            return "";
-        }
-        const texts = content
-            .filter((c) => c.type === "text" && c.text)
-            .map((c) => c.text);
-        return texts.join(" ").substring(0, 500);
-    }
-    catch {
-        return "";
-    }
-}
 /**
  * Check if an error is a non-retryable provider error that should immediately
  * stop the retry/fallback chain. These errors represent permanent failures
@@ -4508,6 +4486,16 @@ Current user's request: ${currentInput}`;
      * @throws {Error} When conversation memory operations fail (if enabled)
      */
     async stream(options) {
+        logger.debug("[NeuroLink] stream() called with options", {
+            provider: options.provider,
+            model: options.model,
+            inputLength: options.input?.text?.length || 0,
+            disableTools: options.disableTools,
+            enableAnalytics: options.enableAnalytics,
+            enableEvaluation: options.enableEvaluation,
+            contextKeys: options.context ? Object.keys(options.context) : [],
+            optionKeys: Object.keys(options),
+        });
         return metricsTraceContextStorage.run(this.createMetricsTraceContext(), () => this.executeStreamRequest({ ...options }));
     }
     async executeStreamRequest(options) {
@@ -4600,8 +4588,26 @@ Current user's request: ${currentInput}`;
     }
     async runStandardStreamRequest(params) {
         const { options, streamSpan, spanStartTime, startTime, hrTimeStart, streamId, originalPrompt, } = params;
+        logger.debug("[NeuroLink] Running standard stream request", {
+            streamId,
+            provider: options.provider,
+            model: options.model,
+            inputLength: options.input?.text?.length || 0,
+            disableTools: options.disableTools,
+            enableAnalytics: options.enableAnalytics,
+            enableEvaluation: options.enableEvaluation,
+            contextKeys: options.context ? Object.keys(options.context) : [],
+            optionKeys: Object.keys(options),
+            sessionId: options.context?.sessionId,
+        });
         try {
             const { enhancedOptions, factoryResult } = await this.prepareStreamOptions(options, streamId, startTime, hrTimeStart);
+            logger.debug("[NeuroLink] Stream options prepared", {
+                streamId,
+                options: enhancedOptions,
+                factoryResult,
+                sessionId: enhancedOptions.context?.sessionId,
+            });
             const { stream: mcpStream, provider: providerName, usage: streamUsage, model: streamModel, finishReason: streamFinishReason, toolCalls: streamToolCalls, toolResults: streamToolResults, analytics: streamAnalytics, } = await this.createMCPStream(enhancedOptions);
             const streamState = {
                 finishReason: streamFinishReason ?? "stop",
@@ -4691,6 +4697,16 @@ Current user's request: ${currentInput}`;
                     });
                 }
                 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",
@@ -4709,6 +4725,16 @@ Current user's request: ${currentInput}`;
                     throw error;
                 }
                 finally {
+                    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,
+                    });
                     self._disableToolCacheForCurrentRequest = false;
                     cleanupListeners();
                     streamSpan.setAttribute("neurolink.response_time_ms", Date.now() - spanStartTime);
@@ -5106,6 +5132,11 @@ Current user's request: ${currentInput}`;
      */
     async storeStreamConversationMemory(params) {
         const { enhancedOptions, providerName, originalPrompt, accumulatedContent, startTime, eventSequence, } = params;
+        logger.debug("[NeuroLink.stream] Preparing to store conversation turn in memory", {
+            options: JSON.stringify(enhancedOptions),
+            sessionId: enhancedOptions.context
+                ?.sessionId,
+        });
         // Guard: skip storing if no meaningful content was produced (no text AND no tool activity)
         const hasToolEvents = eventSequence.some((e) => e.type === "tool:start" || e.type === "tool:end");
         if (!accumulatedContent.trim() && !hasToolEvents) {
@@ -5115,6 +5146,12 @@ Current user's request: ${currentInput}`;
             });
             return;
         }
+        logger.debug("[NeuroLink.stream] Storing conversation turn in memory", {
+            options: JSON.stringify(enhancedOptions),
+            sessionId: enhancedOptions.context
+                ?.sessionId,
+            conversationMemoryExists: this.conversationMemory ? true : false,
+        });
         // Store memory after stream consumption is complete
         if (this.conversationMemory && enhancedOptions.context?.sessionId) {
             const sessionId = enhancedOptions.context
@@ -6267,6 +6304,13 @@ Current user's request: ${currentInput}`;
                 "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));
     }

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

@@ -11,6 +11,32 @@ import { LoggerProvider } from "@opentelemetry/sdk-logs";
 import { type SpanProcessor } from "@opentelemetry/sdk-trace-base";
 import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
 import type { LangfuseConfig, LangfuseContext } from "../../../../types/index.js";
+/**
+ * True when a span is an internal NeuroLink wrapper that should NOT be sent to
+ * Langfuse. Internal wrappers carry the `langfuse.internal: true` attribute.
+ *
+ * Exposed so host apps that bring their own `LangfuseSpanProcessor` (e.g.
+ * `skipLangfuseSpanProcessor: true`, or manual registration on an existing
+ * TracerProvider) can apply the same filter and avoid duplicate observations.
+ */
+export declare function isLangfuseInternalSpan(span: {
+    attributes?: Record<string, unknown>;
+}): boolean;
+/**
+ * Drop-in `shouldExportSpan` predicate for a `LangfuseSpanProcessor` that
+ * filters out NeuroLink internal wrapper spans.
+ *
+ * Usage in host apps:
+ * ```ts
+ * import { langfuseShouldExportSpan } from "@juspay/neurolink";
+ * new LangfuseSpanProcessor({ ..., shouldExportSpan: langfuseShouldExportSpan });
+ * ```
+ */
+export declare function langfuseShouldExportSpan({ otelSpan, }: {
+    otelSpan: {
+        attributes?: Record<string, unknown>;
+    };
+}): boolean;
 /**
  * Initialize OpenTelemetry with Langfuse span processor
  *