@juspay/neurolink 13.4.10 → 13.5.1

package/dist/telemetry/observation.d.ts

@@ -1,7 +1,7 @@
 import type { Span } from "@opentelemetry/api";
 import type { GenerationRecord, ObservationAttributes, ObservationLevel, ObservationType, RawUsageObject, TraceContent } from "../types/index.js";
 /**
- * @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.
+ * @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, and the status message is recorded as given; an attribute that `spanContentAttribute` or `spanModelRequestAttribute` already produced is not masked again, and input is left out when `NEUROLINK_RECORD_INPUTS=false`. Nothing is built when the span is not recording.
  * @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.
@@ -9,7 +9,7 @@ import type { GenerationRecord, ObservationAttributes, ObservationLevel, Observa
  */
 export declare function observe(span: Span, type: ObservationType, attrs: ObservationAttributes): void;
 /**
- * @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.
+ * @description Sets the trace-level input, output and metadata on a span, credential-masked and capped like `observe`, with input left out when `NEUROLINK_RECORD_INPUTS=false` and nothing built when the span is not recording. 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.
@@ -23,13 +23,13 @@ export declare function observeTrace(span: Span, io: TraceContent): void;
 export declare function usageDetails(usage: RawUsageObject | undefined | null): Record<string, number>;
 /**
  * @description Picks the Langfuse level for a model call that finished without throwing.
- * @param finishReason {string | undefined} - Provider finish reason, in any casing.
+ * @param finishReason {unknown} - Provider finish reason: a string in any casing, or an ai@6 `{ unified, raw }` object; any other value is ignored.
  * @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 declare function observationLevel(finishReason?: string, aborted?: boolean): ObservationLevel | undefined;
+export declare function observationLevel(finishReason?: unknown, aborted?: boolean): ObservationLevel | 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.
+ * @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. The request is redacted once, input and the arguments of the tool calls in the output are left out when `NEUROLINK_RECORD_INPUTS=false`, and nothing is built when the span is not recording. Cost is priced on the response model when it has a price, otherwise on the requested model. A field that cannot be built is left out; this never throws into the model call.
  * @param span {Span} - Span of one model request.
  * @param call {GenerationRecord} - What was sent and what came back.
  * @returns {void} Nothing.

package/dist/telemetry/observation.js

@@ -1,47 +1,80 @@
 import { createObservationAttributes, createTraceAttributes, LangfuseOtelSpanAttributes, } from "@langfuse/tracing";
 import { WARNING_FINISH_REASONS } from "../constants/telemetry.js";
-import { calculateCost } from "../utils/pricing.js";
+import { logger } from "../utils/logger.js";
+import { calculateCost, hasPricing } from "../utils/pricing.js";
 import { extractTokenUsage } from "../utils/tokenUtils.js";
-import { ATTR, spanContentAttribute, spanModelRequestAttribute, } from "./attributes.js";
-import { assistantMessages } from "./chatMessages.js";
+import { ATTR, isFinishedAttribute, recordsSpanContent, recordsSpanInputs, spanContentAttribute, spanModelRequestAttribute, } from "./attributes.js";
+import { assistantMessages, withoutToolArguments } from "./chatMessages.js";
+import { inTurnlessTree, isNestedOperation } from "./tracers.js";
+// Recording must never fail the call it describes: a field that cannot be
+// built is dropped and logged, and the rest of the record is still written.
+function attempt(what, compute, fallback) {
+    try {
+        return compute();
+    }
+    catch (error) {
+        logger.debug(`[telemetry] Could not record ${what}`, {
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return fallback;
+    }
+}
+function contentAttribute(value) {
+    return typeof value === "string" && isFinishedAttribute(value)
+        ? value
+        : spanContentAttribute(value);
+}
 function redactedIO(attrs) {
     return {
         ...attrs,
-        ...(attrs.input !== undefined && {
-            input: spanContentAttribute(attrs.input),
-        }),
-        ...(attrs.output !== undefined && {
-            output: spanContentAttribute(attrs.output),
-        }),
+        input: attrs.input !== undefined && recordsSpanInputs()
+            ? contentAttribute(attrs.input)
+            : undefined,
+        output: attrs.output !== undefined && recordsSpanContent()
+            ? contentAttribute(attrs.output)
+            : undefined,
     };
 }
 /**
- * @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.
+ * @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, and the status message is recorded as given; an attribute that `spanContentAttribute` or `spanModelRequestAttribute` already produced is not masked again, and input is left out when `NEUROLINK_RECORD_INPUTS=false`. Nothing is built when the span is not recording.
  * @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)),
+    if (!span.isRecording()) {
+        return;
+    }
+    attempt("observation", () => span.setAttributes({
+        ...createObservationAttributes(type, {
+            ...redactedIO(attrs),
+            ...(attrs.statusMessage !== undefined && {
+                statusMessage: attrs.statusMessage,
+            }),
+        }),
         [ATTR.GEN_AI_OBSERVATION]: type,
-    });
+    }), undefined);
 }
 /**
- * @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.
+ * @description Sets the trace-level input, output and metadata on a span, credential-masked and capped like `observe`, with input left out when `NEUROLINK_RECORD_INPUTS=false` and nothing built when the span is not recording. 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));
-        }
+    if (!span.isRecording()) {
+        return;
     }
+    attempt("trace", () => {
+        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));
+            }
+        }
+    }, undefined);
 }
 /**
  * @description Maps any provider's token usage onto Langfuse usage-detail keys.
@@ -66,47 +99,103 @@ export function usageDetails(usage) {
     }
     return details;
 }
+// ai@6 reports `{ unified, raw }` where other providers report a string; any
+// other shape carries no reason worth recording.
+function finishReasonText(finishReason) {
+    if (typeof finishReason === "string") {
+        return finishReason;
+    }
+    if (typeof finishReason !== "object" || finishReason === null) {
+        return undefined;
+    }
+    if ("unified" in finishReason && typeof finishReason.unified === "string") {
+        return finishReason.unified;
+    }
+    return "raw" in finishReason && typeof finishReason.raw === "string"
+        ? finishReason.raw
+        : undefined;
+}
 /**
  * @description Picks the Langfuse level for a model call that finished without throwing.
- * @param finishReason {string | undefined} - Provider finish reason, in any casing.
+ * @param finishReason {unknown} - Provider finish reason: a string in any casing, or an ai@6 `{ unified, raw }` object; any other value is ignored.
  * @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() ?? "")) {
+        WARNING_FINISH_REASONS.has(finishReasonText(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) {
+// The model that answered sets the price. A served model without one (an
+// alias, a router's own name) falls back to the model that was requested.
+function pricedModel(call) {
+    const { provider, model, responseModel } = call;
+    return provider && responseModel && hasPricing(provider, responseModel)
+        ? responseModel
+        : (model ?? responseModel);
+}
+function generationCost(call) {
+    const model = pricedModel(call);
+    return call.usage && call.provider && model
+        ? calculateCost(call.provider, model, extractTokenUsage(call.usage, { calculateCacheSavings: false }))
+        : 0;
+}
+function recordGeneration(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;
+    const cost = attempt("generation cost", () => generationCost(call), 0);
+    const request = call.input;
+    const input = request === undefined || !recordsSpanInputs()
+        ? undefined
+        : attempt("generation input", () => spanModelRequestAttribute(request), undefined);
+    const output = attempt("generation output", () => {
+        const messages = assistantMessages(call.output);
+        if (messages === undefined) {
+            return undefined;
+        }
+        // A tool call's arguments are the tool's input, so they follow the
+        // inputs setting even though they arrive in the model's output.
+        return spanContentAttribute(recordsSpanInputs() ? messages : withoutToolArguments(messages));
+    }, undefined);
+    const finishReason = finishReasonText(call.finishReason);
     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),
+        input,
+        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,
+        level: observationLevel(finishReason, call.aborted),
+        metadata: call.provider || finishReason
+            ? {
+                ...(call.provider && { provider: call.provider }),
+                ...(finishReason && { finishReason }),
+            }
+            : undefined,
     });
+    // Inside a NeuroLink turn the turn owns the trace's input and output, and
+    // under a host span the host does. Only a direct loop that opened its own
+    // root has nothing above it, so only its generations write them.
+    if (!isNestedOperation(span) && inTurnlessTree(span)) {
+        observeTrace(span, { input, output });
+    }
+}
+/**
+ * @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. The request is redacted once, input and the arguments of the tool calls in the output are left out when `NEUROLINK_RECORD_INPUTS=false`, and nothing is built when the span is not recording. Cost is priced on the response model when it has a price, otherwise on the requested model. A field that cannot be built is left out; this never throws into the model call.
+ * @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) {
+    if (!span.isRecording()) {
+        return;
+    }
+    attempt("generation", () => recordGeneration(span, call), undefined);
 }

package/dist/telemetry/spanSanitizer.d.ts

@@ -7,7 +7,7 @@ import type { JsonValue } from "../types/index.js";
  */
 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.
