@alexkroman1/aai 1.3.2 → 1.4.0

package/dist/sdk/protocol.d.ts

@@ -63,10 +63,10 @@ export declare const SessionErrorCodeSchema: z.ZodEnum<{
     internal: "internal";
     audio: "audio";
     tool: "tool";
-    connection: "connection";
     stt: "stt";
     llm: "llm";
     tts: "tts";
+    connection: "connection";
     protocol: "protocol";
 }>;
 /**
@@ -110,10 +110,10 @@ export declare const ClientEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         internal: "internal";
         audio: "audio";
         tool: "tool";
-        connection: "connection";
         stt: "stt";
         llm: "llm";
         tts: "tts";
+        connection: "connection";
         protocol: "protocol";
     }>;
     message: z.ZodString;
@@ -192,10 +192,10 @@ export declare const ServerMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         internal: "internal";
         audio: "audio";
         tool: "tool";
-        connection: "connection";
         stt: "stt";
         llm: "llm";
         tts: "tts";
+        connection: "connection";
         protocol: "protocol";
     }>;
     message: z.ZodString;

package/dist/sdk/protocol.js

@@ -1,4 +1,4 @@
-import { f as MAX_TOOL_RESULT_CHARS } from "../constants-BL3nvg4I.js";
+import { f as MAX_TOOL_RESULT_CHARS } from "../constants-C2nirZUI.js";
 import { z } from "zod";
 //#region sdk/protocol.ts
 /**

package/dist/sdk/providers/llm/anthropic.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Anthropic LLM factory — returns a pure descriptor.
+ *
+ * Users call this in place of importing from `@ai-sdk/anthropic` directly,
+ * so agent bundles don't drag the Anthropic SDK into the guest sandbox
+ * (which has no `--allow-env` permission and would crash on the SDK's
+ * eager `ANTHROPIC_BASE_URL` read).
+ *
+ * The host-side resolver in `host/providers/resolve.ts` builds a real
+ * Vercel AI SDK `LanguageModel` from this descriptor during
+ * `createRuntime`, using `ANTHROPIC_API_KEY` from the agent's env.
+ */
+import type { LlmProvider } from "../../providers.ts";
+export declare const ANTHROPIC_KIND: "anthropic";
+export interface AnthropicOptions {
+    /** Anthropic model id, e.g. `"claude-haiku-4-5"`. */
+    model: string;
+}
+export type AnthropicProvider = LlmProvider & {
+    readonly kind: typeof ANTHROPIC_KIND;
+    readonly options: AnthropicOptions;
+};
+export declare function anthropic(opts: AnthropicOptions): AnthropicProvider;

package/dist/sdk/providers/llm-barrel.d.ts

@@ -0,0 +1,9 @@
+/**
+ * `@alexkroman1/aai/llm` subpath barrel.
+ *
+ * Re-exports LLM provider factories. Users import from here instead of
+ * `@ai-sdk/anthropic` directly so the agent bundle stays free of eager
+ * env reads and other SDK side-effects.
+ */
+export type { LlmProvider } from "../providers.ts";
+export * from "./llm/anthropic.ts";

package/dist/sdk/providers/llm-barrel.js

@@ -0,0 +1,2 @@
+import { n as anthropic, t as ANTHROPIC_KIND } from "../../anthropic-BrUCPKUc.js";
+export { ANTHROPIC_KIND, anthropic };

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

@@ -0,0 +1,30 @@
+/**
+ * AssemblyAI Universal-Streaming STT factory — returns a pure descriptor.
+ *
+ * The descriptor flows through the bundle → server → runtime pipeline
+ * without importing the `assemblyai` SDK. The host-side resolver in
+ * `host/providers/resolve.ts` turns it into an openable {@link SttOpener}
+ * during `createRuntime`.
+ */
+import type { SttProvider } from "../../providers.ts";
+/** Kind tag recognised by the host-side resolver. */
+export declare const ASSEMBLYAI_KIND: "assemblyai";
+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;
+}
+export type AssemblyAIProvider = SttProvider & {
+    readonly kind: typeof ASSEMBLYAI_KIND;
+    readonly options: AssemblyAIOptions;
+};
+/**
+ * Build an AssemblyAI STT descriptor.
+ *
+ * The API key is resolved host-side from the agent's env
+ * (`ASSEMBLYAI_API_KEY`); there is no factory-time key parameter, so the
+ * descriptor stays free of secrets and safe to serialize.
+ */
+export declare function assemblyAI(opts?: AssemblyAIOptions): AssemblyAIProvider;

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

