@juspay/neurolink 12.47.14 → 12.48.1

package/dist/utils/speechText.js

@@ -0,0 +1,364 @@
+/**
+ * Text preparation for speech synthesis.
+ *
+ * Model output is written for a screen: markdown structure, URLs, emoji.
+ * Read aloud, every one of those is noise — "asterisk asterisk", a 90-character
+ * URL spelled letter by letter, "grinning face with smiling eyes". This module
+ * rewrites such text into what a voice should actually say.
+ *
+ * Every regular expression here is linear-time by construction: no nested
+ * quantifiers, no lazy scan to a closing token, and no unbounded greedy class
+ * followed by a required literal (the `[ \t]+\n` shape that goes quadratic on
+ * a long run of spaces). Where a closing token is required, the scan between
+ * the two is bounded AND excludes the opener's own character, so an unclosed
+ * opener fails at the next opener rather than walking the bound — a run of
+ * `[` costs one step per character, not one thousand. Block-level structure
+ * (fenced code, lists, tables, headings, blockquotes) is a line pass that
+ * toggles state, so an unterminated fence costs one scan rather than a
+ * backtracking search.
+ *
+ * @module utils/speechText
+ */
+// A namespace import, not a named one: the browser bundle replaces every
+// `node:` module with a fixed stub that has no `domainToUnicode`, and a named
+// import of a missing export fails that build. `hostnameOf` checks for the
+// function at runtime and falls back to the punycode form.
+import * as nodeUrl from "node:url";
+const DEFAULT_CODE_BLOCK_PHRASE = "Code block omitted.";
+/** A fence opener/closer: up to three spaces of indent, then ``` or ~~~. */
+const FENCE_LINE = /^[ \t]{0,3}(?:`{3,}|~{3,})/;
+/** ATX heading marker: `#` to `######` followed by whitespace. */
+const HEADING_MARKER = /^[ \t]{0,3}#{1,6}[ \t]+/;
+/** A line made only of `=`, `-`, `*`, `_` and spaces (setext underline or thematic break). */
+const RULE_LINE = /^[ \t]{0,3}[=\-*_][=\-*_ \t]*$/;
+/** A line made only of pipes, dashes, colons and spaces (table separator row). */
+const TABLE_SEPARATOR_CHARS = /^[|:\- \t]+$/;
+/** Unordered list bullet. */
+const BULLET_MARKER = /^([ \t]*)[-*+][ \t]+/;
+/** Ordered list marker (`1.` / `1)`), bounded to nine digits. */
+const ORDERED_MARKER = /^([ \t]*)\d{1,9}[.)][ \t]+/;
+/** Task-list checkbox left after a bullet is stripped. */
+const TASK_CHECKBOX = /^\[[ xX]\][ \t]+/;
+/** One level of blockquote. */
+const BLOCKQUOTE_MARKER = /^[ \t]{0,3}>[ \t]?/;
+// Inline constructs need a closing token. The span between opener and closer
+// is bounded so an unclosed opener never scans to the end of the document.
+// The bound alone is not enough: a label class that admits the opener's own
+// character makes every `[` in a run of `[` walk the full bound before it
+// fails, which is linear with a constant of LINK_TEXT_MAX — 2.6 s per
+// megabyte of `[`. Excluding the opener from the class makes the failure
+// immediate, so a run of openers costs one step each.
+const LINK_TEXT_MAX = 1000;
+const LINK_TARGET_MAX = 2048;
+const CODE_SPAN_MAX = 1000;
+const TAG_BODY_MAX = 500;
+const EMPHASIS_SPAN_MAX = 1000;
+/** Inline image: `![alt](src)` → alt. */
+const INLINE_IMAGE = new RegExp(`!\\[([^\\][\\n]{0,${LINK_TEXT_MAX}})\\]\\([^)[\\n]{0,${LINK_TARGET_MAX}}\\)`, "g");
+/** Inline link: `[text](href)` → text. */
+const INLINE_LINK = new RegExp(`\\[([^\\][\\n]{0,${LINK_TEXT_MAX}})\\]\\([^)[\\n]{0,${LINK_TARGET_MAX}}\\)`, "g");
+/** Reference link: `[text][ref]` → text. */
+const REFERENCE_LINK = new RegExp(`\\[([^\\][\\n]{0,${LINK_TEXT_MAX}})\\]\\[[^\\][\\n]{0,${LINK_TEXT_MAX}}\\]`, "g");
+/**
+ * Autolink: `<https://…>` → the bare URL, so the URL pass sees it. The target
+ * class excludes `<` for the same reason the link classes exclude `[`: an
+ * unterminated `<http://` used to walk the full target bound before failing,
+ * which made 1 MB of them cost ~380 ms instead of under 1 ms.
+ */
+const AUTOLINK = new RegExp(`<(https?://[^<>\\s]{1,${LINK_TARGET_MAX}})>`, "g");
+/** Inline code span: the backticks go, the contents stay. */
+const INLINE_CODE = new RegExp("`{1,3}([^`\\n]{0," + CODE_SPAN_MAX + "})`{1,3}", "g");
+/**
+ * An HTML tag, opening or closing — but only a tag whose name is HTML. Model
+ * output uses angle brackets for placeholders (`<Enter>`, `<order-id>`),
+ * generics (`Map<string, T>`) and comparisons (`x<y and y>z`), and none of
+ * those may be swallowed: the word inside is usually the instruction.
+ */
+const HTML_TAG_NAMES = "p|br|b|i|u|em|strong|a|span|div|code|pre|ul|ol|li|h[1-6]|img|table|thead|tbody|tr|td|th|blockquote|hr|sup|sub|small|mark|del|ins|s";
+const HTML_TAG = new RegExp(`</?(?:${HTML_TAG_NAMES})(?=[\\s/>])[^<>\\n]{0,${TAG_BODY_MAX}}>`, "gi");
+/** Strikethrough markers abutting text. */
+const STRIKETHROUGH = /~~(?=\S)|(?<=\S)~~/g;
+// Emphasis is a PAIR: an opening run preceded by the start of the text,
+// whitespace, punctuation or a symbol and followed by a non-space, then a
+// closing run preceded by a non-space and followed by the end, whitespace,
+// punctuation or a symbol. A `*` between two digits (`2*3*4`, `*123*1#`)
+// satisfies neither side and is left alone — the old "any run touching a
+// non-space" rule spoke `2*3*4 = 24` as "234 = 24". The span between the
+// runs excludes the delimiter, so an unpaired opener fails at the next
+// delimiter instead of scanning to the bound.
+//
+// The boundary classes are Unicode: `\p{P}` and `\p{S}` rather than a list
+// of ASCII brackets and sentence marks. An ASCII list left `**` in Hindi
+// (`**भुगतान सफल रहा**।` — the closer sits before a danda), Chinese
+// (`**总结**：` — a full-width colon), curly quotes (`“**Quoted**”`) and
+// before an em dash (`**Fast**—and`); for a voice assistant those are the
+// common cases, not the edge ones. The delimiter is itself punctuation, so
+// it is excluded from its own boundary: without that, `x**2 + y**2` read the
+// second `*` of each run as an opener/closer and became `x*2 + y*2`.
+//
+// Han, Hiragana, Katakana and Hangul also count as a boundary: those scripts
+// have no spaces between words, so `**` glued straight to surrounding CJK
+// text (`这是**重点**内容`, not `这是 **重点** 内容`) is the normal way it is
+// written, not an edge case — without this, that `**` had neither side
+// satisfy the boundary and was spoken aloud as asterisks.
+const EMPHASIS_BOUNDARY = "\\s\\p{White_Space}\\p{P}\\p{S}\\p{Script=Han}\\p{Script=Hiragana}\\p{Script=Katakana}\\p{Script=Hangul}";
+function emphasisPattern(delimiter) {
+    const openBefore = `(?<![^${EMPHASIS_BOUNDARY}]|${delimiter})`;
+    const closeAfter = `(?![^${EMPHASIS_BOUNDARY}]|${delimiter})`;
+    const run = `${delimiter}{1,3}`;
+    const span = `([^${delimiter}\\n]{1,${EMPHASIS_SPAN_MAX}}?)`;
+    return new RegExp(`${openBefore}${run}(?=[^\\s${delimiter}])${span}(?<=\\S)${run}${closeAfter}`, "gu");
+}
+const EMPHASIS_ASTERISK = emphasisPattern("\\*");
+const EMPHASIS_UNDERSCORE = emphasisPattern("_");
+/** `**bold *and italic* inside**`: each pass peels one level, so nesting needs more than one. */
+const EMPHASIS_PASSES = 3;
+// Backslash escapes must be resolved BEFORE the emphasis and link passes —
+// `\*not bold\*` is literal asterisks, not emphasis — and the resolved
+// character must then survive those passes. Each escapable character is
+// swapped for a sentinel first and swapped back last. The sentinels are
+// Unicode noncharacters (U+FDD0–U+FDEF), which are reserved for exactly this
+// process-internal use and never occur in interchanged text; any that do
+// arrive are dropped so they cannot masquerade as an escape.
+const ESCAPABLE_PUNCTUATION = "\\`*_{}[]()#+-.!|>~<";
+const ESCAPED_PUNCTUATION = /\\([\\`*_{}[\]()#+\-.!|>~<])/g;
+const ESCAPE_SENTINEL_BASE = 0xfdd0;
+const ESCAPE_SENTINELS = /[﷐-﷯]/g;
+/** An absolute http(s) URL, as one unbroken token. */
+const HTTP_URL = /https?:\/\/[^\s<>()[\]"']+/gi;
+/** A bare `www.` host with optional path. */
+const WWW_URL = /\bwww\.[^\s<>()[\]"']+/gi;
+const TRAILING_PUNCTUATION = new Set([".", ",", ";", ":", "!", "?"]);
+// One pictograph with the modifiers, variation selectors and keycap combiner
+// that may trail it, then any number of further pictographs joined to it by
+// U+200D. The whole sequence goes as one unit so a joined family or a
+// skin-toned hand leaves nothing behind. The joiner is consumed ONLY here,
+// between or beside pictographs: U+200D is also a letter-shaping control in
+// Devanagari, Malayalam, Arabic and others, and stripping it everywhere
+// changed the shape and pronunciation of ordinary Indic text.
+const PICTOGRAPH = "(?:\\p{Extended_Pictographic}|\\p{Emoji_Presentation})(?:\\p{Emoji_Modifier}|\\uFE0E|\\uFE0F|\\u20E3)*";
+const EMOJI = new RegExp(`\\u200D?${PICTOGRAPH}(?:\\u200D${PICTOGRAPH})*\\u200D?`, "gu");
+/** Skin-tone modifiers, variation selectors and the keycap combiner left over after a bare digit or symbol. */
+const EMOJI_JOINERS = /\p{Emoji_Modifier}|\uFE0E|\uFE0F|\u20E3/gu;
+/** An `http`/`https` scheme, matched case-insensitively (RFC 3986 \u00A73.1). */
+const HTTP_SCHEME = /^https?:\/\//i;
+const LINE_BREAKS = /\r\n?/g;
+/** Runs of two or more horizontal spaces; nothing is required after the run. */
+const HORIZONTAL_RUNS = /[ \t]{2,}/g;
+/** Applied only after HORIZONTAL_RUNS, when no run is longer than one character. */
+const SPACE_BEFORE_NEWLINE = /[ \t]\n/g;
+const SPACE_AFTER_NEWLINE = /\n[ \t]/g;
+const BLANK_LINE_RUNS = /\n{3,}/g;
+function resolveOptions(opts) {
+    return {
+        markdown: opts?.markdown ?? true,
+        codeBlocks: opts?.codeBlocks ?? "phrase",
+        codeBlockPhrase: opts?.codeBlockPhrase ?? DEFAULT_CODE_BLOCK_PHRASE,
+        urls: opts?.urls ?? "hostname",
+        emoji: opts?.emoji ?? true,
+    };
+}
+/**
+ * Resolve a `TTSOptions.sanitize` value into options, or `undefined` when the
+ * pass is off. `true` means the defaults; an object tunes them.
+ */
+export function resolveSpeechSanitizeOptions(sanitize) {
+    if (sanitize === undefined || sanitize === false) {
+        return undefined;
+    }
+    return sanitize === true ? {} : sanitize;
+}
+function isRuleLine(line) {
+    if (!RULE_LINE.test(line)) {
+        return false;
+    }
+    let markers = 0;
+    for (const ch of line) {
+        if (ch === "=" || ch === "-" || ch === "*" || ch === "_") {
+            markers += 1;
+        }
+    }
+    return markers >= 3;
+}
+function isTableSeparator(line) {
+    return line.includes("---") && TABLE_SEPARATOR_CHARS.test(line);
+}
+function isTableRow(line) {
+    const trimmed = line.trim();
+    return trimmed.startsWith("|") || trimmed.endsWith("|");
+}
+/** `| a | b |` → `a, b`. Split on the pipe and trim each cell — no regex over the padding. */
+function flattenTableRow(line) {
+    const cells = [];
+    for (const cell of line.split("|")) {
+        const trimmed = cell.trim();
+        if (trimmed.length > 0) {
+            cells.push(trimmed);
+        }
+    }
+    return cells.join(", ");
+}
+function stripBlockquote(line) {
+    let current = line;
+    for (;;) {
+        const next = current.replace(BLOCKQUOTE_MARKER, "");
+        if (next === current) {
+            return current;
+        }
+        current = next;
+    }
+}
+/**
+ * One pass over the lines: fenced code per `codeBlocks`, then the per-line
+ * block markers (headings, rules, bullets, blockquotes, tables).
+ */
+function stripBlockMarkdown(text, options) {
+    const out = [];
+    let inFence = false;
+    for (const line of text.split("\n")) {
+        if (FENCE_LINE.test(line)) {
+            if (options.codeBlocks === "keep") {
+                // Streaming: the block's extent is unknowable per segment, so only
+                // the fence line itself is dropped and the contents are spoken.
+                continue;
+            }
+            if (!inFence) {
+                inFence = true;
+                if (options.codeBlocks === "phrase") {
+                    out.push(options.codeBlockPhrase);
+                }
+            }
+            else {
+                inFence = false;
+            }
+            continue;
+        }
+        if (inFence) {
+            continue;
+        }
+        if (isRuleLine(line) || isTableSeparator(line)) {
+            continue;
+        }
+        let current = stripBlockquote(line);
+        current = current.replace(HEADING_MARKER, "");
+        current = current.replace(BULLET_MARKER, "$1");
+        current = current.replace(ORDERED_MARKER, "$1");
+        current = current.replace(TASK_CHECKBOX, "");
+        if (isTableRow(current)) {
+            current = flattenTableRow(current);
+        }
+        out.push(current);
+    }
+    return out.join("\n");
+}
+/** `\*` → sentinel, so the character it protects is invisible to the passes that follow. */
+function protectEscapes(text) {
+    return text
+        .replace(ESCAPE_SENTINELS, "")
+        .replace(ESCAPED_PUNCTUATION, (_match, ch) => String.fromCharCode(ESCAPE_SENTINEL_BASE + ESCAPABLE_PUNCTUATION.indexOf(ch)));
+}
+/** Sentinel → the literal character `\*` stood for. */
+function restoreEscapes(text) {
+    return text.replace(ESCAPE_SENTINELS, (sentinel) => ESCAPABLE_PUNCTUATION[sentinel.charCodeAt(0) - ESCAPE_SENTINEL_BASE] ??
+        "");
+}
+function stripEmphasis(text) {
+    let current = text;
+    for (let pass = 0; pass < EMPHASIS_PASSES; pass++) {
+        const next = current
+            .replace(EMPHASIS_ASTERISK, "$1")
+            .replace(EMPHASIS_UNDERSCORE, "$1");
+        if (next === current) {
+            break;
+        }
+        current = next;
+    }
+    return current;
+}
+function stripInlineMarkdown(text) {
+    const stripped = protectEscapes(text)
+        .replace(INLINE_IMAGE, "$1")
+        .replace(INLINE_LINK, "$1")
+        .replace(REFERENCE_LINK, "$1")
+        .replace(AUTOLINK, "$1")
+        .replace(INLINE_CODE, "$1")
+        .replace(HTML_TAG, " ")
+        .replace(STRIKETHROUGH, "");
+    return restoreEscapes(stripEmphasis(stripped));
+}
+/** Split a URL token into the URL proper and the sentence punctuation glued to its end. */
+function splitTrailingPunctuation(token) {
+    let end = token.length;
+    while (end > 0 && TRAILING_PUNCTUATION.has(token[end - 1] ?? "")) {
+        end -= 1;
+    }
+    return { url: token.slice(0, end), trailing: token.slice(end) };
+}
+/**
+ * The host a URL should be spoken as. `URL.hostname` is the punycode form
+ * (`xn--mnchen-3ya.example`), which a voice spells letter by letter; Node's
+ * `domainToUnicode` gives back `münchen.example`. The scheme test is
+ * case-insensitive because `HTTP_URL` is: `HTTPS://Example.COM/x` used to
+ * fail a case-sensitive `startsWith("http")`, get a second scheme prepended,
+ * and be spoken as "https".
+ */
+function hostnameOf(url) {
+    const withScheme = HTTP_SCHEME.test(url) ? url : `https://${url}`;
+    try {
+        const host = new URL(withScheme).hostname;
+        return typeof nodeUrl.domainToUnicode === "function"
+            ? nodeUrl.domainToUnicode(host)
+            : host;
+    }
+    catch {
+        return "";
+    }
+}
+function rewriteUrls(text, mode) {
+    const replacer = (match) => {
+        const { url, trailing } = splitTrailingPunctuation(match);
+        if (mode === "remove") {
+            return trailing;
+        }
+        const host = hostnameOf(url);
+        return host ? `${host}${trailing}` : trailing;
+    };
+    return text.replace(HTTP_URL, replacer).replace(WWW_URL, replacer);
+}
+function removeEmoji(text) {
+    return text.replace(EMOJI, "").replace(EMOJI_JOINERS, "");
+}
+function collapseWhitespace(text) {
+    return text
+        .replace(HORIZONTAL_RUNS, " ")
+        .replace(SPACE_BEFORE_NEWLINE, "\n")
+        .replace(SPACE_AFTER_NEWLINE, "\n")
+        .replace(BLANK_LINE_RUNS, "\n\n")
+        .trim();
+}
+/**
+ * Rewrite `text` into what a TTS voice should say.
+ *
+ * Pure and deterministic: the same input and options always yield the same
+ * output, and nothing here reads the environment. Runs in time linear in the
+ * length of `text`.
+ *
+ * @example
+ * ```typescript
+ * prepareTextForSpeech("## Title\n\nSee **this** at https://docs.example.com/x 🎉");
+ * // → "Title\n\nSee this at docs.example.com"
+ * ```
+ */
+export function prepareTextForSpeech(text, opts) {
+    const options = resolveOptions(opts);
+    let out = text.replace(LINE_BREAKS, "\n");
+    if (options.markdown) {
+        out = stripBlockMarkdown(out, options);
+        out = stripInlineMarkdown(out);
+    }
+    out = rewriteUrls(out, options.urls);
+    if (options.emoji) {
+        out = removeEmoji(out);
+    }
+    return collapseWhitespace(out);
+}

package/dist/utils/toolResultStatus.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Classification of a tool result that the loop received as a normal return
+ * but that reports a failure in-band.
+ *
+ * `neurolink.executeTool` converts a thrown error and a circuit-breaker
+ * refusal into `{ isError: true, content: [...] }`, MCP servers return the
+ * same shape for a failed call, and the documented custom-tool pattern is
+ * `return { error: "User not found" }`. Every consumer that decides "did this
+ * tool succeed" — the `tool:end` event, the stored `tool_result` row, the
+ * replayed marker, and `toolExecutions[].isError` — has to read those shapes
+ * the same way, so the rule lives in ONE predicate, `isErrorShapedToolResult`,
+ * and this module only extracts the text to report for it.
+ */
+/**
+ * The error text carried by an error-shaped result (`isError: true`, an
+ * `error` field, or a failing `status`), or undefined when the value is not
+ * one. Prefers an `error` string, then a serialized non-string `error`, then
+ * the joined text parts of an MCP `content` array, then a fixed fallback.
+ */
+export declare function extractIsErrorText(output: unknown): string | undefined;
+/**
+ * Same classification for a serialized result: the memory stores keep
+ * `tool_result.content` as a JSON string, so a row written before the store
+ * learned to flag error shapes can still be recognised at replay.
+ */
+export declare function extractIsErrorTextFromContent(content: unknown): string | undefined;

package/dist/utils/toolResultStatus.js

@@ -0,0 +1,73 @@
+/**
+ * Classification of a tool result that the loop received as a normal return
+ * but that reports a failure in-band.
+ *
+ * `neurolink.executeTool` converts a thrown error and a circuit-breaker
+ * refusal into `{ isError: true, content: [...] }`, MCP servers return the
+ * same shape for a failed call, and the documented custom-tool pattern is
+ * `return { error: "User not found" }`. Every consumer that decides "did this
+ * tool succeed" — the `tool:end` event, the stored `tool_result` row, the
+ * replayed marker, and `toolExecutions[].isError` — has to read those shapes
+ * the same way, so the rule lives in ONE predicate, `isErrorShapedToolResult`,
+ * and this module only extracts the text to report for it.
+ */
+import { isErrorShapedToolResult, isMeaningfulError, } from "../core/toolExecutionRecorder.js";
+const ISERROR_FALLBACK_TEXT = "Tool returned isError: true";
+const ERROR_SHAPE_FALLBACK_TEXT = "Tool reported an error";
+/**
+ * The error text carried by an error-shaped result (`isError: true`, an
+ * `error` field, or a failing `status`), or undefined when the value is not
+ * one. Prefers an `error` string, then a serialized non-string `error`, then
+ * the joined text parts of an MCP `content` array, then a fixed fallback.
+ */
+export function extractIsErrorText(output) {
+    if (!isErrorShapedToolResult(output)) {
+        return undefined;
+    }
+    const record = output;
+    if (typeof record.error === "string" && record.error.length > 0) {
+        return record.error;
+    }
+    if (record.error !== true && isMeaningfulError(record.error)) {
+        try {
+            return JSON.stringify(record.error) ?? String(record.error);
+        }
+        catch {
+            return String(record.error);
+        }
+    }
+    if (Array.isArray(record.content)) {
+        const texts = record.content
+            .filter((c) => c && c.type === "text" && typeof c.text === "string")
+            .map((c) => c.text);
+        if (texts.length > 0) {
+            return texts.join(" ");
+        }
+    }
+    return record.isError === true
+        ? ISERROR_FALLBACK_TEXT
+        : ERROR_SHAPE_FALLBACK_TEXT;
+}
+/**
+ * Same classification for a serialized result: the memory stores keep
+ * `tool_result.content` as a JSON string, so a row written before the store
+ * learned to flag error shapes can still be recognised at replay.
+ */
+export function extractIsErrorTextFromContent(content) {
+    if (typeof content !== "string") {
+        return extractIsErrorText(content);
+    }
+    const trimmed = content.trim();
+    if (!trimmed.startsWith("{") ||
+        !(trimmed.includes('"isError"') ||
+            trimmed.includes('"error"') ||
+            trimmed.includes('"status"'))) {
+        return undefined;
+    }
+    try {
+        return extractIsErrorText(JSON.parse(trimmed));
+    }
+    catch {
+        return undefined;
+    }
+}

package/dist/utils/ttsProcessor.d.ts

@@ -20,6 +20,28 @@ export declare const TTS_ERROR_CODES: {
     readonly SYNTHESIS_FAILED: "TTS_SYNTHESIS_FAILED";
     readonly INVALID_INPUT: "TTS_INVALID_INPUT";
 };
+/**
+ * The wall-clock a handler may legitimately spend on one `synthesize()` call:
+ * `timeoutMs × (1 + retries)` plus pause slack (see `TTSHandlerTimeBudget`).
+ * A knob the caller did not set takes the handler default — 30 s per attempt
+ * and one retry — so the budget is always a number. It used to be `undefined`
+ * when neither knob was set, which left the outer synthesis timeout at the
+ * provider's own value: with the 60 s provider default, a first attempt that
+ * hung to its 30 s abort left no room for the documented default retry, and
+ * the caller got a timeout error instead of the retried audio.
+ *
+ * Used by `BaseProvider`'s generate() TTS paths so the outer `withTimeoutFn`
+ * never undercuts the handler's own retry loop.
+ *
+ * `provider` is the name the synthesis will actually be dispatched to —
+ * `tts.provider`, falling back to the request's or the instance's provider —
+ * not just `options.provider`: a caller that reaches ElevenLabs through the
+ * outer provider and leaves `tts.provider` unset got a budget of 0, and the
+ * outer timeout cut the handler's documented default retry. The registry
+ * resolves names case-insensitively, so this check does too; `"ElevenLabs"`
+ * found the handler but not the budget.
+ */
+export declare function resolveTTSHandlerBudgetMs(options: TTSOptions, provider?: string): number;
 /** Internal signal raised after all buffered segments have been attempted. */
 export declare class IncrementalTTSSynthesisError extends Error {
     readonly firstError: unknown;
@@ -74,6 +96,13 @@ export declare class TTSProcessor {
      * @private
      */
     private static readonly DEFAULT_MAX_TEXT_LENGTH;
+    /**
+     * The text cap `synthesize()` enforces for `providerName`: the handler's
+     * `maxTextLength`, or the default when the handler declares none or is not
+     * registered. Lets a caller bound work it does BEFORE synthesis — the
+     * sanitize pass in `BaseProvider` — to text that could ever be accepted.
+     */
+    static maxTextLengthFor(providerName: string): number;
     /**
      * Register a TTS handler for a specific provider
      *

package/dist/utils/ttsProcessor.js

@@ -8,6 +8,7 @@
  */
 import { logger } from "./logger.js";
 import { VALID_AUDIO_FORMATS } from "../types/index.js";
+import { prepareTextForSpeech, resolveSpeechSanitizeOptions, } from "./speechText.js";
 import { ErrorCategory, ErrorSeverity } from "../constants/enums.js";
 import { NeuroLinkError } from "./errorHandling.js";
 import { HandlerRegistry } from "../core/handlerRegistry.js";
@@ -26,6 +27,62 @@ export const TTS_ERROR_CODES = {
 };
 const DEFAULT_STREAMING_BUFFER_SIZE = 120;
 const SENTENCE_BOUNDARY = /[.!?]+(?:["')\]]+)?(?=\s|$)/g;
+/**
+ * Slack added to a handler's declared time budget for the pauses its retry
+ * loop takes between attempts (Retry-After is capped at 10 s per pause).
+ */
+const HANDLER_RETRY_PAUSE_SLACK_MS = 10_000;
+/** The handler defaults the budget assumes when the caller set no knobs (ElevenLabs: 30 s, one retry). */
+const HANDLER_DEFAULT_TIMEOUT_MS = 30_000;
+const HANDLER_DEFAULT_RETRIES = 1;
+/** Handlers with a built-in retry loop, i.e. the ones the defaults describe. */
+const RETRYING_TTS_PROVIDERS = new Set([
+    "elevenlabs",
+    "elevenlabs-tts",
+]);
+/** Largest delay `setTimeout` honours; anything above fires at once. */
+const MAX_TIMER_MS = 2_147_483_647;
+/**
+ * The wall-clock a handler may legitimately spend on one `synthesize()` call:
+ * `timeoutMs × (1 + retries)` plus pause slack (see `TTSHandlerTimeBudget`).
+ * A knob the caller did not set takes the handler default — 30 s per attempt
+ * and one retry — so the budget is always a number. It used to be `undefined`
+ * when neither knob was set, which left the outer synthesis timeout at the
+ * provider's own value: with the 60 s provider default, a first attempt that
+ * hung to its 30 s abort left no room for the documented default retry, and
+ * the caller got a timeout error instead of the retried audio.
+ *
+ * Used by `BaseProvider`'s generate() TTS paths so the outer `withTimeoutFn`
+ * never undercuts the handler's own retry loop.
+ *
+ * `provider` is the name the synthesis will actually be dispatched to —
+ * `tts.provider`, falling back to the request's or the instance's provider —
+ * not just `options.provider`: a caller that reaches ElevenLabs through the
+ * outer provider and leaves `tts.provider` unset got a budget of 0, and the
+ * outer timeout cut the handler's documented default retry. The registry
+ * resolves names case-insensitively, so this check does too; `"ElevenLabs"`
+ * found the handler but not the budget.
+ */
+export function resolveTTSHandlerBudgetMs(options, provider) {
+    const { timeoutMs, retries } = options;
+    const hasTimeout = typeof timeoutMs === "number" &&
+        Number.isFinite(timeoutMs) &&
+        timeoutMs > 0;
+    const hasRetries = typeof retries === "number" && Number.isInteger(retries) && retries >= 0;
+    const resolvedProvider = String(provider ?? options.provider ?? "").toLowerCase();
+    // The defaults describe a retry loop. Only a handler that has one gets a
+    // default budget; for every other provider (Google, OpenAI, Azure,
+    // Cartesia — one attempt, no knobs) the budget is 0 so the caller's own
+    // `timeout` stays the bound instead of being raised to ~70 s.
+    if (!hasTimeout &&
+        !hasRetries &&
+        !RETRYING_TTS_PROVIDERS.has(resolvedProvider)) {
+        return 0;
+    }
+    const perAttempt = Math.min(hasTimeout ? timeoutMs : HANDLER_DEFAULT_TIMEOUT_MS, MAX_TIMER_MS);
+    const attempts = 1 + (hasRetries ? retries : HANDLER_DEFAULT_RETRIES);
+    return Math.min(perAttempt * attempts + (attempts - 1) * HANDLER_RETRY_PAUSE_SLACK_MS, MAX_TIMER_MS);
+}
 /** Internal signal raised after all buffered segments have been attempted. */
 export class IncrementalTTSSynthesisError extends Error {
     firstError;
@@ -247,6 +304,16 @@ export class TTSProcessor {
      * @private
      */
     static DEFAULT_MAX_TEXT_LENGTH = 3000;
+    /**
+     * The text cap `synthesize()` enforces for `providerName`: the handler's
+     * `maxTextLength`, or the default when the handler declares none or is not
+     * registered. Lets a caller bound work it does BEFORE synthesis — the
+     * sanitize pass in `BaseProvider` — to text that could ever be accepted.
+     */
+    static maxTextLengthFor(providerName) {
+        return (this.getHandler(providerName)?.maxTextLength ??
+            this.DEFAULT_MAX_TEXT_LENGTH);
+    }
     /**
      * Register a TTS handler for a specific provider
      *
@@ -779,6 +846,13 @@ export class TTSProcessor {
             const maxTextLength = Math.max(1, handler?.maxTextLength ?? processor.DEFAULT_MAX_TEXT_LENGTH);
             const requestedBoundary = options.streamingBufferSize ?? DEFAULT_STREAMING_BUFFER_SIZE;
             const flushBoundary = Math.min(Math.max(1, Math.trunc(requestedBoundary)), maxTextLength);
+            // Per-segment cleanup when `tts.sanitize` is on. A segment may hold an
+            // unterminated fence, so code blocks are always kept (fence lines
+            // stripped, contents spoken) regardless of the caller's `codeBlocks`.
+            const sanitizeOptions = resolveSpeechSanitizeOptions(options.sanitize);
+            const segmentSanitize = sanitizeOptions
+                ? { ...sanitizeOptions, codeBlocks: "keep" }
+                : undefined;
             let buffer = "";
             let chunkIndex = 0;
             let cumulativeSize = 0;
@@ -920,8 +994,8 @@ export class TTSProcessor {
             };
             try {
                 while (!stopped()) {
-                    const segment = takeSegment();
-                    if (segment === undefined) {
+                    const rawSegment = takeSegment();
+                    if (rawSegment === undefined) {
                         if (inputComplete) {
                             break;
                         }
@@ -935,6 +1009,14 @@ export class TTSProcessor {
                         }
                         continue;
                     }
+                    const segment = segmentSanitize
+                        ? prepareTextForSpeech(rawSegment, segmentSanitize)
+                        : rawSegment;
+                    // A segment that was only markup (a fence line, a table separator,
+                    // a bare heading marker) has nothing to say; it is not a failure.
+                    if (segment.length === 0) {
+                        continue;
+                    }
                     const currentSegment = ++segmentNumber;
                     // NOTHING BELOW MAY `yield` INSIDE A `try` THAT HAS A `catch`.
                     // A consumer can resume this generator with `AsyncGenerator.throw()`

package/dist/voice/index.d.ts

@@ -32,6 +32,7 @@ export { FishAudioTTS, FishAudioTTS as FishAudioTTSHandler, } from "./providers/
 export { OpenAITTS, OpenAITTS as OpenAITTSHandler, } from "./providers/OpenAITTS.js";
 export { AzureSTT, AzureSTT as AzureSTTHandler } from "./providers/AzureSTT.js";
 export { DeepgramSTT, DeepgramSTT as DeepgramSTTHandler, } from "./providers/DeepgramSTT.js";
+export { ElevenLabsSTT, ElevenLabsSTT as ElevenLabsSTTHandler, } from "./providers/ElevenLabsSTT.js";
 export { GoogleSTT, GoogleSTT as GoogleSTTHandler, } from "./providers/GoogleSTT.js";
 export { OpenAISTT, OpenAISTTHandler, WhisperSTT, WhisperSTTHandler, } from "./providers/OpenAISTT.js";
 export { GeminiLive, GeminiLive as GeminiLiveHandler, } from "./providers/GeminiLive.js";

package/dist/voice/index.js

@@ -61,6 +61,7 @@ export { OpenAITTS, OpenAITTS as OpenAITTSHandler, } from "./providers/OpenAITTS
 // ============================================================================
 export { AzureSTT, AzureSTT as AzureSTTHandler } from "./providers/AzureSTT.js";
 export { DeepgramSTT, DeepgramSTT as DeepgramSTTHandler, } from "./providers/DeepgramSTT.js";
+export { ElevenLabsSTT, ElevenLabsSTT as ElevenLabsSTTHandler, } from "./providers/ElevenLabsSTT.js";
 export { GoogleSTT, GoogleSTT as GoogleSTTHandler, } from "./providers/GoogleSTT.js";
 export { OpenAISTT, OpenAISTTHandler, WhisperSTT, WhisperSTTHandler, } from "./providers/OpenAISTT.js";
 // ============================================================================
@@ -79,6 +80,7 @@ import { SixtyDBTTS } from "./providers/SixtyDBTTS.js";
 import { OpenAITTS } from "./providers/OpenAITTS.js";
 import { AzureSTT } from "./providers/AzureSTT.js";
 import { DeepgramSTT } from "./providers/DeepgramSTT.js";
+import { ElevenLabsSTT } from "./providers/ElevenLabsSTT.js";
 import { GoogleSTT } from "./providers/GoogleSTT.js";
 import { OpenAISTT } from "./providers/OpenAISTT.js";
 import { GeminiLive } from "./providers/GeminiLive.js";
@@ -107,6 +109,7 @@ const STT_HANDLER_FACTORIES = {
     deepgram: () => new DeepgramSTT(),
     "google-stt": () => new GoogleSTT(),
     "azure-stt": () => new AzureSTT(),
+    "elevenlabs-stt": () => new ElevenLabsSTT(),
 };
 const STT_HANDLER_CANDIDATES = MEDIA_HANDLER_CATALOG.filter((entry) => entry.kind === "stt").map((entry) => {
     const factory = STT_HANDLER_FACTORIES[entry.name];