@juspay/neurolink 13.5.0 → 13.5.1

package/dist/telemetry/withSpan.d.ts

@@ -1,5 +1,13 @@
 import { type Span } from "@opentelemetry/api";
-import type { GenerationRecord, SpanOptions } from "../types/index.js";
+import type { GenerationOperation, GenerationRecord, SpanOptions } from "../types/index.js";
+export declare function markFailure(span: Span, error: unknown, expected?: boolean): void;
+/**
+ * @description Ends `span` at WARNING once `stream` is garbage collected while the span is still open, for a stream result whose caller dropped it without reading it to the end or closing it. Best effort: it runs only if and when the collector reclaims `stream`, and a span that already ended is left alone.
+ * @param stream {object} - The iterable handed to the caller; `span` must not keep it reachable.
+ * @param span {Span} - Span that reading or closing `stream` would have ended.
+ * @returns {void} Nothing.
+ */
+export declare function endSpanWhenDropped(stream: object, span: Span): void;
 export declare function withSpan<T>(options: SpanOptions, fn: (span: Span) => Promise<T>): Promise<T>;
 export declare function withClientSpan<T>(options: Omit<SpanOptions, "kind">, fn: (span: Span) => Promise<T>): Promise<T>;
 /**
@@ -40,9 +48,15 @@ export declare function withStepSpan<T>(stepNumber: number, fn: () => Promise<T>
  * @description Groups the observations of each agentic loop step under one `step` span. Call `begin` at the top of a step, run the step's model call and tool dispatch through `run`, and `end` when the loop is over; `begin` closes the previous step.
  */
 export declare class StepSpans {
+    private readonly operation?;
     private current;
+    private root;
+    /**
+     * @param operation {GenerationOperation} - Public API the loop serves, naming the root opened when no span is active; inferred from the enclosing span when unset, `generate` when there is none.
+     */
+    constructor(operation?: GenerationOperation | undefined);
     /**
-     * @description Closes the previous step and opens `step` under the active span.
+     * @description Closes the previous step and opens `step` under the active span. When no span is active, the first step also opens a `generate` or `stream` root, so a loop run outside NeuroLink and outside any host span stays in one trace instead of starting a trace per step.
      * @param stepNumber {number} - One-based step number within the turn.
      * @returns {void} Nothing.
      */
@@ -54,8 +68,10 @@ export declare class StepSpans {
      */
     run<T>(fn: () => T): T;
     /**
-     * @description Closes the open step, if any.
+     * @description Closes the open step, and the root when this loop opened one.
      * @returns {void} Nothing.
      */
     end(): void;
+    private endStep;
+    private startOrphanedRoot;
 }

package/dist/telemetry/withSpan.js

@@ -1,12 +1,40 @@
 import { LangfuseOtelSpanAttributes } from "@langfuse/tracing";
-import { context, SpanKind, SpanStatusCode, trace, } from "@opentelemetry/api";
+import { context, SpanKind, SpanStatusCode, isSpanContextValid, trace, } from "@opentelemetry/api";
 import { isAbortError } from "../utils/errorHandling.js";
 import { observe, observeGeneration } from "./observation.js";
 import { generationName, stepSpanName } from "./observationNames.js";
-import { tracers } from "./tracers.js";
-function markFailure(span, error, expected = false) {
-    const message = error instanceof Error ? error.message : String(error);
-    if (isAbortError(error)) {
+import { markTurnlessRoot, tracers } from "./tracers.js";
+// The thrown value is the caller's, and reading it can throw as well (a
+// Proxy, a getter or toString that throws). Failure recording reads it through
+// these, and whatever it still cannot record is skipped, so the caller always
+// rethrows its own error.
+function failureText(error) {
+    try {
+        return String(error instanceof Error ? error.message : error);
+    }
+    catch {
+        return "unreadable error";
+    }
+}
+function readsAsAbort(error) {
+    try {
+        return isAbortError(error);
+    }
+    catch {
+        return false;
+    }
+}
+export function markFailure(span, error, expected = false) {
+    try {
+        recordFailure(span, error, expected);
+    }
+    catch {
+        // The span keeps whatever was recorded before the value could not be read.
+    }
+}
+function recordFailure(span, error, expected) {
+    const message = failureText(error);
+    if (readsAsAbort(error)) {
         span.setAttributes({
             [LangfuseOtelSpanAttributes.OBSERVATION_LEVEL]: "WARNING",
             [LangfuseOtelSpanAttributes.OBSERVATION_STATUS_MESSAGE]: message,
@@ -24,9 +52,50 @@ function markFailure(span, error, expected = false) {
         span.recordException(error);
     }
 }
+// A stream result its caller drops without reading it to the end or closing
+// it can no longer end its span, so the span is ended here once the result is
+// garbage collected. Best effort: collection may come late or never.
+const droppedStreams = new FinalizationRegistry((span) => {
+    try {
+        if (span.isRecording()) {
+            span.setAttributes({
+                [LangfuseOtelSpanAttributes.OBSERVATION_LEVEL]: "WARNING",
+                [LangfuseOtelSpanAttributes.OBSERVATION_STATUS_MESSAGE]: "stream dropped before it was read to the end",
+            });
+            span.end();
+        }
+    }
+    catch {
+        // A finalizer has no caller to report to.
+    }
+});
+/**
+ * @description Ends `span` at WARNING once `stream` is garbage collected while the span is still open, for a stream result whose caller dropped it without reading it to the end or closing it. Best effort: it runs only if and when the collector reclaims `stream`, and a span that already ended is left alone.
+ * @param stream {object} - The iterable handed to the caller; `span` must not keep it reachable.
+ * @param span {Span} - Span that reading or closing `stream` would have ended.
+ * @returns {void} Nothing.
+ */
+export function endSpanWhenDropped(stream, span) {
+    droppedStreams.register(stream, span);
+}
+function startsOrphanedRoot(options) {
+    if (!options.detached || !options.rootWhenOrphaned) {
+        return false;
+    }
+    const active = trace.getSpan(context.active());
+    return !active || !isSpanContextValid(active.spanContext());
+}
 export async function withSpan(options, fn) {
-    const { name, tracer, kind = SpanKind.INTERNAL, attributes, detached, } = options;
+    const { name, tracer, kind = SpanKind.INTERNAL, attributes, detached, observationType, } = options;
+    const asRoot = startsOrphanedRoot(options);
     const run = async (span) => {
+        if (asRoot) {
+            markTurnlessRoot(span);
+            observe(span, "agent", {});
+        }
+        else if (observationType) {
+            observe(span, observationType, {});
+        }
         if (attributes) {
             for (const [key, value] of Object.entries(attributes)) {
                 if (value !== undefined) {
@@ -47,7 +116,7 @@ export async function withSpan(options, fn) {
             span.end();
         }
     };
-    return detached
+    return detached && !asRoot
         ? run(tracer.startSpan(name, { kind }))
         : tracer.startActiveSpan(name, { kind }, run);
 }
@@ -72,8 +141,16 @@ export async function withClientSpan(options, fn) {
  * ```
  */
 export async function withStreamSpan(options, fn, getIterable, setIterable) {
-    const { name, tracer, kind = SpanKind.CLIENT, attributes, detached, } = options;
+    const { name, tracer, kind = SpanKind.CLIENT, attributes, detached, observationType, } = options;
+    const asRoot = startsOrphanedRoot(options);
     const span = tracer.startSpan(name, { kind });
+    if (asRoot) {
+        markTurnlessRoot(span);
+        observe(span, "agent", {});
+    }
+    else if (observationType) {
+        observe(span, observationType, {});
+    }
     if (attributes) {
         for (const [key, value] of Object.entries(attributes)) {
             if (value !== undefined) {
@@ -81,7 +158,7 @@ export async function withStreamSpan(options, fn, getIterable, setIterable) {
             }
         }
     }
-    const spanContext = detached
+    const spanContext = detached && !asRoot
         ? context.active()
         : trace.setSpan(context.active(), span);
     let result;
@@ -93,7 +170,15 @@ export async function withStreamSpan(options, fn, getIterable, setIterable) {
         span.end();
         throw error;
     }
-    const iterator = getIterable(result)[Symbol.asyncIterator]();
+    let iterator;
+    try {
+        iterator = getIterable(result)[Symbol.asyncIterator]();
+    }
+    catch (error) {
+        markFailure(span, error);
+        span.end();
+        throw error;
+    }
     let ended = false;
     let started = false;
     function end(status) {
@@ -134,8 +219,11 @@ export async function withStreamSpan(options, fn, getIterable, setIterable) {
                 return step;
             }
             catch (err) {
-                markFailure(span, err);
-                end();
+                // A return() that raced this pull has already ended the span.
+                if (!ended) {
+                    markFailure(span, err);
+                    end();
+                }
                 throw err;
             }
         },
@@ -144,13 +232,31 @@ export async function withStreamSpan(options, fn, getIterable, setIterable) {
             return { done: true, value: undefined };
         },
         async throw(error) {
-            await close();
-            throw error;
+            const forward = iterator.throw;
+            if (ended || forward === undefined) {
+                await close();
+                throw error;
+            }
+            try {
+                const step = await context.with(spanContext, () => forward.call(iterator, error));
+                if (step.done) {
+                    end({ code: SpanStatusCode.OK });
+                }
+                return step;
+            }
+            catch (err) {
+                if (!ended) {
+                    markFailure(span, err);
+                    end();
+                }
+                throw err;
+            }
         },
         [Symbol.asyncIterator]() {
             return wrapped;
         },
     };
+    endSpanWhenDropped(wrapped, span);
     return setIterable(result, wrapped);
 }
 /**
@@ -189,17 +295,24 @@ export async function withStepSpan(stepNumber, fn) {
  * @description Groups the observations of each agentic loop step under one `step` span. Call `begin` at the top of a step, run the step's model call and tool dispatch through `run`, and `end` when the loop is over; `begin` closes the previous step.
  */
 export class StepSpans {
+    operation;
     current;
+    root;
+    /**
+     * @param operation {GenerationOperation} - Public API the loop serves, naming the root opened when no span is active; inferred from the enclosing span when unset, `generate` when there is none.
+     */
+    constructor(operation) {
+        this.operation = operation;
+    }
     /**
-     * @description Closes the previous step and opens `step` under the active span.
+     * @description Closes the previous step and opens `step` under the active span. When no span is active, the first step also opens a `generate` or `stream` root, so a loop run outside NeuroLink and outside any host span stays in one trace instead of starting a trace per step.
      * @param stepNumber {number} - One-based step number within the turn.
      * @returns {void} Nothing.
      */
     begin(stepNumber) {
-        this.end();
-        this.current = tracers.sdk.startSpan(stepSpanName(), {
-            kind: SpanKind.INTERNAL,
-        });
+        this.endStep();
+        this.root ??= this.startOrphanedRoot();
+        this.current = tracers.sdk.startSpan(stepSpanName(), { kind: SpanKind.INTERNAL }, this.root ? trace.setSpan(context.active(), this.root) : undefined);
         observe(this.current, "span", { metadata: { step_index: stepNumber } });
     }
     /**
@@ -214,11 +327,27 @@ export class StepSpans {
             : fn();
     }
     /**
-     * @description Closes the open step, if any.
+     * @description Closes the open step, and the root when this loop opened one.
      * @returns {void} Nothing.
      */
     end() {
+        this.endStep();
+        this.root?.end();
+        this.root = undefined;
+    }
+    endStep() {
         this.current?.end();
         this.current = undefined;
     }
+    startOrphanedRoot() {
+        const active = trace.getSpan(context.active());
+        if (active && isSpanContextValid(active.spanContext())) {
+            return undefined;
+        }
+        const root = markTurnlessRoot(tracers.sdk.startSpan(generationName(this.operation), {
+            kind: SpanKind.INTERNAL,
+        }));
+        observe(root, "agent", {});
+        return root;
+    }
 }

package/dist/types/exporter.d.ts

@@ -1,3 +1,5 @@
+import type { Agent as HttpAgent } from "node:http";
+import type { Agent as HttpsAgent } from "node:https";
 import type { JsonValue } from "./common.js";
 import type { SpanAttributes } from "./span.js";
 /**
@@ -54,6 +56,32 @@ export type ExporterHealthStatus = {
     pendingSpans: number;
     errors?: string[];
 };
+/**
+ * Point-in-time state of one registered exporter, as `getTelemetryStatus()` and
+ * the CLI status commands report it. `pendingSpans` counts spans queued and not
+ * yet handed to the network; `deliveredSpans` and `failedSpans` count what the
+ * backend accepted and what was dropped since the process started.
+ */
+export type ExporterStatus = {
+    name: string;
+    enabled: boolean;
+    healthy: boolean;
+    pendingSpans: number;
+    deliveredSpans: number;
+    failedSpans: number;
+    /** ISO timestamp of the last export that delivered spans */
+    lastExportTime?: string;
+    errors?: string[];
+};
+/**
+ * What an exporter has delivered and dropped, and why its latest delivery
+ * failed, as `getStatuses()` reports it.
+ */
+export type ExporterDeliveryCounts = {
+    delivered: number;
+    failed: number;
+    lastError: string | undefined;
+};
 /**
  * Langfuse exporter configuration
  */
@@ -70,16 +98,24 @@ export type LangfuseExporterConfig = ExporterConfig & {
      * When true, `input` and `output` fields are omitted from exported spans and
      * generations. Enable in compliance-sensitive deployments where prompt/response
      * content is considered PII or subject to data-minimisation requirements.
-     * Defaults to false (input/output are exported).
+     * Defaults to false (input/output are exported). It acts on what this
+     * exporter sends to Langfuse and nowhere else.
      */
     redactIO?: boolean;
     /**
-     * Applied to input, output and metadata before they are sent. When it
-     * throws, the value is replaced by `<fully masked>`.
+     * Applied to input, output and metadata before they are sent to Langfuse.
+     * When it throws, the value is replaced by `<fully masked>`. It acts on what
+     * this exporter sends and nowhere else: not on other exporters, the OTLP
+     * export, `getSpans()` or error text.
      */
     mask?: (params: {
         data: JsonValue;
     }) => JsonValue;
+    /**
+     * Milliseconds `flush()` and `shutdown()` wait for delivery before they
+     * give up on what is still in flight and drop it. Defaults to 3000.
+     */
+    flushBudgetMs?: number;
 };
 /**
  * LangSmith exporter configuration
@@ -285,6 +321,17 @@ export type OtlpKeyValue = {
     key: string;
     value: OtlpAnyValue;
 };
+/** @description How `createExporterSpanProcessor` treats the exporters of its registry. */
+export type ExporterSpanProcessorOptions = {
+    /** Whether the processor's `shutdown()` also shuts down the registry's exporters. Defaults to `true`; `false` flushes them and leaves them running. */
+    shutdownExporters?: boolean;
+};
+/** @description An OTLP/JSON link from one span to another. */
+export type OtlpLink = {
+    traceId: string;
+    spanId: string;
+    attributes: OtlpKeyValue[];
+};
 /** @description An OTLP/JSON span as Langfuse's ingestion endpoint reads it. */
 export type OtlpSpan = {
     traceId: string;
@@ -300,12 +347,60 @@ export type OtlpSpan = {
         timeUnixNano: string;
         attributes: OtlpKeyValue[];
     }[];
+    links?: OtlpLink[];
     status: {
         code: number;
         message?: string;
     };
 };
+/** @description An encoded span together with the resource and instrumentation scope it was produced under. */
+export type OtlpEncodedSpan = {
+    span: OtlpSpan;
+    resource: OtlpKeyValue[];
+    scope: {
+        name: string;
+        version?: string;
+    };
+};
+/** @description The spans one instrumentation scope produced, as an OTLP/JSON request groups them. */
+export type OtlpScopeSpans = {
+    scope: {
+        name: string;
+        version?: string;
+    };
+    spans: OtlpSpan[];
+};
+/** @description An OTLP/JSON trace export request body. */
+export type OtlpTraceRequest = {
+    resourceSpans: {
+        resource: {
+            attributes: OtlpKeyValue[];
+        };
+        scopeSpans: OtlpScopeSpans[];
+    }[];
+};
+/** @description What one delivery attempt of a batch to Langfuse achieved. */
+export type LangfuseDeliveryReport = {
+    delivered: number;
+    rejected: number;
+    droppedIds: string[];
+    error?: string;
+};
+/** @description How Langfuse answered one export request: it took the spans (some perhaps rejected) or it did not take them. */
+export type LangfusePostOutcome = {
+    accepted: true;
+    rejected: number;
+} | {
+    accepted: false;
+};
 /** @description What the Langfuse exporter adds to, masks in and removes from span attributes before sending. */
 export type LangfuseAttributePolicy = Pick<LangfuseExporterConfig, "environment" | "release" | "mask"> & {
     redactIO: boolean;
 };
+/** @description The connections NeuroLink's OTLP exporters open, which a flush that has run out of its budget can close. */
+export type OtlpConnections = {
+    /** Hands an exporter the agent it opens its connections with. */
+    agentFor: (protocol: string) => HttpAgent | HttpsAgent;
+    /** Closes every connection now, and again once a retry that was asleep at that moment has sent. */
+    cut: () => void;
+};

package/dist/types/livekit.d.ts

@@ -613,16 +613,18 @@ export type VoiceTurnRecorder = {
      * Call it once, when the agent is about to speak its greeting.
      */
     expectGreeting: () => void;
-    /** A tool call started in the current exchange. */
+    /** A tool call started in the current exchange. `callId` pairs it with its end when calls overlap. */
     toolStart: (call: {
         name: string;
         args?: unknown;
+        callId?: string;
     }) => void;
     /** A tool call finished in the current exchange. */
     toolEnd: (call: {
         name: string;
         result?: unknown;
         error?: string;
+        callId?: string;
     }) => void;
     /**
      * Shutdown: close what is open, then wait for pending writes — but no longer
@@ -632,6 +634,15 @@ export type VoiceTurnRecorder = {
     /** Counters, for logs and tests. */
     stats: () => VoiceTurnRecorderStats;
 };
+/** Who and what a realtime turn is traced as; `userId` is set only for a verified binding. */
+export type RealtimeTracedCall = {
+    sessionId?: string;
+    userId?: string;
+    roomName?: string;
+    model?: string;
+    /** The provider of the realtime backend (`vertex` for Gemini Live, `xai` for Grok Voice); `vertex` when absent. */
+    provider?: string;
+};
 /** What a realtime call needs from its memory once its binding verified. */
 export type RealtimeCallMemory = {
     recorder: VoiceTurnRecorder;
@@ -651,6 +662,8 @@ export type VoiceTurnRecorderStats = {
 export type VoiceTurnRecorderOptions = {
     /** Stores one exchange. Throwing means "not stored"; the recorder retries. */
     write: (record: VoiceTurnRecord) => Promise<void>;
+    /** An exchange closed: called once per exchange, in order, before its write is queued, so it never waits behind earlier writes. */
+    onClosed?: (record: VoiceTurnRecord) => void;
     /** A write succeeded. */
     onRecorded?: (record: VoiceTurnRecord) => void;
     /** A write failed after every retry. The call continues. */
@@ -771,11 +784,13 @@ export type BuildRealtimeMcpToolsParams = {
     onToolStart?: (call: {
         name: string;
         args: Record<string, unknown>;
+        callId?: string;
     }) => void;
     /** Observes a tool call as it ends, with its result as text or its error. */
     onToolEnd?: (call: {
         name: string;
         result?: string;
         error?: string;
+        callId?: string;
     }) => void;
 };

package/dist/types/loopEngine.d.ts

@@ -3,7 +3,7 @@ import type { Span } from "@opentelemetry/api";
 import type { Tool } from "./tools.js";
 import type { GenerateStopReason } from "./generate.js";
 import type { UnknownRecord } from "./common.js";
-import type { GenerationRecord } from "./observability.js";
+import type { GenerationOperation, GenerationRecord } from "./observability.js";
 import type { CollectedChunkResult, NativeFunctionCall, NativeToolDeclarationsResult } from "./providers.js";
 import type { ExecutionControlDecision, ExecutionControlStepContext } from "./stream.js";
 /**
@@ -213,6 +213,15 @@ export type AgenticLoopAdapter<TConversation = unknown, TRaw = unknown> = {
      */
     buildToolResultMessages(conversation: TConversation, stepResult: AgenticLoopStepResult<TRaw>, toolResults: AgenticLoopToolCallResult[], step: number): TConversation;
     mapFinishReason(rawStopReason: string | undefined, hadToolCalls: boolean): string;
+    /**
+     * Optional: maps a step's usage onto what its generation observation
+     * prices, where `inputTokens` excludes cache reads and `outputTokens`
+     * includes reasoning. Only for providers whose API reports otherwise
+     * (Gemini counts cached tokens inside the prompt count and thinking tokens
+     * outside the candidate count). The turn totals the engine returns are not
+     * touched: callers already reconcile those once.
+     */
+    observedUsage?(usage: AgenticLoopUsage): AgenticLoopUsage;
     /** Optional: in-turn context-budget reclaim, called once per step before buildStepRequest. */
     planReclaim?(conversation: TConversation, step: number): AgenticLoopReclaimResult<TConversation> | undefined;
     /** Optional: Vertex+Gemini-only single-retry-on-malformed-call. */
@@ -528,6 +537,12 @@ export type AgenticLoopOptions = {
         execute?: (args: Record<string, unknown>, opts: unknown) => Promise<unknown>;
     }>;
     abortSignal?: AbortSignal;
+    /**
+     * Public API the turn serves, used only to name the root observation the
+     * loop opens when it runs with no active span. Inferred from the enclosing
+     * span when omitted, and `generate` when there is none.
+     */
+    operation?: GenerationOperation;
     /**
      * Span the per-step provider retry annotates, via
      * `withProviderRetry(..., span, ...)` — it records

package/dist/types/observability.d.ts

@@ -3,7 +3,7 @@
  * These configs are passed from the parent application (e.g., Lighthouse)
  * to enable telemetry and observability features in Neurolink SDK
  */
-import type { AttributeValue } from "@opentelemetry/api";
+import type { AttributeValue, Counter, Histogram, Meter } from "@opentelemetry/api";
 import type { JsonValue, RawUsageObject, Unknown } from "./common.js";
 import type { SpanData } from "./span.js";
 /**
@@ -37,20 +37,26 @@ export type LangfuseSpanAttributes = {
  * @description Langfuse exporter options. Every field falls back to its `LANGFUSE_*` environment variable when omitted.
  */
 export type NeurolinkLangfuseConfig = {
+    /** `false` keeps Langfuse export off although keys are present; any other value, or leaving it out, leaves it on. */
+    enabled?: boolean;
     /** Project public key; defaults to `LANGFUSE_PUBLIC_KEY`. */
     publicKey?: string;
     /** Project secret key; defaults to `LANGFUSE_SECRET_KEY`. */
     secretKey?: string;
     /** Langfuse host; defaults to `LANGFUSE_BASE_URL`, then Langfuse Cloud. */
     baseUrl?: string;
-    /** Environment name; defaults to `LANGFUSE_TRACING_ENVIRONMENT`. */
+    /** Environment name on Langfuse traces; defaults to `LANGFUSE_TRACING_ENVIRONMENT`. The OTLP resource's `deployment.environment` also falls back to `LANGFUSE_ENVIRONMENT`, then `PUBLIC_APP_ENVIRONMENT`. */
     environment?: string;
-    /** Release identifier; defaults to `LANGFUSE_RELEASE`. */
+    /** Release identifier on Langfuse traces; defaults to `LANGFUSE_RELEASE`. The OTLP resource's `service.version` also falls back to `PUBLIC_APP_VERSION`. */
     release?: string;
-    /** Applied to input, output and metadata before they leave the process. */
+    /** Applied to input, output and metadata before they are sent to Langfuse. It does not reach other exporters, the OTLP export, `getSpans()` or error text. */
     mask?: (params: {
         data: JsonValue;
     }) => JsonValue;
+    /** Leaves input and output out of what is sent to Langfuse. It does not reach other exporters, the OTLP export, `getSpans()` or error text. */
+    redactIO?: boolean;
+    /** Milliseconds a flush or shutdown waits for the Langfuse exporter before it drops what is still in flight; defaults to 3000. */
+    flushBudgetMs?: number;
     /** `"immediate"` sends every span as it ends; `"batched"` (default) queues them. */
     exportMode?: "batched" | "immediate";
     /** Spans queued before a batch is sent; defaults to 15. */
@@ -59,7 +65,26 @@ export type NeurolinkLangfuseConfig = {
     flushInterval?: number;
 };
 /**
- * @description Observability configuration for the NeuroLink SDK. Langfuse turns on automatically when `LANGFUSE_PUBLIC_KEY` and `LANGFUSE_SECRET_KEY` are set; `false` turns it off.
+ * @description Kind of connection counted by the `connections_total` metric.
+ */
+export type MetricConnectionType = "websocket" | "sse" | "http";
+/**
+ * @description The OpenTelemetry instruments behind NeuroLink's `ai_*`, `mcp_*`, `connections_total`, `response_time_ms` and `custom_*` metrics, created on one meter.
+ */
+export type AiMetricInstruments = {
+    meter: Meter;
+    requests: Counter;
+    duration: Histogram;
+    tokens: Counter;
+    cost: Counter;
+    providerErrors: Counter;
+    mcpToolCalls: Counter;
+    connections: Counter;
+    responseTime: Histogram;
+    custom: Map<string, Counter | Histogram>;
+};
+/**
+ * @description Observability configuration for the NeuroLink SDK. Langfuse turns on automatically when `LANGFUSE_PUBLIC_KEY` and `LANGFUSE_SECRET_KEY` are set and `LANGFUSE_ENABLED` is not `false`, `0`, `off` or `no`; `false` turns it off.
  */
 export type ObservabilityConfig = {
     /** `false` disables Langfuse, `true` or an options object enables it. */
@@ -387,12 +412,20 @@ export type HealthMetrics = {
 export type SpanOptions = {
     name: string;
     tracer: import("@opentelemetry/api").Tracer;
+    /** Marks the span as an observation of this type when it starts, which is what sends it to the exporters. Without it a span is exported only if its own code marks it with `observe`. */
+    observationType?: ObservationType;
     kind?: import("@opentelemetry/api").SpanKind;
     attributes?: Record<string, string | number | boolean | undefined>;
     /** Marks a thrown error as an expected skip whose Langfuse level the span set itself, so `withSpan` keeps it instead of raising ERROR. */
     expectedFailure?: (error: unknown) => boolean;
     /** Keeps the span out of the active context, so spans started inside `fn` parent to the nearest ancestor that is exported. */
     detached?: boolean;
+    /**
+     * With `detached`, lets the span be the active, exported root of its trace
+     * when no span is active, so what it wraps stays in one trace instead of
+     * each child starting its own. With an active ancestor it stays detached.
+     */
+    rootWhenOrphaned?: boolean;
 };
 /** Trace + parent span IDs used to correlate metric records with spans. */
 export type MetricsTraceContext = {

package/dist/types/proxy.d.ts

@@ -2478,6 +2478,8 @@ export type CodexStreamEvidence = {
     terminalBytes: number;
     /** Malformed, oversized or undispatched frames prevent proving output absence. */
     observationIncomplete?: boolean;
+    /** Output items past the recorded-size cap were left out of `response.output`. */
+    outputItemsOmitted?: boolean;
     firstUsefulOutputAt?: number;
     firstUsefulOutputEvent?: string;
     errorType?: string;