@juspay/neurolink 12.59.0 → 13.0.1

package/dist/telemetry/observation.js

@@ -0,0 +1,112 @@
+import { createObservationAttributes, createTraceAttributes, LangfuseOtelSpanAttributes, } from "@langfuse/tracing";
+import { WARNING_FINISH_REASONS } from "../constants/telemetry.js";
+import { calculateCost } from "../utils/pricing.js";
+import { extractTokenUsage } from "../utils/tokenUtils.js";
+import { ATTR, spanContentAttribute, spanModelRequestAttribute, } from "./attributes.js";
+import { assistantMessages } from "./chatMessages.js";
+function redactedIO(attrs) {
+    return {
+        ...attrs,
+        ...(attrs.input !== undefined && {
+            input: spanContentAttribute(attrs.input),
+        }),
+        ...(attrs.output !== undefined && {
+            output: spanContentAttribute(attrs.output),
+        }),
+    };
+}
+/**
+ * @description Stamps Langfuse observation attributes on a span, plus a `gen_ai.observation.type` marker so the exporter pipeline recognizes it whatever its tracer scope. Input and output are credential-masked and capped at `SPAN_ATTRIBUTE_MAX_CHARS` before serialization.
+ * @param span {Span} - Span to describe.
+ * @param type {ObservationType} - Observation type Langfuse renders the span as.
+ * @param attrs {ObservationAttributes} - Input, output, model, parameters, usage, cost, level and metadata to record.
+ * @returns {void} Nothing.
+ */
+export function observe(span, type, attrs) {
+    span.setAttributes({
+        ...createObservationAttributes(type, redactedIO(attrs)),
+        [ATTR.GEN_AI_OBSERVATION]: type,
+    });
+}
+/**
+ * @description Sets the trace-level input, output and metadata on a span, credential-masked and capped like `observe`. Each metadata entry is written as its own `langfuse.trace.metadata.<key>` attribute, redacted like input and output.
+ * @param span {Span} - Span whose trace is described.
+ * @param io {TraceContent} - Trace input, output and metadata.
+ * @returns {void} Nothing.
+ */
+export function observeTrace(span, io) {
+    const { metadata, ...content } = io;
+    span.setAttributes(createTraceAttributes(redactedIO(content)));
+    for (const [key, value] of Object.entries(metadata ?? {})) {
+        if (value !== undefined) {
+            span.setAttribute(`${LangfuseOtelSpanAttributes.TRACE_METADATA}.${key}`, spanContentAttribute(value));
+        }
+    }
+}
+/**
+ * @description Maps any provider's token usage onto Langfuse usage-detail keys.
+ * @param usage {RawUsageObject | undefined | null} - Token usage in any naming convention NeuroLink normalizes.
+ * @returns {Record<string, number>} `input`, `output` and `total`, plus `cache_read_input_tokens`, `cache_creation_input_tokens` and `reasoning` when reported.
+ */
+export function usageDetails(usage) {
+    const tokens = extractTokenUsage(usage, { calculateCacheSavings: false });
+    const details = {
+        input: tokens.input,
+        output: tokens.output,
+        total: tokens.total,
+    };
+    if (tokens.cacheReadTokens !== undefined) {
+        details.cache_read_input_tokens = tokens.cacheReadTokens;
+    }
+    if (tokens.cacheCreationTokens !== undefined) {
+        details.cache_creation_input_tokens = tokens.cacheCreationTokens;
+    }
+    if (tokens.reasoning !== undefined) {
+        details.reasoning = tokens.reasoning;
+    }
+    return details;
+}
+/**
+ * @description Picks the Langfuse level for a model call that finished without throwing.
+ * @param finishReason {string | undefined} - Provider finish reason, in any casing.
+ * @param aborted {boolean | undefined} - Whether the caller aborted or closed the call early.
+ * @returns {ObservationLevel | undefined} `"WARNING"` for truncated, filtered, aborted or empty output, otherwise `undefined`.
+ */
+export function observationLevel(finishReason, aborted) {
+    if (aborted ||
+        WARNING_FINISH_REASONS.has(finishReason?.toLowerCase() ?? "")) {
+        return "WARNING";
+    }
+    return undefined;
+}
+/**
+ * @description Records a model request on its span as a Langfuse generation: model, defined parameters, input, output, usage, cost and level. Safe to call once with the request and again with the response; unset fields leave earlier values in place.
+ * @param span {Span} - Span of one model request.
+ * @param call {GenerationRecord} - What was sent and what came back.
+ * @returns {void} Nothing.
+ */
+export function observeGeneration(span, call) {
+    const parameters = {};
+    for (const [key, value] of Object.entries(call.modelParameters ?? {})) {
+        if (value !== undefined) {
+            parameters[key] = value;
+        }
+    }
+    const pricedModel = call.model ?? call.responseModel;
+    const cost = call.usage && call.provider && pricedModel
+        ? calculateCost(call.provider, pricedModel, extractTokenUsage(call.usage, { calculateCacheSavings: false }))
+        : 0;
+    observe(span, "generation", {
+        model: call.responseModel ?? call.model,
+        modelParameters: Object.keys(parameters).length > 0 ? parameters : undefined,
+        input: call.input === undefined
+            ? undefined
+            : spanModelRequestAttribute(call.input),
+        output: assistantMessages(call.output),
+        usageDetails: call.usage ? usageDetails(call.usage) : undefined,
+        costDetails: cost > 0 ? { total: cost } : undefined,
+        completionStartTime: call.completionStartTime,
+        level: observationLevel(call.finishReason, call.aborted),
+        metadata: call.provider ? { provider: call.provider } : undefined,
+    });
+}