+ * @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. Runs in time linear in the length of the text.
  * @param text {string} - Text to scan.
  * @returns {string} The text with credential values replaced.
  */
@@ -32,7 +32,7 @@ export declare function isBinaryKey(key: string): boolean;
 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 value {ArrayBuffer | ArrayBufferView | string} - Raw bytes, or a base64 string long enough to be treated as bytes. A string made only of base64 characters and `=` counts as base64; one with whitespace inside it counts only when it is wrapped at a fixed width (or PEM-armored), so prose, word lists and name lists keep their content.
  * @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.
  */

package/dist/telemetry/spanSanitizer.js

@@ -1,9 +1,24 @@
 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]+$/;
+// A run of base64 characters and `=`, with no whitespace in it.
+const BASE64_RUN_PATTERN = /^[A-Za-z0-9+/_\-=]+$/;
+// What every string was held to before whitespace was told apart.
+const BASE64_OR_SPACE_PATTERN = /^[A-Za-z0-9+/_\-=\s]+$/;
+const WHITESPACE_PATTERN = /\s/;
+const SEGMENT_PATTERN = /\S+/g;
+const PEM_ARMOR_PATTERN = /^-----BEGIN [A-Z0-9 ]+-----/;
+// Encoders wrap at 16 columns or more; a narrower repeat is a list of short
+// words or codes.
+const MIN_WRAPPED_WIDTH = 16;
 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;
