@juspay/neurolink 13.5.0 → 13.5.1

package/dist/neurolink.js

@@ -71,8 +71,9 @@ import { getMetricsAggregator, MetricsAggregator, } from "./observability/metric
 import { AnalyticsService, calculateAdvancedCost, parseAnalyticsQualityScore, } from "./analytics/index.js";
 import { SpanStatus, SpanType, CircuitBreakerOpenError, ConversationMemoryError, DEFAULT_DECISION_HOOK_TIMEOUT_MS, MAX_DECISION_HOOK_TIMEOUT_MS, ModelAccessDeniedError, } from "./types/index.js";
 import { resolveTerminalAgentMode } from "./agent/prompts/terminalAgentPrompt.js";
+import { getExporterRegistry } from "./observability/exporterRegistry.js";
 import { SpanSerializer } from "./observability/utils/spanSerializer.js";
-import { withSpan } from "./telemetry/withSpan.js";
+import { endSpanWhenDropped, withSpan } from "./telemetry/withSpan.js";
 import { getActiveTraceContext } from "./telemetry/traceContext.js";
 import { calculateCost } from "./utils/pricing.js";
 import { acquireTelemetry, ensureTelemetry, flushOpenTelemetry, getLangfuseHealthStatus, isOpenTelemetryInitialized, releaseTelemetry, setLangfuseContext, traceMetadataFromContext, } from "./services/server/ai/observability/instrumentation.js";
@@ -410,6 +411,9 @@ function observeTurn(span, attrs) {
     }
 }
 function startTurn(span, optionsOrPrompt) {
+    if (!span.isRecording()) {
+        return;
+    }
     observeTurn(span, { input: turnInput(optionsOrPrompt) });
     if (typeof optionsOrPrompt !== "string") {
         const name = optionsOrPrompt.context?.observationName;
@@ -474,65 +478,87 @@ function traceTurnStream(result, span, turnContext) {
                 : "stream closed before first chunk");
         }
     };
+    const advance = async (pull, afterThrow = false) => {
+        started = true;
+        try {
+            const step = await context.with(turnContext, pull);
+            if (step.done) {
+                span.setStatus({ code: SpanStatusCode.OK });
+                end(observationLevel(result.finishReason));
+                return { done: true, value: undefined };
+            }
+            const content = typeof step.value === "object" && step.value !== null
+                ? step.value.content
+                : undefined;
+            if (typeof content === "string") {
+                output += content;
+            }
+            return step;
+        }
+        catch (error) {
+            failTurnSpan(span, error instanceof Error ? error : new Error(String(error)));
+            // A consumer that throws into the stream ends it early, as return()
+            // does, and the root has always kept the model in that case.
+            if (afterThrow) {
+                observeTurn(span, { metadata: { model: result.model } });
+            }
+            finish();
+            throw error;
+        }
+    };
     const traced = {
         async next() {
             if (ended) {
                 return { done: true, value: undefined };
             }
-            started = true;
-            try {
-                const step = await context.with(turnContext, () => iterator.next());
-                if (step.done) {
-                    span.setStatus({ code: SpanStatusCode.OK });
-                    end(observationLevel(result.finishReason));
-                    return { done: true, value: undefined };
-                }
-                const content = typeof step.value === "object" && step.value !== null
-                    ? step.value.content
-                    : undefined;
-                if (typeof content === "string") {
-                    output += content;
-                }
-                return step;
-            }
-            catch (error) {
-                failTurnSpan(span, error instanceof Error ? error : new Error(String(error)));
-                finish();
-                throw error;
-            }
+            return advance(() => iterator.next());
         },
         async return() {
             await close();
             return { done: true, value: undefined };
         },
         async throw(error) {
-            await close();
-            throw error;
+            const forward = iterator.throw;
+            if (ended || forward === undefined) {
+                await close();
+                throw error;
+            }
+            return advance(() => forward.call(iterator, error), true);
         },
         [Symbol.asyncIterator]() {
             return traced;
         },
     };
+    endSpanWhenDropped(traced, span);
     return traced;
 }
