@juspay/neurolink 13.4.10 → 13.5.1

package/dist/cli/commands/decide.js

@@ -23,7 +23,7 @@ import { NeuroLink } from "../../neurolink.js";
 import { readDecisionChoice } from "../../utils/decisionAnswers.js";
 import { calculateCost, hasPricing } from "../../utils/pricing.js";
 import { logger } from "../../utils/logger.js";
-const VALID_QUESTION_TYPES = new Set(["boolean", "choice", "score"]);
+const VALID_QUESTION_TYPES = new Set(["boolean", "choice", "score", "value"]);
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -123,6 +123,10 @@ function formatAnswerLine(id, answers) {
         }
         case "score":
             return `${id}: score ${formatNumber(answer.score)}, confidence ${formatNumber(answer.confidence)}`;
+        case "value":
+            return answer.value === null
+                ? `${id}: no value found, confidence ${formatNumber(answer.confidence)}`
+                : `${id}: value ${JSON.stringify(answer.value)}, confidence ${formatNumber(answer.confidence)}`;
         default:
             return `${id}: (unrecognised answer type)`;
     }
@@ -195,12 +199,17 @@ export const decideCommand = {
         type: "string",
         array: true,
         nargs: 1,
-        describe: "Image for the model to read: a file path or a data: URL. Repeat for several (XOR, Perplexity and OpenAI Decisions take up to 8, Cloudflare Clef up to 4)",
+        describe: "Image for the model to read: a file path or a data: URL. Repeat for several (Perplexity and OpenAI Decisions take up to 8, Cloudflare Clef up to 4, XOR 1)",
     })
         .option("video", {
         type: "string",
         nargs: 1,
-        describe: "One video for the model to read: a file path or a data: URL",
+        describe: "One video for the model to read: a file path or a data: URL. No current decision provider reads video, so it is refused before any request",
+    })
+        .option("audio", {
+        type: "string",
+        nargs: 1,
+        describe: "One audio clip for the model to hear: a WAV, FLAC, Ogg or MP3 file path or a data: URL (XOR with its xor-omni model; the first 30 seconds are heard). State may then be omitted",
     })
         .option("timeout", {
         type: "number",
@@ -221,7 +230,8 @@ export const decideCommand = {
     })
         .example('$0 decide "Refund request for a damaged item" --questions \'{"urgent":{"type":"boolean","instructions":"Is this urgent?"}}\'', "Ask a single yes/no question")
         .example("$0 decide --state-file ticket.json --questions-file questions.json --format json", "Read state and questions from files, emit raw JSON")
-        .example('$0 decide "What color is this?" --provider xor --model xor-omni --image ./photo.png --questions \'{"color":{"type":"choice","instructions":"What color is the image?","criteria":{"red":"red","blue":"blue"}}}\'', "Ask about an image (XOR with its xor-omni model, Perplexity, Cloudflare Clef and OpenAI Decisions read images)"),
+        .example('$0 decide "What color is this?" --provider xor --model xor-omni --image ./photo.png --questions \'{"color":{"type":"choice","instructions":"What color is the image?","criteria":{"red":"red","blue":"blue"}}}\'', "Ask about an image (XOR with its xor-omni model, Perplexity, Cloudflare Clef and OpenAI Decisions read images)")
+        .example('$0 decide "Invoice INV-2024-0892 for 18,275 rupees" --provider xor --model xor-omni --questions \'{"amount":{"type":"value","dtype":"int","instructions":"Invoice amount?"}}\'', "Extract a typed value (XOR)"),
     handler: async (argv) => {
         const outputFormat = argv.format ?? "text";
         // --- Validate before any provider work ---------------------------------
@@ -256,8 +266,13 @@ export const decideCommand = {
             logger.error(chalk.red("Error: pass at most one --video."));
             process.exit(1);
         }
+        const audios = [].concat(argv.audio ?? []);
+        if (audios.length > 1) {
+            logger.error(chalk.red("Error: pass at most one --audio."));
+            process.exit(1);
+        }
         if (!isDecisionQuestionMap(parsedQuestions)) {
-            logger.error(chalk.red('Error: questions must be a non-empty object of { type: "boolean" | "choice" | "score", ... }.'));
+            logger.error(chalk.red('Error: questions must be a non-empty object of { type: "boolean" | "choice" | "score" | "value", ... }.'));
             process.exit(1);
         }
         let state;
@@ -268,6 +283,10 @@ export const decideCommand = {
             logger.error(chalk.red(`Error: could not read state file — ${error instanceof Error ? error.message : String(error)}`));
             process.exit(1);
         }
+        // An audio clip can be the whole input.
+        if (state === undefined && audios.length === 1) {
+            state = "";
+        }
         if (state === undefined) {
             logger.error(chalk.red("Error: provide state as a positional argument or via --state-file."));
             process.exit(1);
@@ -284,6 +303,7 @@ export const decideCommand = {
                 timeoutMs: argv.timeout,
                 ...(argv.image && argv.image.length > 0 ? { images: argv.image } : {}),
                 ...(videos.length === 1 ? { video: videos[0] } : {}),
+                ...(audios.length === 1 ? { audio: audios[0] } : {}),
             });
             spinner?.succeed("Decision complete");
             if (outputFormat === "json") {

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/factories/providerDescriptors.d.ts

@@ -45,12 +45,13 @@ export declare const DECISION_PROVIDERS: readonly ProviderDescriptor[];
  */
 export declare function resolveDefaultDecisionProvider(credentials?: NeurolinkCredentials): string | undefined;
 /**
- * Names of the decision providers that accept images, or, with `video`, the
- * ones that accept video too: a hint that names a provider which would refuse
- * the same request is worse than none.
+ * Names of the decision providers that accept images, or, with `video` or
+ * `audio`, the ones that accept that too: a hint that names a provider which
+ * would refuse the same request is worse than none.
  */
 export declare function listMediaDecisionProviders(needs?: {
     video?: boolean;
+    audio?: boolean;
 }): string[];
 /**
  * The variables that would configure each decision provider, one clause per