package/dist/telemetry/observationNames.d.ts

@@ -0,0 +1,18 @@
+import type { GenerationOperation } from "../types/index.js";
+/**
+ * @description Names a model-call observation after the public API the caller used.
+ * @param operation {GenerationOperation | undefined} - Explicit operation; inferred from the active span's ancestry when unset.
+ * @returns {string} `generate` or `stream`; `generate` when the operation cannot be inferred.
+ */
+export declare function generationName(operation?: GenerationOperation): string;
+/**
+ * @description Names a tool observation after the tool, as the model sees it.
+ * @param toolName {string} - Tool name.
+ * @returns {string} The observation name, which is the bare tool name.
+ */
+export declare function toolSpanName(toolName: string): string;
+/**
+ * @description Names one agentic loop step. The one-based index travels as `step_index` metadata so every step of every run aggregates under the same name.
+ * @returns {string} The observation name, `step`.
+ */
+export declare function stepSpanName(): string;

package/dist/telemetry/observationNames.js

@@ -0,0 +1,24 @@
+import { activeOperation } from "./tracers.js";
+/**
+ * @description Names a model-call observation after the public API the caller used.
+ * @param operation {GenerationOperation | undefined} - Explicit operation; inferred from the active span's ancestry when unset.
+ * @returns {string} `generate` or `stream`; `generate` when the operation cannot be inferred.
+ */
+export function generationName(operation) {
+    return operation ?? activeOperation() ?? "generate";
+}
+/**
+ * @description Names a tool observation after the tool, as the model sees it.
+ * @param toolName {string} - Tool name.
+ * @returns {string} The observation name, which is the bare tool name.
+ */
+export function toolSpanName(toolName) {
+    return toolName;
+}
+/**
+ * @description Names one agentic loop step. The one-based index travels as `step_index` metadata so every step of every run aggregates under the same name.
+ * @returns {string} The observation name, `step`.
+ */
+export function stepSpanName() {
+    return "step";
+}

package/dist/telemetry/spanSanitizer.d.ts

