@alexkroman1/aai 0.9.2 → 0.10.0

package/dist/protocol.d.ts

@@ -21,15 +21,7 @@ export declare const DEFAULT_TTS_SAMPLE_RATE = 24000;
  *
  * All audio frames are 16-bit signed PCM, little-endian, mono.
  */
-export declare const AUDIO_FORMAT: "pcm16";
-/** Specification for binary audio frames exchanged over WebSocket. */
-export declare const AudioFrameSpec: {
-    readonly format: "pcm16";
-    readonly bitsPerSample: 16;
-    readonly endianness: "little";
-    readonly channels: 1;
-    readonly bytesPerSample: 2;
-};
+export declare const AUDIO_FORMAT = "pcm16";
 /** Zod schema for KV operation requests from the worker to the host. */
 export declare const KvRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     op: z.ZodLiteral<"get">;
@@ -38,7 +30,7 @@ export declare const KvRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     op: z.ZodLiteral<"set">;
     key: z.ZodString;
     value: z.ZodString;
-    ttl: z.ZodOptional<z.ZodNumber>;
+    expireIn: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>, z.ZodObject<{
     op: z.ZodLiteral<"del">;
     key: z.ZodString;
@@ -57,14 +49,19 @@ export type KvRequest = z.infer<typeof KvRequestSchema>;
 export declare const HOOK_TIMEOUT_MS = 5000;
 /** Default timeout for tool execution in the worker. */
 export declare const TOOL_EXECUTION_TIMEOUT_MS = 30000;
-/** Zod schema for session error codes. */
+/** Maximum length for tool result strings sent to clients. */
+export declare const MAX_TOOL_RESULT_CHARS = 4000;
+/**
+ * Zod schema for session error codes.
+ * @public
+ */
 export declare const SessionErrorCodeSchema: z.ZodEnum<{
     tool: "tool";
-    connection: "connection";
     stt: "stt";
     llm: "llm";
     tts: "tts";
     protocol: "protocol";
+    connection: "connection";
     audio: "audio";
     internal: "internal";
 }>;
@@ -99,6 +96,10 @@ export declare const ClientEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     toolCallId: z.ZodString;
     toolName: z.ZodString;
     args: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"tool_call_update">;
+    toolCallId: z.ZodString;
+    data: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"tool_call_done">;
     toolCallId: z.ZodString;
@@ -109,15 +110,17 @@ export declare const ClientEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"cancelled">;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"reset">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"idle_timeout">;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"error">;
     code: z.ZodEnum<{
         tool: "tool";
-        connection: "connection";
         stt: "stt";
         llm: "llm";
         tts: "tts";
         protocol: "protocol";
+        connection: "connection";
         audio: "audio";
         internal: "internal";
     }>;
@@ -142,18 +145,23 @@ export interface ClientSink {
 }
 /** Supported audio formats for the wire protocol. */
 export type AudioFormatId = "pcm16";
+/** Zod schema for {@link ReadyConfig}. */
+export declare const ReadyConfigSchema: z.ZodObject<{
+    audioFormat: z.ZodEnum<{
+        pcm16: "pcm16";
+    }>;
+    sampleRate: z.ZodNumber;
+    ttsSampleRate: z.ZodNumber;
+}, z.core.$strip>;
 /** Protocol-level session config returned to the client on connect. */
-export type ReadyConfig = {
-    audioFormat: AudioFormatId;
-    sampleRate: number;
-    ttsSampleRate: number;
-};
+export type ReadyConfig = z.infer<typeof ReadyConfigSchema>;
 /** Zod schema for server→client text messages. */
 export declare const ServerMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"config">;
     audioFormat: z.ZodString;
     sampleRate: z.ZodNumber;
     ttsSampleRate: z.ZodNumber;
+    sessionId: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"audio_done">;
 }, z.core.$strip>, z.ZodObject<{
@@ -180,6 +188,10 @@ export declare const ServerMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     toolCallId: z.ZodString;
     toolName: z.ZodString;
     args: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"tool_call_update">;
+    toolCallId: z.ZodString;
+    data: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"tool_call_done">;
     toolCallId: z.ZodString;
@@ -190,15 +202,17 @@ export declare const ServerMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"cancelled">;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"reset">;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"idle_timeout">;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"error">;
     code: z.ZodEnum<{
         tool: "tool";
-        connection: "connection";
         stt: "stt";
         llm: "llm";
         tts: "tts";
         protocol: "protocol";
+        connection: "connection";
         audio: "audio";
         internal: "internal";
     }>;
@@ -220,13 +234,19 @@ export declare const ClientMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
             user: "user";
             assistant: "assistant";
         }>;
