@moureau/pipeflow 0.0.1 → 0.0.3

package/dist/types/providers/llm/adapters/openai-compatible.d.ts

@@ -0,0 +1,44 @@
+import type { LLMEvent, LLMRequest, LLMStreamTimingCallback, LLMUsageCallback, ToolMode } from "../types.js";
+import type { FetchLike } from "../../shared.js";
+export interface OpenAICompatibleStreamParams {
+    /** Provider base URL, e.g. `https://openrouter.ai/api/v1`. */
+    baseUrl: string;
+    apiKey: string;
+    model: string;
+    /** Injectable fetch implementation, mainly for tests. */
+    fetchImpl: FetchLike;
+    request: LLMRequest;
+    signal: AbortSignal;
+    /** Extra headers merged into the request (e.g. attribution headers). */
+    extraHeaders?: Record<string, string>;
+    /** Extra body fields merged after the standard ones. */
+    extraBody?: Record<string, unknown>;
+    /** Provider name used in error messages. */
+    label: string;
+    /** Optional provider-timeline hook (see `LLMStreamTimingPoint`). */
+    onTiming?: LLMStreamTimingCallback;
+    /**
+     * Default tool encoding for requests that do not set `toolMode`
+     * themselves (the request's `toolMode` wins when present). Useful for
+     * models whose endpoints lack native tool calling.
+     */
+    toolMode?: ToolMode;
+    /**
+     * Abort the stream if no data arrives for this long (default 8000ms).
+     * Protects against providers whose connection goes silent after the model
+     * has already produced its output (e.g. a tool call that is never followed
+     * by a terminating frame).
+     */
+    idleTimeoutMs?: number;
+    /**
+     * Called with the provider-reported token usage when the stream includes
+     * it (OpenRouter sends usage in the final chunk).
+     */
+    onUsage?: LLMUsageCallback;
+}
+/**
+ * Stream a request through any OpenAI-compatible `/chat/completions`
+ * endpoint, reassembling fragmented tool calls and normalizing the SSE
+ * stream into `LLMEvent`s. Shared by the DeepSeek and OpenRouter adapters.
+ */
+export declare function openAICompatibleStream(params: OpenAICompatibleStreamParams): AsyncGenerator<LLMEvent>;

package/dist/types/providers/llm/adapters/openrouter/index.d.ts

@@ -0,0 +1,2 @@
+export { OpenRouterLLM } from "./openrouter.js";
+export type { OpenRouterOptions } from "./openrouter.js";

package/dist/types/providers/llm/adapters/openrouter/openrouter.d.ts

