@juspay/neurolink 12.47.14 → 12.48.0

package/dist/types/stt.d.ts

@@ -51,10 +51,25 @@ export type STTOptions = {
 /**
  * STT result from transcription
  */
+/**
+ * Where a provider's `STTResult.confidence` came from, when it has to say —
+ * Scribe reports a per-word `logprob` on some responses and only a
+ * language-detection probability on others, and a caller reading the number
+ * should know which it is getting. `"none"` means the provider reported no
+ * transcript-level signal at all and the field is 0.
+ */
+export type STTConfidenceSource = "word_logprobs" | "language_probability" | "none";
 export type STTResult = {
     /** Full transcribed text */
     text: string;
-    /** Confidence score (0-1) */
+    /**
+     * Transcript confidence (0-1) — Deepgram's alternative confidence,
+     * Whisper's `exp(avg_logprob)`, Scribe's mean per-word `exp(logprob)`.
+     * Always present: a strict-TS consumer reads it without a guard. A provider
+     * with no transcript-level signal reports 0 and, where it can, says so in
+     * `metadata.confidenceSource` rather than passing off a different number
+     * (a language-detection probability, say) as this one silently.
+     */
     confidence: number;
     /** Detected language code */
     language?: string;
@@ -74,6 +89,8 @@ export type STTResult = {
         provider?: string;
         /** Model used */
         model?: string;
+        /** What `confidence` was derived from, for providers that must choose. */
+        confidenceSource?: STTConfidenceSource;
         /** Additional provider-specific metadata */
         [key: string]: unknown;
     };
@@ -435,6 +452,46 @@ export type ElevenLabsVoice = {
 export type ElevenLabsVoicesResponse = {
     voices: ElevenLabsVoice[];
 };
+/**
+ * Scribe model ids the batch `speech-to-text` endpoint accepts. `scribe_v2`
+ * is the current model and the default; `scribe_v2_medical` is its clinical
+ * fine-tune; `scribe_v1` (and the experimental variant) are deprecated. The
+ * `(string & {})` member keeps the union open so a newly released id can be
+ * used without a cast.
+ */
+export type ElevenLabsSTTModel = "scribe_v2" | "scribe_v2_medical" | "scribe_v1" | "scribe_v1_experimental" | (string & {});
+export type ElevenLabsSTTOptions = STTOptions & {
+    /** Scribe model id. Default `scribe_v2`. */
+    model?: ElevenLabsSTTModel;
+    /**
+     * Annotate non-speech audio events ("(laughter)", "(music)") in the
+     * transcript. ElevenLabs defaults this to true; NeuroLink sends `false` so
+     * the transcript reads as plain speech unless asked otherwise.
+     * @default false
+     */
+    tagAudioEvents?: boolean;
+    /** Per-request timeout in milliseconds. Default 60_000. */
+    timeoutMs?: number;
+    /**
+     * API base URL including the `/v1` prefix. Default
+     * `ELEVENLABS_BASE_URL` or `https://api.elevenlabs.io/v1`.
+     */
+    baseUrl?: string;
+};
+export type ElevenLabsSTTWord = {
+    text: string;
+    start?: number;
+    end?: number;
+    type?: "word" | "spacing" | "audio_event" | string;
+    speaker_id?: string;
+    logprob?: number;
+};
+export type ElevenLabsSTTResponse = {
+    language_code?: string;
+    language_probability?: number;
+    text: string;
+    words?: ElevenLabsSTTWord[];
+};
 export type AzureVoiceInfo = {
     Name: string;
     DisplayName: string;

package/dist/types/tools.d.ts

@@ -358,6 +358,8 @@ export type ToolEventPayload = {
     timestamp?: number;
     duration?: number;
     executionId?: string;
+    /** The model's tool-call id when the loop supplied one, for pairing start/end. */
+    toolCallId?: string;
 };
 /**
  * Tool execution summary for completed executions
@@ -570,3 +572,15 @@ export type BashToolResult = {
     stderr: string;
     error?: string;
 };
+/**
+ * Own property stamped on a tool object whose `execute` already emits one
+ * `tool:start` / `tool:end` pair per execution. It lives on the OBJECT, not
+ * the function: later layers (the execution recorder, discovery) replace
+ * `execute` via `{ ...tool, execute }`, which drops a function-identity check
+ * but carries a symbol-keyed own property along.
+ */
+export declare const TOOL_EVENTS_WRAPPED: unique symbol;
+/** A `Tool` that may carry the {@link TOOL_EVENTS_WRAPPED} marker. */
+export type EventWrappedTool = Tool & {
+    [TOOL_EVENTS_WRAPPED]?: true;
+};

package/dist/types/tools.js

@@ -22,3 +22,11 @@ export function isToolDefinition(value) {
         typeof value.description === "string" &&
         typeof value.execute === "function");
 }
+/**
+ * Own property stamped on a tool object whose `execute` already emits one
+ * `tool:start` / `tool:end` pair per execution. It lives on the OBJECT, not
+ * the function: later layers (the execution recorder, discovery) replace
+ * `execute` via `{ ...tool, execute }`, which drops a function-identity check
+ * but carries a symbol-keyed own property along.
+ */
+export const TOOL_EVENTS_WRAPPED = Symbol.for("neurolink.toolEventsWrapped");

package/dist/types/tts.d.ts

@@ -25,12 +25,80 @@ export type TTSQuality = "standard" | "hd";
  * still surfacing the built-in choices in editor autocomplete.
  */
 export type TTSProviderName = "google-ai" | "vertex" | "openai-tts" | "elevenlabs" | "elevenlabs-tts" | "azure-tts" | "fish-audio" | "sixtydb" | "cartesia" | (string & {});
+/**
+ * What `generate({ tts })` synthesizes.
+ *
+ * - `"direct"` — the input text / prompt itself, with no LLM call. This is
+ *   the default, and what every documented "speak this text" caller relies
+ *   on.
+ * - `"response"` — the model's generated reply, after generation completes.
+ *
+ * `stream()` always synthesizes the streamed response and ignores this.
+ */
+export type TTSSynthesisMode = "direct" | "response";
+/**
+ * Options for {@link prepareTextForSpeech} — the optional cleanup pass that
+ * turns model output (markdown, URLs, emoji) into text a TTS voice can read
+ * aloud. Every default below is what `tts: { sanitize: true }` applies.
+ */
+export type SpeechSanitizeOptions = {
+    /**
+     * Strip markdown syntax: headings, emphasis, inline code, list bullets,
+     * blockquotes, tables (kept as comma-separated rows), links and images
+     * (kept as their text). Fenced code blocks follow `codeBlocks`.
+     * @default true
+     */
+    markdown?: boolean;
+    /**
+     * How fenced code blocks are spoken. `"drop"` removes them entirely,
+     * `"phrase"` replaces each block with `codeBlockPhrase`, `"keep"` strips
+     * only the fence lines and reads the contents. Incremental `stream()`
+     * synthesis always uses `"keep"`: a segment may hold an unterminated fence,
+     * so the block's extent is unknowable per segment.
+     * @default "phrase"
+     */
+    codeBlocks?: "drop" | "phrase" | "keep";
+    /**
+     * Spoken stand-in for a fenced code block when `codeBlocks` is `"phrase"`.
+     * @default "Code block omitted."
+     */
+    codeBlockPhrase?: string;
+    /**
+     * How URLs are spoken. `"hostname"` reduces `https://docs.example.com/a/b`
+     * to `docs.example.com`; `"remove"` drops the URL altogether.
+     * @default "hostname"
+     */
+    urls?: "hostname" | "remove";
+    /**
+     * Remove emoji and pictographs (`\p{Extended_Pictographic}`,
+     * `\p{Emoji_Presentation}`, plus modifiers and joiners).
+     * @default true
+     */
+    emoji?: boolean;
+};
+/** {@link SpeechSanitizeOptions} with every default applied. */
+export type ResolvedSpeechSanitizeOptions = Required<SpeechSanitizeOptions>;
 /**
  * TTS configuration options
  */
 export type TTSOptions = {
     /** Enable TTS output */
     enabled?: boolean;
+    /**
+     * What to synthesize: the input text (`"direct"`, the default) or the
+     * model's reply (`"response"`). An explicit `mode` wins over the legacy
+     * `useAiResponse` flag. Ignored by `stream()`, which always synthesizes the
+     * streamed response.
+     *
+     * @example Speak the model's reply
+     * ```typescript
+     * const result = await neurolink.generate({
+     *   input: { text: "Tell me a joke" },
+     *   tts: { enabled: true, mode: "response" },
+     * });
+     * ```
+     */
+    mode?: TTSSynthesisMode;
     /**
      * Use the AI-generated response for TTS instead of the input text
      *
@@ -41,6 +109,8 @@ export type TTSOptions = {
      * When true: TTS will synthesize the AI-generated response after generation completes
      *
      * @default false
+     * @deprecated Use `mode: "response"` / `mode: "direct"` instead. Still
+     * honoured when `mode` is not set.
      *
      * @example Using input text directly (default)
      * ```typescript
@@ -63,12 +133,37 @@ export type TTSOptions = {
      * ```
      */
     useAiResponse?: boolean;
+    /**
+     * Clean the text before it reaches the voice: strip markdown, reduce URLs
+     * to their hostname, drop emoji. `true` applies the defaults of
+     * {@link SpeechSanitizeOptions}; an object tunes them. Off by default so
+     * existing callers get byte-identical synthesis input. In `stream()` the
+     * pass runs per segment with fenced code kept (fence lines stripped).
+     * @default false
+     */
+    sanitize?: boolean | SpeechSanitizeOptions;
+    /**
+     * Cancels synthesis. A handler that supports it (ElevenLabs) aborts the
+     * request in flight and makes no further retry attempt once this fires.
+     * `generate()` derives one from its own synthesis timeout and the caller's
+     * `abortSignal`, so a handler's retry loop cannot outlive the call that
+     * started it and issue a billable request nobody is waiting for.
+     */
+    signal?: AbortSignal;
     /** Voice identifier (e.g., "en-US-Neural2-C") */
     voice?: string;
     /** Audio format (default: mp3) */
     format?: TTSAudioFormat;
     /** Speaking rate 0.25-4.0 (default: 1.0) */
     speed?: number;
+    /**
+     * BCP-47 language tag (e.g. "en-US", "hi") for providers that accept one.
+     * Provider-specific: ElevenLabs reduces it to the ISO 639-1 primary subtag
+     * (`en-US` → `en`) and forwards it as `language_code` on every model except
+     * `eleven_multilingual_v2`, which rejects the field; Cartesia maps it to
+     * `language`.
+     */
+    language?: string;
     /** Voice pitch adjustment -20.0 to 20.0 semitones (default: 0.0) */
     pitch?: number;
     /** Volume gain in dB -96.0 to 16.0 (default: 0.0) */
@@ -88,6 +183,19 @@ export type TTSOptions = {
      */
     streamingBufferSize?: number;
 };
+/**
+ * Handler-level wall-clock knobs a provider option type may carry (today:
+ * `ElevenLabsTTSOptions`). `generate()`'s outer synthesis timeout is raised to
+ * at least `timeoutMs × (1 + retries)` plus backoff slack — with the handler
+ * defaults (30 s, one retry) standing in for a knob the caller left unset —
+ * so a handler's own retry loop is never cut short from outside.
+ */
+export type TTSHandlerTimeBudget = {
+    /** Per-attempt request timeout in milliseconds (default 30 000; capped at 2³¹−1). */
+    timeoutMs?: number;
+    /** Retries after the first attempt (total attempts = 1 + retries). */
+    retries?: number;
+};
 /**
  * TTS audio result returned from generation
  */

package/dist/types/voice.d.ts

@@ -13,7 +13,7 @@
 export * from "./tts.js";
 export * from "./stt.js";
 export * from "./realtime.js";
-import type { TTSAudioFormat, TTSOptions, TTSResult, TTSVoice } from "./tts.js";
+import type { TTSAudioFormat, TTSHandlerTimeBudget, TTSOptions, TTSResult, TTSVoice } from "./tts.js";
 import type { TTSHandler } from "./common.js";
 import type { STTResult, STTHandler } from "./stt.js";
 import type { RealtimeHandler } from "./realtime.js";
@@ -28,7 +28,7 @@ export type VoiceProviderType = "tts" | "stt" | "realtime";
 /**
  * Voice provider name union type
  */
-export type VoiceProviderName = "google-tts" | "elevenlabs" | "openai-tts" | "sixtydb" | "azure-tts" | "sarvam" | "murf" | "playai" | "speechify" | "cartesia" | "deepgram" | "gladia" | "whisper" | "assemblyai" | "google-stt" | "azure-stt" | "openai-realtime" | "gemini-live";
+export type VoiceProviderName = "google-tts" | "elevenlabs" | "openai-tts" | "sixtydb" | "azure-tts" | "sarvam" | "murf" | "playai" | "speechify" | "cartesia" | "deepgram" | "gladia" | "whisper" | "assemblyai" | "google-stt" | "azure-stt" | "elevenlabs-stt" | "openai-realtime" | "gemini-live";
 /**
  * Base voice provider configuration
  */
@@ -264,13 +264,50 @@ export type AzureTTSOptions = TTSOptions & {
      */
     allowRawSSML?: boolean;
 };
-export type ElevenLabsModel = "eleven_multilingual_v2" | "eleven_turbo_v2_5" | "eleven_turbo_v2" | "eleven_monolingual_v1";
-export type ElevenLabsTTSOptions = TTSOptions & {
+export type ElevenLabsModel = "eleven_multilingual_v2" | "eleven_turbo_v2_5" | "eleven_turbo_v2" | "eleven_flash_v2_5" | "eleven_flash_v2" | "eleven_v3" | "eleven_monolingual_v1";
+/** Opus bitrates (kbps) ElevenLabs accepts on `opus_48000_*`. */
+export type ElevenLabsOpusBitrate = 32 | 64 | 96 | 128 | 192;
+/** MP3 bitrates (kbps) ElevenLabs accepts on `mp3_44100_*`. */
+export type ElevenLabsMp3Bitrate = 32 | 64 | 96 | 128 | 192;
+/**
+ * Every `output_format` value the ElevenLabs text-to-speech endpoint accepts.
+ * There is no `ogg_*` family — Ogg/Opus is `opus_48000_<kbps>`.
+ */
+export type ElevenLabsOutputFormat = "mp3_22050_32" | "mp3_44100_32" | "mp3_44100_64" | "mp3_44100_96" | "mp3_44100_128" | "mp3_44100_192" | "opus_48000_32" | "opus_48000_64" | "opus_48000_96" | "opus_48000_128" | "opus_48000_192" | "pcm_8000" | "pcm_16000" | "pcm_22050" | "pcm_24000" | "pcm_44100" | "pcm_48000" | "ulaw_8000" | "alaw_8000";
+/** The `voice_settings` object on an ElevenLabs synthesis request. */
+export type ElevenLabsVoiceSettings = {
+    stability?: number;
+    similarity_boost?: number;
+    style?: number;
+    use_speaker_boost?: boolean;
+    /** 0.7–1.2; `TTSOptions.speed` is clamped into this range. */
+    speed?: number;
+};
+export type ElevenLabsTTSOptions = TTSOptions & TTSHandlerTimeBudget & {
     model?: ElevenLabsModel;
     stability?: number;
     similarityBoost?: number;
     style?: number;
     useSpeakerBoost?: boolean;
+    /** Bitrate for `format: "ogg" | "opus"` (→ `opus_48000_<kbps>`). Default 64; an unlisted value falls back to it with a warning. */
+    opusBitrate?: ElevenLabsOpusBitrate;
+    /** Bitrate for `format: "mp3"` (→ `mp3_44100_<kbps>`). Default 128; an unlisted value falls back to it with a warning. */
+    mp3Bitrate?: ElevenLabsMp3Bitrate;
+    /**
+     * Language sent as `language_code`, an ISO 639-1 code; a BCP-47 tag is
+     * reduced to its primary subtag (`en-US` → `en`). Sent on every model
+     * except `eleven_multilingual_v2`, which does not accept the field (the
+     * API ignores the code on any other model that cannot enforce it).
+     * Falls back to the generic `TTSOptions.language`.
+     */
+    languageCode?: string;
+    /** Raw `voice_settings` overrides; explicit fields win over the camelCase ones. */
+    voiceSettings?: ElevenLabsVoiceSettings;
+    /**
+     * API base URL including the `/v1` prefix. Default
+     * `ELEVENLABS_BASE_URL` or `https://api.elevenlabs.io/v1`.
+     */
+    baseUrl?: string;
 };
 export type GoogleVoiceType = "Standard" | "WaveNet" | "Neural2" | "Studio" | "Polyglot";
 export type GoogleTTSOptions = TTSOptions & {

package/dist/utils/decisionAnswers.d.ts

@@ -7,7 +7,7 @@
  *
  * @module utils/decisionAnswers
  */
-import type { DecisionAnswerMap, DecisionBooleanGate, DecisionChoiceReading, DecisionScoreReading, ProviderDescriptor } from "../types/index.js";
+import type { DecisionAnswerMap, DecisionBooleanGate, DecisionChoiceReading, DecisionQuestion, DecisionResult, DecisionScoreReading, ProviderDescriptor } from "../types/index.js";
 /**
  * Read a yes/no answer as a probability.
  *
@@ -54,3 +54,33 @@ export declare function gateDecisionBoolean(answers: DecisionAnswerMap, id: stri
  * after any normalisation the wire might apply.
  */
 export declare function decisionKey(namespace: string, index: number): string;
+/** Namespace for questions a host adds through `decisionHooks.extendQuestions`. */
+export declare const HOST_DECISION_NAMESPACE = "host";
+/** Whether a wire id is one the funnel gave a host's question (`host__N`). */
+export declare function isHostDecisionKey(id: string): boolean;
+/**
+ * A validated copy of a question a host handed back from `extendQuestions`,
+ * or undefined when it is malformed or cannot be copied. The wire carries
+ * the copy, never the host's object: a getter, a proxy or a later edit on
+ * the host's side can then reach neither the request nor the answers keyed
+ * on it. A value `structuredClone` refuses (a proxy, a function-valued
+ * field, a throwing getter) is treated as malformed.
+ */
+export declare function snapshotDecisionQuestion(value: unknown): DecisionQuestion | undefined;
+/**
+ * `result` without the answers to a host's namespaced questions — what a
+ * consumer is handed when the funnel's host-facing steps failed after the
+ * wire call had already returned. A null-prototype map, so an own id such
+ * as `__proto__` survives the copy.
+ */
+export declare function stripHostAnswers(result: DecisionResult, hostIdByWireId: ReadonlyMap<string, string>): DecisionResult;
+/**
+ * Runtime check that a value from outside the type system — a host's
+ * `extendQuestions` hook — is a well-formed question, so a malformed one
+ * is dropped on its own rather than failing the whole request that
+ * NeuroLink's own routing depends on.
+ *
+ * A `choice` needs at least two options and a `score` at least two levels;
+ * fewer carries no information, and the servers refuse it anyway.
+ */
+export declare function isDecisionQuestion(value: unknown): value is DecisionQuestion;

package/dist/utils/decisionAnswers.js

@@ -93,3 +93,117 @@ export function gateDecisionBoolean(answers, id, gate) {
 export function decisionKey(namespace, index) {
     return `${namespace}__${index}`;
 }
+/** Namespace for questions a host adds through `decisionHooks.extendQuestions`. */
+export const HOST_DECISION_NAMESPACE = "host";
+/** Whether a wire id is one the funnel gave a host's question (`host__N`). */
+export function isHostDecisionKey(id) {
+    return id.startsWith(`${HOST_DECISION_NAMESPACE}__`);
+}
+/**
+ * A validated copy of a question a host handed back from `extendQuestions`,
+ * or undefined when it is malformed or cannot be copied. The wire carries
+ * the copy, never the host's object: a getter, a proxy or a later edit on
+ * the host's side can then reach neither the request nor the answers keyed
+ * on it. A value `structuredClone` refuses (a proxy, a function-valued
+ * field, a throwing getter) is treated as malformed.
+ */
+export function snapshotDecisionQuestion(value) {
+    let copy;
+    try {
+        copy = structuredClone(value);
+    }
+    catch {
+        return undefined;
+    }
+    return isDecisionQuestion(copy) ? copy : undefined;
+}
+/**
+ * `result` without the answers to a host's namespaced questions — what a
+ * consumer is handed when the funnel's host-facing steps failed after the
+ * wire call had already returned. A null-prototype map, so an own id such
+ * as `__proto__` survives the copy.
+ */
+export function stripHostAnswers(result, hostIdByWireId) {
+    if (hostIdByWireId.size === 0) {
+        return result;
+    }
+    const answers = Object.create(null);
+    for (const [id, answer] of Object.entries(result.answers)) {
+        if (!hostIdByWireId.has(id)) {
+            answers[id] = answer;
+        }
+    }
+    return { ...result, answers };
+}
+const isRecordValue = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/**
+ * Whether `value` is something a decision model accepts as content: a
+ * string, number or boolean, or an array or plain object of the same.
+ * `null` and `undefined` are not — a question with no instructions is
+ * refused by every provider.
+ */
+function isDecisionInput(value) {
+    switch (typeof value) {
+        case "string":
+        case "boolean":
+            return true;
+        case "number":
+            // NaN and ±Infinity serialise to null and would make the provider
+            // reject the whole request, not just this question.
+            return Number.isFinite(value);
+        case "object":
+            if (value === null) {
+                return false;
+            }
+            return Array.isArray(value)
+                ? value.every(isDecisionInput)
+                : Object.values(value).every(isDecisionInput);
+        default:
+            return false;
+    }
+}
+/**
+ * Runtime check that a value from outside the type system — a host's
+ * `extendQuestions` hook — is a well-formed question, so a malformed one
+ * is dropped on its own rather than failing the whole request that
+ * NeuroLink's own routing depends on.
+ *
+ * A `choice` needs at least two options and a `score` at least two levels;
+ * fewer carries no information, and the servers refuse it anyway.
+ */
+export function isDecisionQuestion(value) {
+    try {
+        return isWellFormedDecisionQuestion(value);
+    }
+    catch {
+        // Cyclic or otherwise exotic host input: the walk below can overflow the
+        // stack. That drops this question alone rather than failing the request.
+        return false;
+    }
+}
+function isWellFormedDecisionQuestion(value) {
+    if (!isRecordValue(value) || !isDecisionInput(value.instructions)) {
+        return false;
+    }
+    switch (value.type) {
+        case "boolean": {
+            if (value.criteria === undefined) {
+                return true;
+            }
+            if (!isRecordValue(value.criteria)) {
+                return false;
+            }
+            return Object.values(value.criteria).every((side) => side === null || side === undefined || isDecisionInput(side));
+        }
+        case "choice":
+            return (isRecordValue(value.criteria) &&
+                Object.keys(value.criteria).length >= 2 &&
+                Object.values(value.criteria).every((rubric) => rubric === null || isDecisionInput(rubric)));
+        case "score":
+            return (Array.isArray(value.criteria) &&
+                value.criteria.length >= 2 &&
+                value.criteria.every((level) => level === null || isDecisionInput(level)));
+        default:
+            return false;
+    }
+}

package/dist/utils/decisionLimits.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Decision limits — the one place a provider's `decisionLimits` are read and
+ * a state's size is estimated against them.
+ *
+ * `SystemOneDecisionProvider` refuses an over-limit request through these
+ * functions, and `NeuroLink.decisionLimits()` / `estimateDecisionStateTokens`
+ * expose the same functions to hosts, so what a host measures before the call
+ * is exactly what the pre-flight check measures inside it. Two estimators that
+ * drift apart would let a host size a state as fitting and then watch it be
+ * refused.
+ *
+ * @module utils/decisionLimits
+ */
+import type { DecisionLimits, DecisionLimitsReading, DecisionState, ProviderDescriptor } from "../types/index.js";
+/**
+ * Estimate how many tokens a decision model will read from `state`.
+ *
+ * `estimateTokens` assumes ~4 characters per token. That holds for English
+ * and is several times too generous for other scripts on an English
+ * tokenizer, so when the limits declare a `nonAsciiTokensPerChar` rate,
+ * non-ASCII characters are counted at it instead. Digits, ASCII punctuation
+ * and astral characters (emoji) are each counted separately only when the
+ * limits declare a rate for that class — a tokenizer that reads each digit,
+ * and most punctuation, on its own makes a number-heavy or JSON-heavy state
+ * several times longer than the ~4-characters-per-token estimate suggests. A
+ * non-string state is serialized first, as it is on the wire.
+ *
+ * This is the estimator the pre-flight refusal uses: a state this reports at
+ * or under `maxStateTokens` is sent, one over it is refused before any
+ * network call.
+ */
+export declare function estimateDecisionStateTokens(state: DecisionState, limits?: Pick<DecisionLimits, "nonAsciiTokensPerChar" | "digitTokensPerChar" | "symbolTokensPerChar" | "astralTokensPerChar">): number;
+/**
+ * Flatten a descriptor's `decisionLimits` for one model: the per-model entry
+ * overrides the base, field by field, and `advisory` becomes
+ * `enforcedLocally: false`. Returns null for a descriptor that declares no
+ * limits.
+ */
+export declare function resolveDecisionLimitsReading(descriptor: Pick<ProviderDescriptor, "name" | "decisionLimits">, model: string): DecisionLimitsReading | null;

package/dist/utils/decisionLimits.js

@@ -0,0 +1,116 @@
+/**
+ * Decision limits — the one place a provider's `decisionLimits` are read and
+ * a state's size is estimated against them.
+ *
+ * `SystemOneDecisionProvider` refuses an over-limit request through these
+ * functions, and `NeuroLink.decisionLimits()` / `estimateDecisionStateTokens`
+ * expose the same functions to hosts, so what a host measures before the call
+ * is exactly what the pre-flight check measures inside it. Two estimators that
+ * drift apart would let a host size a state as fitting and then watch it be
+ * refused.
+ *
+ * @module utils/decisionLimits
+ */
+import { CHARS_PER_TOKEN, estimateTokens, serializeForEstimate, } from "./tokenEstimation.js";
+/**
+ * Estimate how many tokens a decision model will read from `state`.
+ *
+ * `estimateTokens` assumes ~4 characters per token. That holds for English
+ * and is several times too generous for other scripts on an English
+ * tokenizer, so when the limits declare a `nonAsciiTokensPerChar` rate,
+ * non-ASCII characters are counted at it instead. Digits, ASCII punctuation
+ * and astral characters (emoji) are each counted separately only when the
+ * limits declare a rate for that class — a tokenizer that reads each digit,
+ * and most punctuation, on its own makes a number-heavy or JSON-heavy state
+ * several times longer than the ~4-characters-per-token estimate suggests. A
+ * non-string state is serialized first, as it is on the wire.
+ *
+ * This is the estimator the pre-flight refusal uses: a state this reports at
+ * or under `maxStateTokens` is sent, one over it is refused before any
+ * network call.
+ */
+export function estimateDecisionStateTokens(state, limits) {
+    const text = serializeForEstimate(state);
+    const nonAsciiTokensPerChar = limits?.nonAsciiTokensPerChar;
+    const digit = limits?.digitTokensPerChar;
+    const symbol = limits?.symbolTokensPerChar;
+    const astral = limits?.astralTokensPerChar;
+    if (nonAsciiTokensPerChar === undefined &&
+        digit === undefined &&
+        symbol === undefined &&
+        astral === undefined) {
+        return estimateTokens(text);
+    }
+    // Each class of character is counted once, at its own rate. A class with no
+    // declared rate stays in the ordinary four-characters-a-token estimate (or,
+    // for non-ASCII, at that estimate's per-character rate), so a provider that
+    // declares none of the extra rates is estimated exactly as before.
+    const isDigit = (c) => c >= "0" && c <= "9";
+    const isSymbol = (c) => /[!-/:-@[-`{-~]/.test(c);
+    let digits = 0;
+    let symbols = 0;
+    let astrals = 0;
+    let nonAscii = 0;
+    const rest = [];
+    for (const c of text) {
+        const code = c.codePointAt(0) ?? 0;
+        if (code > 0xffff && astral !== undefined) {
+            astrals += 1;
+        }
+        else if (code > 0x7f) {
+            nonAscii += 1;
+        }
+        else if (digit !== undefined && isDigit(c)) {
+            digits += 1;
+        }
+        else if (symbol !== undefined && isSymbol(c)) {
+            symbols += 1;
+        }
+        else {
+            rest.push(c);
+        }
+    }
+    return (estimateTokens(rest.join("")) +
+        Math.ceil(digits * (digit ?? 0)) +
+        Math.ceil(symbols * (symbol ?? 0)) +
+        Math.ceil(astrals * (astral ?? 0)) +
+        Math.ceil(nonAscii * (nonAsciiTokensPerChar ?? 1 / CHARS_PER_TOKEN)));
+}
+/**
+ * Flatten a descriptor's `decisionLimits` for one model: the per-model entry
+ * overrides the base, field by field, and `advisory` becomes
+ * `enforcedLocally: false`. Returns null for a descriptor that declares no
+ * limits.
+ */
+export function resolveDecisionLimitsReading(descriptor, model) {
+    const limits = descriptor.decisionLimits;
+    if (!limits) {
+        return null;
+    }
+    const modelLimits = limits.models?.[model];
+    const nonAsciiTokensPerChar = modelLimits?.nonAsciiTokensPerChar ?? limits.nonAsciiTokensPerChar;
+    return {
+        provider: descriptor.name,
+        model,
+        maxStateTokens: modelLimits?.maxStateTokens ?? limits.maxStateTokens,
+        // Absent for a provider that caps by tokens or bytes rather than by
+        // question count (TypeSafe, XOR).
+        ...(limits.maxQuestions !== undefined
+            ? { maxQuestions: limits.maxQuestions }
+            : {}),
+        ...(nonAsciiTokensPerChar !== undefined ? { nonAsciiTokensPerChar } : {}),
+        // Not model-overridable — `models` only carries `maxStateTokens` and
+        // `nonAsciiTokensPerChar` — so these three come from the base limits only.
+        ...(limits.digitTokensPerChar !== undefined
+            ? { digitTokensPerChar: limits.digitTokensPerChar }
+            : {}),
+        ...(limits.symbolTokensPerChar !== undefined
+            ? { symbolTokensPerChar: limits.symbolTokensPerChar }
+            : {}),
+        ...(limits.astralTokensPerChar !== undefined
+            ? { astralTokensPerChar: limits.astralTokensPerChar }
+            : {}),
+        ...(limits.media !== undefined ? { media: limits.media } : {}),
+        enforcedLocally: limits.advisory !== true,
+    };
+}