@alexkroman1/aai 1.3.2 → 1.4.1

package/host/providers/resolve.ts

@@ -0,0 +1,90 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * Descriptor → concrete-provider resolution (host-only).
+ *
+ * User code (and the server, after extracting config from a bundled agent)
+ * holds `SttProvider` / `LlmProvider` / `TtsProvider` **descriptors** —
+ * plain `{ kind, options }` data. At session start the runtime calls the
+ * resolvers here to turn each descriptor into its openable / callable
+ * host-side counterpart, importing the third-party SDK only at that point.
+ *
+ * The guest sandbox never imports these functions, which is how the agent
+ * bundle stays free of `@ai-sdk/anthropic` / `assemblyai` /
+ * `@cartesia/cartesia-js`.
+ */
+
+import { createAnthropic } from "@ai-sdk/anthropic";
+import type { LanguageModel } from "ai";
+import { ANTHROPIC_KIND, type AnthropicOptions } from "../../sdk/providers/llm/anthropic.ts";
+import { ASSEMBLYAI_KIND, type AssemblyAIOptions } from "../../sdk/providers/stt/assemblyai.ts";
+import { CARTESIA_KIND, type CartesiaOptions } from "../../sdk/providers/tts/cartesia.ts";
+import type {
+  LlmProvider,
+  SttOpener,
+  SttProvider,
+  TtsOpener,
+  TtsProvider,
+} from "../../sdk/providers.ts";
+import { openAssemblyAI } from "./stt/assemblyai.ts";
+import { openCartesia } from "./tts/cartesia.ts";
+
+/**
+ * Look up a provider API key: agent env first (set via `aai secret put` or
+ * `.env`), then the host's `process.env` as a fallback for self-hosted mode.
+ * Returns `""` if neither has it — the caller decides whether that's fatal.
+ */
+export function resolveApiKey(envVar: string, env: Record<string, string>): string {
+  return env[envVar] ?? process.env[envVar] ?? "";
+}
+
+/** Resolve an {@link SttProvider} descriptor into a host-side opener. */
+export function resolveStt(descriptor: SttProvider): SttOpener {
+  switch (descriptor.kind) {
+    case ASSEMBLYAI_KIND:
+      return openAssemblyAI(descriptor.options as unknown as AssemblyAIOptions);
+    default:
+      throw new Error(
+        `Unknown STT provider kind: "${descriptor.kind}". Supported: ${ASSEMBLYAI_KIND}.`,
+      );
+  }
+}
+
+/** Resolve a {@link TtsProvider} descriptor into a host-side opener. */
+export function resolveTts(descriptor: TtsProvider): TtsOpener {
+  switch (descriptor.kind) {
+    case CARTESIA_KIND:
+      return openCartesia(descriptor.options as unknown as CartesiaOptions);
+    default:
+      throw new Error(
+        `Unknown TTS provider kind: "${descriptor.kind}". Supported: ${CARTESIA_KIND}.`,
+      );
+  }
+}
+
+/**
+ * Resolve an {@link LlmProvider} descriptor into a Vercel AI SDK
+ * {@link LanguageModel}.
+ *
+ * The API key is pulled from the agent's env (e.g. `ANTHROPIC_API_KEY`).
+ * Missing keys throw here — the pipeline session would fail on first
+ * `streamText` call otherwise, and the error is clearer at construction.
+ */
+export function resolveLlm(descriptor: LlmProvider, env: Record<string, string>): LanguageModel {
+  switch (descriptor.kind) {
+    case ANTHROPIC_KIND: {
+      const options = descriptor.options as unknown as AnthropicOptions;
+      const apiKey = resolveApiKey("ANTHROPIC_API_KEY", env);
+      if (!apiKey) {
+        throw new Error("Anthropic LLM: missing API key. Set ANTHROPIC_API_KEY in the agent env.");
+      }
+      // Pass baseURL explicitly so the SDK's loadOptionalSetting returns
+      // before reading process.env["ANTHROPIC_BASE_URL"]. Without this,
+      // the Deno platform server needs --allow-env to start a session.
+      return createAnthropic({ apiKey, baseURL: "https://api.anthropic.com/v1" })(options.model);
+    }
+    default:
+      throw new Error(
+        `Unknown LLM provider kind: "${descriptor.kind}". Supported: ${ANTHROPIC_KIND}.`,
+      );
+  }
+}