@@ -0,0 +1,9 @@
+/**
+ * `@alexkroman1/aai/stt` subpath barrel.
+ *
+ * Re-exports the descriptor factory (`assemblyAI`) and the shared STT
+ * contract types. Importing this barrel does not pull in the `assemblyai`
+ * SDK — that happens only when the host resolver is invoked.
+ */
+export type { SttError, SttEvents, SttOpenOptions, SttProvider, SttSession } from "../providers.ts";
+export * from "./stt/assemblyai.ts";

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

@@ -0,0 +1,2 @@
+import { n as assemblyAI, t as ASSEMBLYAI_KIND } from "../../assemblyai-Cxg9eobY.js";
+export { ASSEMBLYAI_KIND, assemblyAI };

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

@@ -0,0 +1,23 @@
+/**
+ * Cartesia TTS factory — returns a pure descriptor.
+ *
+ * See `sdk/providers/stt/assemblyai.ts` for the descriptor/opener split;
+ * the host-side resolver in `host/providers/resolve.ts` turns this into an
+ * openable {@link TtsOpener} during `createRuntime` using the
+ * `CARTESIA_API_KEY` from the agent's env.
+ */
+import type { TtsProvider } from "../../providers.ts";
+export declare const CARTESIA_KIND: "cartesia";
+export interface CartesiaOptions {
+    /** Cartesia voice ID. Required. */
+    voice: string;
+    /** Model ID. Defaults to `"sonic-2"`. */
+    model?: string;
+    /** Spoken language hint. Defaults to `"en"`. */
+    language?: string;
+}
+export type CartesiaProvider = TtsProvider & {
+    readonly kind: typeof CARTESIA_KIND;
+    readonly options: CartesiaOptions;
+};
+export declare function cartesia(opts: CartesiaOptions): CartesiaProvider;

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

@@ -0,0 +1,9 @@
+/**
+ * `@alexkroman1/aai/tts` subpath barrel.
+ *
+ * Re-exports the descriptor factory (`cartesia`) and the shared TTS
+ * contract types. Does not pull in `@cartesia/cartesia-js` — the host
+ * resolver handles that at session start.
+ */
+export type { TtsError, TtsEvents, TtsOpenOptions, TtsProvider, TtsSession } from "../providers.ts";
+export * from "./tts/cartesia.ts";

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

@@ -0,0 +1,2 @@
+import { n as cartesia, t as CARTESIA_KIND } from "../../cartesia-DwDk2tEu.js";
+export { CARTESIA_KIND, cartesia };

package/dist/sdk/providers.d.ts

@@ -1,18 +1,64 @@
 /**
- * Pluggable provider interfaces — normalized seams over streaming STT / TTS
- * SDKs, plus the LLM provider type.
+ * Pluggable provider contracts.
  *
- * These are zero-runtime **type** declarations with no Node.js dependencies,
- * so they live in `sdk/` alongside the `Manifest` type that references them.
- * Concrete adapters (e.g. AssemblyAI STT, Cartesia TTS) live under
- * `host/providers/` because they depend on Node-only SDKs.
+ * **Two layers, strict boundary.**
+ *
+ * - The *descriptor* layer (`SttProvider` / `LlmProvider` / `TtsProvider`) is
+ *   pure data — `{ kind, options }` objects returned by the user-facing
+ *   factories (`assemblyAI(...)`, `anthropic(...)`, `cartesia(...)`). They
+ *   are JSON-serializable, contain no functions, and can cross the CLI →
+ *   server → guest boundary without evaluating any third-party SDK.
+ *   They live in `sdk/` alongside `Manifest` and have zero Node-only deps.
+ *
+ * - The *openable* layer (`SttOpener` / `TtsOpener` + `SttSession` /
+ *   `TtsSession`) is host-only. The host's internal
+ *   `host/providers/resolve.ts` registry turns descriptors into openers
+ *   during `createRuntime`, importing the concrete SDKs (`assemblyai`,
+ *   `@cartesia/cartesia-js`, `@ai-sdk/anthropic`) only at that point.
+ *   Only the openable layer talks to the network; descriptors never do.
+ *
+ * This split is load-bearing for the sandboxed deployment path: the guest
+ * Deno sandbox can import `@alexkroman1/aai/{stt,tts,llm}` without pulling
+ * in any AI-SDK code, which means no env reads (`ANTHROPIC_BASE_URL`, etc.)
+ * at bundle load — the exact failure mode that forced this refactor.
  */