@@ -0,0 +1,60 @@
+import type { FavoriteModel, LLM, LLMEvent, LLMRequest, LLMStreamTimingCallback, LLMUsageCallback, ToolMode } from "../../types.js";
+import type { FetchLike } from "../../../shared.js";
+export interface OpenRouterOptions {
+    apiKey: string;
+    /**
+     * Any model hosted on OpenRouter, e.g. `anthropic/claude-sonnet-4`.
+     * Defaults to `openrouter/auto`, which routes the request to the best
+     * available model for its shape. The measured `FAVORITE_MODELS`
+     * autocomplete; any model id is accepted.
+     */
+    model?: FavoriteModel;
+    /** Defaults to `https://openrouter.ai/api/v1`. */
+    baseUrl?: string;
+    /**
+     * The site that credits the app on OpenRouter's leaderboard via
+     * `HTTP-Referer`. Defaults to `https://moureau.dev`.
+     */
+    appUrl?: string;
+    /** Injectable fetch implementation, mainly for tests. */
+    fetch?: FetchLike;
+    /** Provider-timeline hook: request-start / headers / first-chunk. */
+    onTiming?: LLMStreamTimingCallback;
+    /**
+     * Abort a stream that delivers no data for this long (default 8000ms) —
+     * protects against provider connections that go silent after the model
+     * already produced its output. Raise it for providers with slow TTFT.
+     */
+    idleTimeoutMs?: number;
+    /** Called with the provider-reported token usage (when included). */
+    onUsage?: LLMUsageCallback;
+    /**
+     * Default tool encoding for requests that don't set `toolMode` (the
+     * request's `toolMode` wins). For models whose endpoints lack native tool
+     * calling — e.g. `sao10k/l3-lunaris-8b` -> `"envelope"`.
+     */
+    toolMode?: ToolMode;
+}
+/**
+ * OpenRouter LLM adapter (OpenAI-compatible chat completions over SSE).
+ *
+ * OpenRouter is a gateway: one API key and one wire format for hundreds of
+ * models from different vendors, so this adapter is a thin wrapper around
+ * the shared OpenAI-compatible streaming engine.
+ */
+export declare class OpenRouterLLM implements LLM {
+    private readonly apiKey;
+    private readonly model;
+    private readonly baseUrl;
+    private readonly appUrl;
+    private readonly fetchImpl;
+    private readonly onTiming;
+    private readonly idleTimeoutMs;
+    private readonly onUsage;
+    private readonly toolMode;
+    private readonly streams;
+    constructor(options: OpenRouterOptions);
+    /** Cancel every in-flight stream (parallel sub-generations included). */
+    stop(): void;
+    stream(request: LLMRequest): AsyncGenerator<LLMEvent>;
+}

package/dist/types/providers/llm/index.d.ts

@@ -1,5 +1,6 @@
 import type { LLM, LLMRequest } from "./types.js";
-export type { LLM, LLMEvent, LLMMessage, LLMRole, LLMToolCall, LLMToolDefinition, LLMRequest, } from "./types.js";
+export type { FavoriteModel, LLM, LLMEvent, LLMMessage, LLMRole, LLMToolCall, LLMToolDefinition, LLMRequest, StringOr, } from "./types.js";
+export { FAVORITE_MODELS } from "./types.js";
 /**
  * Stream only the text deltas of an LLM generation, rethrowing any
  * streamed error.
@@ -7,4 +8,6 @@ export type { LLM, LLMEvent, LLMMessage, LLMRole, LLMToolCall, LLMToolDefinition
 export declare function streamText(llm: LLM, request: LLMRequest): AsyncGenerator<string>;
 /** Collect an entire LLM generation into a single string. */
 export declare function complete(llm: LLM, request: LLMRequest): Promise<string>;
-export { DeepSeekLLM } from "./adapters/index.js";
+export { ClaudeLLM, DeepSeekLLM, OpenAILLM, OpenRouterLLM } from "./adapters/index.js";
+export { ToolModeBenchmark } from "./toolmode.js";
+export type { ToolModeBenchmarkOptions, ToolModeBenchmarkResult, ToolModeBenchmarkRun, ToolModeReportEntry, ToolModeTiming, } from "./toolmode.js";

package/dist/types/providers/llm/toolmode/index.d.ts

@@ -0,0 +1,2 @@
+export { ToolModeBenchmark } from "./toolmode.js";
+export type { ToolModeBenchmarkOptions, ToolModeBenchmarkResult, ToolModeBenchmarkRun, ToolModeReportEntry, ToolModeTiming, } from "./toolmode.js";

