@juspay/neurolink 12.59.0 → 13.0.0

package/dist/telemetry/withSpan.js

@@ -1,7 +1,32 @@
-import { SpanKind, SpanStatusCode } from "@opentelemetry/api";
+import { LangfuseOtelSpanAttributes } from "@langfuse/tracing";
+import { context, SpanKind, SpanStatusCode, 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)) {
+        span.setAttributes({
+            [LangfuseOtelSpanAttributes.OBSERVATION_LEVEL]: "WARNING",
+            [LangfuseOtelSpanAttributes.OBSERVATION_STATUS_MESSAGE]: message,
+        });
+        return;
+    }
+    span.setStatus({ code: SpanStatusCode.ERROR, message });
+    if (!expected) {
+        span.setAttributes({
+            [LangfuseOtelSpanAttributes.OBSERVATION_LEVEL]: "ERROR",
+            [LangfuseOtelSpanAttributes.OBSERVATION_STATUS_MESSAGE]: message,
+        });
+    }
+    if (error instanceof Error) {
+        span.recordException(error);
+    }
+}
 export async function withSpan(options, fn) {
-    const { name, tracer, kind = SpanKind.INTERNAL, attributes } = options;
-    return tracer.startActiveSpan(name, { kind }, async (span) => {
+    const { name, tracer, kind = SpanKind.INTERNAL, attributes, detached, } = options;
+    const run = async (span) => {
         if (attributes) {
             for (const [key, value] of Object.entries(attributes)) {
                 if (value !== undefined) {
@@ -15,49 +40,31 @@ export async function withSpan(options, fn) {
             return result;
         }
         catch (error) {
-            span.setStatus({
-                code: SpanStatusCode.ERROR,
-                message: error instanceof Error ? error.message : String(error),
-            });
-            if (error instanceof Error) {
-                span.recordException(error);
-            }
+            markFailure(span, error, options.expectedFailure?.(error));
             throw error;
         }
         finally {
             span.end();
         }
-    });
+    };
+    return detached
+        ? run(tracer.startSpan(name, { kind }))
+        : tracer.startActiveSpan(name, { kind }, run);
 }
 export async function withClientSpan(options, fn) {
     return withSpan({ ...options, kind: SpanKind.CLIENT }, fn);
 }
 /**
- * Span wrapper for streaming operations.
- *
- * Unlike {@link withSpan}, which ends the span when `fn` resolves, this
- * helper extends the span's lifetime until the **consumer** of the returned
- * iterable reaches end-of-stream (success), throws (error), or aborts.
- *
- * Required for any operation whose result is a producer (`StreamResult`,
- * `AsyncIterable`-returning function, etc.) — ending the span on `fn`
- * resolution would capture only the setup phase and report zero tokens /
- * meaningless duration.
- *
- * @param options       Span options (name, tracer, attributes, kind).
- * @param fn            Callback that produces the result. Must NOT depend on
- *                      the iterable being consumed before returning.
- * @param getIterable   Selector that picks the `AsyncIterable` out of the
- *                      result for wrapping.
- * @param setIterable   Setter that returns a new result with the iterable
- *                      replaced by the wrapped (span-lifetime-extending)
- *                      iterable. Should be a pure function — clone the
- *                      result rather than mutating in place.
- *
+ * @description Wraps a streaming operation in a span that stays open until the consumer reaches end-of-stream, throws, or closes the iterable, so the span covers the whole stream rather than only its setup.
+ * @param options {SpanOptions} - Span name, tracer, kind and initial attributes.
+ * @param fn {(span: Span) => Promise<TResult>} - Produces the result; must not depend on the iterable being consumed before returning.
+ * @param getIterable {(result: TResult) => AsyncIterable<TChunk>} - Selects the iterable to wrap out of the result.
+ * @param setIterable {(result: TResult, wrapped: AsyncIterableIterator<TChunk>) => TResult} - Returns a new result carrying the wrapped iterable; must clone rather than mutate.
+ * @returns {Promise<TResult>} The result with its iterable replaced by the span-lifetime-extending one.
  * @example
  * ```ts
  * return withStreamSpan(
- *   { name: "neurolink.provider.stream", tracer, attributes: {...} },
+ *   { name: "provider.stream", tracer, attributes: {...} },
  *   async () => this.executeStreamInner(options),
  *   (r) => r.stream,
  *   (r, wrapped) => ({ ...r, stream: wrapped }),
@@ -65,7 +72,7 @@ export async function withClientSpan(options, fn) {
  * ```
  */
 export async function withStreamSpan(options, fn, getIterable, setIterable) {
-    const { name, tracer, kind = SpanKind.CLIENT, attributes } = options;
+    const { name, tracer, kind = SpanKind.CLIENT, attributes, detached, } = options;
     const span = tracer.startSpan(name, { kind });
     if (attributes) {
         for (const [key, value] of Object.entries(attributes)) {
@@ -74,25 +81,22 @@ export async function withStreamSpan(options, fn, getIterable, setIterable) {
             }
         }
     }
+    const spanContext = detached
+        ? context.active()
+        : trace.setSpan(context.active(), span);
     let result;
     try {
-        result = await fn(span);
+        result = await context.with(spanContext, () => fn(span));
     }
     catch (error) {
-        span.setStatus({
-            code: SpanStatusCode.ERROR,
-            message: error instanceof Error ? error.message : String(error),
-        });
-        if (error instanceof Error) {
-            span.recordException(error);
-        }
+        markFailure(span, error);
         span.end();
         throw error;
     }
-    // Setup succeeded. Now wrap the iterable so the span ends with the stream.
-    const original = getIterable(result);
+    const iterator = getIterable(result)[Symbol.asyncIterator]();
     let ended = false;
-    const endOnce = (status) => {
+    let started = false;
+    function end(status) {
         if (ended) {
             return;
         }
@@ -100,38 +104,121 @@ export async function withStreamSpan(options, fn, getIterable, setIterable) {
         if (status) {
             span.setStatus(status);
         }
-        else {
-            span.setStatus({ code: SpanStatusCode.OK });
-        }
         span.end();
-    };
-    // Build an AsyncGenerator (not just an AsyncIterable) so the wrapped
-    // value is structurally assignable wherever the original stream type
-    // already expected `AsyncGenerator<X>` (e.g. Ollama's executeStream
-    // returns `AsyncGenerator<{ content: string }>`).
-    const wrapped = (async function* () {
-        try {
-            for await (const chunk of original) {
-                yield chunk;
-            }
-            endOnce();
+    }
+    async function close() {
+        if (ended) {
+            return;
         }
-        catch (err) {
-            // recordException must come BEFORE span.end() — OTel ignores events
-            // on ended spans, so flipping the order silently drops the exception.
-            if (err instanceof Error) {
-                span.recordException(err);
+        span.setAttributes({
+            [LangfuseOtelSpanAttributes.OBSERVATION_LEVEL]: "WARNING",
+            [LangfuseOtelSpanAttributes.OBSERVATION_STATUS_MESSAGE]: started
+                ? "stream closed early"
+                : "stream closed before first chunk",
+        });
+        end();
+        await iterator.return?.();
+    }
+    const wrapped = {
+        async next() {
+            if (ended) {
+                return { done: true, value: undefined };
             }
-            endOnce({
-                code: SpanStatusCode.ERROR,
-                message: err instanceof Error ? err.message : String(err),
-            });
-            throw err;
-        }
-    })();
+            started = true;
+            try {
+                const step = await context.with(spanContext, () => iterator.next());
+                if (step.done) {
+                    end({ code: SpanStatusCode.OK });
+                    return { done: true, value: undefined };
+                }
+                return step;
+            }
+            catch (err) {
+                markFailure(span, err);
+                end();
+                throw err;
+            }
+        },
+        async return() {
+            await close();
+            return { done: true, value: undefined };
+        },
+        async throw(error) {
+            await close();
+            throw error;
+        },
+        [Symbol.asyncIterator]() {
+            return wrapped;
+        },
+    };
     return setIterable(result, wrapped);
 }
+/**
+ * @description Runs one model request inside a Langfuse generation span, recording the request half before `fn` runs. `fn` records the response half with `observeGeneration`; errors mark the span ERROR.
+ * @param request {GenerationRecord} - Provider, model, parameters and input sent.
+ * @param fn {(span: Span) => Promise<T>} - Issues the request and returns its result.
+ * @returns {Promise<T>} Whatever `fn` resolves to.
+ */
+export async function withGeneration(request, fn) {
+    return withSpan({
+        name: generationName(request.operation),
+        tracer: tracers.generation,
+        kind: SpanKind.CLIENT,
+    }, async (span) => {
+        observeGeneration(span, request);
+        return fn(span);
+    });
+}
 /** Convenience CLIENT-kind alias matching `withClientSpan`. */
 export async function withClientStreamSpan(options, fn, getIterable, setIterable) {
     return withStreamSpan({ ...options, kind: SpanKind.CLIENT }, fn, getIterable, setIterable);
 }
+/**
+ * @description Runs `fn` inside a `step` span, for a single model call that belongs to a step outside the shared loop, such as a forced finalization request.
+ * @param stepNumber {number} - One-based step number within the turn.
+ * @param fn {() => Promise<T>} - The step's work.
+ * @returns {Promise<T>} Whatever `fn` resolves to.
+ */
+export async function withStepSpan(stepNumber, fn) {
+    return withSpan({ name: stepSpanName(), tracer: tracers.sdk }, async (span) => {
+        observe(span, "span", { metadata: { step_index: stepNumber } });
+        return 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 {
+    current;
+    /**
+     * @description Closes the previous step and opens `step` under the active span.
+     * @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,
+        });
+        observe(this.current, "span", { metadata: { step_index: stepNumber } });
+    }
+    /**
+     * @description Runs `fn` with the open step as the active span, so the observations it creates become the step's children.
+     * @param fn {() => T} - Work belonging to the current step.
+     * @returns {T} Whatever `fn` returns.
+     */
+    run(fn) {
+        const step = this.current;
+        return step
+            ? context.with(trace.setSpan(context.active(), step), fn)
+            : fn();
+    }
+    /**
+     * @description Closes the open step, if any.
+     * @returns {void} Nothing.
+     */
+    end() {
+        this.current?.end();
+        this.current = undefined;
+    }
+}

package/dist/types/cli.d.ts

@@ -1042,13 +1042,6 @@ export type TelemetryCommandArgs = {
 };
 /** Telemetry status sub-command args */
 export type TelemetryStatusArgs = TelemetryCommandArgs;
-/** Telemetry configure sub-command args */
-export type TelemetryConfigureArgs = TelemetryCommandArgs & {
-    exporter: string;
-    config: string;
-};
-/** Telemetry list-exporters sub-command args */
-export type TelemetryListExportersArgs = TelemetryCommandArgs;
 /** Telemetry flush sub-command args */
 export type TelemetryFlushArgs = TelemetryCommandArgs & {
     timeout?: number;
@@ -1077,8 +1070,6 @@ export type TelemetryNativeValidateArgs = {
     directory: string;
     collectorBin: string;
 };
-/** Available exporter names */
-export type ExporterName = "langfuse" | "langsmith" | "otel" | "datadog" | "sentry" | "braintrust" | "arize" | "posthog" | "laminar";
 /** Observability command arguments */
 export type ObservabilityCommandArgs = {
     format?: "text" | "json" | "table";
@@ -1090,8 +1081,6 @@ export type ObservabilityStatusArgs = ObservabilityCommandArgs;
 export type ObservabilityMetricsArgs = ObservabilityCommandArgs & {
     detailed?: boolean;
 };
-/** Observability exporters sub-command args */
-export type ObservabilityExportersArgs = ObservabilityCommandArgs;
 /** Observability costs sub-command args */
 export type ObservabilityCostsArgs = ObservabilityCommandArgs & {
     byModel?: boolean;

package/dist/types/decision.d.ts

@@ -18,6 +18,7 @@
  * `src/lib/types/` (CLAUDE.md rule 9). Note `evaluate`/`Evaluation*` is a
  * different, unrelated feature — scoring a generated response with RAGAS.
  */
+import type { NeurolinkTraceContext } from "./observability.js";
 import type { NeurolinkCredentials } from "./providers.js";
 /**
  * Anything a decision model accepts as free-form content. `state` may be a
@@ -336,6 +337,8 @@ export type DecisionOptions = DecisionRequest & {
     provider?: string;
     /** Per-call credential overrides, as `generate()` takes. */
     credentials?: NeurolinkCredentials;
+    /** Per-call trace attributes (user, session, tags, trace name, metadata) for this decision's spans. */
+    context?: NeurolinkTraceContext;
 };
 /**
  * The built-in consumers of the `decide` inference type — one name per place

package/dist/types/exporter.d.ts

@@ -1,3 +1,5 @@
+import type { JsonValue } from "./common.js";
+import type { SpanAttributes } from "./span.js";
 /**
  * Exporter configuration types
  * Following NeuroLink's type conventions
@@ -71,6 +73,13 @@ export type LangfuseExporterConfig = ExporterConfig & {
      * Defaults to false (input/output are exported).
      */
     redactIO?: boolean;
+    /**
+     * Applied to input, output and metadata before they are sent. When it
+     * throws, the value is replaced by `<fully masked>`.
+     */
+    mask?: (params: {
+        data: JsonValue;
+    }) => JsonValue;
 };
 /**
  * LangSmith exporter configuration
@@ -255,3 +264,48 @@ export type SamplingRule = {
     /** Optional priority (higher = evaluated first) */
     priority?: number;
 };
+/** @description A span attribute value as `SpanData` carries it before OTLP encoding. */
+export type SpanAttributeValue = SpanAttributes[string];
+/** @description An OTLP/JSON attribute value. */
+export type OtlpAnyValue = {
+    boolValue: boolean;
+} | {
+    intValue: string;
+} | {
+    doubleValue: number;
+} | {
+    stringValue: string;
+} | {
+    arrayValue: {
+        values: OtlpAnyValue[];
+    };
+};
+/** @description An OTLP/JSON attribute. */
+export type OtlpKeyValue = {
+    key: string;
+    value: OtlpAnyValue;
+};
+/** @description An OTLP/JSON span as Langfuse's ingestion endpoint reads it. */
+export type OtlpSpan = {
+    traceId: string;
+    spanId: string;
+    parentSpanId?: string;
+    name: string;
+    kind: number;
+    startTimeUnixNano: string;
+    endTimeUnixNano: string;
+    attributes: OtlpKeyValue[];
+    events: {
+        name: string;
+        timeUnixNano: string;
+        attributes: OtlpKeyValue[];
+    }[];
+    status: {
+        code: number;
+        message?: string;
+    };
+};
+/** @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;
+};

package/dist/types/exporter.js

@@ -1,5 +1 @@
-/**
- * Exporter configuration types
- * Following NeuroLink's type conventions
- */
 export {};

package/dist/types/generate.d.ts

@@ -6,6 +6,7 @@ import type { AnalyticsData, TokenUsage } from "./analytics.js";
 import type { ClaudeLimitSnapshot } from "./subscription.js";
 import type { JsonValue } from "./common.js";
 import type { TerminalAgentModeOption, TerminalAgentModeVersion } from "./agentMode.js";
+import type { NeurolinkTraceContext } from "./observability.js";
 import type { Content, ImageWithAltText } from "./content.js";
 import type { ChatMessage, ConversationMemoryConfig, StreamEventSequence, ToolReplayMode } from "./conversation.js";
 import type { MemoryCallOptions } from "./memory.js";
@@ -647,7 +648,7 @@ export type GenerateOptions = {
     } | undefined>;
     enableEvaluation?: boolean;
     enableAnalytics?: boolean;
-    context?: StandardRecord;
+    context?: StandardRecord & NeurolinkTraceContext;
     evaluationDomain?: string;
     toolUsageContext?: string;
     /**
@@ -1847,6 +1848,8 @@ export type NativeGenerateLoopArgs = {
     prepareStep?: NativeLoopPrepareStep;
     /** Resolved model id, handed to `prepareStep` as its `model` argument. */
     modelId: string;
+    /** Provider name recorded on each step's generation and used to price it. */
+    provider: string;
     responseFormat?: Record<string, unknown>;
     providerOptions?: Record<string, Record<string, unknown>>;
     maxSteps: number;

package/dist/types/isolatedAgent.d.ts

@@ -31,10 +31,11 @@ export type WorkerLogEvent = {
  * Options for `NeuroLink.createWorkerInstance()`.
  *
  * A worker instance is a sub-agent-grade NeuroLink: conversation memory off,
- * orchestration off, observability inherited from the creating instance with
- * `autoDetectExternalProvider: true` + `skipLangfuseSpanProcessor: true`
- * (so worker spans join the host's tracer without duplicate Langfuse
- * exports), and an internal log bridge attached with a caller-supplied tag.
+ * orchestration off, observability config inherited from the creating
+ * instance, and an internal log bridge attached with a caller-supplied tag.
+ * Telemetry is shared through the process-wide tracer provider, which is
+ * auto-detected when the host registered its own, so worker spans join the
+ * host's traces without duplicate Langfuse exports.
  */
 export type WorkerInstanceOptions = {
     /** Tag stamped on every forwarded log event (default "worker"). */

package/dist/types/loopEngine.d.ts

@@ -2,6 +2,8 @@ import type Anthropic from "@anthropic-ai/sdk";
 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 { CollectedChunkResult, NativeFunctionCall, NativeToolDeclarationsResult } from "./providers.js";
 import type { ExecutionControlDecision, ExecutionControlStepContext } from "./stream.js";
 /**
@@ -50,6 +52,8 @@ export type AgenticLoopStepResult<TRaw = unknown> = {
     usage: AgenticLoopUsage;
     /** Provider's own raw stop/finish-reason string, e.g. "tool_use", "MAX_TOKENS" */
     rawStopReason: string | undefined;
+    /** Model the response says served it, when the API reports one. */
+    model?: string;
     /** Adapter-private accumulated response data needed by buildToolResultMessages
      *  (e.g. Anthropic's ordered content blocks, Gemini's rawResponseParts). */
     raw: TRaw;
@@ -61,6 +65,8 @@ export type AgenticLoopToolCallResult = AgenticLoopToolCall & {
 };
 export type AgenticLoopStepRequest = {
     raw: unknown;
+    /** The request half of this step's generation observation. */
+    generation?: GenerationRecord;
     /**
      * Tools that became callable while this step's request was being built —
      * mid-turn discovery hydrating a name the model had already tried.
@@ -248,6 +254,8 @@ export type AnthropicLoopAdapterConfig<TMessage = Anthropic.Messages.MessagePara
     client: {
         messages: Pick<Anthropic["messages"], "create">;
     };
+    /** Provider name recorded on each step's generation and used to price it. */
+    provider: string;
     maxSteps: number;
     /**
      * Build one step's request. A closure so the per-turn work the caller
@@ -346,13 +354,6 @@ export type AnthropicLoopAdapterConfig<TMessage = Anthropic.Messages.MessagePara
  * it, so this cannot quietly give a provider behaviour its hand-rolled loops
  * never had.
  */
-/** One model-requested tool call, as recorded on the tool's observability span. */
-export type ToolSpanCall = {
-    /** Arguments the model passed to the tool. */
-    args?: Record<string, unknown>;
-    /** The model's id for this call, shared with the tool_use block that requested it. */
-    toolCallId?: string;
-};
 export type ToolExecutionGuards = {
     /**
      * Upper bound on a single execute(). Omit, or pass `null`, for no bound.
@@ -374,25 +375,6 @@ export type ToolExecutionGuards = {
      * legitimately slow tool reads as a stalled turn without this.
      */
     onProgress?: () => void;
-    /**
-     * Wrap one tool call in the provider's own observability.
-     *
-     * A function rather than a pair of start/end callbacks, because the caller
-     * needs the execution to happen INSIDE its span's context — spans opened by
-     * the tool itself must nest under the tool call, not dangle as siblings of
-     * the turn. Handing over the whole invocation is the only shape that lets a
-     * caller do `context.with(span, run)`.
-     *
-     * The caller awaits `run()` itself, so it sees the settled result and can
-     * mark a FAILURE THAT WAS RETURNED rather than thrown: MCP tools report
-     * errors in their payload, and an observation that only watches for
-     * exceptions records those calls as successful.
-     *
-     * `call` carries the arguments the model passed and the model's id for the
-     * call, so the observation can show what was asked and be paired with the
-     * request that asked it.
-     */
-    withToolSpan?: <T>(name: string, run: () => Promise<T>, call?: ToolSpanCall) => Promise<T>;
 };
 /**
  * @deprecated Renamed to `ToolExecutionGuards` — the guards were never
@@ -406,6 +388,12 @@ export type GeminiStepRaw = {
     rawResponseParts: unknown[];
     stepFunctionCalls: NativeFunctionCall[];
 };
+/** One Gemini step's request: the model, the conversation and the generation config. */
+export type GeminiStepRequest = {
+    model: string;
+    contents: GeminiTurnContent[];
+    config?: UnknownRecord;
+};
 /** One turn entry in a Gemini conversation: a role plus its content parts. */
 export type GeminiTurnContent = {
     role: string;
@@ -419,9 +407,11 @@ export type GeminiTurnContent = {
 export type GeminiLoopAdapterCoreConfig = {
     /** Used in log lines and generated tool-call ids. */
     providerLabel: string;
+    /** Provider name recorded on each step's generation and used to price it. */
+    provider: string;
     maxSteps: number;
     /** Build one step's request object (model, contents, config). */
-    buildRequest: (conversation: GeminiTurnContent[], step: number) => unknown;
+    buildRequest: (conversation: GeminiTurnContent[], step: number) => GeminiStepRequest;
     /** Issue the request. Kept injectable so each provider keeps its own client. */
     sendStep: (request: unknown, signal: AbortSignal) => Promise<AsyncIterable<{
         functionCalls?: NativeFunctionCall[];
@@ -541,7 +531,7 @@ export type AgenticLoopOptions = {
     /**
      * Span the per-step provider retry annotates, via
      * `withProviderRetry(..., span, ...)` — it records
-     * `gen_ai.provider.total_attempts` on every completed step, retried or not.
+     * `provider.total_attempts` on every completed step, retried or not.
      *
      * Caller-supplied rather than read from the ambient context inside the
      * engine. Reading it here would hand the attribute to every provider on the