@juspay/neurolink 9.55.9 → 9.55.11

package/dist/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
  *

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

@@ -18,6 +18,7 @@ import { BatchSpanProcessor, } from "@opentelemetry/sdk-trace-base";
 import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
 import { ATTR_SERVICE_NAME, ATTR_SERVICE_VERSION, } from "@opentelemetry/semantic-conventions";
 import { AsyncLocalStorage } from "async_hooks";
+import { extractMcpErrorText } from "../../../../utils/mcpErrorText.js";
 import { logger } from "../../../../utils/logger.js";
 const LOG_PREFIX = "[OpenTelemetry]";
 function createOtelResource(config, serviceName) {
@@ -131,6 +132,64 @@ function _hasExternalTracerProvider() {
         return false;
     }
 }
+/**
+ * Parse `ai.toolCall.result` on a Vercel AI SDK tool span and surface any
+ * embedded MCP `{ isError: true }` as a Langfuse ERROR + status message.
+ */
+function applyToolCallIsErrorStatus(attrs) {
+    const resultAttr = attrs["ai.toolCall.result"];
+    if (typeof resultAttr !== "string" || resultAttr.length === 0) {
+        return;
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(resultAttr);
+    }
+    catch {
+        return;
+    }
+    if (!parsed ||
+        typeof parsed !== "object" ||
+        parsed.isError !== true) {
+        return;
+    }
+    attrs["langfuse.level"] = "ERROR";
+    // Always set a status_message, even when the MCP payload has non-text or
+    // empty content. Without a fallback the Curator P0-1 gap reappears for
+    // those failures (level=ERROR but statusMessage=null).
+    const errorText = extractMcpErrorText(parsed);
+    const toolName = typeof attrs["ai.toolCall.name"] === "string"
+        ? attrs["ai.toolCall.name"]
+        : "tool";
+    attrs["langfuse.status_message"] =
+        errorText || `MCP ${toolName} returned isError=true`;
+}
+/**
+ * Map non-ERROR span conditions (content-filter, length, client abort, SDK
+ * timeout, empty output) onto Langfuse WARNING/ERROR levels. Mutates `attrs`.
+ */
+function applyNonErrorLangfuseLevel(attrs) {
+    const finishReason = attrs["ai.finishReason"] ?? attrs["gen_ai.response.finish_reasons"];
+    const reasonStr = Array.isArray(finishReason)
+        ? finishReason.join(",")
+        : String(finishReason ?? "");
+    if (reasonStr.includes("content-filter") || reasonStr === "length") {
+        attrs["langfuse.level"] = "WARNING";
+        attrs["langfuse.status_message"] =
+            `Generation stopped: finishReason=${reasonStr}`;
+        return;
+    }
+    if (attrs["neurolink.no_output"] === true) {
+        attrs["langfuse.level"] = "WARNING";
+        attrs["langfuse.status_message"] =
+            "Stream produced no output (NoOutputGeneratedError)";
+        return;
+    }
+    if (reasonStr === "aborted") {
+        attrs["langfuse.level"] = "WARNING";
+        attrs["langfuse.status_message"] = "Generation aborted by client";
+    }
+}
 /**
  * Span processor that enriches spans with user and session context from AsyncLocalStorage
  * Also extracts GenAI semantic convention attributes for Langfuse integration
@@ -459,26 +518,23 @@ class ContextEnricher {
             const readableStatus = span.status;
             try {
                 const mutableAttrs = span.attributes;
+                // Curator P0-1/P0-2: detect MCP isError pattern on AI SDK tool call spans.
+                // The AI SDK's `ai.toolCall` span stays status=UNSET when the tool
+                // *returns* { isError:true } (no exception thrown), so Langfuse sees
+                // level=DEFAULT and no status message. Parse the stringified result
+                // and surface the embedded error text.
+                if (readableSpan.name === "ai.toolCall" &&
+                    readableStatus?.code !== SpanStatusCode.ERROR) {
+                    applyToolCallIsErrorStatus(mutableAttrs);
+                }
                 if (readableStatus?.code === SpanStatusCode.ERROR) {
                     mutableAttrs["langfuse.level"] = "ERROR";
                     if (readableStatus.message) {
                         mutableAttrs["langfuse.status_message"] = readableStatus.message;
                     }
                 }
-                else {
-                    // P8 extended: Detect WARNING-level conditions on non-ERROR spans.
-                    // The AI SDK sets ai.finishReason on its spans; content-filter and
-                    // length finish reasons indicate partial failures that deserve WARNING.
-                    const finishReason = mutableAttrs["ai.finishReason"] ??
-                        mutableAttrs["gen_ai.response.finish_reasons"];
-                    const reasonStr = Array.isArray(finishReason)
-                        ? finishReason.join(",")
-                        : String(finishReason ?? "");
-                    if (reasonStr.includes("content-filter") || reasonStr === "length") {
-                        mutableAttrs["langfuse.level"] = "WARNING";
-                        mutableAttrs["langfuse.status_message"] =
-                            `Generation stopped: finishReason=${reasonStr}`;
-                    }
+                else if (mutableAttrs["langfuse.level"] === undefined) {
+                    applyNonErrorLangfuseLevel(mutableAttrs);
                 }
             }
             catch {
@@ -520,9 +576,36 @@ async function createLangfuseProcessor(config) {
         baseUrl: config.baseUrl || "https://cloud.langfuse.com",
         environment: config.environment || "dev",
         release: config.release || "v1.0.0",
-        shouldExportSpan: () => true,
+        // Curator P1-3: skip internal wrapper spans that duplicate ai.toolCall /
+        // ai.generateText observations in Langfuse. Wrappers still emit OTel spans
+        // for internal metrics; they just aren't forwarded to Langfuse.
+        shouldExportSpan: langfuseShouldExportSpan,
     });
 }
+/**
+ * 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 function isLangfuseInternalSpan(span) {
+    return span.attributes?.["langfuse.internal"] === true;
+}
+/**
+ * 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 function langfuseShouldExportSpan({ otelSpan, }) {
+    return !isLangfuseInternalSpan(otelSpan);
+}
 async function initializeExternalOpenTelemetryMode(config, resource, otlpEndpoint, serviceName, langfuseRequested, hasLangfuseCreds) {
     if (langfuseRequested && !hasLangfuseCreds) {
         if (!otlpEndpoint) {

package/dist/types/processor.d.ts

@@ -543,6 +543,33 @@ export type ProcessedYaml = ProcessedFileBase & {
     /** YAML content converted to JSON string for AI consumption */
     asJson: string | null;
 };