package/dist/types/providers/llm/toolmode/toolmode.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Tool-mode benchmark: measures availability, latency (percentiles), and cost
+ * of each tool-call encoding (`native` | `envelope` | `prompted`) for a
+ * model, through the real adapter path (`llm.stream({ toolMode })`). A
+ * diagnostic utility for onboarding models — the runtime never calls it.
+ *
+ * ```ts
+ * const bench = new ToolModeBenchmark({ apiKey, model: "..." });
+ * const { fastest, cheapest, report } = await bench.run();
+ * console.log(report.envelope.time.p50);
+ * ```
+ */
+import { z } from "zod";
+import type { FetchLike } from "../../shared.js";
+import type { LLMMessage, LLMToolDefinition, ToolMode } from "../types.js";
+export interface ToolModeBenchmarkOptions {
+    apiKey: string;
+    model: string;
+    /** Override the OpenRouter base URL. */
+    baseUrl?: string;
+    /** Runs per mode (default 3). */
+    runs?: number;
+    /** Probe messages (default: a weather question). */
+    messages?: LLMMessage[];
+    /** Probe tool (default: get_weather). */
+    tools?: LLMToolDefinition[];
+    /**
+     * Validates each emitted tool call's arguments to count `correct` runs — a
+     * call that succeeds with garbage arguments (e.g. `{ "city": "?" }`) is a
+     * failed decision. Defaults to the weather probe's schema.
+     */
+    correctnessSchema?: z.ZodType;
+    /** Injectable fetch implementation, mainly for tests. */
+    fetch?: FetchLike;
+}
+export interface ToolModeBenchmarkRun {
+    /** ms to the tool call (decision latency), or to stream end when none. */
+    latencyMs?: number;
+    toolCall: boolean;
+    /** Every emitted call's arguments parsed cleanly and validated. */
+    correct?: boolean;
+    prompt?: number;
+    completion?: number;
+    error?: string;
+}
+/** Latency percentiles over the runs that produced a tool call. */
+export interface ToolModeTiming {
+    p50: number;
+    p95: number;
+    p99: number;
+}
+export interface ToolModeReportEntry {
+    /** Median cost ($) per decision over runs with provider usage. */
+    cost?: number;
+    /** Decision-latency percentiles; absent when no run emitted a tool call. */
+    time?: ToolModeTiming;
+    /** How many runs produced a tool call. */
+    toolCalls: number;
+    /**
+     * How many runs emitted only schema-valid calls (undefined when no
+     * `correctnessSchema` was provided).
+     */
+    correct: number | undefined;
+    /** Cost per decision that was actually correct: `cost / (correct / runs)`. */
+    effectiveCost?: number;
+    /** How many runs failed outright (transport, envelope parse, …). */
+    errors: number;
+    /** The first run's error, when every run failed. */
+    error?: string;
+    /** Raw per-run rows, for diagnostics. */
+    runs: ToolModeBenchmarkRun[];
+}
+export interface ToolModeBenchmarkResult {
+    model: string;
+    /** Prompt/completion prices ($/token) from the registry, when available. */
+    pricing: {
+        in: number;
+        out: number;
+    } | undefined;
+    report: Record<ToolMode, ToolModeReportEntry>;
+    /** Fastest mode that actually emitted a tool call. */
+    fastest: ToolMode | null;
+    /** Cheapest mode that actually emitted a tool call. */
+    cheapest: ToolMode | null;
+}
+export declare class ToolModeBenchmark {
+    private readonly apiKey;
+    private readonly model;
+    private readonly baseUrl;
+    private readonly runs;
+    private readonly messages;
+    private readonly tools;
+    private readonly correctnessSchema;
+    private readonly fetchImpl;
+    constructor(options: ToolModeBenchmarkOptions);
+    /** Benchmark every mode and return the structured report. */
+    run(): Promise<ToolModeBenchmarkResult>;
+    private benchmarkMode;
+}

package/dist/types/providers/llm/types.d.ts

@@ -21,15 +21,80 @@ export interface LLMToolDefinition {
     /** JSON schema describing the tool arguments. */
     parameters: Record<string, unknown>;
 }
