@juspay/neurolink 13.5.0 → 13.5.1

package/dist/cli/commands/observability.js

@@ -11,7 +11,8 @@ import chalk from "chalk";
 import ora from "ora";
 import { logger } from "../../utils/logger.js";
 import { NeuroLink } from "../../neurolink.js";
-import { formatRow, formatCost } from "../utils/formatters.js";
+import { ensureTelemetry } from "../../services/server/ai/observability/instrumentation.js";
+import { formatRow, formatCost, formatExporterLines, formatOtelStatus, } from "../utils/formatters.js";
 import { redactUrlCredentials } from "../../utils/logSanitize.js";
 /**
  * Observability Command Factory
@@ -66,6 +67,9 @@ export class ObservabilityCommandFactory {
                     ? null
                     : ora("Checking observability status...").start();
                 try {
+                    // A one-shot process only starts telemetry with its first span, so
+                    // start it here to report the exporters this process would run.
+                    ensureTelemetry();
                     const neurolink = new NeuroLink();
                     const status = neurolink.getTelemetryStatus();
                     if (spinner) {
@@ -105,9 +109,7 @@ export class ObservabilityCommandFactory {
                         if (status.openTelemetry) {
                             logger.always("");
                             logger.always(chalk.bold("OpenTelemetry:"));
-                            const otelStatus = status.openTelemetry.enabled
-                                ? chalk.green("Enabled")
-                                : chalk.gray("Disabled");
+                            const otelStatus = formatOtelStatus(status.openTelemetry, "Enabled", "Disabled");
                             logger.always(formatRow("  Status:", otelStatus));
                             if (status.openTelemetry.endpoint) {
                                 logger.always(formatRow("  Endpoint:", redactUrlCredentials(status.openTelemetry.endpoint)));
@@ -117,6 +119,11 @@ export class ObservabilityCommandFactory {
                             }
                         }
                         logger.always("");
+                        logger.always(chalk.bold("Exporters:"));
+                        for (const line of formatExporterLines(status.exporters)) {
+                            logger.always(line);
+                        }
+                        logger.always("");
                     }
                 }
                 catch (error) {

package/dist/cli/commands/telemetry.js

@@ -11,10 +11,20 @@ import chalk from "chalk";
 import ora from "ora";
 import { logger } from "../../utils/logger.js";
 import { NeuroLink } from "../../neurolink.js";
-import { flushOpenTelemetry } from "../../services/server/ai/observability/instrumentation.js";
-import { formatRow, formatCost } from "../utils/formatters.js";
+import { ensureTelemetry, flushOpenTelemetry, } from "../../services/server/ai/observability/instrumentation.js";
+import { getExporterRegistry } from "../../observability/exporterRegistry.js";
+import { formatRow, formatCost, formatExporterLines, formatOtelStatus, } from "../utils/formatters.js";
 import { redactUrlCredentials } from "../../utils/logSanitize.js";
 import { prepareNativeTelemetry, validateNativeTelemetry, } from "../utils/nativeTelemetry.js";
+function exporterTotals() {
+    return getExporterRegistry()
+        .getStatuses()
+        .reduce((sum, exporter) => ({
+        pending: sum.pending + exporter.pendingSpans,
+        delivered: sum.delivered + exporter.deliveredSpans,
+        failed: sum.failed + exporter.failedSpans,
+    }), { pending: 0, delivered: 0, failed: 0 });
+}
 /**
  * Telemetry Command Factory
  */