@@ -0,0 +1,39 @@
+import type { JsonValue } from "../types/index.js";
+/**
+ * @description Masks the value stored under a credential-looking key. Structures under a plural token key (`tokens`) keep their shape with every string masked; anything else collapses to the placeholder.
+ * @param key {string} - Property name that matched the sensitive-key pattern.
+ * @param entry {JsonValue} - Value stored under that key.
+ * @returns {JsonValue} The masked value.
+ */
+export declare function redactSensitiveEntry(key: string, entry: JsonValue): JsonValue;
+/**
+ * @description Masks credentials written as `name=value`, `name: value` or as a recognizable bare key (OpenAI, GitHub, AWS, Slack). Purely numeric values after a credential-looking name are left alone.
+ * @param text {string} - Text to scan.
+ * @returns {string} The text with credential values replaced.
+ */
+export declare function redactSecretAssignments(text: string): string;
+/**
+ * @description Replaces inline base64 data URLs with a size and MIME-type placeholder.
+ * @param text {string} - Text to scan.
+ * @returns {string} The text with each data URL payload replaced by `[N bytes mime/type]`.
+ */
+export declare function describeDataUrls(text: string): string;
+/**
+ * @description Tells whether an object key conventionally holds a binary payload.
+ * @param key {string} - Property name.
+ * @returns {boolean} `true` for keys such as `data`, `image`, `bytes` and `base64`.
+ */
+export declare function isBinaryKey(key: string): boolean;
+/**
+ * @description Reads the MIME type an object declares for its payload.
+ * @param node {object} - Object that may carry `mimeType`, `mediaType`, `media_type` or `mime_type`.
+ * @returns {string | undefined} The declared MIME type, or `undefined` when none is a string.
+ */
+export declare function declaredMimeType(node: object): string | undefined;
+/**
+ * @description Describes a binary payload by size instead of content.
+ * @param value {ArrayBuffer | ArrayBufferView | string} - Raw bytes, or a base64 string long enough to be treated as bytes.
+ * @param mimeType {string | undefined} - MIME type to include in the placeholder.
+ * @returns {string | undefined} `[N bytes mime/type]`, or `undefined` when the value is not binary.
+ */
+export declare function binaryPlaceholder(value: ArrayBuffer | ArrayBufferView | string, mimeType: string | undefined): string | undefined;

package/dist/telemetry/spanSanitizer.js

