@juspay/neurolink 13.4.10 → 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/cli.d.ts

@@ -1312,6 +1312,8 @@ export type CliDecideArgs = {
     image?: string[];
     /** One video file (or data: URL) for a provider that reads video. */
     video?: string;
+    /** One audio file (or data: URL) for a provider that reads audio. */
+    audio?: string;
     provider?: string;
     model?: string;
     timeout?: number;

package/dist/types/decision.d.ts

@@ -53,6 +53,13 @@ export type DecisionChoiceQuestion = {
     type: "choice";
     instructions: DecisionInput;
     criteria: Readonly<Record<string, DecisionInput | null>>;
+    /**
+     * True adds an option named `unknown` the model picks when none of the
+     * criteria fits; the answer then carries `unknown: true`. Only a provider
+     * whose `decisionLimits.questionTypes` lists `"choice-unknown"` accepts it,
+     * and no criteria key may be named `unknown` alongside it.
+     */
+    unknown?: boolean;
 };
 /**
  * Rate against an ordered rubric. The answer is the **0-based index**, so a
@@ -63,7 +70,24 @@ export type DecisionScoreQuestion = {
     instructions: DecisionInput;
     criteria: readonly (DecisionInput | null)[];
 };
-export type DecisionQuestion = DecisionBooleanQuestion | DecisionChoiceQuestion | DecisionScoreQuestion;
+/**
+ * Extract one typed field from the state: an amount, a reference, a name. Only
+ * a provider whose `decisionLimits.questionTypes` lists `"value"` accepts it.
+ */
+export type DecisionValueQuestion = {
+    type: "value";
+    instructions: DecisionInput;
+    /** The type of the extracted value. Omitted means `string`. */
+    dtype?: "string" | "int" | "float";
+    /** A regular expression the extracted text must match. */
+    pattern?: string;
+};
+export type DecisionQuestion = DecisionBooleanQuestion | DecisionChoiceQuestion | DecisionScoreQuestion | DecisionValueQuestion;
+/**
+ * What a provider may be asked, per question. `"choice-unknown"` is a `choice`
+ * question that sets `unknown: true`.
+ */
+export type DecisionQuestionType = DecisionQuestion["type"] | "choice-unknown";
 /** Questions keyed by an id you choose; answers return under the same ids. */
 export type DecisionQuestionMap = Readonly<Record<string, DecisionQuestion>>;
 export type DecisionBooleanAnswer = {
@@ -79,24 +103,34 @@ export type DecisionChoiceAnswer = {
     probabilities: Readonly<Record<string, number>>;
     /** Calibrated certainty, 0–1, derived from the distribution. */
     confidence: number;
+    /** True when the question set `unknown` and the model picked it. */
+    unknown?: boolean;
 };
 export type DecisionScoreAnswer = {
     type: "score";
     /** Probability-weighted level index; lands between levels. */
     score: number;
-    /** Level index (as a string key) → the description supplied. */
+    /** Level index (as a string key) → the description supplied; a level that was not a string is given as its JSON text. */
     legend: Readonly<Record<string, string>>;
     /** Level index (as a string key) → probability. */
     probabilities: Readonly<Record<string, number>>;
     confidence: number;
 };
-export type DecisionAnswer = DecisionBooleanAnswer | DecisionChoiceAnswer | DecisionScoreAnswer;
+export type DecisionValueAnswer = {
+    type: "value";
+    /** The extracted value: a number for `int` / `float`, else a string. Null when the model abstained. */
+    value: string | number | null;
+    confidence: number;
+    /** True when the model found nothing to extract; `value` is then null. */
+    unknown?: boolean;
+};
+export type DecisionAnswer = DecisionBooleanAnswer | DecisionChoiceAnswer | DecisionScoreAnswer | DecisionValueAnswer;
 export type DecisionAnswerMap = Readonly<Record<string, DecisionAnswer>>;
 export type DecisionUsage = {
     inputTokens: number;
     outputTokens: number;
 };
-/** An image or video as the caller supplies it: raw bytes, a file path, or a data URL. */
+/** An image, video or audio clip as the caller supplies it: raw bytes, a file path, or a data URL. */
 export type DecisionMediaSource = Buffer | string;
 export type DecisionRequest = {
     state: DecisionState;
@@ -109,6 +143,11 @@ export type DecisionRequest = {
     images?: readonly DecisionMediaSource[];
     /** One video, in the same forms. Sending images as well is allowed. */
     video?: DecisionMediaSource;
+    /**
+     * One audio clip, in the same forms (a `data:audio/…;base64,` URL). Only a
+     * provider whose `decisionLimits.media.audio` is set accepts it.
+     */
+    audio?: DecisionMediaSource;
     /** Overrides the provider's configured model for this call only. */
     model?: string;
     signal?: AbortSignal;
@@ -127,7 +166,7 @@ export type DecisionResult = {
     latencyMs: number;
     /** Server-side time behind the edge; isolates model time from network. */
     upstreamMs?: number;
-    /** Encoded size of the images and video sent. Absent for a text-only request. */
+    /** Encoded size of the images, video and audio sent. Absent for a text-only request. */
     mediaBytes?: number;
 };
 /**
@@ -147,6 +186,16 @@ export type DecisionLimits = {
     maxStateTokens: number;
     /** Absent when the provider has no cap on questions per request. */
     maxQuestions?: number;
+    /**
+     * The question types the provider reads. Absent means `boolean`, `choice`
+     * and `score`; a request asking anything else is refused before any network
+     * call, whether or not the limits are advisory.
+     */
+    questionTypes?: readonly DecisionQuestionType[];
+    /** Most levels one `score` question may have. Absent means no local cap. */
+    maxScoreLevels?: number;
+    /** Most options one `choice` question may have. Absent means no local cap. */
+    maxChoiceOptions?: number;
     /**
      * Tokens charged per non-ASCII character. The default estimate assumes ~4
      * characters per token, which holds for English and is several times too
@@ -208,9 +257,15 @@ export type DecisionLimitsReading = {
     maxStateTokens: number;
     /**
      * Absent when the provider caps a request by tokens (or bytes) rather
-     * than by question count — TypeSafe and XOR; `Infinity` is never used.
+     * than by question count — TypeSafe; `Infinity` is never used.
      */
     maxQuestions?: number;
+    /** Present only when the descriptor declares it; absent means `boolean`, `choice` and `score`. */
+    questionTypes?: readonly DecisionQuestionType[];
+    /** Most levels one `score` question may have; absent means no local cap. */
+    maxScoreLevels?: number;
+    /** Most options one `choice` question may have; absent means no local cap. */
+    maxChoiceOptions?: number;
     nonAsciiTokensPerChar?: number;
     /** Tokens charged per ASCII digit; see {@link DecisionLimits.digitTokensPerChar}. */
     digitTokensPerChar?: number;
@@ -241,19 +296,36 @@ export type DecisionMediaLimits = {
     video: boolean;
     /** Ceiling on the encoded request body, in bytes. */
     maxRequestBytes: number;
+    /** Whether one audio clip is accepted, and how much of it the model hears. Absent means no audio. */
+    audio?: DecisionAudioLimits;
+};
+export type DecisionAudioLimits = {
+    /**
+     * Seconds of audio the model reads. A clip whose length can be read from its
+     * header (WAV, FLAC, Ogg) and runs longer is refused, since the rest would be cut
+     * off without a word.
+     */
+    maxSeconds: number;
 };
 /** An image's size in pixels, read from its header. */
 export type DecisionImageDimensions = {
     width: number;
     height: number;
 };
-/** Media after preparation: everything is a `data:` URL, ready for the wire. */
+/** Media after preparation: images and video are `data:` URLs, ready for the wire. */
 export type DecisionPreparedMedia = {
     images: string[];
     video?: string;
-    /** Encoded size of every URL above. */
+    audio?: DecisionPreparedAudio;
+    /** Encoded size of everything above. */
     bytes: number;
 };
+/** An audio clip as the wire takes it: raw base64 and the container it was sniffed as. */
+export type DecisionPreparedAudio = {
+    data: string;
+    format: DecisionAudioFormat;
+};
+export type DecisionAudioFormat = "wav" | "flac" | "ogg" | "mp3";
 /**
  * Discriminated by a string literal, not a boolean: the package is also
  * compiled without strictNullChecks, where a boolean discriminant does not
@@ -266,8 +338,8 @@ export type DecisionMediaResult = {
     status: "refused";
     message: string;
 };
-export type DecisionMediaKind = "image" | "video";
-/** One image or video turned into a data URL, or the reason it could not be. Same literal-discriminant rule as above. */
+export type DecisionMediaKind = "image" | "video" | "audio";
+/** One image, video or audio clip turned into a data URL, or the reason it could not be. Same literal-discriminant rule as above. */
 export type DecisionMediaConversion = {
     status: "ok";
     dataUrl: string;
@@ -283,6 +355,21 @@ export type DecisionMediaFileRead = {
     status: "error";
     message: string;
 };
+/**
+ * A caller's media source resolved for one kind: bytes to identify (a Buffer
+ * or a file read from disk), a `data:` URL of that kind as given, or the reason
+ * it is refused.
+ */
+export type DecisionMediaSourceRead = {
+    status: "buffer";
+    buffer: Buffer;
+} | {
+    status: "dataUrl";
+    dataUrl: string;
+} | {
+    status: "error";
+    message: string;
+};
 /**
  * Why a decision call failed, normalised across vendors. TypeSafe alone
  * returns two different error envelopes, so a provider must flatten them.
@@ -318,6 +405,11 @@ export type DecisionChoiceReading = {
         name: string;
         probability: number;
     }[];
+    /**
+     * True when the question set `unknown` and the model picked it: `choice` is
+     * then `"unknown"`, which is none of the question's own options.
+     */
+    unknown: boolean;
 };
 export type DecisionScoreReading = {
     score: number;
@@ -325,6 +417,12 @@ export type DecisionScoreReading = {
     legend: Readonly<Record<string, string>>;
     probabilities: Readonly<Record<string, number>>;
 };
+export type DecisionValueReading = {
+    value: string | number | null;
+    confidence: number;
+    /** True when the model abstained; `value` is then null. */
+    unknown: boolean;
+};
 /**
  * What `NeuroLink.decide()` accepts: a decision request plus the usual
  * provider/credential selection every inference type shares.
@@ -543,6 +641,8 @@ export type DecideMedia = {
     imagesKey: string;
     /** Written only when the request carries a video; required exactly when `decisionLimits.media.video` is true. */
     videoKey?: string;
+    /** Written only when the request carries audio, as `{ data, format }`; required exactly when `decisionLimits.media.audio` is set. */
+    audioKey?: string;
 };
 /**
  * Says when a decide provider's key may be used as the default decision
@@ -580,6 +680,13 @@ export type DecideAmbientKeyCredentialField = {
     /** The field in that slice. Only `baseURL` is read today. */
     field: "baseURL";
 };
+/** See `DecideBlock.capableModel`. */
+export type DecideCapableModel = {
+    /** A key of the entry's `models.catalog`. */
+    model: string;
+    /** Question types that send a request to `model`; media always does. */
+    questionTypes: readonly DecisionQuestionType[];
+};
 /** What a dialect lays out as one request body. */
 export type DecisionDialectBody = {
     readonly state: DecisionState;