@@ -180,6 +190,9 @@ export class TelemetryCommandFactory {
                     ? null
                     : ora("Checking telemetry status...").start();
                 try {
+                    // A one-shot process only starts telemetry with its first span, so
+                    // start it here to report the exporters this process would run.
+                    ensureTelemetry();
                     const neurolink = new NeuroLink();
                     const status = neurolink.getTelemetryStatus();
                     if (spinner) {
@@ -204,9 +217,7 @@ export class TelemetryCommandFactory {
                         if (status.openTelemetry) {
                             logger.always("");
                             logger.always(chalk.bold("OpenTelemetry:"));
-                            const otelStatus = status.openTelemetry.enabled
-                                ? chalk.green("Active")
-                                : chalk.gray("Inactive");
+                            const otelStatus = formatOtelStatus(status.openTelemetry, "Active", "Inactive");
                             logger.always(formatRow("  Status:", otelStatus));
                             if (status.openTelemetry.endpoint) {
                                 logger.always(formatRow("  Endpoint:", redactUrlCredentials(status.openTelemetry.endpoint)));
@@ -231,6 +242,11 @@ export class TelemetryCommandFactory {
                             }
                         }
                         logger.always("");
+                        logger.always(chalk.bold("Exporters:"));
+                        for (const line of formatExporterLines(status.exporters)) {
+                            logger.always(line);
+                        }
+                        logger.always("");
                     }
                 }
                 catch (error) {
@@ -277,6 +293,7 @@ export class TelemetryCommandFactory {
                     ? null
                     : ora("Flushing pending spans...").start();
                 try {
+                    const before = exporterTotals();
                     // Create a timeout promise
                     let flushTimer;
                     const timeoutPromise = new Promise((_, reject) => {
@@ -293,13 +310,26 @@ export class TelemetryCommandFactory {
                     if (spinner) {
                         spinner.succeed("Flush completed");
                     }
+                    const after = exporterTotals();
+                    const flushed = after.delivered - before.delivered;
+                    const dropped = after.failed - before.failed;
                     if (args.format === "json") {
-                        logger.always(JSON.stringify({ success: true }, null, 2));
+                        logger.always(JSON.stringify({
+                            success: true,
+                            pendingBefore: before.pending,
+                            pendingAfter: after.pending,
+                            flushed,
+                            dropped,
+                        }, null, 2));
                     }
                     else {
                         logger.always("");
                         logger.always(chalk.bold.cyan("=== Flush Complete ==="));
                         logger.always("");
+                        logger.always(formatRow("Spans before:", before.pending.toString()));
+                        logger.always(formatRow("Spans after:", after.pending.toString()));
+                        logger.always(formatRow("Flushed:", chalk.green(flushed.toString())));
+                        logger.always(formatRow("Dropped:", dropped > 0 ? chalk.red(dropped.toString()) : "0"));
                         logger.always("");
                     }
                 }

package/dist/cli/utils/formatters.d.ts

@@ -3,10 +3,27 @@
  *
  * Common formatting functions used across CLI command modules.
  */
+import type { ExporterStatus } from "../../types/index.js";
 /**
  * Format a table row with padding
  */
 export declare function formatRow(label: string, value: string, width?: number): string;
+/**
+ * Format the status rows of the registered exporters
+ */
+export declare function formatExporterLines(exporters: ExporterStatus[]): string[];
+/**
+ * @description Labels NeuroLink's OpenTelemetry export for the status commands. Beside a host TracerProvider NeuroLink exports nothing to the endpoint, so it is shown as ignored rather than active.
+ * @param otel {{ enabled: boolean; endpoint?: string; usingExternalProvider?: boolean }} - `getTelemetryStatus().openTelemetry`.
+ * @param on {string} - Label for an export NeuroLink runs.
+ * @param off {string} - Label for no export.
+ * @returns {string} The coloured label.
+ */
+export declare function formatOtelStatus(otel: {
+    enabled: boolean;
+    endpoint?: string;
+    usingExternalProvider?: boolean;
+}, on: string, off: string): string;
 /**
  * Format currency value
  */

package/dist/cli/utils/formatters.js

@@ -3,6 +3,7 @@
  *
  * Common formatting functions used across CLI command modules.
  */
+import chalk from "chalk";
 /**
  * Format a table row with padding
  */
@@ -10,6 +11,44 @@ export function formatRow(label, value, width = 30) {
     const paddedLabel = label.padEnd(width);
     return `${paddedLabel} ${value}`;
 }
+/**
+ * Format the status rows of the registered exporters
+ */
+export function formatExporterLines(exporters) {
+    if (exporters.length === 0) {
+        return ["  None registered"];
+    }
+    return exporters.flatMap((exporter) => {
+        const state = !exporter.enabled
+            ? "Stopped"
+            : exporter.healthy
+                ? "Active"
+                : "Failing";
+        const counts = `pending ${exporter.pendingSpans}, delivered ${exporter.deliveredSpans}, failed ${exporter.failedSpans}`;
+        return [
+            formatRow(`  ${exporter.name}:`, `${state} (${counts})`),
+            ...(exporter.lastExportTime
+                ? [formatRow("    Last export:", exporter.lastExportTime)]
+                : []),
+            ...(exporter.errors ?? []).map((error) => formatRow("    Error:", error)),
+        ];
+    });
+}
+/**
+ * @description Labels NeuroLink's OpenTelemetry export for the status commands. Beside a host TracerProvider NeuroLink exports nothing to the endpoint, so it is shown as ignored rather than active.
+ * @param otel {{ enabled: boolean; endpoint?: string; usingExternalProvider?: boolean }} - `getTelemetryStatus().openTelemetry`.
+ * @param on {string} - Label for an export NeuroLink runs.
+ * @param off {string} - Label for no export.
+ * @returns {string} The coloured label.
+ */
+export function formatOtelStatus(otel, on, off) {
+    if (otel.usingExternalProvider) {
+        return chalk.yellow(otel.endpoint
+            ? "Ignored (a host TracerProvider is registered)"
+            : "Host TracerProvider");
+    }
+    return otel.enabled ? chalk.green(on) : chalk.gray(off);
+}
 /**
  * Format currency value
  */

package/dist/constants/langfuse.d.ts

@@ -11,15 +11,31 @@ export declare const DEFAULT_FLUSH_AT = 15;
 export declare const DEFAULT_FLUSH_INTERVAL_MS = 5000;
 /** @description Milliseconds before an export request is aborted. */
 export declare const DEFAULT_TIMEOUT_MS = 30000;
+/** @description Milliseconds a flush or shutdown waits for delivery before it abandons what is still in flight. */
+export declare const DEFAULT_FLUSH_BUDGET_MS = 3000;
 /** @description Maximum spans sent in one export request. */
 export declare const MAX_SPANS_PER_REQUEST = 500;
+/** @description Export requests to Langfuse in flight at once. Spans that end while every one is busy wait in the buffer. */
+export declare const MAX_CONCURRENT_DELIVERIES = 4;
+/** @description Spans that may wait for a delivery slot. Beyond it the oldest waiting spans are dropped and counted, so a Langfuse that stops answering cannot hold an unbounded backlog in memory. */
+export declare const MAX_QUEUED_SPANS = 10000;
+/** @description Milliseconds between warn-level logs about waiting spans dropped for lack of a delivery slot. */
+export declare const QUEUE_DROP_WARN_INTERVAL_MS = 60000;
+/** @description Longest `Retry-After` a 429 or 503 from Langfuse is waited out before the retry. */
+export declare const MAX_EXPORT_RETRY_AFTER_MS = 60000;
 /** @description Maximum serialized bytes sent in one export request. */
 export declare const MAX_BYTES_PER_REQUEST = 3500000;
 /** @description Placeholder that replaces a value fully removed by the user's mask. */
 export declare const FULLY_MASKED = "<fully masked>";
-/** @description Span attributes holding trace and observation input or output, which the mask applies to. */
+/** @description Span attributes holding trace and observation input or output, which the Langfuse exporter's mask and `redactIO` apply to. */
 export declare const CONTENT_KEYS: Set<string>;
 /** @description Attribute prefixes whose values are metadata entries. */
 export declare const METADATA_PREFIXES: string[];
+/** @description Observation types that hold no model, usage or cost in Langfuse. GenAI model and usage keys on them are left out of the Langfuse export, so a request's generation stays its only priced record. */
+export declare const UNPRICED_OBSERVATION_TYPES: ReadonlySet<string>;
+/** @description GenAI attributes Langfuse reads a model name from. */
+export declare const MODEL_ATTRIBUTE_KEYS: ReadonlySet<string>;
+/** @description Prefix of the GenAI attributes Langfuse reads usage and cost from. */
+export declare const USAGE_ATTRIBUTE_PREFIX = "gen_ai.usage.";
 /** @description OTLP numeric status code for each span status. */
 export declare const OTLP_STATUS_CODES: Record<SpanStatus, number>;

package/dist/constants/langfuse.js

@@ -11,13 +11,23 @@ export const DEFAULT_FLUSH_AT = 15;
 export const DEFAULT_FLUSH_INTERVAL_MS = 5_000;
 /** @description Milliseconds before an export request is aborted. */
 export const DEFAULT_TIMEOUT_MS = 30_000;
+/** @description Milliseconds a flush or shutdown waits for delivery before it abandons what is still in flight. */
+export const DEFAULT_FLUSH_BUDGET_MS = 3_000;
 /** @description Maximum spans sent in one export request. */
 export const MAX_SPANS_PER_REQUEST = 500;
+/** @description Export requests to Langfuse in flight at once. Spans that end while every one is busy wait in the buffer. */
+export const MAX_CONCURRENT_DELIVERIES = 4;
+/** @description Spans that may wait for a delivery slot. Beyond it the oldest waiting spans are dropped and counted, so a Langfuse that stops answering cannot hold an unbounded backlog in memory. */
+export const MAX_QUEUED_SPANS = 10_000;
+/** @description Milliseconds between warn-level logs about waiting spans dropped for lack of a delivery slot. */
+export const QUEUE_DROP_WARN_INTERVAL_MS = 60_000;
+/** @description Longest `Retry-After` a 429 or 503 from Langfuse is waited out before the retry. */
+export const MAX_EXPORT_RETRY_AFTER_MS = 60_000;
 /** @description Maximum serialized bytes sent in one export request. */
 export const MAX_BYTES_PER_REQUEST = 3_500_000;
 /** @description Placeholder that replaces a value fully removed by the user's mask. */
 export const FULLY_MASKED = "<fully masked>";
-/** @description Span attributes holding trace and observation input or output, which the mask applies to. */
+/** @description Span attributes holding trace and observation input or output, which the Langfuse exporter's mask and `redactIO` apply to. */
 export const CONTENT_KEYS = new Set([
     "langfuse.observation.input",
     "langfuse.observation.output",
@@ -29,6 +39,18 @@ export const METADATA_PREFIXES = [
     "langfuse.observation.metadata.",
     "langfuse.trace.metadata.",
 ];
+/** @description Observation types that hold no model, usage or cost in Langfuse. GenAI model and usage keys on them are left out of the Langfuse export, so a request's generation stays its only priced record. */
+export const UNPRICED_OBSERVATION_TYPES = new Set([
+    "span",
+    "event",
+]);
+/** @description GenAI attributes Langfuse reads a model name from. */
+export const MODEL_ATTRIBUTE_KEYS = new Set([
+    "gen_ai.request.model",
+    "gen_ai.response.model",
+]);
+/** @description Prefix of the GenAI attributes Langfuse reads usage and cost from. */
+export const USAGE_ATTRIBUTE_PREFIX = "gen_ai.usage.";
 /** @description OTLP numeric status code for each span status. */
 export const OTLP_STATUS_CODES = {
     [SpanStatus.UNSET]: 0,

package/dist/constants/telemetry.d.ts

@@ -18,3 +18,9 @@ export declare const TRACE_METADATA_CONTEXT_KEY = "neurolink.trace.metadata";
 export declare const OTEL_LOG_PREFIX = "[OpenTelemetry]";
 /** @description Most open and most ended spans the exporter span processor remembers for re-parenting; the oldest are forgotten first. */
 export declare const MAX_REMEMBERED_SPANS = 5000;
+/** @description Most redacted span attribute strings remembered so `observe` does not redact them a second time. */
+export declare const MAX_REDACTED_ATTRIBUTES = 64;
+/** @description Span attribute that keeps a wrapper span out of every exporter. */
+export declare const INTERNAL_SPAN_ATTRIBUTE = "langfuse.internal";
+/** @description Instrumentation scope of the proxy's tracer. Of the proxy's spans only the ones it marks as observations (the request root and its generation) reach the exporters, although its spans also carry `gen_ai.*` keys for collectors. */
+export declare const PROXY_TRACER_SCOPE = "neurolink.proxy";

package/dist/constants/telemetry.js

@@ -32,3 +32,9 @@ export const TRACE_METADATA_CONTEXT_KEY = "neurolink.trace.metadata";
 export const OTEL_LOG_PREFIX = "[OpenTelemetry]";
 /** @description Most open and most ended spans the exporter span processor remembers for re-parenting; the oldest are forgotten first. */
 export const MAX_REMEMBERED_SPANS = 5_000;
+/** @description Most redacted span attribute strings remembered so `observe` does not redact them a second time. */
+export const MAX_REDACTED_ATTRIBUTES = 64;
+/** @description Span attribute that keeps a wrapper span out of every exporter. */
+export const INTERNAL_SPAN_ATTRIBUTE = "langfuse.internal";
+/** @description Instrumentation scope of the proxy's tracer. Of the proxy's spans only the ones it marks as observations (the request root and its generation) reach the exporters, although its spans also carry `gen_ai.*` keys for collectors. */
+export const PROXY_TRACER_SCOPE = "neurolink.proxy";

package/dist/core/baseProvider.js

@@ -1760,6 +1760,7 @@ export class BaseProvider {
                 error,
                 latency,
             };
+            this.telemetryHandler.recordTTSFailure(ttsProvider, error, latency);
             logger.error(`TTS synthesis failed in Mode 1 (direct input synthesis):`, ttsError);
         }
         return this.enhanceResult(baseResult, options, startTime);
@@ -2117,6 +2118,7 @@ export class BaseProvider {
         catch (ttsError) {
             const latency = Date.now() - ttsStartTime;
             const error = this.getTTSErrorDetails(ttsError);
+            this.telemetryHandler.recordTTSFailure(ttsProvider, error, latency);
             logger.error(`TTS synthesis failed in Mode 2 (AI response synthesis):`, ttsError);
             return {
                 ...enhancedResult,

package/dist/core/geminiLoopAdapter.js

@@ -242,6 +242,25 @@ export function createGeminiLoopAdapter(config) {
             });
             return next;
         },
+        // Gemini's prompt count already contains the cached tokens, and its
+        // candidate count leaves out the thinking tokens. The step's usage keeps
+        // that raw shape because the provider clients reconcile the turn totals
+        // from it once, and callers get those counts as the API reported them;
+        // only the generation observation is rebased, so a cached token is not
+        // billed at the input rate as well as the cache rate, a cached count above
+        // the prompt is not billed as extra tokens, and a thinking token is billed
+        // at the output rate.
+        observedUsage(usage) {
+            const cached = usage.cacheReadTokens === undefined
+                ? undefined
+                : Math.min(usage.cacheReadTokens, usage.inputTokens);
+            return {
+                ...usage,
+                inputTokens: Math.max(0, usage.inputTokens - (cached ?? 0)),
+                outputTokens: usage.outputTokens + (usage.reasoningTokens ?? 0),
+                ...(cached !== undefined && { cacheReadTokens: cached }),
+            };
+        },
         mapFinishReason(rawStopReason, hadToolCallsAtCap) {
             const mapped = mapGeminiFinishReason(rawStopReason);
             // "tool-calls" from this hook means the step cap cut the turn off with

package/dist/core/loopEngine.js

@@ -306,6 +306,7 @@ async function executeObservedStep(adapter, request, channel, signal, span) {
         catch (err) {
             throw err instanceof PostEmissionStepError ? err.cause : err;
         }
+        const observed = adapter.observedUsage?.(result.usage) ?? result.usage;
         observeGeneration(generationSpan, {
             provider: request.generation?.provider,
             model: request.generation?.model,
@@ -316,13 +317,15 @@ async function executeObservedStep(adapter, request, channel, signal, span) {
                 ...(result.toolCalls.length > 0 ? { toolCalls: result.toolCalls } : {}),
             },
             usage: {
-                inputTokens: result.usage.inputTokens,
-                outputTokens: result.usage.outputTokens,
-                cacheReadTokens: result.usage.cacheReadTokens,
-                cacheCreationTokens: result.usage.cacheWriteTokens,
-                reasoningTokens: result.usage.reasoningTokens,
+                inputTokens: observed.inputTokens,
+                outputTokens: observed.outputTokens,
+                cacheReadTokens: observed.cacheReadTokens,
+                cacheCreationTokens: observed.cacheWriteTokens,
+                reasoningTokens: observed.reasoningTokens,
             },
-            finishReason: result.rawStopReason,
+            // A step cut short before the provider's terminal event has no stop
+            // reason; record "other", as the turn's own finishReason does.
+            finishReason: result.rawStopReason ?? (signal.aborted ? "other" : undefined),
             aborted: signal.aborted,
             completionStartTime: firstChunkAt,
         });
@@ -370,7 +373,7 @@ export function runAgenticLoop(adapter, initialConversation, options) {
         // ever writes to it, so the loop is the same loop it was.
         let stepCap = adapter.maxSteps;
         const turnStartedAt = Date.now();
-        const stepSpans = new StepSpans();
+        const stepSpans = new StepSpans(options.operation);
         try {
             for (let step = 0; step < stepCap; step++) {
                 if (internalAbort.signal.aborted) {

package/dist/core/modules/StreamHandler.js

@@ -129,10 +129,11 @@ export class StreamHandler {
                     // captured upstream error (if any) so providerError /
                     // modelResponseRaw carry the real cause.
                     const sentinel = await buildNoOutputSentinel(error, result, getUnderlyingError?.());
-                    // Curator P2-5 + P3-6: stamp the active OTel span so
-                    // ContextEnricher.onEnd() surfaces a WARNING-level Langfuse
-                    // observation with finishReason + token usage. Centralized in
-                    // stampNoOutputSpan so every wired site stamps consistently.
+                    // Curator P2-5 + P3-6: stamp the active OTel span with the
+                    // WARNING observation level and a status message carrying
+                    // finishReason + token usage, which ExporterSpanProcessor exports
+                    // with the span. Centralized in stampNoOutputSpan so every wired
+                    // site stamps consistently.
                     stampNoOutputSpan(sentinel);
                     // S4 fix: yield a sentinel chunk so Pipeline B can detect the empty stream
                     // and set the span to WARNING status instead of OK

package/dist/core/modules/TelemetryHandler.d.ts

@@ -13,7 +13,7 @@
  * @module core/modules/TelemetryHandler
  */
 import type { NeuroLink } from "../../neurolink.js";
-import type { StreamOptions, AIProviderName, AnalyticsData, EnhancedGenerateResult, EvaluationData, MemoryToolCallRecord, MemoryToolResultRecord, RawUsageObject, TextGenerationOptions, TokenUsage } from "../../types/index.js";
+import type { StreamOptions, AIProviderName, AnalyticsData, EnhancedGenerateResult, EvaluationData, MemoryToolCallRecord, MemoryToolResultRecord, RawUsageObject, TextGenerationOptions, TokenUsage, TTSMetadata } from "../../types/index.js";
 /**
  * TelemetryHandler class - Handles analytics and telemetry for AI providers
  */
@@ -34,6 +34,10 @@ export declare class TelemetryHandler {
      * Record performance metrics for a generation
      */
     recordPerformanceMetrics(usage: RawUsageObject | undefined, responseTime: number): Promise<void>;
+    /**
+     * Record a TTS synthesis failure without affecting the generation result.
+     */
+    recordTTSFailure(ttsProvider: string, error: NonNullable<TTSMetadata["error"]>, latency: number): void;
     /**
      * Estimate cost only from known per-model rates. Unknown pricing remains
      * absent from cost metrics instead of using another model's default rate.

package/dist/core/modules/TelemetryHandler.js

@@ -16,6 +16,7 @@ import { nanoid } from "nanoid";
 import { extractTokenUsage } from "../../utils/tokenUtils.js";
 import { logger } from "../../utils/logger.js";
 import { recordProviderPerformanceFromMetrics } from "../evaluationProviders.js";
+import { recordAIRequest, recordCustomHistogram, recordCustomMetric, } from "../../telemetry/aiMetrics.js";
 import { calculateCost, hasPricing } from "../../utils/pricing.js";
 /**
  * TelemetryHandler class - Handles analytics and telemetry for AI providers
@@ -84,6 +85,7 @@ export class TelemetryHandler {
                 cost: actualCost,
                 success: true,
             });
+            recordAIRequest(this.providerName, this.modelName, totalTokens, responseTime, actualCost !== undefined && actualCost > 0 ? actualCost : undefined);
             logger.debug(`Performance recorded for ${this.providerName}`, {
                 responseTime: `${responseTime}ms`,
                 tokens: totalTokens,
@@ -94,6 +96,20 @@ export class TelemetryHandler {
             logger.warn("⚠️ Performance recording failed:", perfError);
         }
     }
+    /**
+     * Record a TTS synthesis failure without affecting the generation result.
+     */
+    recordTTSFailure(ttsProvider, error, latency) {
+        const labels = {
+            provider: ttsProvider,
+            error_code: error.code,
+            ...(error.retriable !== undefined
+                ? { retriable: error.retriable.toString() }
+                : {}),
+        };
+        recordCustomMetric("tts_failures", 1, labels);
+        recordCustomHistogram("tts_failure_latency_ms", latency, labels);
+    }
     /**
      * Estimate cost only from known per-model rates. Unknown pricing remains
      * absent from cost metrics instead of using another model's default rate.

package/dist/core/modules/ToolsManager.js

@@ -860,6 +860,9 @@ export class ToolsManager {
                         attributes: {
                             "tool.name": toolName,
                             "tool.type": "custom",
+                            // Pure wrapper around the `tool` observation of the same
+                            // call: it stays an OpenTelemetry span but is not exported.
+                            [ATTR.NL_INTERNAL]: true,
                         },
                     });
                     const startTime = Date.now();

package/dist/core/nativeGenerateLoop.js

@@ -447,7 +447,7 @@ function generateObservedStep(args, request) {
     });
 }
 export async function runNativeGenerateLoop(args, toolExecutionSummaries) {
-    const stepSpans = new StepSpans();
+    const stepSpans = new StepSpans("generate");
     try {
         return await runGenerateSteps(args, toolExecutionSummaries, stepSpans);
     }

package/dist/evaluation/index.d.ts

@@ -1,3 +1,4 @@
+import "../services/server/ai/observability/instrumentation.js";
 import type { EvaluationData, GenerateResult, AutoEvaluationConfig, EvaluationConfig } from "../types/index.js";
 import type { LanguageModelV3CallOptions } from "../types/index.js";
 export * from "./errors/index.js";

package/dist/evaluation/index.js

@@ -1,3 +1,7 @@
+// Imported on its own, this entry starts tracing at its first span, as the
+// main entry does. The import sits here rather than in the shared tracers so
+// that the client entry stays free of the OpenTelemetry Node SDK.
+import "../services/server/ai/observability/instrumentation.js";
 import { ContextBuilder } from "./contextBuilder.js";
 import { RAGASEvaluator } from "./ragasEvaluator.js";
 import { mapToEvaluationData } from "./scoring.js";

package/dist/evaluation/ragasEvaluator.js

@@ -38,6 +38,7 @@ export class RAGASEvaluator {
         return withSpan({
             name: "neurolink.evaluation.ragas",
             tracer: tracers.sdk,
+            observationType: "span",
             attributes: {
                 "evaluation.provider": this.providerName,
                 "evaluation.model": this.evaluationModel,

package/dist/mcp/externalServerManager.js

@@ -14,6 +14,7 @@ import { toolRegistry } from "./toolRegistry.js";
 import { HITLUserRejectedError, HITLTimeoutError } from "../hitl/hitlErrors.js";
 import { detectCategory } from "../utils/mcpDefaults.js";
 import { isObject, isNonNullObject } from "../utils/typeUtils.js";
+import { recordMCPToolCall } from "../telemetry/aiMetrics.js";
 import { tracers } from "../telemetry/tracers.js";
 import { SpanStatusCode } from "@opentelemetry/api";
 // `@modelcontextprotocol/sdk`'s stdio transport (imported above) does
@@ -2045,8 +2046,9 @@ export class ExternalServerManager extends EventEmitter {
             if (result.success) {
                 // A resolved `{ isError: true }` still comes back with success:true so
                 // the caller receives the MCP error payload as-is, but it is a failed
-                // call for telemetry: label mcp_tool_calls_total accordingly instead
-                // of counting every resolved error as a success.
+                // call for telemetry: count it in the server's totalErrors and as
+                // success=false in mcp_tool_calls_total instead of counting every
+                // resolved error as a success.
                 const resolvedError = result.isErrorResult === true;
                 if (resolvedError) {
                     instance.metrics.totalErrors++;
@@ -2056,6 +2058,7 @@ export class ExternalServerManager extends EventEmitter {
                     : `[ExternalServerManager] Tool executed successfully: ${toolName} on ${serverId}`, {
                     duration,
                 });
+                recordMCPToolCall(toolName, duration, !resolvedError);
                 return result.data;
             }
             else {
@@ -2064,6 +2067,7 @@ export class ExternalServerManager extends EventEmitter {
         }
         catch (error) {
             instance.metrics.totalErrors++;
+            recordMCPToolCall(toolName, Date.now() - startTime, false);
             mcpLogger.error(`[ExternalServerManager] Tool execution failed: ${toolName} on ${serverId}`, error);
             // The SDK rejects with its connection-closed error when the server is
             // gone. Without this transition the instance stayed "connected" and

package/dist/mcp/toolRegistry.js

@@ -293,6 +293,9 @@ export class MCPToolRegistry extends MCPRegistry {
             attributes: {
                 "tool.name": toolName,
                 [ATTR.MCP_SERVER_ID]: preResolvedServerId || "builtin",
+                // Registry-level wrapper around the `tool` observation of the same
+                // call: it stays an OpenTelemetry span but is not exported.
+                [ATTR.NL_INTERNAL]: true,
             },
         }, async (span) => {
             try {

package/dist/neurolink.d.ts

@@ -1,5 +1,5 @@
 import type { DecisionCallerOptions, DecisionLimitsQuery, DecisionLimitsReading, DecisionOptions, DecisionResult, AgentDefinition, AgentNetworkConfig, AgentRunOptions, AgentRunOutcome, AgentToolRegistrationOptions, IsolatedAgentDefinition, NetworkExecutionInput, NetworkExecutionOptions, NetworkExecutionResult, NetworkStreamChunk, WorkerInstanceOptions } from "./types/index.js";
-import type { CompactionConfig, CompactionResult, ArtifactStore, SpanData, ObservabilityConfig, MetricsSummary, MCPToolAnnotations, TraceView, AuthenticatedContext, AuthProvider, JsonObject, NeuroLinkEvents, TypedEventEmitter, MCPEnhancementsConfig, NeuroLinkAuthConfig, NeurolinkConstructorConfig, ChatMessage, ConversationSeedMessage, ConversationSeedOptions, RecordConversationTurnOptions, RecordConversationTurnResult, ExternalMCPOperationResult, ExternalMCPServerInstance, ExternalMCPServerHealth, ExternalMCPToolInfo, GenerateOptions, GenerateResult, ProviderStatus, TextGenerationOptions, TextGenerationResult, MCPExecutableTool, MCPServerInfo, MCPStatus, StreamOptions, StreamResult, ToolExecutionContext, ToolExecutionSummary, ToolInfo, ToolRegistrationOptions, BatchOperationResult, StreamGenerationEndContext, ToolRoutingServerDescriptor, ToolDedupConfig, ToolConfig, KnowledgeEngineStatus, ChecklistState, ArtifactPageRequest, BankArtifactOptions, BankedArtifactRef, DelegateCollectRequest, DelegateCollectResult, DelegateHandle, DelegateRegistrationOptions, DelegateSpawnOptions, BackgroundCommandHandle, BackgroundCommandOptions, BackgroundCommandOutputPage, BackgroundCommandPageRequest, BackgroundCommandPolicy, BackgroundCommandStatus, GitToolResult, GitToolsetOptions } from "./types/index.js";
+import type { CompactionConfig, CompactionResult, ArtifactStore, SpanData, ExporterStatus, ObservabilityConfig, MetricsSummary, MCPToolAnnotations, TraceView, AuthenticatedContext, AuthProvider, JsonObject, NeuroLinkEvents, TypedEventEmitter, MCPEnhancementsConfig, NeuroLinkAuthConfig, NeurolinkConstructorConfig, ChatMessage, ConversationSeedMessage, ConversationSeedOptions, RecordConversationTurnOptions, RecordConversationTurnResult, ExternalMCPOperationResult, ExternalMCPServerInstance, ExternalMCPServerHealth, ExternalMCPToolInfo, GenerateOptions, GenerateResult, ProviderStatus, TextGenerationOptions, TextGenerationResult, MCPExecutableTool, MCPServerInfo, MCPStatus, StreamOptions, StreamResult, ToolExecutionContext, ToolExecutionSummary, ToolInfo, ToolRegistrationOptions, BatchOperationResult, StreamGenerationEndContext, ToolRoutingServerDescriptor, ToolDedupConfig, ToolConfig, KnowledgeEngineStatus, ChecklistState, ArtifactPageRequest, BankArtifactOptions, BankedArtifactRef, DelegateCollectRequest, DelegateCollectResult, DelegateHandle, DelegateRegistrationOptions, DelegateSpawnOptions, BackgroundCommandHandle, BackgroundCommandOptions, BackgroundCommandOutputPage, BackgroundCommandPageRequest, BackgroundCommandPolicy, BackgroundCommandStatus, GitToolResult, GitToolsetOptions } from "./types/index.js";
 import { ConversationMemoryManager } from "./core/conversationMemoryManager.js";
 import type { RedisConversationMemoryManager } from "./core/redisConversationMemoryManager.js";
 import { ExternalServerManager } from "./mcp/externalServerManager.js";
@@ -687,6 +687,10 @@ export declare class NeuroLink {
     isTelemetryEnabled(): boolean;
     /**
      * Get comprehensive telemetry status including Langfuse and OpenTelemetry state
+     * and every registered exporter with its queued, delivered and dropped spans.
+     * `openTelemetry.enabled` is whether tracing is initialized, as it always
+     * was. Beside a host TracerProvider, `openTelemetry.usingExternalProvider`
+     * is `true`: NeuroLink exports nothing to the endpoint.
      */
     getTelemetryStatus(): {
         enabled: boolean;
@@ -699,7 +703,9 @@ export declare class NeuroLink {
             enabled: boolean;
             endpoint?: string;
             serviceName?: string;
+            usingExternalProvider?: boolean;
         };
+        exporters: ExporterStatus[];
     };
     /**
      * Get aggregated observability metrics (latency, tokens, cost, success rate)
@@ -2714,13 +2720,15 @@ export declare class NeuroLink {
      * on the wire can differ from the instance's.
      *
      * Fail-open by construction, in three layers. Without a decision provider
-     * nothing runs at all — no hook, no event — and the consumer gets the null
-     * it always got. Everything a host can reach (its hook's return value, the
-     * event payloads, the answer split, `onAnswers`) runs inside one `try`;
-     * whatever a host throws, the consumer gets what `tryRunDecide` alone
-     * would have given it. And every host-facing value is a `structuredClone`,
-     * so a hook or listener that edits what it is handed edits neither the
-     * wire request nor the consumer's own question objects.
+     * no hook runs and no event is emitted: the call goes to `tryRunDecide`
+     * alone, which records the WARNING `decide` observation it always did, and
+     * the consumer gets the null it always got. Everything a host can reach
+     * (its hook's return value, the event payloads, the answer split,
+     * `onAnswers`) runs inside one `try`; whatever a host throws, the consumer
+     * gets what `tryRunDecide` alone would have given it. And every
+     * host-facing value is a `structuredClone`, so a hook or listener that
+     * edits what it is handed edits neither the wire request nor the
+     * consumer's own question objects.
      *
      * `outer` is what the surrounding `generate()` / `stream()` supplies —
      * per-call credentials, abort signal, ids — and wins over the same fields