+/**
+ * Structural types for fluent-ffmpeg probe data.
+ * Defined here so the optional fluent-ffmpeg package is not required at typecheck time.
+ */
+export type FfprobeStream = {
+    codec_type?: string;
+    codec_name?: string;
+    width?: number;
+    height?: number;
+    r_frame_rate?: string;
+    avg_frame_rate?: string;
+    bit_rate?: number | string;
+    channels?: number;
+    sample_rate?: number | string;
+    tags?: Record<string, string | number>;
+    [key: string]: unknown;
+};
+export type FfprobeData = {
+    streams: FfprobeStream[];
+    format: {
+        duration?: number;
+        size?: number | string;
+        bit_rate?: number | string;
+        tags?: Record<string, string | number>;
+        [key: string]: unknown;
+    };
+};
 /**
  * Structural types for exceljs objects.
  * Defined here so the optional exceljs package is not required at typecheck time.

package/dist/utils/mcpErrorText.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Extract a human-readable error string from an MCP isError result object.
+ *
+ * Shared utility — no side effects, no dependencies on other SDK modules —
+ * so it can be imported from the neurolink.ts event loop, the telemetry
+ * instrumentation (which loads earlier), and the MCP discovery layer without
+ * creating circular imports. Any change to truncation or content-type parsing
+ * must happen here and propagate to all three surfaces.
+ */
+export declare function extractMcpErrorText(raw: unknown): string;

