@juspay/neurolink 13.4.10 → 13.5.1

package/dist/types/exporter.d.ts

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

package/dist/types/livekit.d.ts

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

package/dist/types/loopEngine.d.ts

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

package/dist/types/observability.d.ts

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

package/dist/types/providerCatalog.d.ts

@@ -4,7 +4,7 @@
  * src/lib/providers/catalog/<id>.json file per provider is the single
  * source of truth; see docs/superpowers/plans/2026-08-28-provider-json-catalog-spec.md.
  */
-import type { DecideAmbientKeyGuard, DecideDialectName, DecideMedia, DecisionErrorKind, DecisionLimits } from "./decision.js";
+import type { DecideAmbientKeyGuard, DecideCapableModel, DecideDialectName, DecideMedia, DecisionErrorKind, DecisionLimits } from "./decision.js";
 export type CatalogPricingPerMTok = {
     input: number;
     output: number;
@@ -338,6 +338,15 @@ export type DecideBlock = {
     stateEncoding?: "text";
     /** Body keys for images and video, after `model`, `state` and `questions`. Omitted means the body never carries media. */
     media?: DecideMedia;
+    /**
+     * A model the request is sent to instead of the default when the call names
+     * no model, no model variable is set, and the request carries media or a
+     * question of one of `questionTypes`. Its `decisionLimits` row is the one
+     * checked. For a text default that cannot read those requests, whose server
+     * would otherwise hand them to this model behind its back, with a smaller
+     * window than the one checked. Omitted means the default model is always sent.
+     */
+    capableModel?: DecideCapableModel;
     /**
      * Keeps a key found only in the environment from becoming the default
      * decision provider when it plainly belongs to something else. Omitted means
@@ -368,6 +377,8 @@ export type DecideCatalogJson = {
     };
     timeouts?: {
         decideMs?: number;
+        /** Added to `decideMs` per 1,000 estimated state tokens, for a model whose latency grows with the state. */
+        decideMsPerKStateTokens?: number;
     };
     decisionLimits?: DecisionLimits;
     decide: DecideBlock;

package/dist/types/providers.d.ts

@@ -2459,6 +2459,8 @@ export type ProviderDescriptor = {
         generateMs?: number;
         streamMs?: number;
         decideMs?: number;
+        /** Added to `decideMs` per 1,000 estimated state tokens. */
+        decideMsPerKStateTokens?: number;
     };
     /**
      * What a `decide` provider can read. Absent means the provider leaves size

package/dist/types/proxy.d.ts

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

package/dist/types/span.d.ts

@@ -141,8 +141,24 @@ export type SpanAttributes = {
 export type SpanEvent = {
     name: string;
     timestamp: string;
+    /** When the event happened as nanoseconds since the Unix epoch (decimal string); finer than `timestamp`. */
+    timestampUnixNano?: string;
     attributes?: Record<string, unknown>;
 };
+/**
+ * Instrumentation scope that created a span
+ */
+export type SpanScope = {
+    name: string;
+    version?: string;
+};
+/**
+ * The fields an OpenTelemetry SDK 1.x span exposes where 2.x uses `parentSpanContext` and `instrumentationScope`
+ */
+export type LegacyReadableSpan = {
+    parentSpanId?: string;
+    instrumentationLibrary?: SpanScope;
+};
 /**
  * Link to related span
  */