+/**
+ * How tool calls are encoded on the wire. The semantic contract is the same
+ * in every mode — callers still pass `tools` and consume `tool_call` events —
+ * only the encoding differs. The right mode is a property of the model's
+ * endpoints, not the caller: use `ToolModeBenchmark` to measure a model and
+ * set the mode once at adapter construction.
+ *
+ * - `native` (default) — the provider's tool-calling contract: `tools` in
+ *   the request, `tool_calls` in the stream. Streaming deltas and
+ *   provider-enforced argument schemas, at the price of wire overhead: the
+ *   provider expands the schema into its native tool format, which bills
+ *   measurably more prompt tokens (often 5-10x the cost of the modes below).
+ * - `envelope` — no `tools`; `response_format` forces the model to emit a
+ *   JSON envelope (`{ answer?, calls: [{ name, arguments }] }`) that the
+ *   adapter translates back into `tool_call` events. Endpoint-guaranteed
+ *   JSON and a lean prompt (dramatically cheaper per decision), but nothing
+ *   is actionable until the whole envelope arrives — no streaming deltas.
+ *   Only for endpoints that support structured outputs.
+ * - `prompted` — no `tools`; the same envelope is requested by appending an
+ *   instruction to the last user message. The universal fallback: works on
+ *   any chat model, at the cost of extraction/repair/retry, higher token
+ *   use, and tail-latency risk. Because nothing constrains the output, a
+ *   model that ignores the envelope and replies in plain prose is answered
+ *   directly — its text is treated as the reply rather than failing the
+ *   generation.
+ */
+export type ToolMode = "native" | "envelope" | "prompted";
+/**
+ * A string that may also be one of the branded literal values — e.g. any
+ * model id, with the favorites offered for autocomplete. The `& {}` on the
+ * string side stops TypeScript from absorbing the literals into `string`
+ * (the reverse arrangement — `string | (T & {})` — collapses and loses the
+ * literals).
+ */
+export type StringOr<T extends string> = T | (string & {});
+/** Models measured as usable; offered for autocomplete where a model id is taken. */
+export declare const FAVORITE_MODELS: readonly ["meta-llama/llama-4-scout", "google/gemini-2.5-flash-lite", "amazon/nova-micro-v1", "amazon/nova-lite-v1", "inclusionai/ling-3.0-flash", "sao10k/l3-lunaris-8b", "openai/gpt-oss-20b"];
+/** Any model id, with the favorites offered for autocomplete. */
+export type FavoriteModel = StringOr<(typeof FAVORITE_MODELS)[number]>;
 export interface LLMRequest {
     messages: LLMMessage[];
     tools?: LLMToolDefinition[];
     temperature?: number;
     maxTokens?: number;
+    /** How tools are encoded on the wire. Default `native`. */
+    toolMode?: ToolMode;
+}
+/**
+ * Moments in the provider round trip that separate application delay from
+ * network/queue delay from model latency. The callback is invoked
+ * synchronously at each point, so `performance.now()` taken inside it is the
+ * event time.
+ *
+ * - `request-start` — immediately before the HTTP request is issued.
+ * - `headers` — the response headers arrived (2xx).
+ * - `first-chunk` — the first SSE chunk was parsed.
+ */
+export type LLMStreamTimingPoint = "request-start" | "headers" | "first-chunk";
+export type LLMStreamTimingCallback = (point: LLMStreamTimingPoint) => void;
+/** Token usage reported by the provider (when it includes usage in the stream). */
+export interface LLMUsage {
+    promptTokens: number;
+    completionTokens: number;
 }