@@ -0,0 +1,92 @@
+import { BINARY_KEYS, BINARY_PAYLOAD_MIN_CHARS, REDACTED_VALUE, } from "../constants/telemetry.js";
+const TOKEN_KEY_PATTERN = /tokens?$/;
+const BASE64_PATTERN = /^[A-Za-z0-9+/_\-=\s]+$/;
+const MIME_TYPE_KEYS = ["mimeType", "mediaType", "media_type", "mime_type"];
+const DATA_URL_PATTERN = new RegExp(`data:([\\w.+-]+/[\\w.+-]+)?(?:;[\\w=.+-]+)*;base64,[A-Za-z0-9+/_\\-=]{${BINARY_PAYLOAD_MIN_CHARS},}`, "g");
+const ENV_SECRET_PATTERN = /\b([\w.-]*(?:api[_-]?key|secret|password|passwd|token|credential|private[_-]?key|signature)[\w.-]*)(\s*[=:]\s*)(?!\d+\b)[^\s&"',;]+/gi;
+const BARE_SECRET_PATTERN = /\b(?:sk-[A-Za-z0-9_-]{16,}|gh[pousr]_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|AKIA[0-9A-Z]{16}|xox[baprs]-[A-Za-z0-9-]{10,})/g;
+function normalizeKey(key) {
+    return key.replace(/[_-]/g, "").toLowerCase();
+}
+function maskStrings(value) {
+    if (typeof value === "string") {
+        return REDACTED_VALUE;
+    }
+    if (Array.isArray(value)) {
+        return value.map(maskStrings);
+    }
+    if (value === null || typeof value !== "object") {
+        return value;
+    }
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, maskStrings(entry)]));
+}
+/**
+ * @description Masks the value stored under a credential-looking key. Structures under a plural token key (`tokens`) keep their shape with every string masked; anything else collapses to the placeholder.
+ * @param key {string} - Property name that matched the sensitive-key pattern.
+ * @param entry {JsonValue} - Value stored under that key.
+ * @returns {JsonValue} The masked value.
+ */
+export function redactSensitiveEntry(key, entry) {
+    const isStructure = typeof entry === "object" && entry !== null;
+    return isStructure && TOKEN_KEY_PATTERN.test(normalizeKey(key))
+        ? maskStrings(entry)
+        : REDACTED_VALUE;
+}
+/**
+ * @description Masks credentials written as `name=value`, `name: value` or as a recognizable bare key (OpenAI, GitHub, AWS, Slack). Purely numeric values after a credential-looking name are left alone.
+ * @param text {string} - Text to scan.
+ * @returns {string} The text with credential values replaced.
+ */
+export function redactSecretAssignments(text) {
+    return text
+        .replace(ENV_SECRET_PATTERN, (_match, key, separator) => `${key}${separator}${REDACTED_VALUE}`)
+        .replace(BARE_SECRET_PATTERN, REDACTED_VALUE);
+}
+/**
+ * @description Replaces inline base64 data URLs with a size and MIME-type placeholder.
+ * @param text {string} - Text to scan.
+ * @returns {string} The text with each data URL payload replaced by `[N bytes mime/type]`.
+ */
+export function describeDataUrls(text) {
+    return text.replace(DATA_URL_PATTERN, (match, mimeType) => `[${Math.floor(((match.length - match.indexOf(",") - 1) * 3) / 4)} bytes${mimeType ? ` ${mimeType}` : ""}]`);
+}
+/**
+ * @description Tells whether an object key conventionally holds a binary payload.
+ * @param key {string} - Property name.
+ * @returns {boolean} `true` for keys such as `data`, `image`, `bytes` and `base64`.
+ */
+export function isBinaryKey(key) {
+    return BINARY_KEYS.has(normalizeKey(key));
+}
+/**
+ * @description Reads the MIME type an object declares for its payload.
+ * @param node {object} - Object that may carry `mimeType`, `mediaType`, `media_type` or `mime_type`.
+ * @returns {string | undefined} The declared MIME type, or `undefined` when none is a string.
+ */
+export function declaredMimeType(node) {
+    for (const key of MIME_TYPE_KEYS) {
+        const declared = Reflect.get(node, key);
+        if (typeof declared === "string") {
+            return declared;
+        }
+    }
+    return undefined;
+}
+/**
+ * @description Describes a binary payload by size instead of content.
+ * @param value {ArrayBuffer | ArrayBufferView | string} - Raw bytes, or a base64 string long enough to be treated as bytes.
+ * @param mimeType {string | undefined} - MIME type to include in the placeholder.
+ * @returns {string | undefined} `[N bytes mime/type]`, or `undefined` when the value is not binary.
+ */
+export function binaryPlaceholder(value, mimeType) {
+    const suffix = mimeType ? ` ${mimeType}` : "";
+    if (typeof value !== "string") {
+        return value instanceof ArrayBuffer || ArrayBuffer.isView(value)
+            ? `[${value.byteLength} bytes${suffix}]`
+            : undefined;
+    }
+    if (value.length > BINARY_PAYLOAD_MIN_CHARS && BASE64_PATTERN.test(value)) {
+        return `[${Math.floor((value.length * 3) / 4)} bytes${suffix}]`;
+    }
+    return undefined;
+}

package/dist/telemetry/spanSerialization.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @description Serializes a value for a span attribute: strings pass through, everything else is JSON, with a `String()` fallback for circular structures and `[unserializable]` when even that throws.
+ * @param value {T} - Value to serialize.
+ * @returns {string} The serialized value; never throws.
+ */
+export declare function stringify<T>(value: T): string;
+/**
+ * @description Cuts every string inside a structure down to a per-string character budget, in place, leaving a truncation note on each cut string. Only call it on a copy the caller owns.
+ * @param node {T} - String or structure to shorten.
+ * @param budget {number} - Maximum characters kept per string, note included.
+ * @returns {T | string} The shortened string, or the same structure after its strings were cut.
+ */
+export declare function capStrings<T>(node: T, budget: number): T | string;

package/dist/telemetry/spanSerialization.js

