@juspay/neurolink 13.5.0 → 13.6.0

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.d.ts

@@ -152,7 +152,9 @@ export declare abstract class BaseProvider implements AIProvider {
     private sortToolRecord;
     /**
      * On-demand discovery (`tools.discovery: true`): defer external MCP tool
-     * schemas behind one `search_tools` meta-tool. Built-in tools, per-call
+     * schemas — or, with `tools.discoveryScope: "all"`, every non-built-in
+     * tool — behind one `search_tools` meta-tool, except names matching
+     * `tools.discoveryAlwaysVisible`. Built-in tools, per-call
      * tools, explicitly whitelisted tools, and session-pinned (previously
      * discovered) tools always stay hot. No-op when discovery is off — with a
      * one-time WARN when the catalog is large enough that selection accuracy

package/dist/core/baseProvider.js

@@ -1246,7 +1246,9 @@ export class BaseProvider {
     }
     /**
      * On-demand discovery (`tools.discovery: true`): defer external MCP tool
-     * schemas behind one `search_tools` meta-tool. Built-in tools, per-call
+     * schemas — or, with `tools.discoveryScope: "all"`, every non-built-in
+     * tool — behind one `search_tools` meta-tool, except names matching
+     * `tools.discoveryAlwaysVisible`. Built-in tools, per-call
      * tools, explicitly whitelisted tools, and session-pinned (previously
      * discovered) tools always stay hot. No-op when discovery is off — with a
      * one-time WARN when the catalog is large enough that selection accuracy
@@ -1273,8 +1275,13 @@ export class BaseProvider {
             }
             return tools;
         }
-        const externalTools = this.neurolink?.getExternalMCPTools() ?? [];
-        if (externalTools.length === 0) {
+        // "external" defers only attached MCP servers' tools; "all" defers every
+        // tool in the record except the built-ins.
+        const builtinNames = new Set(Object.keys(this.directTools ?? {}));
+        const candidateNames = policy.discoveryScope === "all"
+            ? Object.keys(tools).filter((name) => !builtinNames.has(name))
+            : (this.neurolink?.getExternalMCPTools() ?? []).map((t) => t.name);
+        if (candidateNames.length === 0) {
             return tools;
         }
         // Session pinning requires a caller-provided sessionId. Without one there
@@ -1305,12 +1312,15 @@ export class BaseProvider {
             explicitPatterns.push(toolChoice.toolName);
         }
         const explicitMatcher = explicitPatterns.length > 0 ? toolNameMatcher(explicitPatterns) : null;
-        const deferrableNames = externalTools
-            .map((t) => t.name)
-            .filter((name) => name in tools &&
+        const alwaysVisiblePatterns = policy.discoveryAlwaysVisible ?? [];
+        const alwaysVisibleMatcher = alwaysVisiblePatterns.length > 0
+            ? toolNameMatcher(alwaysVisiblePatterns)
+            : null;
+        const deferrableNames = candidateNames.filter((name) => name in tools &&
             !perCallNames.has(name) &&
-            !(explicitMatcher ? explicitMatcher(name) : false));
-        return partitionToolsForDiscovery(tools, {
+            !(explicitMatcher ? explicitMatcher(name) : false) &&
+            !(alwaysVisibleMatcher ? alwaysVisibleMatcher(name) : false));
+        const partitioned = partitionToolsForDiscovery(tools, {
             deferrableNames,
             pinnedNames,
             onHydrate: (names) => {
@@ -1319,6 +1329,16 @@ export class BaseProvider {
                 }
             },
         });
+        // The meta-tool is built after the event wrappers ran, so without this
+        // a search_tools call never reaches tool:start / tool:end listeners.
+        const metaTool = partitioned["search_tools"];
+        if (isDiscoveryMetaTool(metaTool)) {
+            partitioned["search_tools"] =
+                this.toolsManager.wrapExternalToolsWithEvents({
+                    search_tools: metaTool,
+                })["search_tools"];
+        }
+        return partitioned;
     }
     static warnedLargeCatalog = false;
     warnLargeCatalogOnce(toolCount) {
@@ -1760,6 +1780,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 +2138,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

@@ -512,6 +512,14 @@ export class ToolsManager {
             const idField = typeof toolCallId === "string" && toolCallId.length > 0
                 ? { toolCallId }
                 : {};
+            // Same per-invocation id executeTool gives registered tools, so a
+            // listener can pair this start with its end.
+            const eventIds = {
+                ...idField,
+                executionId: `${toolName}-${Date.now()}-${Math.random()
+                    .toString(36)
+                    .slice(2, 11)}`,
+            };
             return withSpan({
                 name: toolSpanName(toolName),
                 tracer: tracers.mcp,
@@ -521,7 +529,7 @@ export class ToolsManager {
                 const startTime = Date.now();
                 this.emitToolEvent("tool:start", toolName, {
                     input: params,
-                    ...idField,
+                    ...eventIds,
                 });
                 let result;
                 try {
@@ -533,7 +541,7 @@ export class ToolsManager {
                         error: errorMsg,
                         success: false,
                         responseTime: Date.now() - startTime,
-                        ...idField,
+                        ...eventIds,
                     });
                     throw error;
                 }
@@ -549,7 +557,7 @@ export class ToolsManager {
                     success: isErrorText === undefined,
                     ...(isErrorText !== undefined ? { error: isErrorText } : {}),
                     responseTime: Date.now() - startTime,
-                    ...idField,
+                    ...eventIds,
                 });
                 return result;
             });
@@ -860,6 +868,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.d.ts

@@ -84,6 +84,8 @@ export declare const toPrepareStepRecord: (step: {
 export declare const hasNativeDoGenerate: (value: unknown) => value is {
     doGenerate: (options: Record<string, unknown>) => Promise<Record<string, unknown>>;
 };
+/** A tool's inputSchema with its lazy (function) form, if any, resolved. */
+export declare const resolveToolInputSchema: (schema: Tool["inputSchema"]) => Exclude<Tool["inputSchema"], (...args: never[]) => unknown>;
 /**
  * Spell a JSON Schema into the conversation's system turn.
  *