-import type { LanguageModel } from "ai";
 /** Unsubscribe callback returned by `.on()` event subscriptions. */
 export type Unsubscribe = () => void;
+/**
+ * Base shape for a provider descriptor. A `kind` tag + opaque `options`
+ * payload lets the host registry pick the right resolver and pass the
+ * caller's options through verbatim.
+ */
+export interface ProviderDescriptor<Kind extends string, Options> {
+    readonly kind: Kind;
+    readonly options: Options;
+}
+/** Descriptor for an STT provider. Returned by factories like `assemblyAI(...)`. */
+export type SttProvider = ProviderDescriptor<string, Record<string, unknown>>;
+/** Descriptor for an LLM provider. Returned by factories like `anthropic(...)`. */
+export type LlmProvider = ProviderDescriptor<string, Record<string, unknown>>;
+/** Descriptor for a TTS provider. Returned by factories like `cartesia(...)`. */
+export type TtsProvider = ProviderDescriptor<string, Record<string, unknown>>;
+/**
+ * Session mode derived from which provider triple is set.
+ *
+ * `parseManifest`, `toAgentConfig`, `createRuntime`, and the server's
+ * `IsolateConfigSchema` all use {@link assertProviderTriple} so there's
+ * one source of truth for the validation.
+ */
+export type SessionMode = "s2s" | "pipeline";
+/**
+ * Enforce the all-or-nothing provider rule and return the derived mode.
+ *
+ * Pipeline mode requires STT, LLM, and TTS all set; S2S mode requires
+ * none of them. Anything in-between is a configuration error.
+ */
+export declare function assertProviderTriple(stt: unknown, llm: unknown, tts: unknown): SessionMode;
 export interface SttError extends Error {
     readonly code: "stt_connect_failed" | "stt_auth_failed" | "stt_stream_error";
 }