@@ -0,0 +1,46 @@
+import { TRUNCATION_NOTE_ALLOWANCE_CHARS, UNSERIALIZABLE_VALUE, } from "../constants/telemetry.js";
+function safeString(value) {
+    try {
+        return String(value);
+    }
+    catch {
+        return UNSERIALIZABLE_VALUE;
+    }
+}
+/**
+ * @description Serializes a value for a span attribute: strings pass through, everything else is JSON, with a `String()` fallback for circular structures and `[unserializable]` when even that throws.
+ * @param value {T} - Value to serialize.
+ * @returns {string} The serialized value; never throws.
+ */
+export function stringify(value) {
+    try {
+        return typeof value === "string"
+            ? value
+            : (JSON.stringify(value) ?? safeString(value));
+    }
+    catch {
+        return safeString(value);
+    }
+}
+/**
+ * @description Cuts every string inside a structure down to a per-string character budget, in place, leaving a truncation note on each cut string. Only call it on a copy the caller owns.
+ * @param node {T} - String or structure to shorten.
+ * @param budget {number} - Maximum characters kept per string, note included.
+ * @returns {T | string} The shortened string, or the same structure after its strings were cut.
+ */
+export function capStrings(node, budget) {
+    if (typeof node === "string") {
+        if (node.length <= budget) {
+            return node;
+        }
+        const keep = Math.max(0, budget - TRUNCATION_NOTE_ALLOWANCE_CHARS);
+        return `${node.slice(0, keep)}...[truncated ${node.length - keep} chars]`;
+    }
+    if (node === null || typeof node !== "object") {
+        return node;
+    }
+    for (const [key, entry] of Object.entries(node)) {
+        Reflect.set(node, key, capStrings(entry, budget));
+    }
+    return node;
+}

package/dist/telemetry/tracers.d.ts

@@ -1,3 +1,22 @@
+import { type Span, type Tracer } from "@opentelemetry/api";
+import type { GenerationOperation } from "../types/index.js";
+/**
+ * @description Reads which public API call the active span belongs to, following the span's ancestry up to a `generate`, `stream`, `provider.generate` or `provider.stream` span.
+ * @returns {GenerationOperation | undefined} The enclosing operation, or `undefined` when no such span is active.
+ */
+export declare function activeOperation(): GenerationOperation | undefined;
+/**
+ * @description Reports whether a `generate` or `stream` span started inside another operation's span tree.
+ * @param span {Span} - Span returned by a scrubbed tracer.
+ * @returns {boolean} `true` when the span is nested in an enclosing operation, `false` for a trace root.
+ */
+export declare function isNestedOperation(span: Span): boolean;
+/**
+ * @description Resolves a tracer whose spans record exceptions as type and message only, without stack traces or product-name references that would reach trace backends as event metadata.
+ * @param name {string} - Instrumentation scope name.
+ * @returns {Tracer} A tracer delegating to the globally registered provider.
+ */
+export declare function scrubbedTracer(name: string): Tracer;
 /**
  * Pre-resolved tracers cached at module load.
  *
@@ -18,22 +37,22 @@
  * this file and switch to lazy accessors.
  */
 export declare const tracers: {
-    readonly sdk: import("@opentelemetry/api").Tracer;
-    readonly provider: import("@opentelemetry/api").Tracer;
-    readonly generation: import("@opentelemetry/api").Tracer;
-    readonly decision: import("@opentelemetry/api").Tracer;
-    readonly stream: import("@opentelemetry/api").Tracer;
-    readonly http: import("@opentelemetry/api").Tracer;
-    readonly mcp: import("@opentelemetry/api").Tracer;
-    readonly memory: import("@opentelemetry/api").Tracer;
-    readonly redis: import("@opentelemetry/api").Tracer;
-    readonly factory: import("@opentelemetry/api").Tracer;
-    readonly rag: import("@opentelemetry/api").Tracer;
-    readonly context: import("@opentelemetry/api").Tracer;
-    readonly middleware: import("@opentelemetry/api").Tracer;
-    readonly processor: import("@opentelemetry/api").Tracer;
-    readonly file: import("@opentelemetry/api").Tracer;
-    readonly autoresearch: import("@opentelemetry/api").Tracer;
-    readonly auth: import("@opentelemetry/api").Tracer;
-    readonly workflow: import("@opentelemetry/api").Tracer;
+    readonly sdk: Tracer;
+    readonly provider: Tracer;
+    readonly generation: Tracer;
+    readonly decision: Tracer;
+    readonly stream: Tracer;
+    readonly http: Tracer;
+    readonly mcp: Tracer;
+    readonly memory: Tracer;
+    readonly redis: Tracer;
+    readonly factory: Tracer;
+    readonly rag: Tracer;
+    readonly context: Tracer;
+    readonly middleware: Tracer;
+    readonly processor: Tracer;
+    readonly file: Tracer;
+    readonly autoresearch: Tracer;
+    readonly auth: Tracer;
+    readonly workflow: Tracer;
 };

