@alexkroman1/aai 1.2.3 → 1.3.1

package/.turbo/turbo-build.log

@@ -1,20 +1,22 @@
 
-> @alexkroman1/aai@1.2.3 build /home/runner/work/agent/agent/packages/aai
+> @alexkroman1/aai@1.3.1 build /home/runner/work/agent/agent/packages/aai
 > tsdown && tsc -p tsconfig.build.json
 
 ℹ tsdown v0.21.7 powered by rolldown v1.0.0-rc.12
 ℹ config file: /home/runner/work/agent/agent/packages/aai/tsdown.config.ts 
-ℹ entry: index.ts, sdk/protocol.ts, host/runtime-barrel.ts, sdk/manifest-barrel.ts
+ℹ entry: index.ts, sdk/protocol.ts, host/runtime-barrel.ts, sdk/manifest-barrel.ts, host/providers/stt-barrel.ts, host/providers/tts-barrel.ts
 ℹ target: node22
 ℹ tsconfig: tsconfig.json
 ℹ Build start
-ℹ dist/host/runtime-barrel.js       50.02 kB │ gzip: 15.70 kB
-ℹ dist/index.js                      6.38 kB │ gzip:  2.49 kB
-ℹ dist/sdk/protocol.js               4.75 kB │ gzip:  1.76 kB
-ℹ dist/sdk/manifest-barrel.js        0.26 kB │ gzip:  0.17 kB
-ℹ dist/constants-VTFoymJ-.js         2.75 kB │ gzip:  1.23 kB
-ℹ dist/_internal-types-CoDTiBd1.js   2.33 kB │ gzip:  0.99 kB
-ℹ dist/types-Cfx_4QDK.js             1.74 kB │ gzip:  0.93 kB
-ℹ dist/ws-upgrade-BeOQ7fXL.js        1.14 kB │ gzip:  0.54 kB
-ℹ 8 files, total: 69.36 kB
-✔ Build complete in 47ms
+ℹ dist/host/runtime-barrel.js        63.51 kB │ gzip: 19.17 kB
+ℹ dist/index.js                       6.67 kB │ gzip:  2.65 kB
+ℹ dist/host/providers/tts-barrel.js   5.52 kB │ gzip:  2.12 kB
+ℹ dist/sdk/protocol.js                4.75 kB │ gzip:  1.76 kB
+ℹ dist/host/providers/stt-barrel.js   3.08 kB │ gzip:  1.26 kB
+ℹ dist/sdk/manifest-barrel.js         0.26 kB │ gzip:  0.17 kB
+ℹ dist/constants-BL3nvg4I.js          3.10 kB │ gzip:  1.38 kB
+ℹ dist/_internal-types-CoDTiBd1.js    2.33 kB │ gzip:  0.99 kB
+ℹ dist/types-Cfx_4QDK.js              1.74 kB │ gzip:  0.93 kB
+ℹ dist/ws-upgrade-BeOQ7fXL.js         1.14 kB │ gzip:  0.54 kB
+ℹ 10 files, total: 92.10 kB
+✔ Build complete in 43ms

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @alexkroman1/aai
 
+## 1.3.1
+
+### Patch Changes
+
+- 5a9f3d5: Pipeline session concurrency fixes: serialize turns across duplicate STT finals, bound TTS flush with abort+timeout, cascade provider errors to terminate session, atomic provider open, snapshot conversation history in tool executions.
+
+## 1.3.0
+
+### Minor Changes
+
+- f1a9764: Internal: manifests now classify session mode (`s2s` | `pipeline`) at parse time, and expose optional `stt`, `llm`, and `tts` fields on the `Manifest` type. Groundwork for upcoming pluggable provider support — no user-visible behavior change yet.
+
+### Patch Changes
+
+- c95212a: Fix runtime crash when loading the host runtime without the provider SDKs installed. `ai`, `assemblyai`, and `@cartesia/cartesia-js` are now regular dependencies instead of optional peer dependencies — the runtime eagerly imports `pipeline-session.ts`, so they were already required at module load even for S2S-mode agents. Optional peer deps described a design the code didn't enforce; now the metadata matches behavior.
+- f1a9764: Fix PipelineSession: thread agentConfig.maxSteps into streamText via stopWhen: stepCountIs(n). Vercel AI SDK v6 defaults to a single step, so multi-step tool use would silently terminate after the first tool-result.
+- f1a9764: agent() helper accepts stt/llm/tts fields directly, removing the need for the spread workaround in pipeline-mode agents
+- 0231114: Simplify pipeline-session state management and parallelize provider open. Removes redundant PipelineState variable (equivalent to turnController != null), opens STT+TTS concurrently via Promise.allSettled (halves session-start latency), and cleans up either session if one open fails or the session aborts mid-open.
+- 8a79282: Add sendAudioRaw to S2sHandle for batch-encoded audio frames
+
 ## 1.2.3
 
 ### Patch Changes