+/** Build an {@link SttError} with a typed `code`. Zero-dep helper so both sdk/ and host/ can use it. */
+export declare function makeSttError(code: SttError["code"], message: string): SttError;
 export type SttEvents = {
     /** Interim transcript; drives barge-in detection. */
     partial: (text: string) => void;
@@ -32,13 +78,16 @@ export interface SttOpenOptions {
     sttPrompt?: string | undefined;
     signal: AbortSignal;
 }
-export interface SttProvider {
+/** Host-side openable STT provider — produced by `resolveStt(descriptor)`. */
+export interface SttOpener {
     readonly name: string;
     open(opts: SttOpenOptions): Promise<SttSession>;
 }
 export interface TtsError extends Error {
     readonly code: "tts_connect_failed" | "tts_auth_failed" | "tts_stream_error";
 }
+/** Build a {@link TtsError} with a typed `code`. Mirror of {@link makeSttError}. */
+export declare function makeTtsError(code: TtsError["code"], message: string): TtsError;
 export type TtsEvents = {
     /** One PCM16 audio chunk. Orchestrator forwards to the client. */
     audio: (pcm: Int16Array) => void;
@@ -62,9 +111,8 @@ export interface TtsOpenOptions {
     apiKey: string;
     signal: AbortSignal;
 }
-export interface TtsProvider {
+/** Host-side openable TTS provider — produced by `resolveTts(descriptor)`. */
+export interface TtsOpener {
     readonly name: string;
     open(opts: TtsOpenOptions): Promise<TtsSession>;
 }
-/** LLM provider — Vercel AI SDK's `LanguageModel`; no wrapping. */
-export type LlmProvider = LanguageModel;

package/dist/types-KUgezM6u.js

@@ -0,0 +1,128 @@
+import { z } from "zod";
+//#region sdk/allowed-hosts.ts
+/**
+* Allowlist matching for outbound host validation.
+*
+* Used at deploy time (manifest validation) and at runtime (SSRF enforcement)
+* to restrict which external hosts an agent is permitted to contact.
+*
+* Lives in sdk/ because it has zero Node.js dependencies and can run in any
+* environment (browser, Deno, Node.js sandboxes).
+*/
+/** Private/special-use TLDs that must never appear in allowedHosts patterns. */
+const BLOCKED_TLDS = [
+	"local",
+	"internal",
+	"localhost"
+];
+/**
+* Regex that matches an IPv4 address (four decimal octets separated by dots).
+* Anchored so partial matches like "192.168.1.1.example.com" don't trigger it.
+*/
+const IPV4_RE = /^(\d{1,3}\.){3}\d{1,3}$/;
+function fail(reason) {
+	return {
+		valid: false,
+		reason
+	};
+}
+function checkStructural(pattern) {
+	if (pattern === "") return fail("Pattern must not be empty.");
+	if (pattern.includes("://")) return fail("Pattern must not include a protocol (e.g. remove 'https://').");
+	if (pattern.includes("/")) return fail("Pattern must not include a path component (remove '/').");
+	if (pattern.includes("?")) return fail("Pattern must not include a query string (remove '?').");
+	if (pattern.startsWith("[") || pattern.includes("::")) return fail("IP address literals are not allowed in allowedHosts patterns.");
+	if (pattern.includes(":")) return fail("Pattern must not include a port number (e.g. remove ':8080').");
+	return null;
+}
+function checkWildcard(pattern) {
+	if (!pattern.includes("*")) return null;
+	if (pattern === "*" || pattern === "**") return fail("Bare wildcard '*' is not allowed. Use '*.example.com' to allow all subdomains.");
+	if (pattern.indexOf("*") !== 0 || pattern[1] !== ".") return fail("Wildcard '*' may only appear as the leading segment (e.g. '*.example.com').");
+	if (pattern.lastIndexOf("*") !== 0) return fail("Only a single leading wildcard segment is supported.");
+	return null;
+}
+function checkHostPart(hostPart) {
+	if (IPV4_RE.test(hostPart)) return fail("IP address literals are not allowed in allowedHosts patterns.");
+	const tld = hostPart.split(".").at(-1)?.toLowerCase() ?? "";
+	if (BLOCKED_TLDS.includes(tld)) return fail(`Patterns ending in '.${tld}' are not allowed (private/special-use TLD).`);
+	return null;
+}
+/**
+* Validate a single `allowedHosts` pattern at deploy time.
+*
+* Returns `{ valid: true }` for acceptable patterns or
+* `{ valid: false; reason: string }` with a human-readable rejection reason.
+*/
+function validateAllowedHostPattern(pattern) {
+	const structural = checkStructural(pattern);
+	if (structural !== null) return structural;
+	const wildcard = checkWildcard(pattern);
+	if (wildcard !== null) return wildcard;
+	const hostCheck = checkHostPart(pattern.startsWith("*.") ? pattern.slice(2) : pattern);
+	if (hostCheck !== null) return hostCheck;
+	return { valid: true };
+}
+/**
+* Test whether `hostname` matches any pattern in `patterns`.
+*
+* - Exact match is case-insensitive; trailing dots on the hostname are stripped.
+* - Wildcard pattern `*.example.com` matches any hostname ending with
+*   `.example.com` (one or more labels), but does NOT match `example.com` itself.
+* - A port suffix on `hostname` (e.g. `api.example.com:8080`) is stripped before
+*   matching.
+* - Returns `false` when `patterns` is empty.
+*/
+function matchesAllowedHost(hostname, patterns) {
+	if (patterns.length === 0) return false;
+	const portIndex = hostname.lastIndexOf(":");
+	let host = portIndex !== -1 && !hostname.includes("[") ? hostname.slice(0, portIndex) : hostname;
+	host = host.toLowerCase().replace(/\.$/, "");
+	for (const pattern of patterns) {
+		const p = pattern.toLowerCase();
+		if (p.startsWith("*.")) {
+			const suffix = p.slice(1);
+			if (host.endsWith(suffix) && host.length > suffix.length) return true;
+		} else if (host === p) return true;
+	}
+	return false;
+}
+//#endregion
+//#region sdk/types.ts
+/**
+* Core type definitions for the AAI agent SDK.
+*/
+/**
+* Default system prompt used when `systemPrompt` is not provided.
+*
+* Optimized for voice-first interactions: short sentences, no visual
+* formatting, confident tone, and concise answers.
+*/
+const DEFAULT_SYSTEM_PROMPT = `\
+You are AAI, a helpful AI assistant.
+
+Voice-First Rules:
+- Optimize for natural speech. Avoid jargon unless central to the answer. \
+Use short, punchy sentences.
+- Never mention "search results," "sources," or "the provided text." \
+Speak as if the knowledge is your own.
+- No visual formatting. Do not say "bullet point," "bold," or "bracketed one." \
+If you need to list items, say "First," "Next," and "Finally."
+- Start with the most important information. No introductory filler.
+- Be concise. Keep answers to 1-3 sentences. For complex topics, provide a high-level summary.
+- Be confident. Avoid hedging phrases like "It seems that" or "I believe."
+- If you don't have enough information, say so directly rather than guessing.
+- Never use exclamation points. Keep your tone calm and conversational.`;
+/** Default greeting spoken when a session starts. */
+const DEFAULT_GREETING = "Hey there. I'm a voice assistant. What can I help you with?";
+/** @internal Zod schema for {@link BuiltinTool}. Exported for reuse in internal schemas. */
+const BuiltinToolSchema = z.enum([
+	"web_search",
+	"visit_webpage",
+	"fetch_json",
+	"run_code"
+]);
+/** @internal Zod schema for {@link ToolChoice}. Exported for reuse in internal schemas. */
+const ToolChoiceSchema = z.enum(["auto", "required"]);
+//#endregion
+export { matchesAllowedHost as a, ToolChoiceSchema as i, DEFAULT_GREETING as n, validateAllowedHostPattern as o, DEFAULT_SYSTEM_PROMPT as r, BuiltinToolSchema as t };

package/host/_pipeline-test-fakes.ts

@@ -19,12 +19,12 @@ import { createNanoEvents, type Emitter } from "nanoevents";
 import { vi } from "vitest";
 import type {
   SttEvents,
+  SttOpener,
   SttOpenOptions,
-  SttProvider,
   SttSession,
   TtsEvents,
+  TtsOpener,
   TtsOpenOptions,
-  TtsProvider,
   TtsSession,
 } from "../sdk/providers.ts";
 
@@ -43,7 +43,7 @@ export type FakeSttSession = SttSession & {
   ): void;
 };
 
-export type FakeSttProvider = SttProvider & {
+export type FakeSttProvider = SttOpener & {
   /** The most recently opened session, or undefined if `open()` hasn't been called. */
   last(): FakeSttSession | undefined;
   readonly sessions: FakeSttSession[];
@@ -107,7 +107,7 @@ export type FakeTtsSession = TtsSession & {
   ): void;
 };
 
-export type FakeTtsProvider = TtsProvider & {
+export type FakeTtsProvider = TtsOpener & {
   /** The most recently opened session, or undefined if `open()` hasn't been called. */
   last(): FakeTtsSession | undefined;
   readonly sessions: FakeTtsSession[];
@@ -175,7 +175,7 @@ export function createFakeTtsProvider(
 export function createFailingSttProvider(
   code: "stt_connect_failed" | "stt_auth_failed" | "stt_stream_error",
   message: string,
-): SttProvider {
+): SttOpener {
   return {
     name: "failing-stt",
     async open(): Promise<SttSession> {
@@ -192,7 +192,7 @@ export function createFailingSttProvider(
 export function createFailingTtsProvider(
   code: "tts_connect_failed" | "tts_auth_failed" | "tts_stream_error",
   message: string,
-): TtsProvider {
+): TtsOpener {
   return {
     name: "failing-tts",
     async open(): Promise<TtsSession> {

package/host/integration/pipeline-reference.integration.test.ts

@@ -27,8 +27,8 @@ import { describe, expect, test } from "vitest";
 import type { AgentConfig, ExecuteTool } from "../../sdk/_internal-types.ts";
 import type { ClientEvent, ClientSink } from "../../sdk/protocol.ts";
 import { createPipelineSession } from "../pipeline-session.ts";
-import { assemblyAI } from "../providers/stt/assemblyai.ts";
-import { cartesia } from "../providers/tts/cartesia.ts";
+import { openAssemblyAI } from "../providers/stt/assemblyai.ts";
+import { openCartesia } from "../providers/tts/cartesia.ts";
 import { consoleLogger } from "../runtime-config.ts";
 
 const here = dirname(fileURLToPath(import.meta.url));
@@ -90,9 +90,9 @@ describe.skipIf(!envReady)("pipeline integration — reference stack", () => {
       agentConfig,
       toolSchemas: [],
       executeTool,
-      stt: assemblyAI({ model: "u3pro-rt" }),
+      stt: openAssemblyAI({ model: "u3pro-rt" }),
       llm: openai("gpt-4o-mini"),
-      tts: cartesia({ voice: "694f9389-aac1-45b6-b726-9d9369183238" }),
+      tts: openCartesia({ voice: "694f9389-aac1-45b6-b726-9d9369183238" }),
       // biome-ignore lint/style/noNonNullAssertion: envReady guard ensures presence
       sttApiKey: process.env.ASSEMBLYAI_API_KEY!,
       // biome-ignore lint/style/noNonNullAssertion: envReady guard ensures presence

package/host/pipeline-session.ts

@@ -14,10 +14,10 @@ import { DEFAULT_STT_SAMPLE_RATE, PIPELINE_FLUSH_TIMEOUT_MS } from "../sdk/const
 import type { ClientSink, SessionErrorCode } from "../sdk/protocol.ts";
 import type {
   SttError,
-  SttProvider,
+  SttOpener,
   SttSession,
   TtsError,
-  TtsProvider,
+  TtsOpener,
   TtsSession,
   Unsubscribe,
 } from "../sdk/providers.ts";
@@ -45,12 +45,12 @@ export interface PipelineSessionOptions {
   toolGuidance?: readonly string[] | undefined;
   /** Function to invoke tools by name. */
   executeTool: ExecuteTool;
-  /** STT provider (injected via manifest in pipeline mode). */
-  stt: SttProvider;
+  /** STT opener (resolved from an {@link SttProvider} descriptor). */
+  stt: SttOpener;
   /** LLM provider (Vercel AI SDK `LanguageModel`). */
   llm: LanguageModel;
-  /** TTS provider (injected via manifest in pipeline mode). */
-  tts: TtsProvider;
+  /** TTS opener (resolved from a {@link TtsProvider} descriptor). */
+  tts: TtsOpener;
   /** STT API key. */
   sttApiKey: string;
   /** TTS API key. */

package/host/providers/providers.test-d.ts

@@ -1,12 +1,25 @@
 // Copyright 2025 the AAI authors. MIT license.
-import type { LanguageModel } from "ai";
 import { expectTypeOf, test } from "vitest";
-import type { LlmProvider } from "./llm.ts";
-import type { SttEvents, SttProvider, SttSession, Unsubscribe } from "./stt.ts";
-import type { TtsEvents, TtsSession } from "./tts.ts";
+import type {
+  LlmProvider,
+  SttEvents,
+  SttOpener,
+  SttProvider,
+  SttSession,
+  TtsEvents,
+  TtsProvider,
+  TtsSession,
+  Unsubscribe,
+} from "../../sdk/providers.ts";
 
-test("SttProvider.open returns Promise<SttSession>", () => {
-  expectTypeOf<SttProvider["open"]>().returns.toEqualTypeOf<Promise<SttSession>>();
+test("Descriptors are { kind, options } data", () => {
+  expectTypeOf<SttProvider>().toMatchTypeOf<{ kind: string; options: Record<string, unknown> }>();
+  expectTypeOf<LlmProvider>().toMatchTypeOf<{ kind: string; options: Record<string, unknown> }>();
+  expectTypeOf<TtsProvider>().toMatchTypeOf<{ kind: string; options: Record<string, unknown> }>();
+});
+
+test("SttOpener.open returns Promise<SttSession>", () => {
+  expectTypeOf<SttOpener["open"]>().returns.toEqualTypeOf<Promise<SttSession>>();
 });
 
 test("SttEvents.partial takes a string", () => {
@@ -21,10 +34,6 @@ test("TtsEvents.audio takes Int16Array", () => {
   expectTypeOf<TtsEvents["audio"]>().parameters.toEqualTypeOf<[Int16Array]>();
 });
 
-test("LlmProvider is Vercel AI SDK's LanguageModel", () => {
-  expectTypeOf<LlmProvider>().toEqualTypeOf<LanguageModel>();
-});
-
 test("Stt/Tts on() returns Unsubscribe", () => {
   expectTypeOf<SttSession["on"]>().returns.toEqualTypeOf<Unsubscribe>();
   expectTypeOf<TtsSession["on"]>().returns.toEqualTypeOf<Unsubscribe>();

package/host/providers/resolve.ts

@@ -0,0 +1,87 @@
+// 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.");
+      }
+      return createAnthropic({ apiKey })(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,