package/dist/telemetry/tracers.js

@@ -1,4 +1,82 @@
-import { trace } from "@opentelemetry/api";
+import { context, trace, } from "@opentelemetry/api";
+import { ensureTelemetry } from "../services/server/ai/observability/instrumentation.js";
+const PRODUCT_NAME = /neurolink/gi;
+const OPERATION_ROOT = /^(?:provider\.)?(generate|stream)(?:\.|$)/;
+const operations = new WeakMap();
+const nestedOperations = new WeakSet();
+function trackOperation(span, name, parent) {
+    const root = OPERATION_ROOT.exec(name)?.[1];
+    const parentOperation = parent && operations.get(parent);
+    if (root && parentOperation) {
+        nestedOperations.add(span);
+    }
+    const operation = root ?? parentOperation;
+    if (operation) {
+        operations.set(span, operation);
+    }
+    return span;
+}
+/**
+ * @description Reads which public API call the active span belongs to, following the span's ancestry up to a `generate`, `stream`, `provider.generate` or `provider.stream` span.
+ * @returns {GenerationOperation | undefined} The enclosing operation, or `undefined` when no such span is active.
+ */
+export function activeOperation() {
+    const span = trace.getSpan(context.active());
+    return span && operations.get(span);
+}
+/**
+ * @description Reports whether a `generate` or `stream` span started inside another operation's span tree.
+ * @param span {Span} - Span returned by a scrubbed tracer.
+ * @returns {boolean} `true` when the span is nested in an enclosing operation, `false` for a trace root.
+ */
+export function isNestedOperation(span) {
+    return nestedOperations.has(span);
+}
+function scrubException(exception) {
+    if (!(exception instanceof Error)) {
+        return typeof exception === "string"
+            ? exception.replace(PRODUCT_NAME, "ai")
+            : exception;
+    }
+    return {
+        name: exception.name.replace(PRODUCT_NAME, "Ai"),
+        message: exception.message.replace(PRODUCT_NAME, "ai"),
+    };
+}
+function withScrubbedExceptions(span) {
+    const record = span.recordException.bind(span);
+    span.recordException = (exception, time) => record(scrubException(exception), time);
+    return span;
+}
+/**
+ * @description Resolves a tracer whose spans record exceptions as type and message only, without stack traces or product-name references that would reach trace backends as event metadata.
+ * @param name {string} - Instrumentation scope name.
+ * @returns {Tracer} A tracer delegating to the globally registered provider.
+ */
+export function scrubbedTracer(name) {
+    const inner = trace.getTracer(name);
+    return {
+        startSpan: (spanName, options, ctx) => {
+            ensureTelemetry();
+            const span = withScrubbedExceptions(inner.startSpan(spanName, options, ctx));
+            return trackOperation(span, spanName, trace.getSpan(ctx ?? context.active()));
+        },
+        startActiveSpan(spanName, arg2, arg3, arg4) {
+            ensureTelemetry();
+            const fn = [arg4, arg3, arg2].find((arg) => typeof arg === "function");
+            const options = typeof arg2 === "function" ? undefined : arg2;
+            const ctx = typeof arg3 === "function" ? undefined : arg3;
+            const parent = trace.getSpan(ctx ?? context.active());
+            const wrapped = ((span) => fn(trackOperation(withScrubbedExceptions(span), spanName, parent)));
+            if (ctx) {
+                return inner.startActiveSpan(spanName, options ?? {}, ctx, wrapped);
+            }
+            return options
+                ? inner.startActiveSpan(spanName, options, wrapped)
+                : inner.startActiveSpan(spanName, wrapped);
+        },
+    };
+}
 /**
  * Pre-resolved tracers cached at module load.
  *
@@ -19,22 +97,22 @@ import { trace } from "@opentelemetry/api";
  * this file and switch to lazy accessors.
  */
 export const tracers = {
-    sdk: trace.getTracer("neurolink"),
-    provider: trace.getTracer("neurolink.provider"),
-    generation: trace.getTracer("neurolink.generation"),
-    decision: trace.getTracer("neurolink.decision"),
-    stream: trace.getTracer("neurolink.stream"),
-    http: trace.getTracer("neurolink.http"),
-    mcp: trace.getTracer("neurolink.mcp"),
-    memory: trace.getTracer("neurolink.memory"),
-    redis: trace.getTracer("neurolink.redis"),
-    factory: trace.getTracer("neurolink.factory"),
-    rag: trace.getTracer("neurolink.rag"),
-    context: trace.getTracer("neurolink.context"),
-    middleware: trace.getTracer("neurolink.middleware"),
-    processor: trace.getTracer("neurolink.processor"),
-    file: trace.getTracer("neurolink.file"),
-    autoresearch: trace.getTracer("neurolink.autoresearch"),
-    auth: trace.getTracer("neurolink.auth"),
-    workflow: trace.getTracer("neurolink.workflow"),
+    sdk: scrubbedTracer("sdk"),
+    provider: scrubbedTracer("provider"),
+    generation: scrubbedTracer("generation"),
+    decision: scrubbedTracer("decision"),
+    stream: scrubbedTracer("stream"),
+    http: scrubbedTracer("http"),
+    mcp: scrubbedTracer("mcp"),
+    memory: scrubbedTracer("memory"),
+    redis: scrubbedTracer("redis"),
+    factory: scrubbedTracer("factory"),
+    rag: scrubbedTracer("rag"),
+    context: scrubbedTracer("context"),
+    middleware: scrubbedTracer("middleware"),
+    processor: scrubbedTracer("processor"),
+    file: scrubbedTracer("file"),
+    autoresearch: scrubbedTracer("autoresearch"),
+    auth: scrubbedTracer("auth"),
+    workflow: scrubbedTracer("workflow"),
 };