package/dist/utils/mcpErrorText.js

@@ -0,0 +1,35 @@
+/**
+ * Extract a human-readable error string from an MCP isError result object.
+ *
+ * Shared utility — no side effects, no dependencies on other SDK modules —
+ * so it can be imported from the neurolink.ts event loop, the telemetry
+ * instrumentation (which loads earlier), and the MCP discovery layer without
+ * creating circular imports. Any change to truncation or content-type parsing
+ * must happen here and propagate to all three surfaces.
+ */
+export function extractMcpErrorText(raw) {
+    let resultObj;
+    try {
+        resultObj = typeof raw === "string" ? JSON.parse(raw) : raw;
+    }
+    catch {
+        return "";
+    }
+    if (!resultObj || typeof resultObj !== "object") {
+        return "";
+    }
+    const content = resultObj.content;
+    if (!Array.isArray(content)) {
+        return "";
+    }
+    // Fail closed on malformed entries (e.g. `content: [null]`) rather than
+    // throwing — the caller expects an empty string for unparseable input.
+    const texts = content
+        .filter((c) => c !== null &&
+        typeof c === "object" &&
+        c.type === "text" &&
+        typeof c.text === "string" &&
+        c.text.length > 0)
+        .map((c) => c.text);
+    return texts.join(" ").substring(0, 500);
+}

package/dist/utils/timeout.js

@@ -313,6 +313,12 @@ export function createTimeoutController(timeout, provider, operation) {
     }
     const controller = new AbortController();
     const timer = setTimeout(() => {
+        // NOTE: we cannot stamp the AI SDK's ai.streamText/ai.generateText span
+        // from here — the setTimeout callback runs in the async context captured
+        // at schedule time, which is BEFORE the AI SDK span exists. Instead we
+        // rely on the AI SDK propagating the TimeoutError through its recordSpan
+        // wrapper, which sets span.status = ERROR + message. ContextEnricher's
+        // SpanStatusCode.ERROR branch then surfaces level=ERROR + status_message.
         controller.abort(new TimeoutError(`${provider} ${operation} operation timed out after ${timeout}`, timeoutMs, provider, operation));
     }, timeoutMs);
     const cleanup = () => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@juspay/neurolink",
-  "version": "9.55.9",
+  "version": "9.55.11",
   "packageManager": "pnpm@10.15.1",
   "description": "Universal AI Development Platform with working MCP integration, multi-provider support, and professional CLI. Built-in tools operational, 58+ external MCP servers discoverable. Connect to filesystem, GitHub, database operations, and more. Build, test, and deploy AI applications with 13 providers: OpenAI, Anthropic, Google AI, AWS Bedrock, Azure, Hugging Face, Ollama, and Mistral AI.",
   "author": {
@@ -230,14 +230,11 @@
     "croner": "^9.1.0",
     "csv-parser": "^3.2.0",
     "dotenv": "^17.3.1",
-    "fluent-ffmpeg": "^2.1.3",
     "google-auth-library": "^10.6.1",
     "hono": "^4.12.3",
     "inquirer": "^13.3.0",
     "jose": "^6.1.3",
     "json-schema-to-zod": "^2.7.0",
-    "mediabunny": "^1.40.1",
-    "music-metadata": "^11.11.2",
     "nanoid": "^5.1.5",
     "ollama-ai-provider": "^1.2.0",
     "open": "^11.0.0",
@@ -271,6 +268,9 @@
     "@picovoice/cobra-node": "^3.0.2",
     "bullmq": "^5.52.2",
     "exceljs": "^4.4.0",
+    "fluent-ffmpeg": "^2.1.3",
+    "mediabunny": "^1.40.1",
+    "music-metadata": "^11.11.2",
     "mammoth": "^1.11.0",
     "pptxgenjs": "^4.0.1",
     "pdf-parse": "^2.4.5",