-        text: z.ZodString;
+        content: z.ZodString;
     }, z.core.$strip>>;
 }, z.core.$strip>], "type">;
 /** Client→server text messages (binary frames carry raw PCM16 audio). */
 export type ClientMessage = z.infer<typeof ClientMessageSchema>;
+/** Build the protocol-level session config from S2S sample rates. */
+export declare function buildReadyConfig(s2sConfig: {
+    inputSampleRate: number;
+    outputSampleRate: number;
+}): ReadyConfig;
+/** Zod schema for {@link TurnConfig}. */
+export declare const TurnConfigSchema: z.ZodObject<{
+    maxSteps: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
 /** Combined turn configuration resolved from the worker before a turn starts. */
-export type TurnConfig = {
-    maxSteps?: number;
-    activeTools?: string[];
-};
+export type TurnConfig = z.infer<typeof TurnConfigSchema>;

package/dist/protocol.js

@@ -23,14 +23,6 @@ const DEFAULT_TTS_SAMPLE_RATE = 24e3;
 * All audio frames are 16-bit signed PCM, little-endian, mono.
 */
 const AUDIO_FORMAT = "pcm16";
-/** Specification for binary audio frames exchanged over WebSocket. */
-const AudioFrameSpec = {
-	format: AUDIO_FORMAT,
-	bitsPerSample: 16,
-	endianness: "little",
-	channels: 1,
-	bytesPerSample: 2
-};
 /** Zod schema for KV operation requests from the worker to the host. */
 const KvRequestSchema = z.discriminatedUnion("op", [
 	z.object({
@@ -41,7 +33,7 @@ const KvRequestSchema = z.discriminatedUnion("op", [
 		op: z.literal("set"),
 		key: z.string().min(1),
 		value: z.string(),
-		ttl: z.number().int().positive().optional()
+		expireIn: z.number().int().positive().optional()
 	}),
 	z.object({
 		op: z.literal("del"),
@@ -62,7 +54,12 @@ const KvRequestSchema = z.discriminatedUnion("op", [
 const HOOK_TIMEOUT_MS = 5e3;
 /** Default timeout for tool execution in the worker. */
 const TOOL_EXECUTION_TIMEOUT_MS = 3e4;
-/** Zod schema for session error codes. */
+/** Maximum length for tool result strings sent to clients. */
+const MAX_TOOL_RESULT_CHARS = 4e3;
+/**
+* Zod schema for session error codes.
+* @public
+*/
 const SessionErrorCodeSchema = z.enum([
 	"stt",
 	"llm",
@@ -100,27 +97,40 @@ const ClientEventSchema = z.discriminatedUnion("type", [
 		toolName: z.string(),
 		args: z.record(z.string(), z.unknown())
 	}),
+	z.object({
+		type: z.literal("tool_call_update"),
+		toolCallId: z.string(),
+		data: z.string().max(MAX_TOOL_RESULT_CHARS)
+	}),
 	z.object({
 		type: z.literal("tool_call_done"),
 		toolCallId: z.string(),
-		result: z.string().max(4e3)
+		result: z.string().max(MAX_TOOL_RESULT_CHARS)
 	}),
 	ev("tts_done"),
 	ev("cancelled"),
 	ev("reset"),
+	ev("idle_timeout"),
 	z.object({
 		type: z.literal("error"),
 		code: SessionErrorCodeSchema,
 		message: z.string()
 	})
 ]);
+/** Zod schema for {@link ReadyConfig}. */
+const ReadyConfigSchema = z.object({
+	audioFormat: z.enum(["pcm16"]),
+	sampleRate: z.number().int().positive(),
+	ttsSampleRate: z.number().int().positive()
+});
 /** Zod schema for server→client text messages. */
 const ServerMessageSchema = z.discriminatedUnion("type", [
 	z.object({
 		type: z.literal("config"),
 		audioFormat: z.string(),
 		sampleRate: z.number(),
-		ttsSampleRate: z.number()
+		ttsSampleRate: z.number(),
+		sessionId: z.string().optional()
 	}),
 	ev("audio_done"),
 	...ClientEventSchema.options
@@ -134,9 +144,19 @@ const ClientMessageSchema = z.discriminatedUnion("type", [
 		type: z.literal("history"),
 		messages: z.array(z.object({
 			role: z.enum(["user", "assistant"]),
-			text: z.string().max(1e5)
+			content: z.string().max(1e5)
 		})).max(200)
 	})
 ]);
+/** Build the protocol-level session config from S2S sample rates. */
+function buildReadyConfig(s2sConfig) {
+	return {
+		audioFormat: AUDIO_FORMAT,
+		sampleRate: s2sConfig.inputSampleRate,
+		ttsSampleRate: s2sConfig.outputSampleRate
+	};
+}
+/** Zod schema for {@link TurnConfig}. */
+const TurnConfigSchema = z.object({ maxSteps: z.number().int().positive().optional() });
 //#endregion
-export { AUDIO_FORMAT, AudioFrameSpec, ClientEventSchema, ClientMessageSchema, DEFAULT_STT_SAMPLE_RATE, DEFAULT_TTS_SAMPLE_RATE, HOOK_TIMEOUT_MS, KvRequestSchema, ServerMessageSchema, SessionErrorCodeSchema, TOOL_EXECUTION_TIMEOUT_MS };
+export { AUDIO_FORMAT, ClientEventSchema, ClientMessageSchema, DEFAULT_STT_SAMPLE_RATE, DEFAULT_TTS_SAMPLE_RATE, HOOK_TIMEOUT_MS, KvRequestSchema, MAX_TOOL_RESULT_CHARS, ReadyConfigSchema, ServerMessageSchema, SessionErrorCodeSchema, TOOL_EXECUTION_TIMEOUT_MS, TurnConfigSchema, buildReadyConfig };

package/dist/runtime.d.ts

@@ -1,17 +1,41 @@
 /** Structured context attached to log messages. */
 export type LogContext = Record<string, unknown>;
-/** Structured logger interface. Used by tests to suppress output. */
+/**
+ * Structured logger interface. Used by tests to suppress output and by
+ * consumers to plug in custom logging backends.
+ *
+ * @example
+ * ```ts
+ * const myLogger: Logger = {
+ *   info: (msg, ctx) => myBackend.log("info", msg, ctx),
+ *   warn: (msg, ctx) => myBackend.log("warn", msg, ctx),
+ *   error: (msg, ctx) => myBackend.log("error", msg, ctx),
+ *   debug: (msg, ctx) => myBackend.log("debug", msg, ctx),
+ * };
+ * createServer({ agent, logger: myLogger });
+ * ```
+ */
 export type Logger = {
     info(msg: string, ctx?: LogContext): void;
     warn(msg: string, ctx?: LogContext): void;
     error(msg: string, ctx?: LogContext): void;
     debug(msg: string, ctx?: LogContext): void;
 };
+/** Default console-backed logger. */
 export declare const consoleLogger: Logger;
-/** S2S endpoint configuration. */
+export declare const jsonLogger: Logger;
+/**
+ * Speech-to-Speech (S2S) endpoint configuration.
+ *
+ * Controls which AssemblyAI real-time WebSocket endpoint to connect to and
+ * the audio sample rates for input (microphone → STT) and output (TTS → speaker).
+ */
 export type S2SConfig = {
+    /** The WebSocket URL of the S2S real-time endpoint. */
     wssUrl: string;
+    /** Sample rate in Hz for audio sent to STT (microphone capture). */
     inputSampleRate: number;
+    /** Sample rate in Hz for TTS audio received from the server. */
     outputSampleRate: number;
 };
 /** Default S2S endpoint configuration. */

package/dist/runtime.js

@@ -1,16 +1,53 @@
-import { DEFAULT_TTS_SAMPLE_RATE } from "./protocol.js";
+import { DEFAULT_STT_SAMPLE_RATE, DEFAULT_TTS_SAMPLE_RATE } from "./protocol.js";
+import { context, trace } from "@opentelemetry/api";
 //#region runtime.ts
+/**
+* Runtime dependencies injected into the session pipeline.
+*
+* Defines the {@link Logger} interface, a default {@link consoleLogger},
+* and the {@link S2SConfig} for Speech-to-Speech endpoint configuration.
+*/
+/** Default console-backed logger. */
 const consoleLogger = {
-	info: (msg, ctx) => console.log(msg, ...ctx ? [ctx] : []),
-	warn: (msg, ctx) => console.warn(msg, ...ctx ? [ctx] : []),
-	error: (msg, ctx) => console.error(msg, ...ctx ? [ctx] : []),
-	debug: (msg, ctx) => console.debug(msg, ...ctx ? [ctx] : [])
+	info: (msg, ctx) => ctx ? console.log(msg, ctx) : console.log(msg),
+	warn: (msg, ctx) => ctx ? console.warn(msg, ctx) : console.warn(msg),
+	error: (msg, ctx) => ctx ? console.error(msg, ctx) : console.error(msg),
+	debug: (msg, ctx) => ctx ? console.debug(msg, ctx) : console.debug(msg)
+};
+/**
+* Structured JSON logger for production diagnostics. Each log entry is a
+* single-line JSON object with `timestamp`, `level`, `msg`, and any
+* caller-provided context fields. When an active OpenTelemetry span exists,
+* `trace_id` and `span_id` are included automatically.
+*/
+function jsonLog(level) {
+	return (msg, ctx) => {
+		const entry = {
+			timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+			level,
+			msg
+		};
+		const span = trace.getSpan(context.active());
+		if (span) {
+			const sc = span.spanContext();
+			entry.trace_id = sc.traceId;
+			entry.span_id = sc.spanId;
+		}
+		if (ctx) Object.assign(entry, ctx);
+		(level === "error" || level === "warn" ? process.stderr : process.stdout).write(`${JSON.stringify(entry)}\n`);
+	};
+}
+const jsonLogger = {
+	info: jsonLog("info"),
+	warn: jsonLog("warn"),
+	error: jsonLog("error"),
+	debug: jsonLog("debug")
 };
 /** Default S2S endpoint configuration. */
 const DEFAULT_S2S_CONFIG = {
 	wssUrl: "wss://speech-to-speech.us.assemblyai.com/v1/realtime",
-	inputSampleRate: DEFAULT_TTS_SAMPLE_RATE,
+	inputSampleRate: DEFAULT_STT_SAMPLE_RATE,
 	outputSampleRate: DEFAULT_TTS_SAMPLE_RATE
 };
 //#endregion
-export { DEFAULT_S2S_CONFIG, consoleLogger };
+export { DEFAULT_S2S_CONFIG, consoleLogger, jsonLogger };

package/dist/s2s.d.ts

@@ -4,7 +4,6 @@
 import type { JSONSchema7 } from "json-schema";
 import { type Unsubscribe } from "nanoevents";
 import type { Logger, S2SConfig } from "./runtime.ts";
-/** Minimal WebSocket interface for the S2S client. */
 export type S2sWebSocket = {
     readonly readyState: number;
     send(data: string): void;
@@ -21,14 +20,12 @@ export type S2sWebSocket = {
         message?: string;
     }) => void): void;
 };
-/** Factory for creating WebSocket connections (e.g. the `ws` package). */
 export type CreateS2sWebSocket = (url: string, opts: {
     headers: Record<string, string>;
 }) => S2sWebSocket;
-/** Default S2S WebSocket factory using the `ws` package (Node-only). */
 export declare const defaultCreateS2sWebSocket: CreateS2sWebSocket;
 export type S2sSessionConfig = {
-    system_prompt: string;
+    systemPrompt: string;
     tools: S2sToolSchema[];
     greeting?: string;
 };
@@ -39,40 +36,42 @@ export type S2sToolSchema = {
     parameters: JSONSchema7;
 };
 export type S2sToolCall = {
-    call_id: string;
+    callId: string;
     name: string;
     args: Record<string, unknown>;
 };
-/** Typed event map for S2S handle events. */
 export type S2sEvents = {
     ready: (detail: {
-        session_id: string;
+        sessionId: string;
     }) => void;
-    session_updated: (detail: Record<string, unknown>) => void;
-    session_expired: (detail: {
+    sessionUpdated: (detail: Record<string, unknown>) => void;
+    sessionExpired: (detail: {
         code: string;
         message: string;
     }) => void;
-    speech_started: () => void;
-    speech_stopped: () => void;
-    user_transcript_delta: (detail: {
+    speechStarted: () => void;
+    speechStopped: () => void;
+    userTranscriptDelta: (detail: {
         text: string;
     }) => void;
-    user_transcript: (detail: {
-        item_id: string;
+    userTranscript: (detail: {
+        itemId: string;
         text: string;
     }) => void;
-    reply_started: (detail: {
-        reply_id: string;
+    replyStarted: (detail: {
+        replyId: string;
     }) => void;
-    agent_transcript_delta: (detail: {
+    agentTranscriptDelta: (detail: {
         text: string;
     }) => void;
-    agent_transcript: (detail: {
+    agentTranscript: (detail: {
         text: string;
+        replyId: string;
+        itemId: string;
+        interrupted: boolean;
     }) => void;
-    tool_call: (detail: S2sToolCall) => void;
-    reply_done: (detail: {
+    toolCall: (detail: S2sToolCall) => void;
+    replyDone: (detail: {
         status?: string;
     }) => void;
     audio: (detail: {
@@ -98,13 +97,4 @@ export type ConnectS2sOptions = {
     createWebSocket: CreateS2sWebSocket;
     logger?: Logger;
 };
-/**
- * Connect to AssemblyAI's Speech-to-Speech WebSocket API.
- *
- * Returns an {@link S2sHandle} with a typed `on()` method.
- * Consumers listen for events: `ready`, `speech_started`, `speech_stopped`,
- * `user_transcript_delta`, `user_transcript`, `reply_started`,
- * `reply_done`, `audio`, `agent_transcript`, `tool_call`,
- * `session_expired`, `error`, `close`.
- */
 export declare function connectS2s(opts: ConnectS2sOptions): Promise<S2sHandle>;