@alexkroman1/aai 0.8.8 → 0.9.0

package/dist/s2s.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Speech-to-Speech WebSocket client for AssemblyAI's S2S API.
+ */
+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;
+    close(): void;
+    addEventListener(type: "open", listener: () => void): void;
+    addEventListener(type: "message", listener: (event: {
+        data: unknown;
+    }) => void): void;
+    addEventListener(type: "close", listener: (event: {
+        code?: number;
+        reason?: string;
+    }) => void): void;
+    addEventListener(type: "error", listener: (event: {
+        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;
+    tools: S2sToolSchema[];
+    greeting?: string;
+};
+export type S2sToolSchema = {
+    type: "function";
+    name: string;
+    description: string;
+    parameters: JSONSchema7;
+};
+export type S2sToolCall = {
+    call_id: string;
+    name: string;
+    args: Record<string, unknown>;
+};
+/** Typed event map for S2S handle events. */
+export type S2sEvents = {
+    ready: (detail: {
+        session_id: string;
+    }) => void;
+    session_updated: (detail: Record<string, unknown>) => void;
+    session_expired: (detail: {
+        code: string;
+        message: string;
+    }) => void;
+    speech_started: () => void;
+    speech_stopped: () => void;
+    user_transcript_delta: (detail: {
+        text: string;
+    }) => void;
+    user_transcript: (detail: {
+        item_id: string;
+        text: string;
+    }) => void;
+    reply_started: (detail: {
+        reply_id: string;
+    }) => void;
+    agent_transcript_delta: (detail: {
+        text: string;
+    }) => void;
+    agent_transcript: (detail: {
+        text: string;
+    }) => void;
+    tool_call: (detail: S2sToolCall) => void;
+    reply_done: (detail: {
+        status?: string;
+    }) => void;
+    audio: (detail: {
+        audio: Uint8Array;
+    }) => void;
+    error: (detail: {
+        code: string;
+        message: string;
+    }) => void;
+    close: () => void;
+};
+export type S2sHandle = {
+    on<K extends keyof S2sEvents>(event: K, cb: S2sEvents[K]): Unsubscribe;
+    sendAudio(audio: Uint8Array): void;
+    sendToolResult(callId: string, result: string): void;
+    updateSession(config: S2sSessionConfig): void;
+    resumeSession(sessionId: string): void;
+    close(): void;
+};
+export type ConnectS2sOptions = {
+    apiKey: string;
+    config: S2SConfig;
+    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>;

package/dist/s2s.js

@@ -0,0 +1,242 @@
+import { consoleLogger } from "./runtime.js";
+import { z } from "zod";
+import { WebSocket } from "ws";
+import { createNanoEvents } from "nanoevents";
+//#region s2s.ts
+const uint8ToBase64 = (bytes) => Buffer.from(bytes).toString("base64");
+const base64ToUint8 = (base64) => new Uint8Array(Buffer.from(base64, "base64"));
+/** WebSocket readyState constant for OPEN. */
+const WS_OPEN = 1;
+/** Default S2S WebSocket factory using the `ws` package (Node-only). */
+const defaultCreateS2sWebSocket = (url, opts) => new WebSocket(url, { headers: opts.headers });
+const S2sServerMessageSchema = z.discriminatedUnion("type", [
+	z.object({
+		type: z.literal("session.ready"),
+		session_id: z.string()
+	}),
+	z.object({ type: z.literal("session.updated") }).passthrough(),
+	z.object({ type: z.literal("input.speech.started") }),
+	z.object({ type: z.literal("input.speech.stopped") }),
+	z.object({
+		type: z.literal("transcript.user.delta"),
+		text: z.string()
+	}),
+	z.object({
+		type: z.literal("transcript.user"),
+		item_id: z.string(),
+		text: z.string()
+	}),
+	z.object({
+		type: z.literal("reply.started"),
+		reply_id: z.string()
+	}),
+	z.object({
+		type: z.literal("transcript.agent.delta"),
+		delta: z.string()
+	}).passthrough(),
+	z.object({
+		type: z.literal("transcript.agent"),
+		text: z.string()
+	}),
+	z.object({ type: z.literal("reply.content_part.started") }).passthrough(),
+	z.object({ type: z.literal("reply.content_part.done") }).passthrough(),
+	z.object({
+		type: z.literal("tool.call"),
+		call_id: z.string(),
+		name: z.string(),
+		args: z.record(z.string(), z.unknown()).optional().default({})
+	}),
+	z.object({
+		type: z.literal("reply.done"),
+		status: z.string().optional()
+	}),
+	z.object({
+		type: z.literal("session.error"),
+		code: z.string(),
+		message: z.string()
+	}),
+	z.object({
+		type: z.literal("error"),
+		message: z.string()
+	})
+]);
+/** Dispatch a parsed S2S server message to the emitter. */
+function dispatchS2sMessage(emitter, msg) {
+	switch (msg.type) {
+		case "session.ready":
+			emitter.emit("ready", { session_id: msg.session_id });
+			break;
+		case "session.updated":
+			emitter.emit("session_updated", msg);
+			break;
+		case "input.speech.started":
+			emitter.emit("speech_started");
+			break;
+		case "input.speech.stopped":
+			emitter.emit("speech_stopped");
+			break;
+		case "transcript.user.delta":
+			emitter.emit("user_transcript_delta", { text: msg.text });
+			break;
+		case "transcript.user":
+			emitter.emit("user_transcript", {
+				item_id: msg.item_id,
+				text: msg.text
+			});
+			break;
+		case "reply.started":
+			emitter.emit("reply_started", { reply_id: msg.reply_id });
+			break;
+		case "transcript.agent.delta":
+			emitter.emit("agent_transcript_delta", { text: msg.delta });
+			break;
+		case "transcript.agent":
+			emitter.emit("agent_transcript", { text: msg.text });
+			break;
+		case "tool.call":
+			emitter.emit("tool_call", {
+				call_id: msg.call_id,
+				name: msg.name,
+				args: msg.args
+			});
+			break;
+		case "reply.done":
+			emitter.emit("reply_done", { ...msg.status ? { status: msg.status } : {} });
+			break;
+		case "session.error":
+			if (msg.code === "session_not_found" || msg.code === "session_forbidden") emitter.emit("session_expired", {
+				code: msg.code,
+				message: msg.message
+			});
+			else emitter.emit("error", {
+				code: msg.code,
+				message: msg.message
+			});
+			break;
+		case "error":
+			emitter.emit("error", {
+				code: "connection",
+				message: msg.message
+			});
+			break;
+		case "reply.content_part.started":
+		case "reply.content_part.done": break;
+	}
+}
+/**
+* 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`.
+*/
+function connectS2s(opts) {
+	const { apiKey, config, createWebSocket, logger: log = consoleLogger } = opts;
+	return new Promise((resolve, reject) => {
+		log.info("S2S connecting", { url: config.wssUrl });
+		const ws = createWebSocket(config.wssUrl, { headers: { Authorization: `Bearer ${apiKey}` } });
+		const emitter = createNanoEvents();
+		let opened = false;
+		function send(msg) {
+			if (ws.readyState !== WS_OPEN) return;
+			const json = JSON.stringify(msg);
+			if (msg.type !== "input.audio") log.info(`S2S >> ${msg.type}`, msg.type === "session.update" ? { payload: json } : void 0);
+			ws.send(json);
+		}
+		const handle = {
+			on: emitter.on.bind(emitter),
+			sendAudio(audio) {
+				if (ws.readyState !== WS_OPEN) return;
+				ws.send(`{"type":"input.audio","audio":"${uint8ToBase64(audio)}"}`);
+			},
+			sendToolResult(callId, result) {
+				const msg = {
+					type: "tool.result",
+					call_id: callId,
+					result
+				};
+				log.info("S2S >> tool.result", {
+					call_id: callId,
+					resultLength: result.length
+				});
+				send(msg);
+			},
+			updateSession(sessionConfig) {
+				send({
+					type: "session.update",
+					session: sessionConfig
+				});
+			},
+			resumeSession(sessionId) {
+				send({
+					type: "session.resume",
+					session_id: sessionId
+				});
+			},
+			close() {
+				log.info("S2S closing");
+				ws.close();
+			}
+		};
+		ws.addEventListener("open", () => {
+			opened = true;
+			log.info("S2S WebSocket open");
+			resolve(handle);
+		});
+		function tryParseJson(data) {
+			try {
+				return JSON.parse(String(data));
+			} catch {
+				log.warn("S2S << invalid JSON", { data: String(data).slice(0, 200) });
+				return;
+			}
+		}
+		function handleAudioFastPath(obj) {
+			if (obj.type === "reply.audio" && typeof obj.data === "string") {
+				const audioBytes = base64ToUint8(obj.data);
+				emitter.emit("audio", { audio: audioBytes });
+				return true;
+			}
+			return false;
+		}
+		function logIncoming(obj) {
+			if (obj.type === "reply.audio" || obj.type === "input.audio") return;
+			log.info(`S2S << ${obj.type}`, obj.type === "transcript.agent.delta" ? { delta: obj.delta } : void 0);
+		}
+		function handleS2sMessage(ev) {
+			const raw = tryParseJson(ev.data);
+			if (raw === void 0) return;
+			const obj = raw;
+			logIncoming(obj);
+			if (handleAudioFastPath(obj)) return;
+			const parsed = S2sServerMessageSchema.safeParse(raw);
+			if (!parsed.success) {
+				log.warn(`S2S << unrecognised message type: ${obj.type ?? JSON.stringify(raw).slice(0, 200)}`);
+				return;
+			}
+			dispatchS2sMessage(emitter, parsed.data);
+		}
+		ws.addEventListener("message", handleS2sMessage);
+		ws.addEventListener("close", (ev) => {
+			log.info("S2S WebSocket closed", {
+				code: ev.code ?? 0,
+				reason: ev.reason ?? ""
+			});
+			emitter.emit("close");
+		});
+		ws.addEventListener("error", (ev) => {
+			const message = typeof ev.message === "string" ? ev.message : "WebSocket error";
+			const errObj = new Error(message);
+			log.error("S2S WebSocket error", { error: errObj.message });
+			if (!opened) reject(errObj);
+			else emitter.emit("error", {
+				code: "ws_error",
+				message: errObj.message
+			});
+		});
+	});
+}
+//#endregion
+export { connectS2s, defaultCreateS2sWebSocket };

package/dist/{sdk/server.d.ts → server.d.ts}

@@ -1,14 +1,12 @@
 /**
  * Self-hostable agent server.
  *
- * `createServer()` returns a server with a standard `fetch(Request): Response`
- * handler and a Node.js `listen()` method for HTTP + WebSocket.
- *
- * @module
+ * `createServer()` returns a server with `listen()` for HTTP + WebSocket.
+ * Calls `createDirectExecutor` + `wireSessionSocket` directly — no
+ * intermediate WintercServer layer.
  */
 import type { Kv } from "./kv.ts";
 import type { Logger, S2SConfig } from "./runtime.ts";
-import { type CreateS2sWebSocket } from "./s2s.ts";
 import type { AgentDef } from "./types.ts";
 export type ServerOptions = {
     /** The agent definition returned by `defineAgent()`. */
@@ -25,29 +23,11 @@ export type ServerOptions = {
     logger?: Logger;
     /** S2S configuration. Defaults to AssemblyAI production. */
     s2sConfig?: S2SConfig;
-    /** WebSocket factory for S2S connections. Auto-detected if not provided. */
-    createWebSocket?: CreateS2sWebSocket;
 };
 export type AgentServer = {
-    /** Standard fetch handler using web `Request`/`Response` types. */
-    fetch(request: Request): Promise<Response>;
     /** Start listening on the given port. */
     listen(port?: number): Promise<void>;
     /** Stop the server. */
     close(): Promise<void>;
 };
-/**
- * Create a self-hostable agent server.
- *
- * @example
- * ```ts
- * import { defineAgent } from "aai";
- * import { createServer } from "aai/server";
- *
- * const agent = defineAgent({ name: "my-agent" });
- * const server = createServer({ agent });
- * await server.listen(3000);
- * ```
- */
 export declare function createServer(options: ServerOptions): AgentServer;
-//# sourceMappingURL=server.d.ts.map

package/dist/server.js

@@ -0,0 +1,105 @@
+import { AUDIO_FORMAT } from "./protocol.js";
+import { DEFAULT_S2S_CONFIG, consoleLogger } from "./runtime.js";
+import { createDirectExecutor } from "./direct-executor.js";
+import { wireSessionSocket } from "./ws-handler.js";
+import { serve } from "@hono/node-server";
+import { serveStatic } from "@hono/node-server/serve-static";
+import { Hono } from "hono";
+import { WebSocketServer } from "ws";
+//#region server.ts
+/**
+* Self-hostable agent server.
+*
+* `createServer()` returns a server with `listen()` for HTTP + WebSocket.
+* Calls `createDirectExecutor` + `wireSessionSocket` directly — no
+* intermediate WintercServer layer.
+*/
+function resolveEnv(env) {
+	return Object.fromEntries(Object.entries(env).filter(([, v]) => v !== void 0));
+}
+function createServer(options) {
+	const { agent, kv, clientHtml, clientDir, logger = consoleLogger, s2sConfig = DEFAULT_S2S_CONFIG } = options;
+	const executor = createDirectExecutor({
+		agent,
+		env: resolveEnv(options.env ?? (typeof process !== "undefined" ? process.env : {})),
+		...kv ? { kv } : {},
+		logger,
+		s2sConfig
+	});
+	const sessions = /* @__PURE__ */ new Map();
+	const readyConfig = {
+		audioFormat: AUDIO_FORMAT,
+		sampleRate: s2sConfig.inputSampleRate,
+		ttsSampleRate: s2sConfig.outputSampleRate
+	};
+	function handleWs(ws, skipGreeting) {
+		wireSessionSocket(ws, {
+			sessions,
+			createSession: (sid, client) => executor.createSession({
+				id: sid,
+				agent: agent.name,
+				client,
+				skipGreeting
+			}),
+			readyConfig,
+			logger
+		});
+	}
+	let serverHandle = null;
+	return {
+		async listen(port = 3e3) {
+			const app = new Hono();
+			app.onError((err, c) => {
+				logger.error(`${c.req.method} ${new URL(c.req.url).pathname} error: ${err.message}`);
+				return c.json({ error: "Internal Server Error" }, 500);
+			});
+			app.use("/*", async (c, next) => {
+				const start = Date.now();
+				await next();
+				const ms = Date.now() - start;
+				const { status } = c.res;
+				const method = c.req.method;
+				const path = new URL(c.req.url).pathname;
+				if (status >= 400) logger.error(`${method} ${path} ${status} ${ms}ms`);
+				else logger.info(`${method} ${path} ${status} ${ms}ms`);
+			});
+			app.get("/health", (c) => c.json({
+				status: "ok",
+				name: agent.name
+			}));
+			if (clientDir) app.use("/*", serveStatic({ root: clientDir }));
+			app.get("/", (c) => {
+				if (clientHtml) return c.html(clientHtml);
+				return c.html(`<!DOCTYPE html><html><body><h1>${agent.name}</h1><p>Agent server running.</p></body></html>`);
+			});
+			const nodeServer = serve({
+				fetch: app.fetch,
+				port
+			});
+			await new Promise((resolve) => {
+				nodeServer.on("listening", resolve);
+			});
+			const wss = new WebSocketServer({ noServer: true });
+			nodeServer.on("upgrade", (req, socket, head) => {
+				const reqUrl = new URL(req.url ?? "/", `http://localhost:${port}`);
+				const resume = reqUrl.searchParams.has("resume");
+				logger.info(`WS upgrade ${reqUrl.pathname}${resume ? " (resume)" : ""}`);
+				wss.handleUpgrade(req, socket, head, (ws) => {
+					handleWs(ws, resume);
+				});
+			});
+			serverHandle = { async shutdown() {
+				await new Promise((resolve, reject) => {
+					nodeServer.close((err) => err ? reject(err) : resolve());
+				});
+			} };
+		},
+		async close() {
+			for (const session of sessions.values()) await session.stop();
+			sessions.clear();
+			await serverHandle?.shutdown();
+		}
+	};
+}
+//#endregion
+export { createServer };

package/dist/{sdk/session.d.ts → session.d.ts}

@@ -1,18 +1,13 @@
 /**
  * S2S session — relays audio between the client and AssemblyAI's
  * Speech-to-Speech API, intercepting only tool calls for local execution.
- *
- * Cross-runtime: accepts Logger, Metrics, and a WebSocket factory via
- * dependency injection.
- *
- * @module
  */
-import type { AgentConfig, ToolSchema } from "./_internal_types.ts";
+import type { AgentConfig, ToolSchema } from "./_internal-types.ts";
 import type { ClientSink } from "./protocol.ts";
-import type { Logger, Metrics, S2SConfig } from "./runtime.ts";
+import type { Logger, S2SConfig } from "./runtime.ts";
 import { type CreateS2sWebSocket, connectS2s } from "./s2s.ts";
 import { type StepInfo } from "./types.ts";
-import type { ExecuteTool } from "./worker_entry.ts";
+import type { ExecuteTool } from "./worker-entry.ts";
 /** A voice session managing the S2S connection for one client. */
 export type Session = {
     start(): Promise<void>;
@@ -51,12 +46,11 @@ export type SessionOptions = {
     apiKey: string;
     s2sConfig: S2SConfig;
     executeTool: ExecuteTool;
-    createWebSocket: CreateS2sWebSocket;
+    createWebSocket?: CreateS2sWebSocket;
     env?: Record<string, string | undefined>;
     hookInvoker?: HookInvoker;
     skipGreeting?: boolean;
     logger?: Logger;
-    metrics?: Metrics;
 };
 export declare const _internals: {
     connectS2s: typeof connectS2s;
@@ -67,4 +61,3 @@ export declare function buildSystemPrompt(config: AgentConfig, opts: {
     hasTools: boolean;
     voice?: boolean;
 }): string;
-//# sourceMappingURL=session.d.ts.map