@alexkroman1/aai 0.5.0 → 0.6.1

package/dist/sdk/s2s.js

@@ -0,0 +1,171 @@
+import { consoleLogger } from "./runtime.js";
+// ─── Cross-runtime base64 helpers ───────────────────────────────────────────
+function uint8ToBase64(bytes) {
+    const CHUNK = 0x8000; // 32KB chunks to avoid call stack limits
+    const parts = [];
+    for (let i = 0; i < bytes.length; i += CHUNK) {
+        parts.push(String.fromCharCode(...bytes.subarray(i, i + CHUNK)));
+    }
+    return btoa(parts.join(""));
+}
+function base64ToUint8(base64) {
+    const binary = atob(base64);
+    const bytes = new Uint8Array(binary.length);
+    for (let i = 0; i < binary.length; i++) {
+        bytes[i] = binary.charCodeAt(i);
+    }
+    return bytes;
+}
+/** WebSocket readyState constant for OPEN. */
+const WS_OPEN = 1;
+/**
+ * Connect to AssemblyAI's Speech-to-Speech WebSocket API.
+ *
+ * Returns an {@linkcode S2sHandle} that extends EventTarget. 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 function connectS2s(opts) {
+    const { apiKey, config, createWebSocket, logger: log = consoleLogger } = opts;
+    return new Promise((resolve, reject) => {
+        log.debug("S2S connecting", { url: config.wssUrl });
+        const ws = createWebSocket(config.wssUrl, {
+            headers: { Authorization: `Bearer ${apiKey}` },
+        });
+        const target = new EventTarget();
+        let opened = false;
+        function send(msg) {
+            if (ws.readyState !== WS_OPEN)
+                return;
+            const type = msg.type;
+            if (type !== "input.audio") {
+                log.info(`S2S >> ${JSON.stringify(msg)}`);
+            }
+            ws.send(JSON.stringify(msg));
+        }
+        const handle = Object.assign(target, {
+            sendAudio(audio) {
+                send({ type: "input.audio", audio: uint8ToBase64(audio) });
+            },
+            sendToolResult(callId, result) {
+                send({ type: "tool.result", call_id: callId, result });
+            },
+            updateSession(sessionConfig) {
+                send({ type: "session.update", session: sessionConfig });
+            },
+            resumeSession(sessionId) {
+                send({ type: "session.resume", session_id: sessionId });
+            },
+            close() {
+                log.debug("S2S closing");
+                ws.close();
+            },
+        });
+        ws.on("open", () => {
+            opened = true;
+            log.info("S2S WebSocket open");
+            resolve(handle);
+        });
+        ws.on("message", (data) => {
+            let msg;
+            try {
+                msg = JSON.parse(String(data));
+            }
+            catch {
+                return;
+            }
+            const type = msg.type;
+            if (type !== "reply.audio") {
+                log.info(`S2S << ${JSON.stringify(msg)}`);
+            }
+            switch (type) {
+                case "session.ready":
+                    target.dispatchEvent(new CustomEvent("ready", {
+                        detail: { session_id: msg.session_id },
+                    }));
+                    break;
+                case "session.updated":
+                    target.dispatchEvent(new CustomEvent("session_updated", { detail: msg }));
+                    break;
+                case "input.speech.started":
+                    target.dispatchEvent(new CustomEvent("speech_started"));
+                    break;
+                case "input.speech.stopped":
+                    target.dispatchEvent(new CustomEvent("speech_stopped"));
+                    break;
+                case "transcript.user.delta":
+                    target.dispatchEvent(new CustomEvent("user_transcript_delta", {
+                        detail: { text: msg.text },
+                    }));
+                    break;
+                case "transcript.user":
+                    target.dispatchEvent(new CustomEvent("user_transcript", {
+                        detail: {
+                            item_id: msg.item_id,
+                            text: msg.text,
+                        },
+                    }));
+                    break;
+                case "reply.started":
+                    target.dispatchEvent(new CustomEvent("reply_started", {
+                        detail: { reply_id: msg.reply_id },
+                    }));
+                    break;
+                case "reply.audio": {
+                    const audioBytes = base64ToUint8(msg.data);
+                    target.dispatchEvent(new CustomEvent("audio", { detail: { audio: audioBytes } }));
+                    break;
+                }
+                case "transcript.agent":
+                    target.dispatchEvent(new CustomEvent("agent_transcript", {
+                        detail: { text: msg.text },
+                    }));
+                    break;
+                case "tool.call":
+                    target.dispatchEvent(new CustomEvent("tool_call", {
+                        detail: {
+                            call_id: msg.call_id,
+                            name: msg.name,
+                            args: (msg.args ?? {}),
+                        },
+                    }));
+                    break;
+                case "reply.done":
+                    target.dispatchEvent(new CustomEvent("reply_done", {
+                        detail: { status: msg.status ?? undefined },
+                    }));
+                    break;
+                case "session.error": {
+                    const code = msg.code;
+                    const isExpired = code === "session_not_found" || code === "session_forbidden";
+                    target.dispatchEvent(new CustomEvent(isExpired ? "session_expired" : "error", {
+                        detail: { code, message: msg.message },
+                    }));
+                    break;
+                }
+            }
+        });
+        ws.on("close", (code, reason) => {
+            log.info("S2S WebSocket closed", {
+                code: code,
+                reason: reason instanceof Uint8Array ? new TextDecoder().decode(reason) : String(reason ?? ""),
+            });
+            target.dispatchEvent(new CustomEvent("close"));
+        });
+        ws.on("error", (err) => {
+            const errObj = err instanceof Error ? err : new Error(String(err));
+            log.error("S2S WebSocket error", { error: errObj.message });
+            if (!opened) {
+                reject(errObj);
+            }
+            else {
+                target.dispatchEvent(new CustomEvent("error", {
+                    detail: { code: "ws_error", message: errObj.message },
+                }));
+            }
+        });
+    });
+}
+//# sourceMappingURL=s2s.js.map

package/dist/sdk/s2s.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"s2s.js","sourceRoot":"","sources":["../../sdk/s2s.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAE7C,+EAA+E;AAE/E,SAAS,aAAa,CAAC,KAAiB;IACtC,MAAM,KAAK,GAAG,MAAM,CAAC,CAAC,yCAAyC;IAC/D,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,IAAI,KAAK,EAAE,CAAC;QAC7C,KAAK,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,KAAK,CAAC,QAAQ,CAAC,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;IACnE,CAAC;IACD,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAAC;AAC9B,CAAC;AAED,SAAS,aAAa,CAAC,MAAc;IACnC,MAAM,MAAM,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC;IAC5B,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAClC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAYD,8CAA8C;AAC9C,MAAM,OAAO,GAAG,CAAC,CAAC;AA8ClB;;;;;;;;GAQG;AACH,MAAM,UAAU,UAAU,CAAC,IAAuB;IAChD,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,MAAM,EAAE,GAAG,GAAG,aAAa,EAAE,GAAG,IAAI,CAAC;IAE9E,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QACrC,GAAG,CAAC,KAAK,CAAC,gBAAgB,EAAE,EAAE,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;QAEpD,MAAM,EAAE,GAAG,eAAe,CAAC,MAAM,CAAC,MAAM,EAAE;YACxC,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,MAAM,EAAE,EAAE;SAC/C,CAAC,CAAC;QAEH,MAAM,MAAM,GAAG,IAAI,WAAW,EAAE,CAAC;QACjC,IAAI,MAAM,GAAG,KAAK,CAAC;QAEnB,SAAS,IAAI,CAAC,GAA4B;YACxC,IAAI,EAAE,CAAC,UAAU,KAAK,OAAO;gBAAE,OAAO;YACtC,MAAM,IAAI,GAAG,GAAG,CAAC,IAAc,CAAC;YAChC,IAAI,IAAI,KAAK,aAAa,EAAE,CAAC;gBAC3B,GAAG,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC5C,CAAC;YACD,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;QAC/B,CAAC;QAED,MAAM,MAAM,GAAc,MAAM,CAAC,MAAM,CAAC,MAAM,EAAE;YAC9C,SAAS,CAAC,KAAiB;gBACzB,IAAI,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,aAAa,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;YAC7D,CAAC;YAED,cAAc,CAAC,MAAc,EAAE,MAAc;gBAC3C,IAAI,CAAC,EAAE,IAAI,EAAE,aAAa,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC;YACzD,CAAC;YAED,aAAa,CAAC,aAA+B;gBAC3C,IAAI,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,OAAO,EAAE,aAAa,EAAE,CAAC,CAAC;YAC3D,CAAC;YAED,aAAa,CAAC,SAAiB;gBAC7B,IAAI,CAAC,EAAE,IAAI,EAAE,gBAAgB,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,CAAC;YAC1D,CAAC;YAED,KAAK;gBACH,GAAG,CAAC,KAAK,CAAC,aAAa,CAAC,CAAC;gBACzB,EAAE,CAAC,KAAK,EAAE,CAAC;YACb,CAAC;SACF,CAAC,CAAC;QAEH,EAAE,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE;YACjB,MAAM,GAAG,IAAI,CAAC;YACd,GAAG,CAAC,IAAI,CAAC,oBAAoB,CAAC,CAAC;YAC/B,OAAO,CAAC,MAAM,CAAC,CAAC;QAClB,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,IAAa,EAAE,EAAE;YACjC,IAAI,GAA4B,CAAC;YACjC,IAAI,CAAC;gBACH,GAAG,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;YACjC,CAAC;YAAC,MAAM,CAAC;gBACP,OAAO;YACT,CAAC;YAED,MAAM,IAAI,GAAG,GAAG,CAAC,IAAc,CAAC;YAEhC,IAAI,IAAI,KAAK,aAAa,EAAE,CAAC;gBAC3B,GAAG,CAAC,IAAI,CAAC,UAAU,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;YAC5C,CAAC;YAED,QAAQ,IAAI,EAAE,CAAC;gBACb,KAAK,eAAe;oBAClB,MAAM,CAAC,aAAa,CAClB,IAAI,WAAW,CAAC,OAAO,EAAE;wBACvB,MAAM,EAAE,EAAE,UAAU,EAAE,GAAG,CAAC,UAAoB,EAAE;qBACjD,CAAC,CACH,CAAC;oBACF,MAAM;gBACR,KAAK,iBAAiB;oBACpB,MAAM,CAAC,aAAa,CAAC,IAAI,WAAW,CAAC,iBAAiB,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC;oBAC1E,MAAM;gBACR,KAAK,sBAAsB;oBACzB,MAAM,CAAC,aAAa,CAAC,IAAI,WAAW,CAAC,gBAAgB,CAAC,CAAC,CAAC;oBACxD,MAAM;gBACR,KAAK,sBAAsB;oBACzB,MAAM,CAAC,aAAa,CAAC,IAAI,WAAW,CAAC,gBAAgB,CAAC,CAAC,CAAC;oBACxD,MAAM;gBACR,KAAK,uBAAuB;oBAC1B,MAAM,CAAC,aAAa,CAClB,IAAI,WAAW,CAAC,uBAAuB,EAAE;wBACvC,MAAM,EAAE,EAAE,IAAI,EAAE,GAAG,CAAC,IAAc,EAAE;qBACrC,CAAC,CACH,CAAC;oBACF,MAAM;gBACR,KAAK,iBAAiB;oBACpB,MAAM,CAAC,aAAa,CAClB,IAAI,WAAW,CAAC,iBAAiB,EAAE;wBACjC,MAAM,EAAE;4BACN,OAAO,EAAE,GAAG,CAAC,OAAiB;4BAC9B,IAAI,EAAE,GAAG,CAAC,IAAc;yBACzB;qBACF,CAAC,CACH,CAAC;oBACF,MAAM;gBACR,KAAK,eAAe;oBAClB,MAAM,CAAC,aAAa,CAClB,IAAI,WAAW,CAAC,eAAe,EAAE;wBAC/B,MAAM,EAAE,EAAE,QAAQ,EAAE,GAAG,CAAC,QAAkB,EAAE;qBAC7C,CAAC,CACH,CAAC;oBACF,MAAM;gBACR,KAAK,aAAa,CAAC,CAAC,CAAC;oBACnB,MAAM,UAAU,GAAG,aAAa,CAAC,GAAG,CAAC,IAAc,CAAC,CAAC;oBACrD,MAAM,CAAC,aAAa,CAAC,IAAI,WAAW,CAAC,OAAO,EAAE,EAAE,MAAM,EAAE,EAAE,KAAK,EAAE,UAAU,EAAE,EAAE,CAAC,CAAC,CAAC;oBAClF,MAAM;gBACR,CAAC;gBACD,KAAK,kBAAkB;oBACrB,MAAM,CAAC,aAAa,CAClB,IAAI,WAAW,CAAC,kBAAkB,EAAE;wBAClC,MAAM,EAAE,EAAE,IAAI,EAAE,GAAG,CAAC,IAAc,EAAE;qBACrC,CAAC,CACH,CAAC;oBACF,MAAM;gBACR,KAAK,WAAW;oBACd,MAAM,CAAC,aAAa,CAClB,IAAI,WAAW,CAAC,WAAW,EAAE;wBAC3B,MAAM,EAAE;4BACN,OAAO,EAAE,GAAG,CAAC,OAAiB;4BAC9B,IAAI,EAAE,GAAG,CAAC,IAAc;4BACxB,IAAI,EAAE,CAAC,GAAG,CAAC,IAAI,IAAI,EAAE,CAA4B;yBAClD;qBACF,CAAC,CACH,CAAC;oBACF,MAAM;gBACR,KAAK,YAAY;oBACf,MAAM,CAAC,aAAa,CAClB,IAAI,WAAW,CAAC,YAAY,EAAE;wBAC5B,MAAM,EAAE,EAAE,MAAM,EAAG,GAAG,CAAC,MAAiB,IAAI,SAAS,EAAE;qBACxD,CAAC,CACH,CAAC;oBACF,MAAM;gBACR,KAAK,eAAe,CAAC,CAAC,CAAC;oBACrB,MAAM,IAAI,GAAG,GAAG,CAAC,IAAc,CAAC;oBAChC,MAAM,SAAS,GAAG,IAAI,KAAK,mBAAmB,IAAI,IAAI,KAAK,mBAAmB,CAAC;oBAC/E,MAAM,CAAC,aAAa,CAClB,IAAI,WAAW,CAAC,SAAS,CAAC,CAAC,CAAC,iBAAiB,CAAC,CAAC,CAAC,OAAO,EAAE;wBACvD,MAAM,EAAE,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,CAAC,OAAiB,EAAE;qBACjD,CAAC,CACH,CAAC;oBACF,MAAM;gBACR,CAAC;YACH,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAa,EAAE,MAAe,EAAE,EAAE;YAChD,GAAG,CAAC,IAAI,CAAC,sBAAsB,EAAE;gBAC/B,IAAI,EAAE,IAAc;gBACpB,MAAM,EACJ,MAAM,YAAY,UAAU,CAAC,CAAC,CAAC,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,MAAM,IAAI,EAAE,CAAC;aACzF,CAAC,CAAC;YACH,MAAM,CAAC,aAAa,CAAC,IAAI,WAAW,CAAC,OAAO,CAAC,CAAC,CAAC;QACjD,CAAC,CAAC,CAAC;QAEH,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAY,EAAE,EAAE;YAC9B,MAAM,MAAM,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;YACnE,GAAG,CAAC,KAAK,CAAC,qBAAqB,EAAE,EAAE,KAAK,EAAE,MAAM,CAAC,OAAO,EAAE,CAAC,CAAC;YAC5D,IAAI,CAAC,MAAM,EAAE,CAAC;gBACZ,MAAM,CAAC,MAAM,CAAC,CAAC;YACjB,CAAC;iBAAM,CAAC;gBACN,MAAM,CAAC,aAAa,CAClB,IAAI,WAAW,CAAC,OAAO,EAAE;oBACvB,MAAM,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,CAAC,OAAO,EAAE;iBACtD,CAAC,CACH,CAAC;YACJ,CAAC;QACH,CAAC,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/sdk/server.d.ts

@@ -0,0 +1,51 @@
+/**
+ * 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
+ */
+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()`. */
+    agent: AgentDef;
+    /** Environment variables. Defaults to `process.env`. */
+    env?: Record<string, string>;
+    /** KV store. Defaults to in-memory. */
+    kv?: Kv;
+    /** HTML to serve at `GET /`. */
+    clientHtml?: string;
+    /** Logger. Defaults to console. */
+    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/sdk/server.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../sdk/server.ts"],"names":[],"mappings":"AACA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,SAAS,CAAC;AAClC,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAEtD,OAAO,KAAK,EAAE,kBAAkB,EAAgB,MAAM,UAAU,CAAC;AACjE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAI3C,MAAM,MAAM,aAAa,GAAG;IAC1B,wDAAwD;IACxD,KAAK,EAAE,QAAQ,CAAC;IAChB,wDAAwD;IACxD,GAAG,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,uCAAuC;IACvC,EAAE,CAAC,EAAE,EAAE,CAAC;IACR,gCAAgC;IAChC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,mCAAmC;IACnC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,4DAA4D;IAC5D,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,4EAA4E;IAC5E,eAAe,CAAC,EAAE,kBAAkB,CAAC;CACtC,CAAC;AAEF,MAAM,MAAM,WAAW,GAAG;IACxB,mEAAmE;IACnE,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC3C,yCAAyC;IACzC,MAAM,CAAC,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACrC,uBAAuB;IACvB,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB,CAAC;AA0BF;;;;;;;;;;;;GAYG;AACH,wBAAgB,YAAY,CAAC,OAAO,EAAE,aAAa,GAAG,WAAW,CAuHhE"}

package/dist/sdk/server.js

@@ -0,0 +1,145 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * 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
+ */
+import { consoleLogger, DEFAULT_S2S_CONFIG } from "./runtime.js";
+import { createWintercServer } from "./winterc_server.js";
+/** Try to load the `ws` package for WebSocket connections. */
+async function loadWsFactory() {
+    try {
+        const mod = await import("ws");
+        const WS = mod.default ?? mod;
+        return (url, opts) => new WS(url, { headers: opts.headers });
+    }
+    catch {
+        throw new Error("WebSocket factory not provided and `ws` package not found. " +
+            "Install `ws` (`npm install ws`) or pass `createWebSocket` option.");
+    }
+}
+/** Filter env to only defined string values. */
+function resolveEnv(env) {
+    const resolved = {};
+    for (const [key, value] of Object.entries(env)) {
+        if (value !== undefined)
+            resolved[key] = value;
+    }
+    return resolved;
+}
+/**
+ * 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 function createServer(options) {
+    const { agent, kv, clientHtml, logger = consoleLogger, s2sConfig = DEFAULT_S2S_CONFIG } = options;
+    const env = resolveEnv(options.env ?? (typeof process !== "undefined" ? process.env : {}));
+    let wsFactory = options.createWebSocket ?? null;
+    async function getWsFactory() {
+        if (!wsFactory) {
+            wsFactory = await loadWsFactory();
+        }
+        return wsFactory;
+    }
+    // WintercServer is created lazily after wsFactory is resolved
+    let winterc = null;
+    function getWinterc() {
+        if (!winterc) {
+            winterc = createWintercServer({
+                agent,
+                env,
+                ...(kv ? { kv } : {}),
+                createWebSocket: wsFactory,
+                ...(clientHtml !== undefined ? { clientHtml } : {}),
+                logger,
+                s2sConfig,
+            });
+        }
+        return winterc;
+    }
+    let serverHandle = null;
+    return {
+        fetch(request) {
+            return getWinterc().fetch(request);
+        },
+        async listen(port = 3000) {
+            // Ensure WS factory is loaded before starting
+            await getWsFactory();
+            const http = await import("node:http");
+            const nodeServer = http.createServer(async (req, res) => {
+                try {
+                    const protocol = req.socket.encrypted ? "https" : "http";
+                    const host = req.headers.host ?? `localhost:${port}`;
+                    const url = new URL(req.url ?? "/", `${protocol}://${host}`);
+                    const headers = new Headers();
+                    for (const [key, val] of Object.entries(req.headers)) {
+                        if (val)
+                            headers.set(key, Array.isArray(val) ? val[0] : val);
+                    }
+                    const request = new Request(url, {
+                        method: req.method ?? "GET",
+                        headers,
+                    });
+                    const response = await getWinterc().fetch(request);
+                    res.writeHead(response.status, Object.fromEntries(response.headers));
+                    const body = await response.text();
+                    res.end(body);
+                }
+                catch (err) {
+                    res.writeHead(500);
+                    res.end(err instanceof Error ? err.message : "Internal Server Error");
+                }
+            });
+            // WebSocket upgrade via ws package
+            try {
+                const wsMod = await import("ws");
+                const WSServer = wsMod.WebSocketServer;
+                if (WSServer) {
+                    const wss = new WSServer({ noServer: true });
+                    nodeServer.on("upgrade", (req, socket, head) => {
+                        wss.handleUpgrade(req, socket, head, (ws) => {
+                            const reqUrl = new URL(req.url ?? "/", `http://localhost:${port}`);
+                            const resume = reqUrl.searchParams.has("resume");
+                            getWinterc().handleWebSocket(ws, {
+                                skipGreeting: resume,
+                            });
+                        });
+                    });
+                }
+            }
+            catch {
+                logger.warn("ws package not available for Node.js WebSocket upgrade");
+            }
+            await new Promise((resolve) => {
+                nodeServer.listen(port, () => {
+                    logger.info(`Agent "${agent.name}" listening on http://localhost:${port}`);
+                    resolve();
+                });
+            });
+            serverHandle = {
+                async shutdown() {
+                    await new Promise((resolve, reject) => {
+                        nodeServer.close((err) => (err ? reject(err) : resolve()));
+                    });
+                },
+            };
+        },
+        async close() {
+            await winterc?.close();
+            await serverHandle?.shutdown();
+        },
+    };
+}
+//# sourceMappingURL=server.js.map