+/**
+ * Runs every pull of `stream` inside `drainContext`, and forwards `return()`
+ * and `throw()` to it even before the first `next()`. A generator that has not
+ * started never enters its body, so wrapping the drain in one would swallow a
+ * pre-start close and leave the drain's own settle step unreached.
+ */
 function drainInContext(stream, drainContext) {
-    return (async function* () {
-        const iterator = stream[Symbol.asyncIterator]();
-        try {
-            while (true) {
-                const step = await context.with(drainContext, () => iterator.next());
-                if (step.done) {
-                    return;
-                }
-                yield step.value;
+    const iterator = stream[Symbol.asyncIterator]();
+    const drained = {
+        next: () => context.with(drainContext, () => iterator.next()),
+        async return() {
+            await context.with(drainContext, async () => iterator.return?.());
+            return { done: true, value: undefined };
+        },
+        async throw(error) {
+            const forward = iterator.throw;
+            if (forward === undefined) {
+                await context.with(drainContext, async () => iterator.return?.());
+                throw error;
             }
-        }
-        finally {
-            await context.with(drainContext, async () => {
-                await iterator.return?.();
-            });
-        }
-    })();
+            return context.with(drainContext, () => forward.call(iterator, error));
+        },
+        [Symbol.asyncIterator]() {
+            return drained;
+        },
+    };
+    return drained;
 }
 /** Monotonic source for {@link NeuroLink.logInstanceId}. Process-local by design. */
 let neuroLinkInstanceCounter = 0;
@@ -834,8 +860,8 @@ export class NeuroLink {
         }, callback);
     }
     createMetricsTraceContext() {
-        // Attempt to reuse the active OTel trace context so Pipeline B spans
-        // land in the same Langfuse trace as Pipeline A spans.
+        // Reuse the active OTel trace context so the in-process span records
+        // carry the traceId of the exported OTEL trace of the same request.
         const activeSpan = trace.getSpan(context.active());
         if (activeSpan) {
             const spanCtx = activeSpan.spanContext();
@@ -3168,11 +3194,15 @@ Current user's request: ${currentInput}`;
     }
     /**
      * 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() {
         const langfuseConfig = this.observabilityConfig?.langfuse;
         const langfuseOptions = typeof langfuseConfig === "object" ? langfuseConfig : undefined;
-        const { hasProcessor } = getLangfuseHealthStatus();
+        const { hasProcessor, usingExternalProvider } = getLangfuseHealthStatus();
         return {
             enabled: isOpenTelemetryInitialized(),
             langfuse: langfuseConfig !== undefined || hasProcessor
@@ -3188,8 +3218,10 @@ Current user's request: ${currentInput}`;
                     enabled: isOpenTelemetryInitialized(),
                     endpoint: process.env.OTEL_EXPORTER_OTLP_ENDPOINT,
                     serviceName: process.env.OTEL_SERVICE_NAME,
+                    ...(usingExternalProvider && { usingExternalProvider }),
                 }
                 : undefined,
+            exporters: getExporterRegistry().getStatuses(),
         };
     }
     /**
@@ -7435,8 +7467,12 @@ Current user's request: ${currentInput}`;
                 return { done: true, value: undefined };
             },
             async throw(error) {
-                await scope.run(eventScope, async () => iterator.return?.());
-                throw error;
+                const forward = iterator.throw;
+                if (forward === undefined) {
+                    await scope.run(eventScope, async () => iterator.return?.());
+                    throw error;
+                }
+                return scope.run(eventScope, () => forward.call(iterator, error));
             },
             [Symbol.asyncIterator]() {
                 return bound;
@@ -7805,6 +7841,7 @@ Current user's request: ${currentInput}`;
                     },
                 });
                 attempt.stream = drainInContext(attempt.stream, context.active());
+                endSpanWhenDropped(attempt.stream, streamSpan);
                 return attempt;
             }));
             if (streamSttTranscription) {
@@ -8615,7 +8652,18 @@ Current user's request: ${currentInput}`;
                 }
                 return stream.return(value);
             },
-            throw: (error) => stream.throw(error),
+            throw: async (error) => {
+                if (!started) {
+                    started = true;
+                    await this.settleStandardStreamDrain(drain, {
+                        accumulatedContent: "",
+                        chunkCount: 0,
+                        streamError: error instanceof Error ? error : new Error(String(error)),
+                        resolvedUsage: undefined,
+                    });
+                }
+                return stream.throw(error);
+            },
             [Symbol.asyncIterator]: () => guarded,
         };
         return guarded;
@@ -14066,13 +14114,15 @@ Current user's request: ${currentInput}`;
      * 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
@@ -14094,9 +14144,10 @@ Current user's request: ${currentInput}`;
         if (!site) {
             return this.tryRunDecide(merged);
         }
-        // Inert without a decision provider: a host's hook must not sit on the
-        // request path of a tenant that has no decision model to reach, and an
-        // event for a call that could never be made would only mislead.
+        // No host hook or event without a decision provider: a hook must not sit
+        // on the request path of a tenant that has no decision model to reach, and
+        // an event for a call that could never be made would only mislead. The
+        // plain call still runs, so the WARNING observation it records is kept.
         if (!this.resolveDecisionProviderName(merged.provider, merged.credentials)) {
             return this.tryRunDecide(merged);
         }
@@ -14419,11 +14470,14 @@ Current user's request: ${currentInput}`;
                         ? { "decision.upstream_ms": result.upstreamMs }
                         : {}),
                 });
-                // BOTH aggregators, exactly as the generate path does. The
-                // instance one is what `neurolink.getMetrics()` / `getSpans()`
-                // read; the global one is what the exporters drain. Recording to
-                // only the global one would make a decision invisible to the very
-                // API a caller would use to check whether it ran.
+                // BOTH aggregators, exactly as the generate path does. They are
+                // in-process stores that are never exported: what Langfuse and the
+                // OTLP exporters receive for this decision is the `decide`
+                // generation span. The instance one is what
+                // `neurolink.getMetrics()` / `getSpans()` read; the global one is
+                // what `getMetricsAggregator()` readers see. Recording to only the
+                // global one would make a decision invisible to the very API a
+                // caller would use to check whether it ran.
                 const ended = SpanSerializer.endSpan(span, SpanStatus.OK);
                 this.metricsAggregator.recordSpan(ended);
                 getMetricsAggregator().recordSpan(ended);

package/dist/observability/FEATURE-STATUS.md

@@ -160,10 +160,6 @@ neurolink observability status
 neurolink observability metrics
 neurolink obs metrics --detailed
 
-# List exporters
-neurolink observability exporters
-neurolink obs exp --format json
-
 # Cost breakdown
 neurolink observability costs
 neurolink obs costs --by-model --by-provider

package/dist/observability/exporterRegistry.d.ts

@@ -3,7 +3,7 @@
  * Manages multiple observability exporters with circuit breaker protection
  */
 import type { BaseExporter } from "./exporters/baseExporter.js";
-import type { ExportResult, ExporterHealthStatus, ObservabilityCircuitBreakerConfig, ObservabilityCircuitBreakerState, Sampler, SpanData } from "../types/index.js";
+import type { ExportResult, ExporterHealthStatus, ExporterStatus, ObservabilityCircuitBreakerConfig, ObservabilityCircuitBreakerState, Sampler, SpanData } from "../types/index.js";
 /**
  * Registry for managing multiple observability exporters
  * Includes circuit breaker protection to prevent cascading failures
@@ -117,6 +117,11 @@ export declare class ExporterRegistry {
      * Get total pending spans across all exporters
      */
     getTotalPendingSpans(): number;
+    /**
+     * Snapshot of every registered exporter without a network call: whether it
+     * runs, what is queued, delivered and dropped, and an open circuit breaker
+     */
+    getStatuses(): ExporterStatus[];
     /**
      * Clear all registered exporters and reset state
      * (For testing and cleanup)

package/dist/observability/exporterRegistry.js

@@ -3,6 +3,7 @@
  * Manages multiple observability exporters with circuit breaker protection
  */
 import { logger } from "../utils/logger.js";
+import { exporterStatusOf } from "./exporters/baseExporter.js";
 import { AlwaysSampler } from "./sampling/samplers.js";
 /** Default timeout for exporter API calls (30 seconds) */
 const DEFAULT_EXPORT_TIMEOUT_MS = 30_000;
@@ -378,6 +379,23 @@ export class ExporterRegistry {
         }
         return total;
     }