+// A name made of word characters, dots and dashes that is followed by `=` or
+// `:` and a value that is not a bare number. Starting only where a run begins
+// keeps the scan linear: the run is read once, and whether it names a
+// credential is decided afterwards on the matched run alone.
+const ASSIGNMENT_NAME_PATTERN = /(?<![\w.-])[\w.-]+(?=\s*[=:]\s*(?!\d+\b)[^\s&"',;])/g;
+const ASSIGNMENT_VALUE_PATTERN = /(\s*[=:]\s*)(?!\d+\b)[^\s&"',;]+/y;
+const SECRET_NAME_PATTERN = /api[_-]?key|secret|password|passwd|token|credential|private[_-]?key|signature/i;
 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();
@@ -33,14 +48,30 @@ export function redactSensitiveEntry(key, 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.
+ * @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. Runs in time linear in the length of the text.
  * @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);
+    const names = new RegExp(ASSIGNMENT_NAME_PATTERN);
+    const value = new RegExp(ASSIGNMENT_VALUE_PATTERN);
+    let redacted = "";
+    let copied = 0;
+    for (let name = names.exec(text); name; name = names.exec(text)) {
+        if (!SECRET_NAME_PATTERN.test(name[0])) {
+            continue;
+        }
+        const nameEnd = name.index + name[0].length;
+        value.lastIndex = nameEnd;
+        const assignment = value.exec(text);
+        if (!assignment) {
+            continue;
+        }
+        redacted += `${text.slice(copied, nameEnd)}${assignment[1]}${REDACTED_VALUE}`;
+        copied = nameEnd + assignment[0].length;
+        names.lastIndex = copied;
+    }
+    return `${redacted}${text.slice(copied)}`.replace(BARE_SECRET_PATTERN, REDACTED_VALUE);
 }
 /**
  * @description Replaces inline base64 data URLs with a size and MIME-type placeholder.
@@ -72,9 +103,46 @@ export function declaredMimeType(node) {
     }
     return undefined;
 }
+// Encoded text with whitespace in it is wrapped: every segment but the last has
+// the same width, as MIME, PEM and `base64 -w` produce. Prose and lists of names
+// break wherever they like, so their segments differ in length.
+function isWrappedBase64(text) {
+    if (PEM_ARMOR_PATTERN.test(text)) {
+        return BASE64_OR_SPACE_PATTERN.test(text);
+    }
+    let width;
+    let sawShorter = false;
+    for (const [segment] of text.matchAll(SEGMENT_PATTERN)) {
+        if (!BASE64_RUN_PATTERN.test(segment)) {
+            return false;
+        }
+        if (width === undefined) {
+            width = segment.length;
+            if (width < MIN_WRAPPED_WIDTH) {
+                return false;
+            }
+        }
+        else if (sawShorter || segment.length > width) {
+            return false;
+        }
+        else if (segment.length < width) {
+            sawShorter = true;
+        }
+    }
+    return true;
+}
+// A string without whitespace is held to the rule it always was; one with
+// whitespace inside it must also read as wrapped base64, which keeps prose and
+// word lists readable. Whitespace around the ends does not count.
+function isBase64Payload(value) {
+    const text = value.trim();
+    return WHITESPACE_PATTERN.test(text)
+        ? isWrappedBase64(text)
+        : BASE64_RUN_PATTERN.test(text);
+}
 /**
  * @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 value {ArrayBuffer | ArrayBufferView | string} - Raw bytes, or a base64 string long enough to be treated as bytes. A string made only of base64 characters and `=` counts as base64; one with whitespace inside it counts only when it is wrapped at a fixed width (or PEM-armored), so prose, word lists and name lists keep their content.
  * @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.
  */
@@ -85,7 +153,7 @@ export function binaryPlaceholder(value, mimeType) {
             ? `[${value.byteLength} bytes${suffix}]`
             : undefined;
     }
-    if (value.length > BINARY_PAYLOAD_MIN_CHARS && BASE64_PATTERN.test(value)) {
+    if (value.length > BINARY_PAYLOAD_MIN_CHARS && isBase64Payload(value)) {
         return `[${Math.floor((value.length * 3) / 4)} bytes${suffix}]`;
     }
     return undefined;

package/dist/telemetry/telemetryStarter.d.ts

@@ -0,0 +1,16 @@
+/**
+ * @description Registers the function that starts NeuroLink's tracing. The shared tracers call it through `startTelemetry`, so they depend on this module and on `@opentelemetry/api` only, and the OpenTelemetry SDK loads with the entries that register a starter.
+ * @param start {() => void} - Starts tracing once per process; safe to call repeatedly.
+ * @returns {void} Nothing.
+ */
+export declare function registerTelemetryStarter(start: () => void): void;
+/**
+ * @description Starts NeuroLink's tracing through the registered starter. Without one nothing starts and spans go to whatever provider the host registered.
+ * @returns {void} Nothing.
+ */
+export declare function startTelemetry(): void;
+/**
+ * @description Reports whether a TracerProvider other than the API's placeholder is registered globally, whoever registered it.
+ * @returns {boolean} `true` when spans reach a real provider.
+ */
+export declare function hasHostTracerProvider(): boolean;

package/dist/telemetry/telemetryStarter.js

@@ -0,0 +1,28 @@
+import { ProxyTracerProvider, trace } from "@opentelemetry/api";
+let starter;
+/**
+ * @description Registers the function that starts NeuroLink's tracing. The shared tracers call it through `startTelemetry`, so they depend on this module and on `@opentelemetry/api` only, and the OpenTelemetry SDK loads with the entries that register a starter.
+ * @param start {() => void} - Starts tracing once per process; safe to call repeatedly.
+ * @returns {void} Nothing.
+ */
+export function registerTelemetryStarter(start) {
+    starter = start;
+}
+/**
+ * @description Starts NeuroLink's tracing through the registered starter. Without one nothing starts and spans go to whatever provider the host registered.
+ * @returns {void} Nothing.
+ */
+export function startTelemetry() {
+    starter?.();
+}
+/**
+ * @description Reports whether a TracerProvider other than the API's placeholder is registered globally, whoever registered it.
+ * @returns {boolean} `true` when spans reach a real provider.
+ */
+export function hasHostTracerProvider() {
+    const global = trace.getTracerProvider();
+    if (!(global instanceof ProxyTracerProvider)) {
+        return true;
+    }
+    return global.getDelegateTracer("ai") !== undefined;
+}

package/dist/telemetry/traceContext.d.ts

@@ -1,7 +1,7 @@
 /**
- * Extract the current OTel trace context for use by Pipeline B spans.
- * Returns undefined values when no OTel context is active, allowing
- * Pipeline B spans to share the same trace as Pipeline A spans.
+ * Extract the current OTel trace context for the in-process span records
+ * (`SpanSerializer`), so they carry the traceId of the exported OTEL trace.
+ * Returns undefined values when no OTel context is active.
  */
 export declare function getActiveTraceContext(): {
     traceId?: string;

package/dist/telemetry/traceContext.js

@@ -1,8 +1,8 @@
 import { trace, context } from "@opentelemetry/api";
 /**
- * Extract the current OTel trace context for use by Pipeline B spans.
- * Returns undefined values when no OTel context is active, allowing
- * Pipeline B spans to share the same trace as Pipeline A spans.
+ * Extract the current OTel trace context for the in-process span records
+ * (`SpanSerializer`), so they carry the traceId of the exported OTEL trace.
+ * Returns undefined values when no OTel context is active.
  */
 export function getActiveTraceContext() {
     const activeSpan = trace.getSpan(context.active());

package/dist/telemetry/tracers.d.ts

@@ -12,7 +12,19 @@ export declare function activeOperation(): GenerationOperation | undefined;
  */
 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.
+ * @description Reports whether a span belongs to the tree of a root a direct provider loop opened for itself, so neither a host span nor a NeuroLink turn sits above it.
+ * @param span {Span} - Span returned by a scrubbed tracer.
+ * @returns {boolean} `true` for that root and the spans started under it, apart from a NeuroLink turn's own subtree; `false` for everything under a host span or a turn.
+ */
+export declare function inTurnlessTree(span: Span): boolean;
+/**
+ * @description Marks the root a direct provider loop opened for itself. It names the operation its steps belong to, but no NeuroLink turn sits above it and it records no input or output, so a generation under it is still the top owner of the trace's input and output and `isNestedOperation` stays `false` for it. A NeuroLink `generate` or `stream` turn started inside it, such as a sub-agent run by a tool, is not marked: that turn and its generations stay nested.
+ * @param span {Span} - Root span returned by a scrubbed tracer, marked before any child is started.
+ * @returns {Span} The same span.
+ */
+export declare function markTurnlessRoot(span: Span): 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. Exception and status messages have credentials masked, like recorded input and output.
  * @param name {string} - Instrumentation scope name.
  * @returns {Tracer} A tracer delegating to the globally registered provider.
  */

package/dist/telemetry/tracers.js

@@ -1,15 +1,26 @@
 import { context, trace, } from "@opentelemetry/api";
-import { ensureTelemetry } from "../services/server/ai/observability/instrumentation.js";
+import { startTelemetry } from "./telemetryStarter.js";
 const PRODUCT_NAME = /neurolink/gi;
 const OPERATION_ROOT = /^(?:provider\.)?(generate|stream)(?:\.|$)/;
+const TURN_NAME = /^(?:generate|stream)$/;
 const operations = new WeakMap();
 const nestedOperations = new WeakSet();
-function trackOperation(span, name, parent) {
+const turnlessTrees = new WeakSet();
+function trackOperation(span, name, scope, parent) {
     const root = OPERATION_ROOT.exec(name)?.[1];
     const parentOperation = parent && operations.get(parent);
-    if (root && parentOperation) {
+    // A NeuroLink turn (a sub-agent a direct loop's tool runs) stops the loop's
+    // turnless mark, so it and its generations stay nested and leave the
+    // trace's input and output to the loop.
+    const turnless = parent !== undefined &&
+        turnlessTrees.has(parent) &&
+        !(scope === "sdk" && TURN_NAME.test(name));
+    if (root && parentOperation && !turnless) {
         nestedOperations.add(span);
     }
+    if (turnless) {
+        turnlessTrees.add(span);
+    }
     const operation = root ?? parentOperation;
     if (operation) {
         operations.set(span, operation);
@@ -32,6 +43,34 @@ export function activeOperation() {
 export function isNestedOperation(span) {
     return nestedOperations.has(span);
 }
+/**
+ * @description Reports whether a span belongs to the tree of a root a direct provider loop opened for itself, so neither a host span nor a NeuroLink turn sits above it.
+ * @param span {Span} - Span returned by a scrubbed tracer.
+ * @returns {boolean} `true` for that root and the spans started under it, apart from a NeuroLink turn's own subtree; `false` for everything under a host span or a turn.
+ */
+export function inTurnlessTree(span) {
+    return turnlessTrees.has(span);
+}
+/**
+ * @description Marks the root a direct provider loop opened for itself. It names the operation its steps belong to, but no NeuroLink turn sits above it and it records no input or output, so a generation under it is still the top owner of the trace's input and output and `isNestedOperation` stays `false` for it. A NeuroLink `generate` or `stream` turn started inside it, such as a sub-agent run by a tool, is not marked: that turn and its generations stay nested.
+ * @param span {Span} - Root span returned by a scrubbed tracer, marked before any child is started.
+ * @returns {Span} The same span.
+ */
+export function markTurnlessRoot(span) {
+    turnlessTrees.add(span);
+    return span;
+}
+// An Error's name or message may be missing, not a string, or a getter that
+// throws; recording the exception must not throw in its place.
+function exceptionText(read, fallback) {
+    try {
+        const value = read();
+        return value === undefined || value === null ? fallback : String(value);
+    }
+    catch {
+        return fallback;
+    }
+}
 function scrubException(exception) {
     if (!(exception instanceof Error)) {
         return typeof exception === "string"
@@ -39,8 +78,8 @@ function scrubException(exception) {
             : exception;
     }
     return {
-        name: exception.name.replace(PRODUCT_NAME, "Ai"),
-        message: exception.message.replace(PRODUCT_NAME, "ai"),
+        name: exceptionText(() => exception.name, "Error").replace(PRODUCT_NAME, "Ai"),
+        message: exceptionText(() => exception.message, "").replace(PRODUCT_NAME, "ai"),
     };
 }
 function withScrubbedExceptions(span) {
@@ -49,7 +88,7 @@ function withScrubbedExceptions(span) {
     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.
+ * @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. Exception and status messages have credentials masked, like recorded input and output.
  * @param name {string} - Instrumentation scope name.
  * @returns {Tracer} A tracer delegating to the globally registered provider.
  */
@@ -57,17 +96,17 @@ export function scrubbedTracer(name) {
     const inner = trace.getTracer(name);
     return {
         startSpan: (spanName, options, ctx) => {
-            ensureTelemetry();
+            startTelemetry();
             const span = withScrubbedExceptions(inner.startSpan(spanName, options, ctx));
-            return trackOperation(span, spanName, trace.getSpan(ctx ?? context.active()));
+            return trackOperation(span, spanName, name, trace.getSpan(ctx ?? context.active()));
         },
         startActiveSpan(spanName, arg2, arg3, arg4) {
-            ensureTelemetry();
+            startTelemetry();
             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)));
+            const wrapped = ((span) => fn(trackOperation(withScrubbedExceptions(span), spanName, name, parent)));
             if (ctx) {
                 return inner.startActiveSpan(spanName, options ?? {}, ctx, wrapped);
             }