package/dist/{constants-VTFoymJ-.js → constants-BL3nvg4I.js}

@@ -21,6 +21,13 @@ const FETCH_TIMEOUT_MS = 15e3;
 const RUN_CODE_TIMEOUT_MS = 5e3;
 /** Maximum time to wait for sessions to stop during graceful shutdown. */
 const DEFAULT_SHUTDOWN_TIMEOUT_MS = 3e4;
+/**
+* Maximum time to wait for a pipeline-mode TTS drain after `flush()` before
+* forcing the turn to complete. Prevents a stuck TTS provider from wedging
+* the session. Short relative to `DEFAULT_SHUTDOWN_TIMEOUT_MS` so stop()
+* can still reclaim the socket cleanly.
+*/
+const PIPELINE_FLUSH_TIMEOUT_MS = 1e4;
 /** Maximum length for tool result strings sent to clients. */
 const MAX_TOOL_RESULT_CHARS = 4e3;
 /** Maximum chars for webpage text after HTML-to-text conversion. */
@@ -44,4 +51,4 @@ const WS_OPEN = 1;
 */
 const AGENT_CSP = "default-src 'self'; script-src 'self' 'unsafe-eval' blob:; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; connect-src 'self' wss: ws:; img-src 'self' data:; font-src 'self' https://fonts.gstatic.com; object-src 'none'; base-uri 'self'";
 //#endregion
-export { WS_OPEN as _, DEFAULT_SHUTDOWN_TIMEOUT_MS as a, FETCH_TIMEOUT_MS as c, MAX_PAGE_CHARS as d, MAX_TOOL_RESULT_CHARS as f, TOOL_EXECUTION_TIMEOUT_MS as g, RUN_CODE_TIMEOUT_MS as h, DEFAULT_SESSION_START_TIMEOUT_MS as i, MAX_HTML_BYTES as l, MAX_WS_PAYLOAD_BYTES as m, DEFAULT_IDLE_TIMEOUT_MS as n, DEFAULT_STT_SAMPLE_RATE as o, MAX_VALUE_SIZE as p, DEFAULT_MAX_HISTORY as r, DEFAULT_TTS_SAMPLE_RATE as s, AGENT_CSP as t, MAX_MESSAGE_BUFFER_SIZE as u };
+export { TOOL_EXECUTION_TIMEOUT_MS as _, DEFAULT_SHUTDOWN_TIMEOUT_MS as a, FETCH_TIMEOUT_MS as c, MAX_PAGE_CHARS as d, MAX_TOOL_RESULT_CHARS as f, RUN_CODE_TIMEOUT_MS as g, PIPELINE_FLUSH_TIMEOUT_MS as h, DEFAULT_SESSION_START_TIMEOUT_MS as i, MAX_HTML_BYTES as l, MAX_WS_PAYLOAD_BYTES as m, DEFAULT_IDLE_TIMEOUT_MS as n, DEFAULT_STT_SAMPLE_RATE as o, MAX_VALUE_SIZE as p, DEFAULT_MAX_HISTORY as r, DEFAULT_TTS_SAMPLE_RATE as s, AGENT_CSP as t, MAX_MESSAGE_BUFFER_SIZE as u, WS_OPEN as v };

