@alexkroman1/aai 1.4.5 → 1.5.1

package/dist/host/runtime.d.ts

@@ -14,7 +14,7 @@ import { type LlmProvider, type SttOpener, type SttProvider, type TtsOpener, typ
 import type { AgentDef } from "../sdk/types.ts";
 import type { Logger, S2SConfig } from "./runtime-config.ts";
 import type { CreateS2sWebSocket } from "./s2s.ts";
-import { type Session } from "./session.ts";
+import { type SessionCore } from "./session-core.ts";
 import { type ExecuteTool } from "./tool-executor.ts";
 import { type SessionWebSocket } from "./ws-handler.ts";
 /** Per-session options passed to {@link AgentRuntime.startSession}. */
@@ -132,7 +132,7 @@ export type Runtime = AgentRuntime & {
         client: ClientSink;
         skipGreeting?: boolean;
         resumeFrom?: string;
-    }): Session;
+    }): SessionCore;
 };
 /**
  * Create an agent runtime — the execution engine for a voice agent.

package/dist/host/s2s.d.ts

@@ -2,7 +2,6 @@
  * Speech-to-Speech WebSocket client for AssemblyAI's S2S API.
  */
 import type { JSONSchema7 } from "json-schema";
-import { type Unsubscribe } from "nanoevents";
 import type { ClientEvent } from "../sdk/protocol.ts";
 import type { Logger, S2SConfig } from "./runtime-config.ts";
 export type S2sWebSocket = {
@@ -44,23 +43,23 @@ export type S2sToolSchema = {
     description: string;
     parameters: JSONSchema7;
 };
-export type S2sEvents = {
-    ready: (detail: {
-        sessionId: string;
-    }) => void;
-    replyStarted: (detail: {
-        replyId: string;
-    }) => void;
-    sessionExpired: () => void;
-    event: (event: S2sEvent) => void;
-    audio: (detail: {
-        audio: Uint8Array;
-    }) => void;
-    error: (err: Error) => void;
-    close: (code: number, reason: string) => void;
+/** Callbacks fired into the owning session at construction time. */
+export type S2sCallbacks = {
+    onSessionReady(sessionId: string): void;
+    onReplyStarted(replyId: string): void;
+    onReplyDone(): void;
+    onCancelled(): void;
+    onAudio(bytes: Uint8Array): void;
+    onUserTranscript(text: string): void;
+    onAgentTranscript(text: string, interrupted: boolean): void;
+    onToolCall(callId: string, name: string, args: Record<string, unknown>): void;
+    onSpeechStarted(): void;
+    onSpeechStopped(): void;
+    onSessionExpired(): void;
+    onError(err: Error): void;
+    onClose(code: number, reason: string): void;
 };
 export type S2sHandle = {
-    on<K extends keyof S2sEvents>(event: K, cb: S2sEvents[K]): Unsubscribe;
     sendAudio(audio: Uint8Array): void;
     /**
      * Send a pre-encoded audio wire frame. For perf-critical callers (load tests)
@@ -76,6 +75,7 @@ export type ConnectS2sOptions = {
     apiKey: string;
     config: S2SConfig;
     createWebSocket: CreateS2sWebSocket;
+    callbacks: S2sCallbacks;
     logger?: Logger;
     /**
      * Session id attached to diagnostic log lines (e.g. raw `reply.done`

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

@@ -0,0 +1,37 @@
+import type { AgentConfig, ExecuteTool } from "../sdk/_internal-types.ts";
+import type { ClientSink, SessionErrorCode } from "../sdk/protocol.ts";
+import type { Message } from "../sdk/types.ts";
+import type { Logger } from "./runtime-config.ts";
+import type { Transport } from "./transports/types.ts";
+export type SessionCoreOptions = {
+    id: string;
+    agent: string;
+    client: ClientSink;
+    agentConfig: AgentConfig;
+    executeTool: ExecuteTool;
+    transport: Transport;
+    logger?: Logger;
+    maxHistory?: number;
+};
+export type SessionCore = {
+    readonly id: string;
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    onAudio(bytes: Uint8Array): void;
+    onAudioReady(): void;
+    onCancel(): void;
+    onReset(): void;
+    onHistory(messages: readonly Message[]): void;
+    onReplyStarted(replyId: string): void;
+    onReplyDone(): void;
+    onCancelled(): void;
+    onAudioChunk(bytes: Uint8Array): void;
+    onAudioDone(): void;
+    onUserTranscript(text: string): void;
+    onAgentTranscript(text: string, interrupted: boolean): void;
+    onToolCall(callId: string, name: string, args: Record<string, unknown>): void;
+    onError(code: SessionErrorCode, message: string): void;
+    onSpeechStarted(): void;
+    onSpeechStopped(): void;
+};
+export declare function createSessionCore(opts: SessionCoreOptions): SessionCore;

package/dist/host/transports/pipeline-transport.d.ts

@@ -0,0 +1,48 @@
+import type { LanguageModel } from "ai";
+import type { ExecuteTool, ToolSchema } from "../../sdk/_internal-types.ts";
+import type { SttOpener, TtsOpener } from "../../sdk/providers.ts";
+import type { ToolChoice } from "../../sdk/types.ts";
+import { type Logger } from "../runtime-config.ts";
+import type { Transport, TransportCallbacks, TransportSessionConfig } from "./types.ts";
+/** Configuration for {@link createPipelineTransport}. */
+export interface PipelineTransportOptions {
+    /** Unique session identifier. */
+    sid: string;
+    /** Agent slug. */
+    agent: string;
+    /** STT opener (resolved from an SttProvider descriptor). */
+    stt: SttOpener;
+    /** LLM provider (Vercel AI SDK LanguageModel). */
+    llm: LanguageModel;
+    /** TTS opener (resolved from a TtsProvider descriptor). */
+    tts: TtsOpener;
+    /** Transport-level callbacks into SessionCore. */
+    callbacks: TransportCallbacks;
+    /** Session config: systemPrompt, greeting, tools, history. */
+    sessionConfig: TransportSessionConfig;
+    /** Tool schemas (JSON Schema) for Vercel AI tool binding. */
+    toolSchemas?: readonly ToolSchema[];
+    /** Agent's tool-execution function. */
+    executeTool?: ExecuteTool;
+    /** Provider-specific API keys. */
+    providerKeys: {
+        stt: string;
+        tts: string;
+    };
+    /** STT audio input sample rate (PCM16, Hz). Defaults to DEFAULT_STT_SAMPLE_RATE. */
+    sttSampleRate?: number | undefined;
+    /** TTS audio output sample rate (PCM16, Hz). Defaults to DEFAULT_TTS_SAMPLE_RATE. */
+    ttsSampleRate?: number | undefined;
+    /** Optional STT prompt injected via SttOpenOptions.sttPrompt. */
+    sttPrompt?: string | undefined;
+    /** Max LLM tool-call steps per turn. Defaults to 5. */
+    maxSteps?: number | undefined;
+    /** Tool selection policy passed to `streamText`. Defaults to `"auto"`. */
+    toolChoice?: ToolChoice | undefined;
+    /** Logger. Defaults to consoleLogger. */
+    logger?: Logger | undefined;
+    /** Skip the initial greeting (used for session resume). */
+    skipGreeting?: boolean | undefined;
+}
+/** Create a pipeline-mode Transport (STT → LLM → TTS). */
+export declare function createPipelineTransport(opts: PipelineTransportOptions): Transport;

package/dist/host/transports/s2s-transport.d.ts

@@ -0,0 +1,19 @@
+import type { Logger, S2SConfig } from "../runtime-config.ts";
+import { type CreateS2sWebSocket, connectS2s, type S2sSessionConfig, type S2sToolSchema } from "../s2s.ts";
+import type { Transport, TransportCallbacks } from "./types.ts";
+/** @internal Exposed for testing — allows spying on connectS2s in unit tests. */
+export declare const _internals: {
+    connectS2s: typeof connectS2s;
+};
+export type S2sTransportOptions = {
+    apiKey: string;
+    s2sConfig: S2SConfig;
+    sessionConfig: S2sSessionConfig;
+    toolSchemas: S2sToolSchema[];
+    callbacks: TransportCallbacks;
+    sid: string;
+    agent: string;
+    createWebSocket?: CreateS2sWebSocket;
+    logger?: Logger;
+};
+export declare function createS2sTransport(opts: S2sTransportOptions): Transport;

package/dist/host/transports/types.d.ts

@@ -0,0 +1,45 @@
+import type { SessionErrorCode } from "../../sdk/protocol.ts";
+import type { Message } from "../../sdk/types.ts";
+/**
+ * Typed callbacks into the SessionCore. One per event the transport produces.
+ * Constructed at transport-creation time; no emitter.on-style indirection.
+ */
+export type TransportCallbacks = {
+    onReplyStarted(replyId: string): void;
+    onReplyDone(): void;
+    onCancelled(): void;
+    onAudioChunk(bytes: Uint8Array): void;
+    onAudioDone(): void;
+    onUserTranscript(text: string): void;
+    onAgentTranscript(text: string, interrupted: boolean): void;
+    onToolCall(callId: string, name: string, args: Record<string, unknown>): void;
+    onError(code: SessionErrorCode, message: string): void;
+    onSpeechStarted(): void;
+    onSpeechStopped(): void;
+    onSessionReady?(providerSessionId: string): void;
+};
+/** Minimal config a transport may receive at construction time. */
+export type TransportSessionConfig = {
+    systemPrompt: string;
+    greeting?: string;
+    tools?: unknown[];
+    history?: Message[];
+};
+/**
+ * Transport abstraction — one implementation per provider strategy
+ * (see `s2s-transport.ts`, `pipeline-transport.ts`).
+ */
+export interface Transport {
+    /** Open any underlying connections and send initial session config. */
+    start(): Promise<void>;
+    /** Tear down, flush, close. Idempotent. */
+    stop(): Promise<void>;
+    /** Forward user audio to the provider. */
+    sendUserAudio(bytes: Uint8Array): void;
+    /** Forward a tool result back to the provider's reply stream. */
+    sendToolResult(callId: string, result: string): void;
+    /** Cancel the currently in-flight reply (barge-in / client cancel). */
+    cancelReply(): void;
+    /** Re-send session config (S2S only; pipeline is a no-op). */
+    updateSession?(config: TransportSessionConfig): void;
+}

package/dist/host/ws-handler.d.ts

@@ -3,9 +3,9 @@
  *
  * Audio validation is handled at the host transport layer (see server.ts).
  */
-import type { ClientSink, ReadyConfig } from "../sdk/protocol.ts";
+import { type ClientSink } from "../sdk/protocol.ts";
 import type { Logger } from "./runtime-config.ts";
-import type { Session } from "./session.ts";
+import type { SessionCore } from "./session-core.ts";
 /**
  * Minimal WebSocket interface accepted by {@link wireSessionSocket}.
  *
@@ -25,11 +25,15 @@ export type SessionWebSocket = {
 /** Options for wiring a WebSocket to a session. */
 export type WsSessionOptions = {
     /** Map of active sessions (session is added on open, removed on close). */
-    sessions: Map<string, Session>;
+    sessions: Map<string, SessionCore>;
     /** Factory function to create a session for a given ID and client sink. */
-    createSession: (sessionId: string, client: ClientSink) => Session;
+    createSession: (sessionId: string, client: ClientSink) => SessionCore;
     /** Protocol config sent to the client immediately on connect. */
-    readyConfig: ReadyConfig;
+    readyConfig: {
+        audioFormat: "pcm16";
+        sampleRate: number;
+        ttsSampleRate: number;
+    };
     /** Additional key-value pairs included in log messages. */
     logContext?: Record<string, string>;
     /** Callback invoked when the WebSocket connection opens. */
@@ -48,12 +52,12 @@ export type WsSessionOptions = {
     resumeFrom?: string;
 };
 /**
- * Attaches session lifecycle handlers to a native WebSocket using
- * plain JSON text frames and binary audio frames.
+ * Attaches session lifecycle handlers to a native WebSocket using JSON text
+ * frames for control messages and raw PCM16 binary frames for audio.
  *
  * Connection flow:
- * 1. WebSocket opens → server sends `{ type: "config", ...ReadyConfig }`
- * 2. Client sets up audio → sends `{ type: "audio_ready" }`
- * 3. If reconnecting → client sends `{ type: "history", messages: [...] }`
+ * 1. WebSocket opens → server sends JSON CONFIG frame with sampleRate, ttsSampleRate, sessionId
+ * 2. Client sets up audio → sends JSON AUDIO_READY frame
+ * 3. If reconnecting → client sends JSON HISTORY frame with prior messages
  */
 export declare function wireSessionSocket(ws: SessionWebSocket, opts: WsSessionOptions): void;

package/dist/sdk/_internal-types.d.ts

@@ -104,12 +104,14 @@ export declare function toAgentConfig(src: AgentConfigSource): AgentConfig;
  * etc.) — the Vercel AI SDK wraps it via `jsonSchema()`.
  */
 export declare const ToolSchemaSchema: z.ZodObject<{
+    type: z.ZodLiteral<"function">;
     name: z.ZodString;
     description: z.ZodString;
     parameters: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 }, z.core.$strip>;
 /** Serialized tool schema — derived from {@link ToolSchemaSchema}. */
 export type ToolSchema = {
+    type: "function";
     name: string;
     description: string;
     parameters: JSONSchema7;

package/dist/sdk/manifest-barrel.js

@@ -1,2 +1,2 @@
-import { a as toAgentConfig, i as agentToolsToSchemas, n as EMPTY_PARAMS, o as ProviderDescriptorSchema, r as ToolSchemaSchema, s as assertProviderTriple, t as AgentConfigSchema } from "../_internal-types-3p3OJZPb.js";
+import { a as toAgentConfig, i as agentToolsToSchemas, n as EMPTY_PARAMS, o as ProviderDescriptorSchema, r as ToolSchemaSchema, s as assertProviderTriple, t as AgentConfigSchema } from "../_internal-types-DFL07G3f.js";
 export { AgentConfigSchema, EMPTY_PARAMS, ProviderDescriptorSchema, ToolSchemaSchema, agentToolsToSchemas, assertProviderTriple, toAgentConfig };

package/dist/sdk/protocol.d.ts

@@ -127,16 +127,17 @@ export type ClientEvent = z.infer<typeof ClientEventSchema>;
 /**
  * Typed interface for pushing session events to a connected client.
  *
- * For WebSocket sessions this sends JSON text frames and binary audio frames.
+ * Events (`event`, `playAudioDone`) send JSON text frames. Audio chunks
+ * (`playAudioChunk`) send raw PCM16 binary frames.
  */
 export interface ClientSink {
-    /** Whether the underlying connection is open and accepting calls. */
+    /** True when the underlying connection is open and will accept calls. */
     readonly open: boolean;
-    /** Push a session event to the client. */
+    /** Push a session event (JSON text frame) to the client. */
     event(e: ClientEvent): void;
-    /** Send a single TTS audio chunk to the client. */
+    /** Send a single PCM16 audio chunk (raw binary frame) to the client. */
     playAudioChunk(chunk: Uint8Array): void;
-    /** Signal that TTS audio is complete. */
+    /** Signal that TTS audio is complete (JSON text frame). */
     playAudioDone(): void;
 }
 /** Zod schema for {@link ReadyConfig}. */

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

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

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

@@ -0,0 +1,35 @@
+/**
+ * Deepgram Nova streaming STT factory — returns a pure descriptor.
+ *
+ * The descriptor flows through the bundle → server → runtime pipeline
+ * without importing the `@deepgram/sdk` package. 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 DEEPGRAM_KIND: "deepgram";
+export interface DeepgramOptions {
+    /**
+     * Streaming speech model. Defaults to `"nova-3"`. Any string is forwarded
+     * to the SDK unchanged, which allows opt-in to future models.
+     */
+    model?: "nova-3" | "nova-2" | string;
+    /**
+     * BCP-47 language code for transcription. Defaults to `"en"`.
+     * Examples: `"en"`, `"es"`, `"fr"`, `"de"`.
+     */
+    language?: string;
+}
+export type DeepgramProvider = SttProvider & {
+    readonly kind: typeof DEEPGRAM_KIND;
+    readonly options: DeepgramOptions;
+};
+/**
+ * Build a Deepgram STT descriptor.
+ *
+ * The API key is resolved host-side from the agent's env
+ * (`DEEPGRAM_API_KEY`); there is no factory-time key parameter, so the
+ * descriptor stays free of secrets and safe to serialize.
+ */
+export declare function deepgram(opts?: DeepgramOptions): DeepgramProvider;

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

@@ -7,3 +7,4 @@
  */
 export type { SttError, SttEvents, SttOpenOptions, SttProvider, SttSession } from "../providers.ts";
 export * from "./stt/assemblyai.ts";
+export * from "./stt/deepgram.ts";

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

@@ -1,2 +1,2 @@
-import { n as assemblyAI, t as ASSEMBLYAI_KIND } from "../../assemblyai-Cxg9eobY.js";
-export { ASSEMBLYAI_KIND, assemblyAI };
+import { i as deepgram, n as assemblyAI, r as DEEPGRAM_KIND, t as ASSEMBLYAI_KIND } from "../../assemblyai-C969QGi4.js";
+export { ASSEMBLYAI_KIND, DEEPGRAM_KIND, assemblyAI, deepgram };

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

@@ -8,9 +8,15 @@
  */
 import type { TtsProvider } from "../../providers.ts";
 export declare const CARTESIA_KIND: "cartesia";
+/**
+ * Default voice used when callers invoke `cartesia()` with no `voice`. This
+ * is the same voice the example templates ship with, so a bare `cartesia()`
+ * works out of the box for new agents.
+ */
+export declare const CARTESIA_DEFAULT_VOICE = "f786b574-daa5-4673-aa0c-cbe3e8534c02";
 export interface CartesiaOptions {
-    /** Cartesia voice ID. Required. */
-    voice: string;
+    /** Cartesia voice ID. Defaults to {@link CARTESIA_DEFAULT_VOICE}. */
+    voice?: string;
     /** Model ID. Defaults to `"sonic-2"`. */
     model?: string;
     /** Spoken language hint. Defaults to `"en"`. */
@@ -18,6 +24,8 @@ export interface CartesiaOptions {
 }
 export type CartesiaProvider = TtsProvider & {
     readonly kind: typeof CARTESIA_KIND;
-    readonly options: CartesiaOptions;
+    readonly options: CartesiaOptions & {
+        voice: string;
+    };
 };
-export declare function cartesia(opts: CartesiaOptions): CartesiaProvider;
+export declare function cartesia(opts?: CartesiaOptions): CartesiaProvider;

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

@@ -0,0 +1,42 @@
+/**
+ * Rime 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
+ * `RIME_API_KEY` from the agent's env.
+ *
+ * Language codes follow ISO 639-3 (three-letter): `"eng"`, `"fra"`, etc.
+ * This differs from many APIs that use ISO 639-1 two-letter codes like `"en"`.
+ */
+import type { TtsProvider } from "../../providers.ts";
+export declare const RIME_KIND: "rime";
+/**
+ * Default Rime speaker used when callers invoke `rime()` with no `voice`.
+ * `cove` is a `mistv2` speaker, matching the default model below — so a
+ * bare `rime()` works out of the box for new agents.
+ */
+export declare const RIME_DEFAULT_VOICE = "cove";
+export interface RimeOptions {
+    /** Rime speaker ID. Defaults to {@link RIME_DEFAULT_VOICE}. */
+    voice?: string;
+    /**
+     * Rime model ID. Defaults to `"mistv2"` (Rime's most compatible model).
+     * Common values: `"mistv2"`, `"arcana"`.
+     */
+    model?: "mistv2" | "arcana" | string;
+    /**
+     * Spoken language. Uses ISO 639-3 (three-letter codes).
+     * Defaults to `"eng"` (English).
+     *
+     * Note: Rime uses 3-letter codes — use `"eng"` not `"en"`.
+     */
+    language?: string;
+}
+export type RimeProvider = TtsProvider & {
+    readonly kind: typeof RIME_KIND;
+    readonly options: RimeOptions & {
+        voice: string;
+    };
+};
+export declare function rime(opts?: RimeOptions): RimeProvider;

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

@@ -7,3 +7,4 @@
  */
 export type { TtsError, TtsEvents, TtsOpenOptions, TtsProvider, TtsSession } from "../providers.ts";
 export * from "./tts/cartesia.ts";
+export * from "./tts/rime.ts";

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

@@ -1,2 +1,2 @@
-import { n as cartesia, t as CARTESIA_KIND } from "../../cartesia-DwDk2tEu.js";
-export { CARTESIA_KIND, cartesia };
+import { a as RIME_KIND, i as RIME_DEFAULT_VOICE, n as CARTESIA_KIND, o as rime, r as cartesia, t as CARTESIA_DEFAULT_VOICE } from "../../cartesia-BfQPOQ7Y.js";
+export { CARTESIA_DEFAULT_VOICE, CARTESIA_KIND, RIME_DEFAULT_VOICE, RIME_KIND, cartesia, rime };

package/host/_pipeline-test-fakes.ts

@@ -326,21 +326,24 @@ export function createFakeLanguageModel(
   options:
     | { script: ScriptedPart[]; delayMs?: number }
     | { steps: ScriptedPart[][]; delayMs?: number },
-): LanguageModel {
+): LanguageModel & { readonly calls: readonly Record<string, unknown>[] } {
   const delayMs = options.delayMs;
   const steps: ScriptedPart[][] = "steps" in options ? options.steps : [options.script];
   let stepIndex = 0;
+  const calls: Record<string, unknown>[] = [];
   const model = {
     specificationVersion: "v3" as const,
     provider: "fake-llm",
     modelId: "fake-llm-1",
     supportedUrls: {} as Record<string, RegExp[]>,
+    calls,
     async doGenerate(): Promise<never> {
       throw new Error("fake LLM: doGenerate not implemented");
     },
-    async doStream(opts: { abortSignal?: AbortSignal }): Promise<{
+    async doStream(opts: Record<string, unknown> & { abortSignal?: AbortSignal }): Promise<{
       stream: ReadableStream<StreamPart>;
     }> {
+      calls.push(opts);
       // Advance one step per call; after the last scripted step, keep
       // yielding an empty step so an unexpected extra call completes cleanly.
       const current = steps[stepIndex] ?? [];
@@ -353,5 +356,5 @@ export function createFakeLanguageModel(
       return { stream };
     },
   };
-  return model as unknown as LanguageModel;
+  return model as unknown as LanguageModel & { readonly calls: readonly Record<string, unknown>[] };
 }