package/dist/sdk/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../sdk/server.ts"],"names":[],"mappings":"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"}

package/dist/sdk/session.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 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 { ClientSink } from "./protocol.ts";
+import type { Logger, Metrics, S2SConfig } from "./runtime.ts";
+import { type CreateS2sWebSocket, connectS2s } from "./s2s.ts";
+import type { StepInfo } from "./types.ts";
+import type { ExecuteTool } from "./worker_entry.ts";
+/** A voice session managing the S2S connection for one client. */
+export type Session = {
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    onAudio(data: Uint8Array): void;
+    onAudioReady(): void;
+    onCancel(): void;
+    onReset(): void;
+    onHistory(incoming: readonly {
+        role: "user" | "assistant";
+        text: string;
+    }[]): void;
+    waitForTurn(): Promise<void>;
+};
+/** Generic interface for invoking agent lifecycle hooks. */
+export type HookInvoker = {
+    onConnect(sessionId: string, timeoutMs?: number): Promise<void>;
+    onDisconnect(sessionId: string, timeoutMs?: number): Promise<void>;
+    onTurn(sessionId: string, text: string, timeoutMs?: number): Promise<void>;
+    onError(sessionId: string, error: {
+        message: string;
+    }, timeoutMs?: number): Promise<void>;
+    onStep(sessionId: string, step: StepInfo, timeoutMs?: number): Promise<void>;
+    resolveTurnConfig(sessionId: string, timeoutMs?: number): Promise<{
+        maxSteps?: number;
+        activeTools?: string[];
+    } | null>;
+};
+/** Configuration options for creating a new session. */
+export type SessionOptions = {
+    id: string;
+    agent: string;
+    client: ClientSink;
+    agentConfig: AgentConfig;
+    toolSchemas: readonly ToolSchema[];
+    apiKey: string;
+    s2sConfig: S2SConfig;
+    executeTool: ExecuteTool;
+    createWebSocket: CreateS2sWebSocket;
+    env?: Record<string, string | undefined>;
+    hookInvoker?: HookInvoker;
+    skipGreeting?: boolean;
+    logger?: Logger;
+    metrics?: Metrics;
+};
+export declare const _internals: {
+    connectS2s: typeof connectS2s;
+};
+/** Create an S2S-backed session with the same interface as the STT+LLM+TTS session. */
+export declare function createS2sSession(opts: SessionOptions): Session;
+//# sourceMappingURL=session.d.ts.map

package/dist/sdk/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../sdk/session.ts"],"names":[],"mappings":"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"}