package/dist/host/_pipeline-test-fakes.d.ts

@@ -0,0 +1,117 @@
+/**
+ * In-memory fake providers + fake `LanguageModel` for pipeline-session tests.
+ *
+ * These fakes do not touch the network. Each `createFake*Provider()` returns a
+ * provider whose `open()` records the most recently opened session so tests
+ * can reach into it via `.last()` and drive events (partial/final transcripts,
+ * TTS chunks) or observe calls (`sendText`, `flush`, `cancel`).
+ *
+ * The fake `LanguageModel` implements the minimum of {@link LanguageModelV3}
+ * required by `streamText` — `doStream()` returns a `ReadableStream` of
+ * {@link LanguageModelV3StreamPart}s produced from a scripted sequence.
+ *
+ * @internal Not part of the public API.
+ */
+import type { LanguageModel } from "ai";
+import { type Emitter } from "nanoevents";
+import { vi } from "vitest";
+import type { SttEvents, SttOpenOptions, SttProvider, SttSession, TtsEvents, TtsOpenOptions, TtsProvider, TtsSession } from "../sdk/providers.ts";
+export type FakeSttSession = SttSession & {
+    readonly emitter: Emitter<SttEvents>;
+    readonly opts: SttOpenOptions;
+    readonly audioFrames: Int16Array[];
+    readonly closed: {
+        value: boolean;
+    };
+    firePartial(text: string): void;
+    fireFinal(text: string): void;
+    fireError(code: "stt_stream_error" | "stt_connect_failed" | "stt_auth_failed", message: string): void;
+};
+export type FakeSttProvider = SttProvider & {
+    /** The most recently opened session, or undefined if `open()` hasn't been called. */
+    last(): FakeSttSession | undefined;
+    readonly sessions: FakeSttSession[];
+};
+export declare function createFakeSttProvider(): FakeSttProvider;
+export type FakeTtsSession = TtsSession & {
+    readonly emitter: Emitter<TtsEvents>;
+    readonly opts: TtsOpenOptions;
+    readonly textChunks: string[];
+    readonly closed: {
+        value: boolean;
+    };
+    readonly sendText: ReturnType<typeof vi.fn<(text: string) => void>>;
+    readonly flush: ReturnType<typeof vi.fn<() => void>>;
+    readonly cancel: ReturnType<typeof vi.fn<() => void>>;
+    fireAudio(pcm: Int16Array): void;
+    fireError(code: "tts_stream_error" | "tts_connect_failed" | "tts_auth_failed", message: string): void;
+};
+export type FakeTtsProvider = TtsProvider & {
+    /** The most recently opened session, or undefined if `open()` hasn't been called. */
+    last(): FakeTtsSession | undefined;
+    readonly sessions: FakeTtsSession[];
+};
+/**
+ * Fake TTS provider. By default, `flush()` synchronously emits a single `done`
+ * event so tests don't have to script the drain separately. Pass
+ * `{ autoDoneOnFlush: false }` to drive `done` manually.
+ */
+export declare function createFakeTtsProvider(options?: {
+    autoDoneOnFlush?: boolean;
+}): FakeTtsProvider;
+/**
+ * Fake STT provider that throws on `open()` with a given error code. Used to
+ * test atomic provider open — TTS should not be opened at all when STT fails.
+ */
+export declare function createFailingSttProvider(code: "stt_connect_failed" | "stt_auth_failed" | "stt_stream_error", message: string): SttProvider;
+/**
+ * Fake TTS provider that throws on `open()` with a given error code. Used to
+ * test atomic provider open — STT should be closed when TTS fails.
+ */
+export declare function createFailingTtsProvider(code: "tts_connect_failed" | "tts_auth_failed" | "tts_stream_error", message: string): TtsProvider;
+/**
+ * A scripted stream part. `text` yields a `text-delta` in the LLM provider's
+ * raw wire format; `tool-call` / `tool-result` emit the corresponding parts
+ * (v3 provider spec: `toolCallId`, `toolName`, `input` as JSON string for
+ * calls, `result` as JSON-serialisable value for results).
+ */
+export type ScriptedPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "tool-call";
+    toolCallId: string;
+    toolName: string;
+    input: string;
+} | {
+    type: "tool-result";
+    toolCallId: string;
+    toolName: string;
+    result: unknown;
+} | {
+    type: "error";
+    error: unknown;
+};
+/**
+ * Create a fake {@link LanguageModel} that yields a scripted sequence of
+ * parts when `streamText` drives `doStream()`. The fake ignores the prompt
+ * and tools — it simply replays the script.
+ *
+ * Pass `{ delayMs: N }` to space out parts with `setTimeout(N)` so that
+ * barge-in tests can abort mid-stream deterministically.
+ *
+ * Pass `{ steps: ScriptedPart[][] }` (instead of `script`) for multi-step
+ * scenarios: each call to `doStream()` consumes the next step's parts.
+ * This is how `streamText` drives multi-turn tool loops under `stopWhen`.
+ *
+ * The returned value is cast to the `LanguageModel` union because we
+ * implement the provider shape structurally rather than importing the
+ * full `@ai-sdk/provider` types into the aai package.
+ */
+export declare function createFakeLanguageModel(options: {
+    script: ScriptedPart[];
+    delayMs?: number;
+} | {
+    steps: ScriptedPart[][];
+    delayMs?: number;
+}): LanguageModel;