package/host/providers/stt/assemblyai.test.ts

@@ -7,7 +7,7 @@ import { fileURLToPath } from "node:url";
 import type { TurnEvent } from "assemblyai";
 import { describe, expect, test, vi } from "vitest";
 import { flush } from "../../_test-utils.ts";
-import { type AssemblyAISession, assemblyAI } from "./assemblyai.ts";
+import { type AssemblyAISession, openAssemblyAI } from "./assemblyai.ts";
 
 const here = dirname(fileURLToPath(import.meta.url));
 
@@ -66,7 +66,7 @@ describe("assemblyAI STT adapter — fixture replay", () => {
       await readFile(join(here, "fixtures/assemblyai/basic-turn.json"), "utf8"),
     ) as Record<string, unknown>[];
 
-    const provider = assemblyAI({ model: "u3pro-rt", apiKey: "k" });
+    const provider = openAssemblyAI({ model: "u3pro-rt" });
     const controller = new AbortController();
     const session = (await provider.open({
       sampleRate: 16_000,

package/host/providers/stt/assemblyai.ts

@@ -1,10 +1,11 @@
 // Copyright 2025 the AAI authors. MIT license.
 /**
- * AssemblyAI Universal-Streaming STT adapter.
+ * AssemblyAI Universal-Streaming STT opener (host-only).
  *
- * 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.
+ * The user-facing descriptor factory (`assemblyAI(...)`) lives in
+ * `sdk/providers/stt/assemblyai.ts`. This module is the host-side
+ * counterpart: it takes the descriptor options + an API key and
+ * returns an {@link SttOpener} that the pipeline session drives.
  *
  * Default model: `"u3pro-rt"` (Universal-3 Pro Real-Time). The adapter
  * maps that to the SDK's `"u3-rt-pro"` `speechModel` value; any other
@@ -13,57 +14,39 @@
 
 import { AssemblyAI, type StreamingTranscriber } from "assemblyai";
 import { createNanoEvents, type Emitter } from "nanoevents";
-import type {
-  SttError,
-  SttEvents,
-  SttOpenOptions,
-  SttProvider,
-  SttSession,
+import type { AssemblyAIOptions } from "../../../sdk/providers/stt/assemblyai.ts";
+import {
+  makeSttError,
+  type SttEvents,
+  type SttOpener,
+  type SttOpenOptions,
+  type 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;
 }
 
-/** Translate the adapter's model alias to the SDK's `speechModel` value. */
+/** Translate the descriptor's model alias to the SDK's `speechModel` value. */
 function resolveSpeechModel(model: string): string {
   // Plan's public name is "u3pro-rt"; the SDK's enum uses "u3-rt-pro".
   if (model === "u3pro-rt") return "u3-rt-pro";
   return model;
 }
 
-function makeError(message: string): SttError {
-  const err = new Error(message) as SttError & { code: SttError["code"] };
-  (err as { code: SttError["code"] }).code = "stt_stream_error";
-  return err;
-}
-
-export function assemblyAI(opts: AssemblyAIOptions = {}): SttProvider {
+/** Build an {@link SttOpener} from resolved AssemblyAI descriptor options. */
+export function openAssemblyAI(opts: AssemblyAIOptions = {}): SttOpener {
   return {
     name: "assemblyai",
     async open(openOpts: SttOpenOptions): Promise<SttSession> {
-      const apiKey = opts.apiKey ?? openOpts.apiKey ?? process.env.ASSEMBLYAI_API_KEY;
+      const apiKey = openOpts.apiKey || process.env.ASSEMBLYAI_API_KEY;
       if (!apiKey) {
-        const err = new Error(
-          "AssemblyAI STT adapter: missing API key. Provide via the factory option, SttOpenOptions, or the ASSEMBLYAI_API_KEY environment variable.",
-        ) as SttError & { code: SttError["code"] };
-        (err as { code: SttError["code"] }).code = "stt_auth_failed";
-        throw err;
+        throw makeSttError(
+          "stt_auth_failed",
+          "AssemblyAI STT: missing API key. Set ASSEMBLYAI_API_KEY in the agent env.",
+        );
       }
 
       const client = new AssemblyAI({ apiKey });
@@ -91,25 +74,24 @@ export function assemblyAI(opts: AssemblyAIOptions = {}): SttProvider {
 
       transcriber.on("error", (err) => {
         if (closed) return;
-        emitter.emit("error", makeError(err?.message ?? String(err)));
+        emitter.emit("error", makeSttError("stt_stream_error", err?.message ?? String(err)));
       });
 
       transcriber.on("close", (code) => {
         if (closed) return;
         // 1000 = normal closure.
         if (code !== 1000) {
-          emitter.emit("error", makeError(`socket closed ${code}`));
+          emitter.emit("error", makeSttError("stt_stream_error", `socket closed ${code}`));
         }
       });
 
       try {
         await transcriber.connect();
       } catch (cause) {
-        const err = new Error(
+        throw makeSttError(
+          "stt_connect_failed",
           `AssemblyAI STT: connect failed: ${cause instanceof Error ? cause.message : String(cause)}`,
-        ) as SttError & { code: SttError["code"] };
-        (err as { code: SttError["code"] }).code = "stt_connect_failed";
-        throw err;
+        );
       }
 
       const close = async (): Promise<void> => {
@@ -122,7 +104,6 @@ export function assemblyAI(opts: AssemblyAIOptions = {}): SttProvider {
         }
       };
 
-      // Wire session-level abort to close the SDK socket.
       if (openOpts.signal.aborted) {
         void close();
       } else {
@@ -134,9 +115,6 @@ export function assemblyAI(opts: AssemblyAIOptions = {}): SttProvider {
       const session: AssemblyAISession = {
         sendAudio(pcm: Int16Array) {
           if (closed) return;
-          // The SDK's sendAudio accepts ArrayBufferLike. Forward a detached
-          // copy of the PCM view's window so the consumer sees only this
-          // chunk's bytes.
           const copy = new Uint8Array(pcm.byteLength);
           copy.set(new Uint8Array(pcm.buffer, pcm.byteOffset, pcm.byteLength));
           transcriber.sendAudio(copy.buffer);

package/host/providers/tts/cartesia.test.ts

@@ -3,7 +3,7 @@
 
 import { beforeEach, describe, expect, test, vi } from "vitest";
 import { flush } from "../../_test-utils.ts";
-import { type CartesiaSession, cartesia } from "./cartesia.ts";
+import { type CartesiaSession, openCartesia } from "./cartesia.ts";
 
 // Recorded interactions on the fake `TTSWSContext` — one entry per method call.
 interface RecordedSend {
@@ -101,7 +101,7 @@ async function openSession(): Promise<{
   session: CartesiaSession;
   controller: AbortController;
 }> {
-  const provider = cartesia({ voice: "voice-id", apiKey: "k" });
+  const provider = openCartesia({ voice: "voice-id" });
   const controller = new AbortController();
   const session = (await provider.open({
     sampleRate: 16_000,

package/host/providers/tts/cartesia.ts

@@ -1,10 +1,14 @@
 // Copyright 2025 the AAI authors. MIT license.
 /**
- * Cartesia TTS adapter — streaming WebSocket with per-turn `context_id`.
+ * Cartesia TTS opener (host-only).
+ *
+ * The user-facing descriptor factory (`cartesia(...)`) lives in
+ * `sdk/providers/tts/cartesia.ts`. This module is the host-side
+ * counterpart: it takes the descriptor options + an API key and
+ * returns a {@link TtsOpener} that the pipeline session drives.
  *
  * Wraps `@cartesia/cartesia-js`'s `TTSWS` / `TTSWSContext` and normalizes it
- * onto the {@link TtsProvider} / {@link TtsEvents} contract consumed by the
- * pipeline orchestrator.
+ * onto the {@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
@@ -20,28 +24,15 @@ import { randomUUID } from "node:crypto";
 import { Cartesia } from "@cartesia/cartesia-js";
 import type { TTSWS, TTSWSContext } from "@cartesia/cartesia-js/resources/tts";
 import { createNanoEvents, type Emitter } from "nanoevents";
-import type {
-  TtsError,
-  TtsEvents,
-  TtsOpenOptions,
-  TtsProvider,
-  TtsSession,
+import type { CartesiaOptions } from "../../../sdk/providers/tts/cartesia.ts";
+import {
+  makeTtsError,
+  type TtsEvents,
+  type TtsOpener,
+  type TtsOpenOptions,
+  type 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. */
@@ -50,12 +41,6 @@ export interface CartesiaSession extends TtsSession {
   readonly _currentContextId: () => string;
 }
 
-function makeError(message: string): TtsError {
-  const err = new Error(message) as TtsError & { code: TtsError["code"] };
-  (err as { code: TtsError["code"] }).code = "tts_stream_error";
-  return err;
-}
-
 /** PCM16 sample rates supported by Cartesia's `raw` output format. */
 const CARTESIA_PCM16_RATES = [
   8000, 16_000, 22_050, 24_000, 44_100, 48_000,
@@ -66,24 +51,23 @@ function assertSupportedSampleRate(rate: number): CartesiaSampleRate {
   if ((CARTESIA_PCM16_RATES as readonly number[]).includes(rate)) {
     return rate as CartesiaSampleRate;
   }
-  const err = new Error(
-    `Cartesia TTS adapter: unsupported sample rate ${rate}. Supported: ${CARTESIA_PCM16_RATES.join(", ")}.`,
-  ) as TtsError & { code: TtsError["code"] };
-  (err as { code: TtsError["code"] }).code = "tts_connect_failed";
-  throw err;
+  throw makeTtsError(
+    "tts_connect_failed",
+    `Cartesia TTS: unsupported sample rate ${rate}. Supported: ${CARTESIA_PCM16_RATES.join(", ")}.`,
+  );
 }
 
-export function cartesia(opts: CartesiaOptions): TtsProvider {
+/** Build a {@link TtsOpener} from resolved Cartesia descriptor options. */
+export function openCartesia(opts: CartesiaOptions): TtsOpener {
   return {
     name: "cartesia",
     async open(openOpts: TtsOpenOptions): Promise<TtsSession> {
-      const apiKey = opts.apiKey ?? openOpts.apiKey ?? process.env.CARTESIA_API_KEY;
+      const apiKey = openOpts.apiKey || process.env.CARTESIA_API_KEY;
       if (!apiKey) {
-        const err = new Error(
-          "Cartesia TTS adapter: missing API key. Provide via the factory option, TtsOpenOptions, or the CARTESIA_API_KEY environment variable.",
-        ) as TtsError & { code: TtsError["code"] };
-        (err as { code: TtsError["code"] }).code = "tts_auth_failed";
-        throw err;
+        throw makeTtsError(
+          "tts_auth_failed",
+          "Cartesia TTS: missing API key. Set CARTESIA_API_KEY in the agent env.",
+        );
       }
 
       const sampleRate = assertSupportedSampleRate(openOpts.sampleRate);
@@ -95,11 +79,10 @@ export function cartesia(opts: CartesiaOptions): TtsProvider {
       try {
         ws = await client.tts.websocket();
       } catch (cause) {
-        const err = new Error(
+        throw makeTtsError(
+          "tts_connect_failed",
           `Cartesia TTS: connect failed: ${cause instanceof Error ? cause.message : String(cause)}`,
-        ) as TtsError & { code: TtsError["code"] };
-        (err as { code: TtsError["code"] }).code = "tts_connect_failed";
-        throw err;
+        );
       }
 
       const emitter: Emitter<TtsEvents> = createNanoEvents<TtsEvents>();
@@ -134,17 +117,15 @@ export function cartesia(opts: CartesiaOptions): TtsProvider {
         emitter.emit("done");
       };
 
-      // Route SDK events onto the adapter's event surface, filtering by the
-      // currently-active `context_id`. The TTSWS EventEmitter fires globally
-      // across all contexts on the socket; we only care about the active one.
+      // TTSWS fires events globally across all contexts on the shared
+      // socket; filter by the currently-active context_id.
       ws.on("chunk", (event) => {
         if (closed) return;
         if (event.context_id !== context.contextId) return;
-        // SDK decodes base64 → Buffer on receipt (`event.audio`). Forward as
-        // Int16Array over the same byte window.
         const buf = event.audio;
         if (!buf || buf.byteLength === 0) return;
-        // Cartesia sends PCM16 little-endian with even byte counts. Be defensive.
+        // Cartesia sends PCM16 LE; be defensive about odd byte counts
+        // so `new Int16Array` never throws on a misaligned length.
         const evenBytes = buf.byteLength - (buf.byteLength % 2);
         if (evenBytes === 0) return;
         const pcm = new Int16Array(buf.buffer.slice(buf.byteOffset, buf.byteOffset + evenBytes));
@@ -159,7 +140,7 @@ export function cartesia(opts: CartesiaOptions): TtsProvider {
 
       ws.on("error", (err) => {
         if (closed) return;
-        emitter.emit("error", makeError(err?.message ?? String(err)));
+        emitter.emit("error", makeTtsError("tts_stream_error", err?.message ?? String(err)));
       });
 
       const close = async (): Promise<void> => {
@@ -172,7 +153,6 @@ export function cartesia(opts: CartesiaOptions): TtsProvider {
         }
       };
 
-      // Session-level abort → close the SDK socket.
       if (openOpts.signal.aborted) {
         void close();
       } else {
@@ -181,8 +161,6 @@ export function cartesia(opts: CartesiaOptions): TtsProvider {
         });
       }
 
-      /** 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" as const, id: opts.voice },
@@ -194,11 +172,6 @@ export function cartesia(opts: CartesiaOptions): TtsProvider {
         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: unknown): void => {
         // intentionally empty
       };
@@ -206,22 +179,19 @@ export function cartesia(opts: CartesiaOptions): TtsProvider {
       const session: CartesiaSession = {
         sendText(text: string) {
           if (closed || text.length === 0) return;
-          // Send a delta with `continue: true`, sharing the same
-          // context_id across all deltas of this turn.
           void context
             .send({ ...baseRequest, transcript: text, continue: true })
             .catch(ignoreRejection);
         },
         flush() {
           if (closed) return;
-          // Send an empty transcript with `continue: false` — the canonical
-          // end-of-turn signal. The server replies with a `done` event
-          // tagged with this context's id, which drives `emitDoneOnce`. We
-          // also microtask-emit `done` as a fallback so the orchestrator's
-          // state machine can't wedge if the server event is dropped.
-          // TODO: drop the microtask fallback once we've verified Cartesia
-          // always emits a `done` for cleanly-flushed contexts. See
-          // 2026-04-22-pluggable-providers-design.md → "Note on flush() timing".
+          // Empty transcript with `continue: false` is the canonical
+          // end-of-turn signal. Cartesia replies with a `done` tagged
+          // by context_id, driving `emitDoneOnce`. The microtask
+          // fallback guards against a dropped server event wedging
+          // the orchestrator's state machine.
+          // TODO: drop the microtask fallback once we've verified
+          // Cartesia always emits `done` for cleanly-flushed contexts.
           void context
             .send({ ...baseRequest, transcript: "", continue: false })
             .catch(ignoreRejection);
@@ -230,10 +200,10 @@ export function cartesia(opts: CartesiaOptions): TtsProvider {
         },
         cancel() {
           if (closed) return;
-          // `cancel()` calls ws.cancelContext(contextId) under the hood.
           void context.cancel().catch(ignoreRejection);
-          // Emit `done` synchronously — the orchestrator's state machine
-          // advances on `done`, and barge-in must not be delayed.
+          // Emit synchronously: barge-in advances the orchestrator's
+          // state machine on `done`, and delaying it would audibly
+          // stall subsequent turns.
           emitDoneOnce();
           rotateContext();
         },

package/host/runtime.ts

@@ -7,6 +7,7 @@
  * lifecycle hooks, and session management.
  */
 
+import type { LanguageModel } from "ai";
 import pTimeout from "p-timeout";
 import { createStorage } from "unstorage";
 import { agentToolsToSchemas, type ToolSchema, toAgentConfig } from "../sdk/_internal-types.ts";
@@ -14,11 +15,19 @@ import { DEFAULT_SHUTDOWN_TIMEOUT_MS } from "../sdk/constants.ts";
 import type { Kv } from "../sdk/kv.ts";
 import type { ClientSink } from "../sdk/protocol.ts";
 import { buildReadyConfig, type ReadyConfig } from "../sdk/protocol.ts";
-import type { LlmProvider, SttProvider, TtsProvider } from "../sdk/providers.ts";
+import {
+  assertProviderTriple,
+  type LlmProvider,
+  type SttOpener,
+  type SttProvider,
+  type TtsOpener,
+  type TtsProvider,
+} from "../sdk/providers.ts";
 import type { AgentDef } from "../sdk/types.ts";
 import { toolError } from "../sdk/utils.ts";
 import { resolveAllBuiltins } from "./builtin-tools.ts";
 import { createPipelineSession } from "./pipeline-session.ts";
+import { resolveApiKey, resolveLlm, resolveStt, resolveTts } from "./providers/resolve.ts";
 import type { Logger, S2SConfig } from "./runtime-config.ts";
 import { consoleLogger, DEFAULT_S2S_CONFIG } from "./runtime-config.ts";
 import type { CreateS2sWebSocket } from "./s2s.ts";
@@ -55,23 +64,36 @@ export type AgentRuntime = {
 
 // ─── Runtime implementation ──────────────────────────────────────────────────
 
+/**
+ * Distinguish a descriptor (`{ kind, options }`) from an already-resolved
+ * opener / `LanguageModel`. The production path always passes descriptors;
+ * openers are a test escape hatch (fakes in `_pipeline-test-fakes.ts`).
+ * STT/TTS openers are identified by the `open` method, `LanguageModel` by
+ * its `specificationVersion` field — both absent on descriptors.
+ */
+function resolveSttIfDescriptor(value: SttProvider | SttOpener): SttOpener {
+  return "open" in value ? value : resolveStt(value);
+}
+
+function resolveTtsIfDescriptor(value: TtsProvider | TtsOpener): TtsOpener {
+  return "open" in value ? value : resolveTts(value);
+}
+
+function resolveLlmIfDescriptor(
+  value: LlmProvider | LanguageModel,
+  env: Record<string, string>,
+): LanguageModel {
+  // LanguageModel can be a string (model-id shortcut) or an object with
+  // `specificationVersion`; descriptors are plain `{ kind, options }` objects.
+  if (typeof value === "string") return value;
+  return "specificationVersion" in value ? value : resolveLlm(value, env);
+}
+
 /** Create an in-memory KV store (default for self-hosted). */
 function createLocalKv(): Kv {
   return createUnstorageKv({ storage: createStorage() });
 }
 
-/**
- * Resolve an API key host-side for pipeline providers.
- *
- * Checks the agent's declared env first, then the host process env as a
- * fallback. Returns `""` when absent — pipeline providers surface a clear
- * `MissingCredentialsError` via their `open()` that the orchestrator
- * converts to a `session.error` wire event.
- */
-function resolveApiKey(envVar: string, env: Record<string, string>): string {
-  return env[envVar] ?? process.env[envVar] ?? "";
-}
-
 /**
  * Configuration for {@link createRuntime}.
  *
@@ -126,21 +148,24 @@ export type RuntimeOptions = {
    */
   fetch?: typeof globalThis.fetch | undefined;
   /**
-   * Pluggable STT provider. Must be set together with `llm` and `tts` to
+   * STT provider. Accepts either a descriptor ({@link SttProvider},
+   * the normal production path) or a pre-resolved {@link SttOpener}
+   * (test escape hatch). Must be set together with `llm` and `tts` to
    * route sessions through the pipeline path; leave all three unset for
    * the default AssemblyAI Streaming Speech-to-Speech (S2S) path.
    */
-  stt?: SttProvider | undefined;
+  stt?: SttProvider | SttOpener | undefined;
   /**
-   * Pluggable LLM provider (Vercel AI SDK `LanguageModel`). Must be set
-   * together with `stt` and `tts` to route sessions through the pipeline path.
+   * LLM provider. Accepts either a descriptor ({@link LlmProvider},
+   * produced by factories like `anthropic(...)`) or a concrete Vercel AI
+   * SDK `LanguageModel` (self-hosted / test escape hatch).
    */
-  llm?: LlmProvider | undefined;
+  llm?: LlmProvider | LanguageModel | undefined;
   /**
-   * Pluggable TTS provider. Must be set together with `stt` and `llm` to
-   * route sessions through the pipeline path.
+   * TTS provider. Accepts either a descriptor ({@link TtsProvider})
+   * or a pre-resolved {@link TtsOpener}.
    */
-  tts?: TtsProvider | undefined;
+  tts?: TtsProvider | TtsOpener | undefined;
 };
 
 /**
@@ -190,14 +215,7 @@ export function createRuntime(opts: RuntimeOptions): Runtime {
     sessionStartTimeoutMs,
     shutdownTimeoutMs = DEFAULT_SHUTDOWN_TIMEOUT_MS,
   } = opts;
-  // Derive session mode from the provider triple: all three set ⇒ pipeline,
-  // none set ⇒ s2s. Anything in-between is a configuration error.
-  const providerCount =
-    (opts.stt != null ? 1 : 0) + (opts.llm != null ? 1 : 0) + (opts.tts != null ? 1 : 0);
-  if (providerCount !== 0 && providerCount !== 3) {
-    throw new Error("stt, llm, and tts must be set together");
-  }
-  const mode: "s2s" | "pipeline" = providerCount === 3 ? "pipeline" : "s2s";
+  const mode = assertProviderTriple(opts.stt, opts.llm, opts.tts);
   const agentConfig = toAgentConfig(agent);
   const sessions = new Map<string, Session>();
   const sinkMap = new Map<string, ClientSink>();
@@ -271,6 +289,21 @@ export function createRuntime(opts: RuntimeOptions): Runtime {
     };
   }
 
+  // Resolve pipeline providers once per runtime (not per session). Each
+  // session reuses the same opener / LanguageModel — the opener's `open()`
+  // mints the per-session stream inside.
+  const pipelineProviders =
+    mode === "pipeline"
+      ? {
+          // biome-ignore lint/style/noNonNullAssertion: mode === "pipeline" ⇒ all three set
+          stt: resolveSttIfDescriptor(opts.stt!),
+          // biome-ignore lint/style/noNonNullAssertion: mode === "pipeline" ⇒ all three set
+          llm: resolveLlmIfDescriptor(opts.llm!, env),
+          // biome-ignore lint/style/noNonNullAssertion: mode === "pipeline" ⇒ all three set
+          tts: resolveTtsIfDescriptor(opts.tts!),
+        }
+      : null;
+
   function createSession(sessionOpts: {
     id: string;
     agent: string;
@@ -279,13 +312,7 @@ export function createRuntime(opts: RuntimeOptions): Runtime {
     resumeFrom?: string;
   }): Session {
     sinkMap.set(sessionOpts.id, sessionOpts.client);
-    if (mode === "pipeline") {
-      // biome-ignore lint/style/noNonNullAssertion: providerCount === 3 ⇒ all set
-      const stt = opts.stt!;
-      // biome-ignore lint/style/noNonNullAssertion: providerCount === 3 ⇒ all set
-      const llm = opts.llm!;
-      // biome-ignore lint/style/noNonNullAssertion: providerCount === 3 ⇒ all set
-      const tts = opts.tts!;
+    if (pipelineProviders) {
       return createPipelineSession({
         id: sessionOpts.id,
         agent: sessionOpts.agent,
@@ -294,9 +321,9 @@ export function createRuntime(opts: RuntimeOptions): Runtime {
         toolSchemas,
         toolGuidance,
         executeTool,
-        stt,
-        llm,
-        tts,
+        stt: pipelineProviders.stt,
+        llm: pipelineProviders.llm,
+        tts: pipelineProviders.tts,
         sttApiKey: resolveApiKey("ASSEMBLYAI_API_KEY", env),
         ttsApiKey: resolveApiKey("CARTESIA_API_KEY", env),
         logger,