+export type LLMUsageCallback = (usage: LLMUsage) => void;
 export type LLMEvent = {
     type: "delta";
     content: string;
+    /**
+     * Reasoning/thinking tokens, when the provider streams them separately
+     * from content (OpenRouter `reasoning`, DeepSeek `reasoning_content`).
+     * Omitted when the model does not emit reasoning.
+     */
+    reasoning?: string;
 } | {
     type: "tool_call";
     id: string;

package/dist/types/providers/stt/adapters/deepgram/deepgram.d.ts

@@ -13,7 +13,10 @@ export interface STTSocket {
 }
 export interface DeepgramOptions extends STTOptions {
     apiKey: string;
-    /** Defaults to `wss://api.deepgram.com/v1/listen`. */
+    /**
+     * Overrides the listen endpoint. Defaults to `wss://api.deepgram.com/v2/listen`
+     * for Flux models (`flux-*`) and `wss://api.deepgram.com/v1/listen` otherwise.
+     */
     endpoint?: string;
     /** Injectable socket factory, mainly for tests. */
     createSocket?: (url: string) => STTSocket;

package/dist/types/providers/stt/adapters/index.d.ts

@@ -1 +1,2 @@
 export { DeepgramSTT } from "./deepgram/deepgram.js";
+export { OpenRouterSTT } from "./openrouter/openrouter.js";

package/dist/types/providers/stt/adapters/openrouter/index.d.ts

@@ -0,0 +1,2 @@
+export { OpenRouterSTT, OpenRouterSession, toWav } from "./openrouter.js";
+export type { OpenRouterAudioFormat, OpenRouterSTTOptions } from "./openrouter.js";

package/dist/types/providers/stt/adapters/openrouter/openrouter.d.ts

@@ -0,0 +1,196 @@
+import type { STT, STTOptions, STTSession } from "../../types.js";
+import type { FetchLike } from "../../../shared.js";
+/** Audio formats the OpenRouter transcription endpoint accepts. */
+export type OpenRouterAudioFormat = "pcm" | "mp3" | "flac" | "m4a" | "ogg" | "webm" | "aac";
+export interface OpenRouterSTTOptions extends STTOptions {
+    apiKey: string;
+    /** Defaults to `https://openrouter.ai/api/v1`. */
+    baseUrl?: string;
+    /** The STT model. Defaults to `openai/whisper-large-v3-turbo`. */
+    model?: string;
+    /**
+     * Silence (ms) that ends an utterance. OpenRouter's transcription endpoint
+     * is batch-only (one request per audio clip), so the adapter segments the
+     * incoming stream client-side and transcribes a clip once this much silence
+     * has elapsed since the last audio. Default 800.
+     */
+    silenceMs?: number;
+    /**
+     * Format of the audio written to the session. `"pcm"` (the default)
+     * assumes raw linear16 samples at `sampleRate` and wraps each clip in a
+     * WAV container. Pass the actual encoding (e.g. `"mp3"`, `"ogg"`, …) when
+     * feeding pre-encoded audio — those formats are self-describing and are
+     * sent as-is.
+     */
+    audioFormat?: OpenRouterAudioFormat;
+    /**
+     * Strip common whisper hallucinations from transcripts: asterisk stage
+     * directions ("*Dramatic music*"), repeated filler phrases ("Thank you.
+     * Thank you."), and pure-filler clips whisper emits on near-silence
+     * ("Thank you.", "E aí.", "Bye.", …). Set `false` to pass transcripts
+     * through untouched. Default `true`.
+     */
+    filterHallucinations?: boolean;
+    /**
+     * Extra phrases (lowercased) treated as hallucinations on top of the
+     * built-in multilingual filler list — for fillers whisper "hears" in the
+     * languages you deploy. A transcript that is *entirely* built from known
+     * fillers is dropped. Default none.
+     */
+    fillerPhrases?: string[];
+    /**
+     * Energy floor (0–1 RMS, on the raw sample range) for transcribing a
+     * buffered `pcm` clip. Near-silence clips — the ones whisper hallucinates
+     * "E aí." / "Thank you." / *stage directions* on — are skipped entirely
+     * (no transcription request, no `final`), instead of being filtered after
+     * the fact. Real speech sits far above any reasonable floor; start around
+     * `0.01`–`0.02` and raise it if artifacts persist. Only applies to
+     * `audioFormat: "pcm"` (the only format whose samples are measurable).
+     * Default: no floor (transcribe everything the client sends).
+     */
+    minClipRms?: number;
+    /**
+     * Called for every buffered `pcm` clip with its measured mean RMS and
+     * whether it was transcribed — for logging the real distribution and
+     * tuning `minClipRms` against it (speech clips sit far above artifact
+     * clips). Fires when this callback or `minClipRms` is set.
+     */
+    onClipEnergy?: (rms: number, transcribed: boolean) => void;
+    /**
+     * Abort a transcription request that produces no response within this
+     * long (default 30000ms). Transcriptions are serialized on one session
+     * chain, so a hung provider request would otherwise block every later
+     * clip (each turn silently waits) until the server restarts. Raise it for
+     * very long clips or slow providers.
+     */
+    transcriptionTimeoutMs?: number;
+    /**
+     * Sampling temperature (0–1) for transcription. Lower is more
+     * deterministic; whisper's API default is already 0, so this is rarely the
+     * lever for hallucinations.
+     */
+    temperature?: number;
+    /**
+     * Provider-specific passthrough, serialized as the `provider` multipart
+     * field. OpenRouter ignores the top-level `prompt` field ("accepted but
+     * ignored"), so the only way to reach whisper's prompt — vocabulary /
+     * context steering — is per-provider:
+     *
+     * ```ts
+     * providerOptions: { options: { groq: { prompt: "Transcribe exactly what is said." } } }
+     * ```
+     *
+     * Only the options for the provider that actually serves the request are
+     * forwarded, so the key must match the serving provider (openai, groq,
+     * together, …).
+     */
+    providerOptions?: Record<string, unknown>;
+    /** Injectable fetch, mainly for tests. */
+    fetch?: FetchLike;
+}
+/**
+ * OpenRouter batch STT adapter (`POST /api/v1/audio/transcriptions`).
+ *
+ * OpenRouter does not stream transcripts — it transcribes a complete audio
+ * clip and returns the text. The adapter therefore buffers the raw audio
+ * written by `write()`, assumes linear16 PCM (mono, `sampleRate`, default
+ * 16 kHz — matching the Deepgram adapter's defaults), wraps each utterance
+ * in a WAV header, and posts it after `silenceMs` of silence. Interim
+ * results are unavailable, so no `partial` events are ever emitted: a turn
+ * arrives whole at the `final` event once its clip has been transcribed.
+ *
+ * `language` accepts an ISO-639-1 code to force a language (which whisper
+ * docs say improves accuracy and latency); omitting it — or passing `"auto"`,
+ * the whisper convention, which is normalized to "omit" — leaves detection to
+ * the provider, matching OpenRouter's "auto-detected if omitted" contract.
+ *
+ * By default the written audio is treated as raw linear16 PCM and wrapped in
+ * a WAV container; set `audioFormat` to the real encoding (e.g. `"mp3"`) to
+ * send pre-encoded audio as-is instead.
+ *
+ * `end()` transcribes any remaining buffered audio; `cancel()` drops
+ * buffered audio and aborts in-flight requests.
+ */
+export declare class OpenRouterSTT implements STT {
+    private readonly options;
+    private readonly sessions;
+    constructor(options: OpenRouterSTTOptions);
+    start(options?: STTOptions): STTSession;
+    /**
+     * Live-tunable energy floor (0–1 RMS) for `pcm` clips: raise it to skip
+     * more near-silence clips (the whisper hallucinations), lower it to keep
+     * quieter speech. Applies to all sessions immediately.
+     */
+    set minClipRms(value: number | undefined);
+    get minClipRms(): number | undefined;
+    cancel(): void;
+}
+export declare class OpenRouterSession implements STTSession {
+    private readonly listeners;
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly model;
+    private readonly language;
+    private readonly sampleRate;
+    private readonly silenceMs;
+    private readonly audioFormat;
+    private readonly filterHallucinations;
+    private readonly fillerPhrases;
+    private readonly onClipEnergy;
+    private readonly transcriptionTimeoutMs;
+    private readonly temperature;
+    private readonly providerOptions;
+    private readonly fetchImpl;
+    /** The adapter's live options object; live-tunable fields are read here. */
+    private readonly liveOptions;
+    /** Live-tunable energy floor, read through the adapter (not a snapshot). */
+    private get minClipRms();
+    private chunks;
+    private timer;
+    private chain;
+    private readonly controllers;
+    private ended;
+    private aborted;
+    constructor(options: OpenRouterSTTOptions, liveOptions: OpenRouterSTTOptions);
+    write(audio: Uint8Array): void;
+    end(): Promise<void>;
+    /** Drop buffered audio and abort in-flight requests (cancel). */
+    abort(): void;
+    on(event: "partial", listener: (transcript: string) => void): void;
+    on(event: "final", listener: (transcript: string) => void): void;
+    on(event: "error", listener: (error: Error) => void): void;
+    on(event: "close", listener: () => void): void;
+    /** Queue a transcription of whatever audio is buffered (serialized). */
+    /**
+     * Queue a transcription of whatever audio is buffered (serialized). The
+     * clip boundary is frozen *now* — the moment the trailing silence was
+     * detected — so audio that arrives while this transcription is queued or
+     * in flight starts the next clip instead of being swept into this one.
+     */
+    private flush;
+    private takeBuffer;
+    private transcribe;
+    private emit;
+}
+/**
+ * Wrap linear16 PCM (mono) in a minimal WAV container so whisper can read it.
+ * The header is the standard 44-byte RIFF/WAVE layout.
+ */
+export declare function toWav(pcm: Uint8Array, sampleRate: number): Uint8Array;
+/**
+ * Mean RMS of linear16 PCM (mono), in the 0–1 sample range. Used as the
+ * clip-level energy floor: near-silence clips sit far below real speech.
+ */
+export declare function pcmRms(pcm: Uint8Array): number;
+/**
+ * Clean a whisper transcript of its most common hallucinations, returning
+ * "" when nothing worth speaking remains:
+ *
+ * 1. Asterisk stage directions ("*Dramatic music*", "*laughs*") are
+ *    dropped — whisper transcribes background noise as stage notes.
+ * 2. Consecutive repeated sentences ("Thank you. Thank you.") collapse to
+ *    one — a doubled filler is a classic near-silence artifact.
+ * 3. A transcript built entirely from filler phrases (the built-in
+ *    multilingual list plus `extraFillers`) is dropped.
+ */
+export declare function cleanTranscript(text: string, extraFillers?: string[]): string;

package/dist/types/providers/tts/adapters/index.d.ts

@@ -1 +1,2 @@
 export { KokoroTTS } from "./kokoro/kokoro.js";
+export { OpenRouterTTS } from "./openrouter/openrouter.js";

package/dist/types/providers/tts/adapters/kokoro/kokoro.d.ts

@@ -4,21 +4,35 @@ export interface KokoroOptions {
     /**
      * Base URL of a Kokoro TTS server exposing the OpenAI-compatible
      * `/v1/audio/speech` endpoint. Defaults to a local kokoro-fastapi server.
+     * For Together AI use `https://api.together.ai`.
      */
     baseUrl?: string;
     /** Default voice, e.g. `af_heart`. */
     voice?: string;
+    /**
+     * Model name. Defaults to `kokoro` (local kokoro-fastapi); Together AI
+     * serves the model as `hexgrad/Kokoro-82M`.
+     */
     model?: string;
     apiKey?: string;
     /** Size of the audio chunks yielded from the response stream. */
     chunkSize?: number;
+    /**
+     * Ask the server for progressive (streaming) synthesis. Local
+     * kokoro-fastapi streams by default; hosted endpoints such as Together AI
+     * require this flag. Together AI responds with server-sent events carrying
+     * base64-encoded audio deltas (pcm_s16le, 24 kHz for Kokoro) terminated by
+     * `data: [DONE]`; the adapter decodes them into raw audio chunks. wav/mp3
+     * formats are not streamable.
+     */
+    stream?: boolean;
     /** Injectable fetch implementation, mainly for tests. */
     fetch?: FetchLike;
 }
 /**
  * Kokoro TTS adapter. Consumes a Kokoro server's OpenAI-compatible speech
- * endpoint and re-chunks the returned audio so it can be played as it
- * arrives.
+ * endpoint (local kokoro-fastapi or a hosted service such as Together AI)
+ * and re-chunks the returned audio so it can be played as it arrives.
  */
 export declare class KokoroTTS implements TTS {
     private readonly baseUrl;
@@ -26,8 +40,9 @@ export declare class KokoroTTS implements TTS {
     private readonly model;
     private readonly apiKey;
     private readonly chunkSize;
+    private readonly streaming;
     private readonly fetchImpl;
-    private abort;
+    private readonly streams;
     constructor(options?: KokoroOptions);
     stop(): void;
     stream(request: TTSRequest): AsyncGenerator<Uint8Array>;

package/dist/types/providers/tts/adapters/openrouter/index.d.ts

@@ -0,0 +1,2 @@
+export { OpenRouterTTS } from "./openrouter.js";
+export type { OpenRouterTTSOptions } from "./openrouter.js";

package/dist/types/providers/tts/adapters/openrouter/openrouter.d.ts

@@ -0,0 +1,64 @@
+import type { TTS, TTSRequest } from "../../types.js";
+import type { FetchLike } from "../../../shared.js";
+export interface OpenRouterTTSOptions {
+    apiKey: string;
+    /** Defaults to `https://openrouter.ai/api/v1`. */
+    baseUrl?: string;
+    /**
+     * TTS model. Defaults to the free `fish-audio/s2.1-pro-free:free` variant —
+     * fast, per-character priced. Pass `fish-audio/s2.1-pro` for the paid tier
+     * (no free-variant rate limits). Note the free variant is intermittently
+     * unavailable on OpenRouter (404 "No endpoints found").
+     */
+    model?: string;
+    /**
+     * Default voice, sent when the request carries none. Set it for a
+     * consistent voice: the default fish model accepts exactly `"alloy"` and
+     * rejects other names, and omitting `voice` lets the free variant vary the
+     * voice per request. Models like OpenAI TTS require a voice. Voice support
+     * varies by model and provider.
+     */
+    voice?: string;
+    /**
+     * Output format used when the request doesn't specify one. `"pcm"` (the
+     * default) is the lowest-latency realtime format, but its sample rate is
+     * provider-defined and opaque — clients must know it. `"mp3"` is
+     * self-describing: decoders read the real rate from the stream.
+     */
+    format?: "pcm" | "mp3";
+    /** Size of the audio chunks yielded from the response stream. Default 8192. */
+    chunkSize?: number;
+    /**
+     * Abort a synthesis that delivers no audio bytes for this long (default
+     * 15000ms). A provider connection that goes silent — or never responds —
+     * would otherwise wedge the speech pipeline forever, since the pipeline
+     * holds one synthesis slot and its delivery chain until the stream ends.
+     * Any byte resets the clock; a genuinely slow synthesis just needs a
+     * response within this window.
+     */
+    idleTimeoutMs?: number;
+    /** Injectable fetch, mainly for tests. */
+    fetch?: FetchLike;
+}
+/**
+ * OpenRouter TTS adapter (`POST /api/v1/audio/speech`, OpenAI-compatible).
+ *
+ * The endpoint returns raw audio bytes (not JSON) in `mp3` or `pcm` format.
+ * The adapter re-chunks the response stream so audio can be played as it
+ * arrives; `stop()` aborts the in-flight synthesis. `pcm` is the default
+ * output (OpenRouter's own recommendation for realtime pipelines).
+ */
+export declare class OpenRouterTTS implements TTS {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly model;
+    private readonly voice;
+    private readonly format;
+    private readonly chunkSize;
+    private readonly idleTimeoutMs;
+    private readonly fetchImpl;
+    private readonly streams;
+    constructor(options: OpenRouterTTSOptions);
+    stop(): void;
+    stream(request: TTSRequest): AsyncGenerator<Uint8Array>;
+}