package/dist/host/pipeline-session-ctx.d.ts

@@ -0,0 +1,24 @@
+/** Pipeline session context — base ctx + STT/TTS session slots. */
+import type { AgentConfig, ExecuteTool } from "../sdk/_internal-types.ts";
+import type { ClientSink } from "../sdk/protocol.ts";
+import type { SttSession, TtsSession } from "../sdk/providers.ts";
+import type { Logger } from "./runtime-config.ts";
+import { type BaseSessionCtx } from "./session-ctx.ts";
+/**
+ * Pipeline session context — {@link BaseSessionCtx} plus STT/TTS provider
+ * session handles. Replaces the S2S `s2s` field with decoupled `stt` + `tts`
+ * slots so the pipeline orchestrator can drive independent providers.
+ */
+export type PipelineSessionCtx = BaseSessionCtx & {
+    stt: SttSession | null;
+    tts: TtsSession | null;
+};
+export declare function buildPipelineCtx(opts: {
+    id: string;
+    agent: string;
+    client: ClientSink;
+    agentConfig: AgentConfig;
+    executeTool: ExecuteTool;
+    log: Logger;
+    maxHistory?: number | undefined;
+}): PipelineSessionCtx;

package/dist/host/pipeline-session.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Pipeline session — pluggable STT → LLM → TTS orchestrator.
+ *
+ * Alternative to the S2S session (see `session.ts`) that drives three
+ * independent providers. A new partial STT event while the agent is replying
+ * triggers barge-in (aborts the LLM stream and cancels TTS).
+ */
+import type { LanguageModel } from "ai";
+import type { AgentConfig, ExecuteTool, ToolSchema } from "../sdk/_internal-types.ts";
+import type { ClientSink } from "../sdk/protocol.ts";
+import type { SttProvider, TtsProvider } from "../sdk/providers.ts";
+import { type Logger } from "./runtime-config.ts";
+import type { Session } from "./session.ts";
+/** Configuration options for {@link createPipelineSession}. */
+export interface PipelineSessionOptions {
+    /** Unique session identifier. */
+    id: string;
+    /** Agent slug. */
+    agent: string;
+    /** Sink for wire events + audio back to the browser client. */
+    client: ClientSink;
+    /** Serializable agent config (name, system prompt, maxSteps, etc.). */
+    agentConfig: AgentConfig;
+    /** JSON Schema definitions for the agent's tools. */
+    toolSchemas: readonly ToolSchema[];
+    /** Optional natural-language guidance appended to the system prompt. */
+    toolGuidance?: readonly string[] | undefined;
+    /** Function to invoke tools by name. */
+    executeTool: ExecuteTool;
+    /** STT provider (injected via manifest in pipeline mode). */
+    stt: SttProvider;
+    /** LLM provider (Vercel AI SDK `LanguageModel`). */
+    llm: LanguageModel;
+    /** TTS provider (injected via manifest in pipeline mode). */
+    tts: TtsProvider;
+    /** STT API key. */
+    sttApiKey: string;
+    /** TTS API key. */
+    ttsApiKey: string;
+    /** Audio sample rate (PCM16, Hz). Defaults to {@link DEFAULT_STT_SAMPLE_RATE}. */
+    sampleRate?: number | undefined;
+    /** Logger. Defaults to the console logger. */
+    logger?: Logger | undefined;
+    /** Sliding-window conversation history size. */
+    maxHistory?: number | undefined;
+}
+/** Create a pluggable-provider voice session. */
+export declare function createPipelineSession(opts: PipelineSessionOptions): Session;

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