+    /**
+     * Snapshot of every registered exporter without a network call: whether it
+     * runs, what is queued, delivered and dropped, and an open circuit breaker
+     */
+    getStatuses() {
+        return Array.from(this.exporters.entries()).map(([name, exporter]) => {
+            const status = exporterStatusOf(exporter);
+            if (this.circuitBreakers.get(name)?.state !== "open") {
+                return status;
+            }
+            return {
+                ...status,
+                healthy: false,
+                errors: [...(status.errors ?? []), "Circuit breaker open"],
+            };
+        });
+    }
     /**
      * Clear all registered exporters and reset state
      * (For testing and cleanup)

package/dist/observability/exporterSpanProcessor.d.ts

@@ -1,18 +1,23 @@
 import { type Context } from "@opentelemetry/api";
 import type { ReadableSpan, Span, SpanProcessor as OtelSpanProcessor } from "@opentelemetry/sdk-trace-base";
+import type { ExporterSpanProcessorOptions } from "../types/index.js";
 import type { ExporterRegistry } from "./exporterRegistry.js";
 /**
- * @description OpenTelemetry span processor that turns every observation span into `SpanData` and hands it to an `ExporterRegistry`, so one instrumentation feeds Langfuse, Datadog, Sentry and every other registered exporter. Spans that are not observations are skipped and their children are re-parented onto the nearest exported ancestor. Delivery never blocks the span's thread.
+ * @description OpenTelemetry span processor that turns every observation span into `SpanData` and hands it to an `ExporterRegistry`, so one instrumentation feeds Langfuse, Datadog, Sentry and every other registered exporter. Spans that are not observations (health checks, auth, middleware, NeuroLink's helper spans), wrapper spans marked `langfuse.internal` and spans from other libraries are skipped and their children are re-parented onto the nearest exported ancestor. `shutdown()` shuts the registry's exporters down, as it always did, unless the processor was created to leave them running. Parent ids are read from OpenTelemetry SDK 2.x (`parentSpanContext`) and 1.x (`parentSpanId`) spans alike. At most `MAX_REMEMBERED_SPANS` open and ended spans are remembered for re-parenting; an ancestor of a span that is still open is kept past that limit. Delivery never blocks the span's thread, and a span that cannot be converted is skipped without throwing into the code that ended it.
  */
 export declare class ExporterSpanProcessor implements OtelSpanProcessor {
     private readonly registry;
+    private readonly shutsDownExporters;
     private readonly open;
     private readonly ended;
+    private readonly pins;
+    private evictionLogged;
     /**
      * @description Creates a processor bound to a registry.
      * @param registry {ExporterRegistry} - Registry that receives every exported span.
+     * @param shutsDownExporters {boolean} - Whether `shutdown()` also shuts down the registry's exporters; defaults to `true`. Pass `false` for a host provider that is shut down and rebuilt while the exporters stay shared.
      */
-    constructor(registry: ExporterRegistry);
+    constructor(registry: ExporterRegistry, shutsDownExporters?: boolean);
     /**
      * @description Copies the propagated Langfuse trace attributes (user, session, trace name, tags, metadata) from the parent context onto the new span and remembers it until it ends.
      * @param span {Span} - Span that just started.
@@ -32,19 +37,28 @@ export declare class ExporterSpanProcessor implements OtelSpanProcessor {
      */
     forceFlush(): Promise<void>;
     /**
-     * @description Shuts down every exporter in the registry.
-     * @returns {Promise<void>} Resolves when all exporters have shut down.
+     * @description Shuts down every exporter in the registry, or only flushes them when the processor was created to leave them running.
+     * @returns {Promise<void>} Resolves when the exporters have shut down or flushed.
      */
     shutdown(): Promise<void>;
+    private contain;
     private exportQuietly;
+    private hold;
+    private release;
+    private evictOldestOpen;
     private remember;
+    private trimEnded;
     private nearestExportedAncestor;
 }
 /**
- * @description Creates a span processor that feeds NeuroLink's observation spans to an exporter registry. Add it to a host `TracerProvider` to deliver spans through the registered exporters (such as `LangfuseExporter`) instead of `LangfuseSpanProcessor`.
+ * @description Creates a span processor that feeds NeuroLink's observation spans to an exporter registry. Add it to a host `TracerProvider` to deliver spans through the registered exporters (such as `LangfuseExporter`) instead of `LangfuseSpanProcessor`. Shutting that provider down shuts the registry's exporters down; pass `{ shutdownExporters: false }` to flush them and leave them running, so a provider the host rebuilds keeps exporting.
  * @param registry {ExporterRegistry} - Registry to export to; defaults to the process-wide registry.
+ * @param options {ExporterSpanProcessorOptions} - `shutdownExporters` (default `true`) says whether the processor's `shutdown()` also shuts down the registry's exporters.
  * @returns {ExporterSpanProcessor} A processor ready to be added to a TracerProvider.
  * @example
  * const provider = new NodeTracerProvider({ spanProcessors: [createExporterSpanProcessor()] });
+ * @example
+ * // A host provider that is shut down and rebuilt over the same exporters
+ * const processor = createExporterSpanProcessor(getExporterRegistry(), { shutdownExporters: false });
  */
-export declare function createExporterSpanProcessor(registry?: ExporterRegistry): ExporterSpanProcessor;
+export declare function createExporterSpanProcessor(registry?: ExporterRegistry, options?: ExporterSpanProcessorOptions): ExporterSpanProcessor;