@juspay/neurolink 12.47.13 → 12.48.0

package/dist/types/memory.d.ts

@@ -19,6 +19,9 @@
  *    re-export) keep their original public names — only their definitions
  *    move from `import("@juspay/hippocampus").Foo` to local structural form.
  */
+import type { TokenUsage } from "./analytics.js";
+import type { AdditionalMemoryUser } from "./generate.js";
+import type { NeurolinkCredentials } from "./providers.js";
 export type MemorySqliteStorageConfig = {
     type: "sqlite";
     /** Path to SQLite file. Default: ./data/hippocampus.sqlite */
@@ -56,17 +59,159 @@ export type HippocampusAddOptions = {
     prompt?: string;
     maxWords?: number;
 };
+/**
+ * The exact request shape Hippocampus's condenser sends to `generate()`
+ * (`@juspay/hippocampus` `src/client.ts`, the `neurolink.generate({...})`
+ * call inside `add()`). A full `NeuroLink` instance satisfies this
+ * structurally; so does any host object that can answer a plain text prompt.
+ */
+export type HippocampusCondenserGenerateOptions = {
+    input: {
+        text: string;
+    };
+    provider?: string;
+    model?: string;
+    temperature?: number;
+    disableTools?: boolean;
+};
+/** The only field Hippocampus reads back from the condensation call. */
+export type HippocampusCondenserResult = {
+    content?: string;
+};
+/**
+ * Minimal `generate()`-bearing object Hippocampus can use for condensation
+ * instead of constructing its own bare `new NeuroLink()`.
+ */
+export type HippocampusNeurolinkLike = {
+    generate: (options: HippocampusCondenserGenerateOptions) => Promise<HippocampusCondenserResult>;
+};
+/**
+ * Condenser settings forwarded to Hippocampus.
+ *
+ * `provider` / `model` / `temperature` select the condensation model.
+ * `credentials` and `instance` are read by `@juspay/hippocampus` ≥0.2.0;
+ * the peer floor is 0.2.1, which also substitutes the condensation
+ * placeholders literally (user content containing `$&` no longer corrupts
+ * the prompt). NeuroLink always fills `instance` itself — a dedicated
+ * child instance that carries this instance's `credentials` — unless the
+ * host supplies one, so condensation stops depending on provider keys being
+ * present in `process.env`.
+ */
+export type HippocampusNeurolinkConfig = {
+    provider?: string;
+    model?: string;
+    temperature?: number;
+    /**
+     * Credentials for the condenser's own NeuroLink instance. Defaults to the
+     * parent `new NeuroLink({ credentials })` value.
+     */
+    credentials?: NeurolinkCredentials;
+    /**
+     * Host-managed condenser. When set, NeuroLink does not build a child
+     * instance and passes this object through untouched.
+     */
+    instance?: HippocampusNeurolinkLike;
+};
 /** Constructor config accepted by the Hippocampus class. */
 export type HippocampusConfig = {
     storage?: HippocampusStorageConfig;
     prompt?: string;
-    neurolink?: {
-        provider?: string;
-        model?: string;
-        temperature?: number;
-    };
+    neurolink?: HippocampusNeurolinkConfig;
     maxWords?: number;
 };
+/**
+ * One completed turn as seen by the memory write hooks. `usage`,
+ * `finishReason` and `toolsUsed` are best-effort: the generate path has the
+ * full result, the stream path only knows the provider, the accumulated
+ * text and this request's own stream result's tool names.
+ */
+export type MemoryTurn = {
+    /** The caller's original prompt, before memory context was prepended. */
+    prompt: string;
+    /** The assistant's final text, trimmed. */
+    response: string;
+    /** Primary memory owner — `context.userId`. */
+    userId: string;
+    /** `context.sessionId`, when the call carried one. */
+    sessionId?: string;
+    provider?: string;
+    model?: string;
+    /** Names of tools that ran during the turn. */
+    toolsUsed?: string[];
+    /** Token usage — generate path only. */
+    usage?: TokenUsage;
+    /** Provider finish reason — generate path only. */
+    finishReason?: string;
+};
+/**
+ * Gate that decides whether a turn is written to memory at all. Runs inside
+ * the deferred background write, never on the response path. Returning
+ * `false` skips every `add()` for the turn (primary owner and
+ * `additionalUsers`). A thrown error is logged and treated as `false`.
+ */
+export type MemoryShouldWriteHook = (turn: MemoryTurn) => boolean | Promise<boolean>;
+/**
+ * Transform (or veto) the exact text handed to `Hippocampus.add()`. Receives
+ * the default `"User: …\nAssistant: …"` rendering; return a replacement
+ * string, or `null` to skip the write. A thrown error is logged and the
+ * write is skipped — a missed memory is recoverable, a polluted condensed
+ * summary is not.
+ */
+export type MemoryBeforeStoreHook = (content: string, turn: MemoryTurn) => string | null | Promise<string | null>;
+/**
+ * Write-side hooks accepted both per call (`generate({ memory })` /
+ * `stream({ memory })`) and on the instance
+ * (`conversationMemory.memory`). When both are set for the same hook, the
+ * per-call one wins for that call.
+ */
+export type MemoryWriteHooks = {
+    shouldWrite?: MemoryShouldWriteHook;
+    onBeforeStore?: MemoryBeforeStoreHook;
+};
+/**
+ * Per-call `memory` block shared by `GenerateOptions` and `StreamOptions`.
+ *
+ * Overrides the instance-level memory behaviour for one call. All flags
+ * default to `true` when the instance memory SDK is enabled; when it is
+ * disabled this block has no effect.
+ */
+export type MemoryCallOptions = MemoryWriteHooks & {
+    /** Master toggle for this call. When false, both read and write are skipped. Defaults to true. */
+    enabled?: boolean;
+    /** Whether to read condensed memory and prepend to prompt. Defaults to true. */
+    read?: boolean;
+    /** Whether to write (add/condense) the conversation into memory after completion. Defaults to true. */
+    write?: boolean;
+    /**
+     * Additional users whose memory should be retrieved/stored alongside the primary user.
+     * Each entry can override the condensation prompt and maxWords for that user.
+     * Primary user is still determined by context.userId.
+     */
+    additionalUsers?: AdditionalMemoryUser[];
+    /**
+     * Condensation prompt for the primary owner on this call. Precedence:
+     * per-call > instance `conversationMemory.memory.prompt` > Hippocampus
+     * default. Must contain `{{OLD_MEMORY}}` and `{{NEW_CONTENT}}`; a template
+     * missing either is logged and the instance prompt is used instead. An
+     * empty or whitespace-only string counts as unset.
+     */
+    prompt?: string;
+    /** Max words for the primary owner's condensed memory on this call. */
+    maxWords?: number;
+};
+/** Placeholder names a condensation prompt template can carry. */
+export type CondensationPlaceholder = "OLD_MEMORY" | "NEW_CONTENT" | "MAX_WORDS";
+/**
+ * Result of `validateCondensationPrompt()`. `missing` lists every absent
+ * placeholder; `fatal` is the subset whose absence breaks memory
+ * (`OLD_MEMORY`: each turn overwrites the summary; `NEW_CONTENT`: memory
+ * never grows). A missing `MAX_WORDS` only loses the word cap.
+ */
+export type CondensationPromptValidation = {
+    valid: boolean;
+    missing: CondensationPlaceholder[];
+    fatal: CondensationPlaceholder[];
+};
 /**
  * Subset of the @juspay/hippocampus client surface that NeuroLink core
  * actually calls. Defining this locally lets the initializer / SDK code
@@ -78,13 +223,36 @@ export type HippocampusLike = {
     delete: (ownerId: string) => Promise<void>;
     close: () => Promise<void>;
 };
+/** Builds a Hippocampus-compatible client from the config NeuroLink assembled. */
+export type HippocampusClientFactory = (config: HippocampusConfig) => HippocampusLike;
 /**
- * Consumer-facing memory config. Same shape as before — the `enabled`
- * flag toggles activation while the rest is passed straight through to
- * the Hippocampus constructor when the optional package is installed.
+ * Consumer-facing memory config. The `enabled` flag toggles activation; the
+ * `HippocampusConfig` part is passed to the Hippocampus constructor when the
+ * optional package is installed. The remaining fields are NeuroLink-side and
+ * never reach Hippocampus.
  */
-export type HippocampusMemory = HippocampusConfig & {
+export type HippocampusMemory = HippocampusConfig & MemoryWriteHooks & {
     enabled?: boolean;
+    /**
+     * Host-managed Hippocampus client (or any object with the same
+     * `add/get/delete/close` surface). When set, NeuroLink skips loading and
+     * constructing `@juspay/hippocampus` and uses this instance directly.
+     * `add()` and `get()` are what core calls and must both be functions;
+     * a client missing either disables memory with an `error` log.
+     *
+     * As a factory it receives the `HippocampusConfig` NeuroLink assembled —
+     * including the credentialed condenser under `neurolink.instance` — so a
+     * host can construct its own client (a subclass, a different version, a
+     * test double) from exactly what `new Hippocampus(config)` would get.
+     */
+    client?: HippocampusLike | HippocampusClientFactory;
+    /**
+     * When true, a condensation prompt template (instance `prompt` or
+     * `HC_CONDENSATION_PROMPT`) missing `{{OLD_MEMORY}}` or `{{NEW_CONTENT}}`
+     * makes the constructor throw instead of the default disable-and-log
+     * (at `error`). An empty or whitespace-only template counts as unset.
+     */
+    strictPrompt?: boolean;
 };
 /**
  * Shape of the dynamically-required `@juspay/hippocampus` module surface

package/dist/types/openaiCompatible.d.ts

@@ -1,8 +1,9 @@
-import type { DeferredUsage, NeuroLinkEvents, TypedEventEmitter } from "./common.js";
+import type { DeferredUsage } from "./common.js";
 import type { JSONSchema7 } from "./middleware.js";
 import type { LanguageModelV3, LanguageModelV3CallOptions } from "./middleware.js";
 import type { StreamOptions } from "./stream.js";
 import type { Tool } from "./tools.js";
+import type { StepResult } from "./providers.js";
 export type OpenAICompatChatRole = "system" | "user" | "assistant" | "tool";
 export type OpenAICompatTextContent = {
     type: "text";
@@ -223,6 +224,8 @@ export type ToolExecutionSummaryInternal = {
     error?: string;
     startTime: Date;
     endTime: Date;
+    /** Zero-based loop step that ran this tool, when the loop tracks one. */
+    stepIndex?: number;
 };
 export type StreamLoopArgs = {
     maxSteps: number;
@@ -233,11 +236,16 @@ export type StreamLoopArgs = {
     options: StreamOptions;
     conversation: OpenAICompatChatMessage[];
     openAITools: OpenAICompatChatTool[] | undefined;
-    openAIToolChoice: OpenAICompatToolChoiceWire | undefined;
+    /**
+     * The wire `tool_choice` for one step. A function rather than a value
+     * because a forced choice applies only to the first `toolChoiceSteps`
+     * steps, and a caller's `prepareStep` hook may override it per step;
+     * `steps` is the record of the steps completed so far, handed to that hook.
+     */
+    stepToolChoice: (step: number, steps: StepResult<Record<string, Tool>>[]) => Promise<OpenAICompatToolChoiceWire | undefined>;
     toolsRecord: Record<string, Tool>;
     /** Wire → registered tool-name map when sanitization was needed (see buildWireToolNameMaps). */
     toolNameFromWire?: Map<string, string>;
-    emitter: TypedEventEmitter<NeuroLinkEvents> | undefined;
     toolsUsed: string[];
     toolExecutionSummaries: ToolExecutionSummaryInternal[];
     pushChunk: (chunk: OpenAICompatStreamChunk) => void;

package/dist/types/stream.d.ts

@@ -9,9 +9,10 @@ import type { TokenUsage } from "./analytics.js";
 import type { JsonValue, UnknownRecord } from "./common.js";
 import type { TerminalAgentModeOption, TerminalAgentModeVersion } from "./agentMode.js";
 import type { Content, ImageWithAltText } from "./content.js";
-import type { ChatMessage } from "./conversation.js";
+import type { ChatMessage, ToolReplayMode } from "./conversation.js";
 import type { StreamNoOutputSentinel } from "./noOutputSentinel.js";
-import type { AdditionalMemoryUser, GenerateStopReason, TTSMetadata, ToolExecutionCaptureOptions } from "./generate.js";
+import type { GenerateStopReason, TTSMetadata, ToolExecutionCaptureOptions } from "./generate.js";
+import type { MemoryCallOptions } from "./memory.js";
 import type { AIModelProviderConfig, NeurolinkCredentials } from "./providers.js";
 import type { TTSChunk, TTSOptions, TTSResult } from "./tts.js";
 import type { STTOptions, STTResult } from "./stt.js";
@@ -580,10 +581,18 @@ export type StreamOptions = {
     /**
      * Tool choice configuration for streaming generation.
      * Mirrors generate() so translated/fallback requests can preserve forced tool use.
+     * A forced choice (`"required"` or a named tool) is applied only to the
+     * first `toolChoiceSteps` steps (default 1); see GenerateOptions.toolChoice.
      */
     toolChoice?: ToolChoice<Record<string, Tool>>;
+    /** Leading steps a forced `toolChoice` stays in force (default 1). See GenerateOptions.toolChoiceSteps. */
+    toolChoiceSteps?: number;
+    /** How stored tool steps are replayed into the prompt. See GenerateOptions.replayToolSteps. */
+    replayToolSteps?: ToolReplayMode;
     /**
      * Optional callback that runs before each stream step in a multi-step generation.
+     * Only a returned `toolChoice` is honoured (for that step); `activeTools` is
+     * accepted but ignored. See GenerateOptions.prepareStep.
      */
     prepareStep?: (options: {
         steps: StepResult<Record<string, Tool>>[];
@@ -739,21 +748,9 @@ export type StreamOptions = {
      * Override the global memory SDK behavior for this specific call.
      * All flags default to `true` when the global memory SDK is enabled.
      * If the global memory SDK is disabled, these flags have no effect.
+     * Shared with `GenerateOptions` — see `MemoryCallOptions`.
      */
-    memory?: {
-        /** Master toggle for this call. When false, both read and write are skipped. Defaults to true. */
-        enabled?: boolean;
-        /** Whether to read condensed memory and prepend to prompt. Defaults to true. */
-        read?: boolean;
-        /** Whether to write (add/condense) the conversation into memory after completion. Defaults to true. */
-        write?: boolean;
-        /**
-         * Additional users whose memory should be retrieved/stored alongside the primary user.
-         * Each entry can override the condensation prompt and maxWords for that user.
-         * Primary user is still determined by context.userId.
-         */
-        additionalUsers?: AdditionalMemoryUser[];
-    };
+    memory?: MemoryCallOptions;
     /** PII detection — scans and optionally redacts PII from input before the LLM call. */
     piiDetection?: {
         enabled?: boolean;

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 & {