@@ -0,0 +1,2 @@
+/** LLM provider type — re-exported from sdk/ for host-side consumption. */
+export type * from "../../sdk/providers.ts";

package/dist/host/providers/stt/assemblyai.d.ts

@@ -0,0 +1,31 @@
+/**
+ * AssemblyAI Universal-Streaming STT adapter.
+ *
+ * Wraps the `assemblyai` Node SDK's {@link StreamingTranscriber} and
+ * normalizes its event surface onto the {@link SttProvider} /
+ * {@link SttEvents} contract consumed by the pipeline orchestrator.
+ *
+ * Default model: `"u3pro-rt"` (Universal-3 Pro Real-Time). The adapter
+ * maps that to the SDK's `"u3-rt-pro"` `speechModel` value; any other
+ * string is forwarded verbatim.
+ */
+import { type StreamingTranscriber } from "assemblyai";
+import type { SttProvider, SttSession } from "../../../sdk/providers.ts";
+export interface AssemblyAIOptions {
+    /**
+     * Streaming speech model. Defaults to `"u3pro-rt"` (Universal-3 Pro
+     * Real-Time). Arbitrary strings are forwarded to the SDK unchanged.
+     */
+    model?: "u3pro-rt" | string;
+    /**
+     * AssemblyAI API key. Falls back to `SttOpenOptions.apiKey`, then
+     * `process.env.ASSEMBLYAI_API_KEY`.
+     */
+    apiKey?: string;
+}
+/** Internal: SttSession with a test-only handle to the raw SDK transcriber. */
+export interface AssemblyAISession extends SttSession {
+    /** @internal Test-only: exposes the underlying SDK transcriber for fixture replay. */
+    readonly _transcriber: StreamingTranscriber;
+}
+export declare function assemblyAI(opts?: AssemblyAIOptions): SttProvider;

package/dist/host/providers/stt-barrel.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `@alexkroman1/aai/stt` subpath barrel. Re-exports the STT provider
+ * contract types (via `stt.ts` → `sdk/providers.ts`) alongside the
+ * concrete AssemblyAI adapter factory. Task 9 owns wiring this file
+ * into `package.json` exports.
+ */
+export * from "./stt/assemblyai.ts";
+export type * from "./stt.ts";

package/dist/host/providers/stt-barrel.js