package/dist/telemetry/withSpan.d.ts

@@ -1,39 +1,61 @@
 import { type Span } from "@opentelemetry/api";
-import type { SpanOptions } from "../types/index.js";
+import type { GenerationRecord, SpanOptions } from "../types/index.js";
 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>;
 /**
- * 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 }),
  * );
  * ```
  */
-export declare function withStreamSpan<TResult, TChunk>(options: SpanOptions, fn: (span: Span) => Promise<TResult>, getIterable: (result: TResult) => AsyncIterable<TChunk>, setIterable: (result: TResult, wrapped: AsyncGenerator<TChunk>) => TResult): Promise<TResult>;
+export declare function withStreamSpan<TResult, TChunk>(options: SpanOptions, fn: (span: Span) => Promise<TResult>, getIterable: (result: TResult) => AsyncIterable<TChunk>, setIterable: (result: TResult, wrapped: AsyncIterableIterator<TChunk>) => TResult): Promise<TResult>;
+/**
+ * @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 declare function withGeneration<T>(request: GenerationRecord, fn: (span: Span) => Promise<T>): Promise<T>;
 /** Convenience CLIENT-kind alias matching `withClientSpan`. */
-export declare function withClientStreamSpan<TResult, TChunk>(options: Omit<SpanOptions, "kind">, fn: (span: Span) => Promise<TResult>, getIterable: (result: TResult) => AsyncIterable<TChunk>, setIterable: (result: TResult, wrapped: AsyncGenerator<TChunk>) => TResult): Promise<TResult>;
+export declare function withClientStreamSpan<TResult, TChunk>(options: Omit<SpanOptions, "kind">, fn: (span: Span) => Promise<TResult>, getIterable: (result: TResult) => AsyncIterable<TChunk>, setIterable: (result: TResult, wrapped: AsyncIterableIterator<TChunk>) => TResult): Promise<TResult>;
+/**
+ * @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 declare function withStepSpan<T>(stepNumber: number, fn: () => Promise<T>): 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 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: number): void;
+    /**
+     * @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<T>(fn: () => T): T;
+    /**
+     * @description Closes the open step, if any.
+     * @returns {void} Nothing.
+     */
+    end(): void;
+}