@@ -169,8 +185,18 @@ export type SpanData = {
     startTime: string;
     /** End timestamp (ISO 8601) */
     endTime?: string;
+    /** Start as nanoseconds since the Unix epoch (decimal string); finer than `startTime` */
+    startTimeUnixNano?: string;
+    /** End as nanoseconds since the Unix epoch (decimal string); finer than `endTime` */
+    endTimeUnixNano?: string;
     /** Duration in milliseconds */
     durationMs?: number;
+    /** OpenTelemetry span kind: 0 internal, 1 server, 2 client, 3 producer, 4 consumer */
+    kind?: number;
+    /** Attributes of the resource that produced the span, such as `service.name` */
+    resource?: SpanAttributes;
+    /** Instrumentation scope that created the span */
+    scope?: SpanScope;
     /** Span status */
     status: SpanStatus;
     /** Status message (for errors) */

package/dist/utils/decisionAnswers.d.ts

@@ -7,7 +7,7 @@
  *
  * @module utils/decisionAnswers
  */
-import type { DecisionAnswerMap, DecisionBooleanGate, DecisionChoiceReading, DecisionQuestion, DecisionResult, DecisionScoreReading, ProviderDescriptor } from "../types/index.js";
+import type { DecisionAnswerMap, DecisionBooleanGate, DecisionChoiceReading, DecisionQuestion, DecisionResult, DecisionScoreReading, DecisionValueReading, ProviderDescriptor } from "../types/index.js";
 /**
  * Read a yes/no answer as a probability.
  *
@@ -24,6 +24,12 @@ export declare function readDecisionBoolean(answers: DecisionAnswerMap, id: stri
  */
 export declare function readDecisionChoice(answers: DecisionAnswerMap, id: string): DecisionChoiceReading | undefined;
 export declare function readDecisionScore(answers: DecisionAnswerMap, id: string): DecisionScoreReading | undefined;
+/**
+ * Read an extracted value. `value` is null and `unknown` true when the model
+ * found nothing to extract, which is an answer, not a missing one: undefined
+ * still means the id is absent or the answer was another type.
+ */
+export declare function readDecisionValue(answers: DecisionAnswerMap, id: string): DecisionValueReading | undefined;
 /**
  * A yes/no answer carries no confidence of its own, so certainty has to be
  * inferred from how far the probability sits from a coin flip. 0.5 → 0, and

package/dist/utils/decisionAnswers.js

@@ -34,7 +34,13 @@ export function readDecisionChoice(answers, id) {
     const ranked = Object.entries(probabilities)
         .map(([name, probability]) => ({ name, probability }))
         .sort((a, b) => b.probability - a.probability);
-    return { choice, confidence, probabilities, ranked };
+    return {
+        choice,
+        confidence,
+        probabilities,
+        ranked,
+        unknown: answer.unknown === true,
+    };
 }
 export function readDecisionScore(answers, id) {
     const answer = answers[id];
@@ -44,6 +50,22 @@ export function readDecisionScore(answers, id) {
     const { score, confidence, legend, probabilities } = answer;
     return { score, confidence, legend, probabilities };
 }
+/**
+ * Read an extracted value. `value` is null and `unknown` true when the model
+ * found nothing to extract, which is an answer, not a missing one: undefined
+ * still means the id is absent or the answer was another type.
+ */
+export function readDecisionValue(answers, id) {
+    const answer = answers[id];
+    if (answer?.type !== "value") {
+        return undefined;
+    }
+    return {
+        value: answer.value,
+        confidence: answer.confidence,
+        unknown: answer.unknown === true || answer.value === null,
+    };
+}
 /**
  * A yes/no answer carries no confidence of its own, so certainty has to be
  * inferred from how far the probability sits from a coin flip. 0.5 → 0, and
@@ -136,6 +158,15 @@ export function stripHostAnswers(result, hostIdByWireId) {
     return { ...result, answers };
 }
 const isRecordValue = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+function compilesAsRegex(pattern) {
+    try {
+        new RegExp(pattern);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 /**
  * Whether `value` is something a decision model accepts as content: a
  * string, number or boolean, or an array or plain object of the same.
@@ -198,7 +229,17 @@ function isWellFormedDecisionQuestion(value) {
         case "choice":
             return (isRecordValue(value.criteria) &&
                 Object.keys(value.criteria).length >= 2 &&
-                Object.values(value.criteria).every((rubric) => rubric === null || isDecisionInput(rubric)));
+                Object.values(value.criteria).every((rubric) => rubric === null || isDecisionInput(rubric)) &&
+                (value.unknown === undefined || typeof value.unknown === "boolean"));
+        case "value":
+            return ((value.dtype === undefined ||
+                value.dtype === "string" ||
+                value.dtype === "int" ||
+                value.dtype === "float") &&
+                (value.pattern === undefined ||
+                    (typeof value.pattern === "string" &&
+                        value.pattern.length > 0 &&
+                        compilesAsRegex(value.pattern))));
         case "score":
             return (Array.isArray(value.criteria) &&
                 value.criteria.length >= 2 &&

package/dist/utils/decisionLimits.d.ts

@@ -11,7 +11,7 @@
  *
  * @module utils/decisionLimits
  */
-import type { DecisionLimits, DecisionLimitsReading, DecisionState, ProviderDescriptor } from "../types/index.js";
+import type { DecisionLimits, DecisionLimitsReading, DecisionQuestion, DecisionQuestionType, DecisionState, ProviderDescriptor } from "../types/index.js";
 /**
  * Estimate how many tokens a decision model will read from `state`.
  *
@@ -37,3 +37,15 @@ export declare function estimateDecisionStateTokens(state: DecisionState, limits
  * limits.
  */
 export declare function resolveDecisionLimitsReading(descriptor: Pick<ProviderDescriptor, "name" | "decisionLimits">, model: string): DecisionLimitsReading | null;
+/** What a provider reads when its limits list no `questionTypes`. */
+export declare const DEFAULT_DECISION_QUESTION_TYPES: readonly DecisionQuestionType[];
+/** The type a question needs a provider to read; a `choice` with `unknown` on needs `choice-unknown`. */
+export declare function decisionQuestionTypeOf(question: DecisionQuestion): DecisionQuestionType;
+/**
+ * Why a provider with these limits cannot be asked `question`, or undefined
+ * when it can. Applies whether or not the limits are advisory: a question type
+ * the server does not know is refused outright, never answered from a guess.
+ * `limits` is null for a provider that declares no limits at all, which reads
+ * the default types and has no per-question caps.
+ */
+export declare function unsupportedDecisionQuestion(question: DecisionQuestion, limits: Pick<DecisionLimitsReading, "questionTypes" | "maxScoreLevels" | "maxChoiceOptions"> | null): string | undefined;

package/dist/utils/decisionLimits.js

@@ -94,10 +94,19 @@ export function resolveDecisionLimitsReading(descriptor, model) {
         model,
         maxStateTokens: modelLimits?.maxStateTokens ?? limits.maxStateTokens,
         // Absent for a provider that caps by tokens or bytes rather than by
-        // question count (TypeSafe, XOR).
+        // question count (TypeSafe).
         ...(limits.maxQuestions !== undefined
             ? { maxQuestions: limits.maxQuestions }
             : {}),
+        ...(limits.questionTypes !== undefined
+            ? { questionTypes: [...limits.questionTypes] }
+            : {}),
+        ...(limits.maxScoreLevels !== undefined
+            ? { maxScoreLevels: limits.maxScoreLevels }
+            : {}),
+        ...(limits.maxChoiceOptions !== undefined
+            ? { maxChoiceOptions: limits.maxChoiceOptions }
+            : {}),
         ...(nonAsciiTokensPerChar !== undefined ? { nonAsciiTokensPerChar } : {}),
         // Not model-overridable — `models` only carries `maxStateTokens` and
         // `nonAsciiTokensPerChar` — so these three come from the base limits only.
@@ -114,3 +123,45 @@ export function resolveDecisionLimitsReading(descriptor, model) {
         enforcedLocally: limits.advisory !== true,
     };
 }
+/** What a provider reads when its limits list no `questionTypes`. */
+export const DEFAULT_DECISION_QUESTION_TYPES = ["boolean", "choice", "score"];
+/** The type a question needs a provider to read; a `choice` with `unknown` on needs `choice-unknown`. */
+export function decisionQuestionTypeOf(question) {
+    return question.type === "choice" && question.unknown === true
+        ? "choice-unknown"
+        : question.type;
+}
+/**
+ * Why a provider with these limits cannot be asked `question`, or undefined
+ * when it can. Applies whether or not the limits are advisory: a question type
+ * the server does not know is refused outright, never answered from a guess.
+ * `limits` is null for a provider that declares no limits at all, which reads
+ * the default types and has no per-question caps.
+ */
+export function unsupportedDecisionQuestion(question, limits) {
+    const types = limits?.questionTypes ?? DEFAULT_DECISION_QUESTION_TYPES;
+    const type = decisionQuestionTypeOf(question);
+    if (!types.includes(type)) {
+        return type === "choice-unknown"
+            ? "a choice with unknown: true is not accepted"
+            : `the question type "${type}" is not accepted (accepted: ${types.join(", ")})`;
+    }
+    if (question.type === "choice") {
+        const keys = Object.keys(question.criteria);
+        if (question.unknown === true && keys.includes("unknown")) {
+            return 'a choice with unknown: true cannot also name an option "unknown"';
+        }
+        const options = keys.length + (question.unknown === true ? 1 : 0);
+        const max = limits?.maxChoiceOptions;
+        if (max !== undefined && options > max) {
+            return `a choice may have at most ${max} options${question.unknown === true ? ", counting unknown" : ""}; this one has ${options}`;
+        }
+    }
+    if (question.type === "score") {
+        const max = limits?.maxScoreLevels;
+        if (max !== undefined && question.criteria.length > max) {
+            return `a score may have at most ${max} levels; this one has ${question.criteria.length}`;
+        }
+    }
+    return undefined;
+}

package/dist/utils/decisionMedia.d.ts

@@ -1,9 +1,11 @@
 import type { DecisionMediaLimits, DecisionMediaResult, DecisionMediaSource } from "../types/index.js";
 /**
- * Turn the caller's images and video into `data:` URLs, or say why not.
- * Runs before any request, so every refusal costs nothing and none is retried.
+ * Turn the caller's images and video into `data:` URLs, and an audio clip into
+ * `{ data, format }`, or say why not. Runs before any request, so every
+ * refusal costs nothing and none is retried.
  */
 export declare function prepareDecisionMedia(request: {
     images?: readonly DecisionMediaSource[];
     video?: DecisionMediaSource;
+    audio?: DecisionMediaSource;
 }, limits: DecisionMediaLimits | undefined, vendor: string, alternatives: readonly string[]): Promise<DecisionMediaResult>;