@@ -0,0 +1,92 @@
+import { createNanoEvents } from "nanoevents";
+import { AssemblyAI } from "assemblyai";
+//#region host/providers/stt/assemblyai.ts
+/**
+* AssemblyAI Universal-Streaming STT adapter.
+*
+* Wraps the `assemblyai` Node SDK's {@link StreamingTranscriber} and
+* normalizes its event surface onto the {@link SttProvider} /
+* {@link SttEvents} contract consumed by the pipeline orchestrator.
+*
+* Default model: `"u3pro-rt"` (Universal-3 Pro Real-Time). The adapter
+* maps that to the SDK's `"u3-rt-pro"` `speechModel` value; any other
+* string is forwarded verbatim.
+*/
+/** Translate the adapter's model alias to the SDK's `speechModel` value. */
+function resolveSpeechModel(model) {
+	if (model === "u3pro-rt") return "u3-rt-pro";
+	return model;
+}
+function makeError(message) {
+	const err = new Error(message);
+	err.code = "stt_stream_error";
+	return err;
+}
+function assemblyAI(opts = {}) {
+	return {
+		name: "assemblyai",
+		async open(openOpts) {
+			const apiKey = opts.apiKey ?? openOpts.apiKey ?? process.env.ASSEMBLYAI_API_KEY;
+			if (!apiKey) {
+				const err = /* @__PURE__ */ new Error("AssemblyAI STT adapter: missing API key. Provide via the factory option, SttOpenOptions, or the ASSEMBLYAI_API_KEY environment variable.");
+				err.code = "stt_auth_failed";
+				throw err;
+			}
+			const client = new AssemblyAI({ apiKey });
+			const speechModel = resolveSpeechModel(opts.model ?? "u3pro-rt");
+			const transcriber = client.streaming.transcriber({
+				sampleRate: openOpts.sampleRate,
+				speechModel,
+				...openOpts.sttPrompt ? { prompt: openOpts.sttPrompt } : {}
+			});
+			const emitter = createNanoEvents();
+			let closed = false;
+			transcriber.on("turn", (event) => {
+				if (closed) return;
+				const text = event.transcript ?? "";
+				if (event.end_of_turn) {
+					if (text.length > 0) emitter.emit("final", text);
+				} else if (text.length > 0) emitter.emit("partial", text);
+			});
+			transcriber.on("error", (err) => {
+				if (closed) return;
+				emitter.emit("error", makeError(err?.message ?? String(err)));
+			});
+			transcriber.on("close", (code) => {
+				if (closed) return;
+				if (code !== 1e3) emitter.emit("error", makeError(`socket closed ${code}`));
+			});
+			try {
+				await transcriber.connect();
+			} catch (cause) {
+				const err = /* @__PURE__ */ new Error(`AssemblyAI STT: connect failed: ${cause instanceof Error ? cause.message : String(cause)}`);
+				err.code = "stt_connect_failed";
+				throw err;
+			}
+			const close = async () => {
+				if (closed) return;
+				closed = true;
+				try {
+					await transcriber.close();
+				} catch {}
+			};
+			if (openOpts.signal.aborted) close();
+			else openOpts.signal.addEventListener("abort", () => void close(), { once: true });
+			return {
+				sendAudio(pcm) {
+					if (closed) return;
+					const copy = new Uint8Array(pcm.byteLength);
+					copy.set(new Uint8Array(pcm.buffer, pcm.byteOffset, pcm.byteLength));
+					transcriber.sendAudio(copy.buffer);
+				},
+				on(event, fn) {
+					return emitter.on(event, fn);
+				},
+				close,
+				_transcriber: transcriber
+			};
+		}
+	};
+}
+//#endregion
+export { assemblyAI };

package/dist/host/providers/stt.d.ts

@@ -0,0 +1,2 @@
+/** STT provider interface — re-exported from sdk/ for host-side consumption. */
+export type * from "../../sdk/providers.ts";

package/dist/host/providers/tts/cartesia.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Cartesia TTS adapter — streaming WebSocket with per-turn `context_id`.
+ *
+ * Wraps `@cartesia/cartesia-js`'s `TTSWS` / `TTSWSContext` and normalizes it
+ * onto the {@link TtsProvider} / {@link TtsEvents} contract consumed by the
+ * pipeline orchestrator.
+ *
+ * **Per-turn context lifecycle.** Each `sendText(...)` within the same turn
+ * appends to the same Cartesia context. On `flush()` or `cancel()`, a new
+ * context is minted for the next turn — so concurrent `cancel({ contextId })`
+ * only targets the in-flight turn, never the one that follows.
+ *
+ * **Audio format.** The adapter requests `raw` / `pcm_s16le` at the
+ * negotiated `sampleRate` so it can forward chunks as `Int16Array` with no
+ * conversion.
+ */
+import type { TTSWS } from "@cartesia/cartesia-js/resources/tts";
+import type { TtsProvider, TtsSession } from "../../../sdk/providers.ts";
+export interface CartesiaOptions {
+    /** Cartesia voice ID. Required. */
+    voice: string;
+    /** Model ID. Defaults to `"sonic-2"`. */
+    model?: string;
+    /**
+     * Cartesia API key. Falls back to `TtsOpenOptions.apiKey`, then
+     * `process.env.CARTESIA_API_KEY`.
+     */
+    apiKey?: string;
+    /** Spoken language hint. Defaults to `"en"`. */
+    language?: string;
+}
+/** Internal: TtsSession with a test-only handle to the raw SDK socket. */
+export interface CartesiaSession extends TtsSession {
+    /** @internal Test-only: exposes the underlying SDK WebSocket wrapper. */
+    readonly _ws: TTSWS;
+    /** @internal Test-only: id of the currently-active context. */
+    readonly _currentContextId: () => string;
+}
+export declare function cartesia(opts: CartesiaOptions): TtsProvider;

package/dist/host/providers/tts-barrel.d.ts

@@ -0,0 +1,8 @@
+/**
+ * `@alexkroman1/aai/tts` subpath barrel. Re-exports the TTS provider
+ * contract types (via `tts.ts` → `sdk/providers.ts`) alongside the
+ * concrete Cartesia adapter factory. Task 9 owns wiring this file
+ * into `package.json` exports.
+ */
+export * from "./tts/cartesia.ts";
+export type * from "./tts.ts";

package/dist/host/providers/tts-barrel.js

@@ -0,0 +1,182 @@
+import { createNanoEvents } from "nanoevents";
+import { randomUUID } from "node:crypto";
+import { Cartesia } from "@cartesia/cartesia-js";
+//#region host/providers/tts/cartesia.ts
+/**
+* Cartesia TTS adapter — streaming WebSocket with per-turn `context_id`.
+*
+* Wraps `@cartesia/cartesia-js`'s `TTSWS` / `TTSWSContext` and normalizes it
+* onto the {@link TtsProvider} / {@link TtsEvents} contract consumed by the
+* pipeline orchestrator.
+*
+* **Per-turn context lifecycle.** Each `sendText(...)` within the same turn
+* appends to the same Cartesia context. On `flush()` or `cancel()`, a new
+* context is minted for the next turn — so concurrent `cancel({ contextId })`
+* only targets the in-flight turn, never the one that follows.
+*
+* **Audio format.** The adapter requests `raw` / `pcm_s16le` at the
+* negotiated `sampleRate` so it can forward chunks as `Int16Array` with no
+* conversion.
+*/
+function makeError(message) {
+	const err = new Error(message);
+	err.code = "tts_stream_error";
+	return err;
+}
+/** PCM16 sample rates supported by Cartesia's `raw` output format. */
+const CARTESIA_PCM16_RATES = [
+	8e3,
+	16e3,
+	22050,
+	24e3,
+	44100,
+	48e3
+];
+function assertSupportedSampleRate(rate) {
+	if (CARTESIA_PCM16_RATES.includes(rate)) return rate;
+	const err = /* @__PURE__ */ new Error(`Cartesia TTS adapter: unsupported sample rate ${rate}. Supported: ${CARTESIA_PCM16_RATES.join(", ")}.`);
+	err.code = "tts_connect_failed";
+	throw err;
+}
+function cartesia(opts) {
+	return {
+		name: "cartesia",
+		async open(openOpts) {
+			const apiKey = opts.apiKey ?? openOpts.apiKey ?? process.env.CARTESIA_API_KEY;
+			if (!apiKey) {
+				const err = /* @__PURE__ */ new Error("Cartesia TTS adapter: missing API key. Provide via the factory option, TtsOpenOptions, or the CARTESIA_API_KEY environment variable.");
+				err.code = "tts_auth_failed";
+				throw err;
+			}
+			const sampleRate = assertSupportedSampleRate(openOpts.sampleRate);
+			const model = opts.model ?? "sonic-2";
+			const language = opts.language ?? "en";
+			const client = new Cartesia({ apiKey });
+			let ws;
+			try {
+				ws = await client.tts.websocket();
+			} catch (cause) {
+				const err = /* @__PURE__ */ new Error(`Cartesia TTS: connect failed: ${cause instanceof Error ? cause.message : String(cause)}`);
+				err.code = "tts_connect_failed";
+				throw err;
+			}
+			const emitter = createNanoEvents();
+			let closed = false;
+			/** Mint a fresh context bound to the shared TTSWS connection. */
+			const mintContext = () => ws.context({
+				model_id: model,
+				voice: {
+					mode: "id",
+					id: opts.voice
+				},
+				output_format: {
+					container: "raw",
+					encoding: "pcm_s16le",
+					sample_rate: sampleRate
+				},
+				contextId: randomUUID()
+			});
+			let context = mintContext();
+			/**
+			* `doneEmitted` guards against emitting `done` more than once per turn.
+			* Reset whenever a fresh context is minted (i.e. at turn boundaries).
+			*/
+			let doneEmitted = false;
+			const rotateContext = () => {
+				context = mintContext();
+				doneEmitted = false;
+			};
+			const emitDoneOnce = () => {
+				if (doneEmitted || closed) return;
+				doneEmitted = true;
+				emitter.emit("done");
+			};
+			ws.on("chunk", (event) => {
+				if (closed) return;
+				if (event.context_id !== context.contextId) return;
+				const buf = event.audio;
+				if (!buf || buf.byteLength === 0) return;
+				const evenBytes = buf.byteLength - buf.byteLength % 2;
+				if (evenBytes === 0) return;
+				const pcm = new Int16Array(buf.buffer.slice(buf.byteOffset, buf.byteOffset + evenBytes));
+				emitter.emit("audio", pcm);
+			});
+			ws.on("done", (event) => {
+				if (closed) return;
+				if (event.context_id !== context.contextId) return;
+				emitDoneOnce();
+			});
+			ws.on("error", (err) => {
+				if (closed) return;
+				emitter.emit("error", makeError(err?.message ?? String(err)));
+			});
+			const close = async () => {
+				if (closed) return;
+				closed = true;
+				try {
+					ws.close({
+						code: 1e3,
+						reason: "client close"
+					});
+				} catch {}
+			};
+			if (openOpts.signal.aborted) close();
+			else openOpts.signal.addEventListener("abort", () => void close(), { once: true });
+			/** Static part of each generation request; only `transcript` and
+			* `continue` vary per send. Pinned here so `language` threads through. */
+			const baseRequest = {
+				model_id: model,
+				voice: {
+					mode: "id",
+					id: opts.voice
+				},
+				output_format: {
+					container: "raw",
+					encoding: "pcm_s16le",
+					sample_rate: sampleRate
+				},
+				language
+			};
+			/**
+			* Swallow rejections from async SDK calls — the global `error`
+			* listener on `ws` emits a normalized {@link TtsError}, so there's
+			* nothing useful for the caller to do with per-send failures.
+			*/
+			const ignoreRejection = (_err) => {};
+			return {
+				sendText(text) {
+					if (closed || text.length === 0) return;
+					context.send({
+						...baseRequest,
+						transcript: text,
+						continue: true
+					}).catch(ignoreRejection);
+				},
+				flush() {
+					if (closed) return;
+					context.send({
+						...baseRequest,
+						transcript: "",
+						continue: false
+					}).catch(ignoreRejection);
+					queueMicrotask(emitDoneOnce);
+					rotateContext();
+				},
+				cancel() {
+					if (closed) return;
+					context.cancel().catch(ignoreRejection);
+					emitDoneOnce();
+					rotateContext();
+				},
+				on(event, fn) {
+					return emitter.on(event, fn);
+				},
+				close,
+				_ws: ws,
+				_currentContextId: () => context.contextId
+			};
+		}
+	};
+}
+//#endregion
+export { cartesia };

package/dist/host/providers/tts.d.ts

@@ -0,0 +1,2 @@
+/** TTS provider interface — re-exported from sdk/ for host-side consumption. */
+export type * from "../../sdk/providers.ts";