@alexkroman1/aai 0.10.3 → 0.10.4

package/dist/protocol.js

@@ -1,2 +1,140 @@
-import { a as DEFAULT_TTS_SAMPLE_RATE, c as MAX_TOOL_RESULT_CHARS, d as SessionErrorCodeSchema, f as TOOL_EXECUTION_TIMEOUT_MS, i as DEFAULT_STT_SAMPLE_RATE, l as ReadyConfigSchema, m as buildReadyConfig, n as ClientEventSchema, o as HOOK_TIMEOUT_MS, p as TurnConfigSchema, r as ClientMessageSchema, s as KvRequestSchema, t as AUDIO_FORMAT, u as ServerMessageSchema } from "./protocol-B-H2Q4ox.js";
-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 };
+import { p as MAX_TOOL_RESULT_CHARS } from "./constants-BbAOvKl_.js";
+import { z } from "zod";
+//#region protocol.ts
+/**
+* WebSocket wire-format types shared by server and client.
+*
+* Note: this module is for internal use only and should not be used directly.
+*/
+/**
+* Audio codec identifier used in the wire protocol.
+*
+* All audio frames are 16-bit signed PCM, little-endian, mono.
+*/
+const AUDIO_FORMAT = "pcm16";
+/** Zod schema for KV operation requests from the worker to the host. */
+const KvRequestSchema = z.discriminatedUnion("op", [
+	z.object({
+		op: z.literal("get"),
+		key: z.string().min(1)
+	}),
+	z.object({
+		op: z.literal("set"),
+		key: z.string().min(1),
+		value: z.string(),
+		expireIn: z.number().int().positive().optional()
+	}),
+	z.object({
+		op: z.literal("del"),
+		key: z.string().min(1)
+	}),
+	z.object({
+		op: z.literal("list"),
+		prefix: z.string(),
+		limit: z.number().int().positive().optional(),
+		reverse: z.boolean().optional()
+	}),
+	z.object({
+		op: z.literal("keys"),
+		pattern: z.string().optional()
+	})
+]);
+/**
+* Zod schema for session error codes.
+* @public
+*/
+const SessionErrorCodeSchema = z.enum([
+	"stt",
+	"llm",
+	"tts",
+	"tool",
+	"protocol",
+	"connection",
+	"audio",
+	"internal"
+]);
+/** Helper: simple event with only a type field. */
+const ev = (t) => z.object({ type: z.literal(t) });
+/** Helper: event with type + text. */
+const textEv = (t) => z.object({
+	type: z.literal(t),
+	text: z.string()
+});
+const turnOrder = z.number().int().nonnegative().optional();
+/** Zod schema for {@link ClientEvent}. */
+const ClientEventSchema = z.discriminatedUnion("type", [
+	ev("speech_started"),
+	ev("speech_stopped"),
+	z.object({
+		type: z.literal("transcript"),
+		text: z.string(),
+		isFinal: z.boolean(),
+		turnOrder
+	}),
+	textEv("turn").extend({ turnOrder }),
+	textEv("chat"),
+	textEv("chat_delta"),
+	z.object({
+		type: z.literal("tool_call_start"),
+		toolCallId: z.string(),
+		toolName: z.string(),
+		args: z.record(z.string(), z.unknown())
+	}),
+	z.object({
+		type: z.literal("tool_call_done"),
+		toolCallId: z.string(),
+		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(),
+		sessionId: z.string().optional()
+	}),
+	ev("audio_done"),
+	...ClientEventSchema.options
+]);
+/** Zod schema for client→server text messages. */
+const ClientMessageSchema = z.discriminatedUnion("type", [
+	ev("audio_ready"),
+	ev("cancel"),
+	ev("reset"),
+	z.object({
+		type: z.literal("history"),
+		messages: z.array(z.object({
+			role: z.enum(["user", "assistant"]),
+			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, ClientEventSchema, ClientMessageSchema, KvRequestSchema, ReadyConfigSchema, ServerMessageSchema, SessionErrorCodeSchema, TurnConfigSchema, buildReadyConfig };

package/dist/server.d.ts

@@ -1,61 +1,48 @@
 /**
  * Self-hostable agent server.
  *
- * `createServer()` returns a server with `listen()` for HTTP + WebSocket.
- * Calls `createDirectExecutor` + `wireSessionSocket` directly — no
- * intermediary needed.
+ * {@link createServer} wraps a {@link Runtime} with an HTTP + WebSocket
+ * server using only `node:http` and `ws` (no framework dependencies).
  */
-import { type Storage } from "unstorage";
-import type { Logger, S2SConfig } from "./runtime.ts";
-import type { AgentDef } from "./types.ts";
+import type { Runtime } from "./direct-executor.ts";
+import type { Kv } from "./kv.ts";
+import type { Logger } from "./runtime.ts";
+export { createRuntime, type Runtime, type RuntimeOptions } from "./direct-executor.ts";
 /**
- * Configuration for a self-hosted agent server created by {@link createServer}.
- *
+ * Configuration for {@link createServer}.
  * @public
  */
 export type ServerOptions = {
-    /** The agent definition returned by `defineAgent()`. */
-    agent: AgentDef<any>;
-    /** Environment variables. Defaults to `process.env`. */
-    env?: Record<string, string>;
-    /**
-     * Unstorage instance for KV and vector storage. Defaults to in-memory.
-     * Configure with an S3/R2/filesystem driver for persistence.
-     */
-    storage?: Storage;
-    /** HTML to serve at `GET /`. */
+    runtime: Runtime;
+    name?: string;
+    kv?: Kv;
     clientHtml?: string;
-    /** Directory containing built client files (index.html + assets/). */
     clientDir?: string;
-    /** Logger. Defaults to console. */
     logger?: Logger;
-    /** S2S configuration. Defaults to AssemblyAI production. */
-    s2sConfig?: S2SConfig;
-    /**
-     * Timeout in ms for `session.start()` (S2S connection setup).
-     * Defaults to 10 000 (10 s). If the session doesn't initialize within
-     * this window the connection is cleaned up.
-     */
-    sessionStartTimeoutMs?: number;
-    /**
-     * Maximum time in milliseconds to wait for sessions to stop during
-     * {@link AgentServer.close | close()}. Sessions still running after this
-     * deadline are force-closed. Defaults to `30_000` (30 seconds).
-     */
-    shutdownTimeoutMs?: number;
 };
 /**
- * Handle returned by {@link createServer} with lifecycle methods to start
- * and stop the HTTP + WebSocket server.
- *
+ * Handle returned by {@link createServer}.
  * @public
  */
 export type AgentServer = {
-    /** Start listening on the given port. */
     listen(port?: number): Promise<void>;
-    /** Stop the server. */
     close(): Promise<void>;
-    /** The port the server is listening on, or `undefined` before `listen()`. */
     port: number | undefined;
 };
+/**
+ * Create an HTTP + WebSocket server for self-hosted agent deployments.
+ *
+ * @example
+ * ```ts
+ * import { defineAgent } from "@alexkroman1/aai";
+ * import { createRuntime, createServer } from "@alexkroman1/aai/server";
+ *
+ * const agent = defineAgent({ name: "my-agent" });
+ * const runtime = createRuntime({ agent, env: process.env });
+ * const server = createServer({ runtime, name: agent.name });
+ * await server.listen(3000);
+ * ```
+ *
+ * @public
+ */
 export declare function createServer(options: ServerOptions): AgentServer;

package/dist/server.js

@@ -1,183 +1,155 @@
-import { t as createUnstorageVectorStore } from "./unstorage-vector-Cj5llNhg.js";
-import { i as filterEnv } from "./_utils-DgzpOMSV.js";
-import { t as createDirectExecutor } from "./direct-executor-B-5mq3cu.js";
-import { m as buildReadyConfig } from "./protocol-B-H2Q4ox.js";
-import { n as consoleLogger, t as DEFAULT_S2S_CONFIG } from "./runtime-CxcwaK68.js";
-import { t as createUnstorageKv } from "./unstorage-kv-CDgP-frt.js";
-import { t as wireSessionSocket } from "./ws-handler-C0Q6eSay.js";
-import { createStorage } from "unstorage";
-import { serve } from "@hono/node-server";
-import { serveStatic } from "@hono/node-server/serve-static";
-import { createNodeWebSocket } from "@hono/node-ws";
-import { Hono } from "hono";
-import { html } from "hono/html";
-import { secureHeaders } from "hono/secure-headers";
+import { t as AGENT_CSP } from "./constants-BbAOvKl_.js";
+import { _ as consoleLogger, t as createRuntime } from "./direct-executor-BfHrDdPL.js";
+import fs from "node:fs";
+import http from "node:http";
+import path from "node:path";
+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
-* intermediary needed.
+* {@link createServer} wraps a {@link Runtime} with an HTTP + WebSocket
+* server using only `node:http` and `ws` (no framework dependencies).
 */
+const MIME_TYPES = {
+	".html": "text/html",
+	".js": "application/javascript",
+	".mjs": "application/javascript",
+	".css": "text/css",
+	".json": "application/json",
+	".svg": "image/svg+xml",
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".ico": "image/x-icon",
+	".woff2": "font/woff2",
+	".woff": "font/woff",
+	".map": "application/json"
+};
+function serveStatic(dir, req, res) {
+	const url = req.url?.split("?")[0] ?? "/";
+	const filePath = path.join(dir, url === "/" ? "index.html" : url);
+	if (!filePath.startsWith(dir)) return false;
+	try {
+		const stat = fs.statSync(filePath);
+		if (!stat.isFile()) return false;
+		const mime = MIME_TYPES[path.extname(filePath).toLowerCase()] ?? "application/octet-stream";
+		res.writeHead(200, {
+			"Content-Type": mime,
+			"Content-Length": stat.size
+		});
+		fs.createReadStream(filePath).pipe(res);
+		return true;
+	} catch {
+		return false;
+	}
+}
 /**
 * Create an HTTP + WebSocket server for self-hosted agent deployments.
 *
-* Sets up a Hono HTTP server with a `/health` endpoint and WebSocket upgrade
-* handling. Agent tools execute directly in-process via {@link createDirectExecutor}.
-*
-* @param options - Server configuration including the agent definition, optional
-*   KV store, client assets, logger, and S2S config. See {@link ServerOptions}.
-* @returns An {@link AgentServer} with `listen()` and `close()` lifecycle methods.
-*
 * @example
 * ```ts
 * import { defineAgent } from "@alexkroman1/aai";
-* import { createServer } from "@alexkroman1/aai/server";
+* import { createRuntime, createServer } from "@alexkroman1/aai/server";
 *
 * const agent = defineAgent({ name: "my-agent" });
-* const server = createServer({ agent });
+* const runtime = createRuntime({ agent, env: process.env });
+* const server = createServer({ runtime, name: agent.name });
 * await server.listen(3000);
 * ```
 *
 * @public
 */
-async function drainSessions(sessions, shutdownTimeoutMs, logger) {
-	if (sessions.size === 0) return;
-	let timer;
-	const timeout = new Promise((resolve) => {
-		timer = setTimeout(resolve, shutdownTimeoutMs, "timeout");
-	});
-	const graceful = Promise.allSettled([...sessions.values()].map((s) => s.stop())).then((results) => {
-		for (const r of results) if (r.status === "rejected") logger.warn(`Session stop failed during close: ${r.reason}`);
-		return "done";
-	});
-	const outcome = await Promise.race([graceful, timeout]);
-	if (timer) clearTimeout(timer);
-	if (outcome === "timeout") logger.warn(`Shutdown timeout (${shutdownTimeoutMs}ms) exceeded — force-closing ${sessions.size} remaining session(s)`);
-	sessions.clear();
-}
 function createServer(options) {
-	if (options.clientHtml && options.clientDir) throw new Error("ServerOptions: clientHtml and clientDir are mutually exclusive — provide one or the other, not both.");
-	const { agent, clientHtml, clientDir, logger = consoleLogger, s2sConfig = DEFAULT_S2S_CONFIG, shutdownTimeoutMs = 3e4 } = options;
-	const env = filterEnv(options.env ?? (typeof process !== "undefined" ? process.env : {}));
-	const storage = options.storage ?? createStorage();
-	const kv = createUnstorageKv({ storage });
-	const executor = createDirectExecutor({
-		agent,
-		env,
-		kv,
-		vector: createUnstorageVectorStore({ storage }),
-		logger,
-		s2sConfig
+	const { runtime, clientHtml, clientDir, logger = consoleLogger, kv } = options;
+	const name = options.name ?? "agent";
+	if (clientHtml && clientDir) throw new Error("clientHtml and clientDir are mutually exclusive");
+	const httpServer = http.createServer((req, res) => {
+		const url = req.url?.split("?")[0] ?? "/";
+		const method = req.method ?? "GET";
+		res.setHeader("Content-Security-Policy", AGENT_CSP);
+		res.setHeader("X-Content-Type-Options", "nosniff");
+		res.setHeader("X-Frame-Options", "SAMEORIGIN");
+		if (method === "GET" && url === "/health") {
+			res.writeHead(200, { "Content-Type": "application/json" });
+			res.end(JSON.stringify({
+				status: "ok",
+				name
+			}));
+			return;
+		}
+		if (kv && method === "GET" && url === "/kv") {
+			const key = new URL(req.url ?? "/", "http://localhost").searchParams.get("key");
+			if (!key) {
+				res.writeHead(400, { "Content-Type": "application/json" });
+				res.end(JSON.stringify({ error: "Missing key query parameter" }));
+				return;
+			}
+			kv.get(key).then((value) => {
+				if (value === null) {
+					res.writeHead(404, { "Content-Type": "application/json" });
+					res.end("null");
+				} else {
+					res.writeHead(200, { "Content-Type": "application/json" });
+					res.end(JSON.stringify(value));
+				}
+			}).catch(() => {
+				res.writeHead(500, { "Content-Type": "application/json" });
+				res.end(JSON.stringify({ error: "KV error" }));
+			});
+			return;
+		}
+		if (clientDir && serveStatic(clientDir, req, res)) return;
+		if (method === "GET" && url === "/") {
+			const escaped = name.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+			const body = clientHtml ?? `<!DOCTYPE html><html><body><h1>${escaped}</h1><p>Agent server running.</p></body></html>`;
+			res.writeHead(200, { "Content-Type": "text/html" });
+			res.end(body);
+			return;
+		}
+		logger.error(`${method} ${url} 404`);
+		res.writeHead(404, { "Content-Type": "application/json" });
+		res.end(JSON.stringify({ error: "Not found" }));
 	});
-	const sessions = /* @__PURE__ */ new Map();
-	const readyConfig = buildReadyConfig(s2sConfig);
-	function handleWs(ws, skipGreeting, resumeFrom) {
-		wireSessionSocket(ws, {
-			sessions,
-			createSession: (sid, client) => executor.createSession({
-				id: sid,
-				agent: agent.name,
-				client,
+	const wss = new WebSocketServer({ noServer: true });
+	httpServer.on("upgrade", (req, socket, head) => {
+		const url = req.url?.split("?")[0] ?? "";
+		if (!url.startsWith("/websocket")) return;
+		wss.handleUpgrade(req, socket, head, (ws) => {
+			const search = req.url?.includes("?") ? req.url.split("?")[1] ?? "" : "";
+			const params = new URLSearchParams(search);
+			const resumeFrom = params.get("sessionId") ?? void 0;
+			const skipGreeting = params.has("resume") || resumeFrom !== void 0;
+			logger.info(`WS upgrade ${url}${skipGreeting ? " (resume)" : ""}`);
+			runtime.startSession(ws, {
 				skipGreeting,
 				...resumeFrom ? { resumeFrom } : {}
-			}),
-			readyConfig,
-			logger,
-			...options.sessionStartTimeoutMs !== void 0 ? { sessionStartTimeoutMs: options.sessionStartTimeoutMs } : {},
-			...resumeFrom ? { resumeFrom } : {}
+			});
 		});
-	}
-	let serverHandle = null;
+	});
 	let listenPort;
 	return {
 		get port() {
 			return listenPort;
 		},
 		async listen(port = 3e3) {
-			if (serverHandle) throw new Error("Server is already listening");
-			const app = new Hono();
-			const { injectWebSocket, upgradeWebSocket } = createNodeWebSocket({ app });
-			app.onError((err, c) => {
-				logger.error(`${c.req.method} ${c.req.path} 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 = c.req.path;
-				if (status >= 400) logger.error(`${method} ${path} ${status} ${ms}ms`);
-				else logger.info(`${method} ${path} ${status} ${ms}ms`);
-			});
-			app.use("*", secureHeaders({ contentSecurityPolicy: {
-				defaultSrc: ["'self'"],
-				scriptSrc: ["'self'", "blob:"],
-				styleSrc: [
-					"'self'",
-					"'unsafe-inline'",
-					"https://fonts.googleapis.com"
-				],
-				connectSrc: [
-					"'self'",
-					"wss:",
-					"ws:"
-				],
-				imgSrc: ["'self'", "data:"],
-				fontSrc: ["'self'", "https://fonts.gstatic.com"],
-				objectSrc: ["'none'"],
-				baseUri: ["'self'"]
-			} }));
-			app.get("/health", (c) => c.json({
-				status: "ok",
-				name: agent.name
-			}));
-			app.get("/kv", async (c) => {
-				const key = c.req.query("key");
-				if (!key) return c.json({ error: "Missing key query parameter" }, 400);
-				const value = await kv.get(key);
-				if (value === null) return c.json(null, 404);
-				return c.json(value);
-			});
-			if (clientDir) app.use("/*", serveStatic({ root: clientDir }));
-			app.get("/", (c) => {
-				if (clientHtml) return c.html(clientHtml);
-				return c.html(html`<!DOCTYPE html><html><body><h1>${agent.name}</h1><p>Agent server running.</p></body></html>`);
-			});
-			app.get("/websocket", upgradeWebSocket((c) => {
-				const resumeFrom = c.req.query("sessionId") ?? void 0;
-				const skipGreeting = c.req.query("resume") !== void 0 || resumeFrom !== void 0;
-				logger.info(`WS upgrade ${c.req.path}${skipGreeting ? " (resume)" : ""}`);
-				return { onOpen(_evt, ws) {
-					if (ws.raw) handleWs(ws.raw, skipGreeting, resumeFrom);
-				} };
-			}));
-			const nodeServer = serve({
-				fetch: app.fetch,
-				port
-			});
-			injectWebSocket(nodeServer);
 			await new Promise((resolve, reject) => {
-				nodeServer.on("listening", resolve);
-				nodeServer.on("error", reject);
-			});
-			const addr = nodeServer.address();
-			listenPort = typeof addr === "object" && addr ? addr.port : port;
-			serverHandle = { async shutdown() {
-				await new Promise((resolve, reject) => {
-					nodeServer.close((err) => err ? reject(err) : resolve());
+				httpServer.on("error", reject);
+				httpServer.listen(port, () => {
+					const addr = httpServer.address();
+					listenPort = typeof addr === "object" && addr ? addr.port : port;
+					resolve();
 				});
-			} };
+			});
 		},
 		async close() {
-			await drainSessions(sessions, shutdownTimeoutMs, logger);
-			await serverHandle?.shutdown();
+			await runtime.shutdown();
+			wss.close();
+			if (listenPort !== void 0) await new Promise((resolve, reject) => {
+				httpServer.close((err) => err ? reject(err) : resolve());
+			});
 			listenPort = void 0;
 		}
 	};
 }
 //#endregion
-export { createServer };
+export { createRuntime, createServer };

package/dist/session.d.ts

@@ -1,15 +1,70 @@
 /** S2S session — relays audio between client and AssemblyAI S2S API. */
-import type { AgentConfig, ToolSchema } from "./_internal-types.ts";
-import { type SessionPersistence } from "./_session-persist.ts";
-import type { HookInvoker } from "./middleware.ts";
+import type { AgentConfig, ExecuteTool, ToolSchema } from "./_internal-types.ts";
+import type { AgentHookMap, AgentHooks } from "./hooks.ts";
 import type { ClientSink } from "./protocol.ts";
 import type { Logger, S2SConfig } from "./runtime.ts";
-import { type CreateS2sWebSocket, connectS2s } from "./s2s.ts";
-import type { ExecuteTool } from "./worker-entry.ts";
-export type { S2sSessionCtx } from "./_session-ctx.ts";
-export type { PersistedSession, SessionPersistence } from "./_session-persist.ts";
-export { persistKey } from "./_session-persist.ts";
-export type { HookInvoker, ToolInterceptResult } from "./middleware.ts";
+import { type CreateS2sWebSocket, connectS2s, type S2sHandle } from "./s2s.ts";
+import type { Message } from "./types.ts";
+export type { S2sHandle } from "./s2s.ts";
+type PendingTool = {
+    callId: string;
+    result: string;
+};
+/** Per-reply mutable state — reset on beginReply/cancelReply. */
+export type ReplyState = {
+    pendingTools: PendingTool[];
+    toolCallCount: number;
+    currentReplyId: string | null;
+};
+/** Immutable dependencies injected at session creation. */
+export type SessionDeps = {
+    readonly id: string;
+    readonly agent: string;
+    readonly client: ClientSink;
+    readonly agentConfig: AgentConfig;
+    readonly executeTool: ExecuteTool;
+    readonly hooks: AgentHooks | undefined;
+    readonly log: Logger;
+    readonly maxHistory: number;
+};
+/**
+ * Session context threaded through event handlers.
+ *
+ * Split into three layers:
+ * - {@link SessionDeps} — immutable dependencies (set once)
+ * - {@link ReplyState} via `reply` — per-reply mutable state (reset on beginReply/cancelReply)
+ * - Remaining fields — connection, conversation, and lifecycle methods
+ */
+export type S2sSessionCtx = SessionDeps & {
+    s2s: S2sHandle | null;
+    reply: ReplyState;
+    turnPromise: Promise<void> | null;
+    conversationMessages: Message[];
+    resolveTurnConfig(): Promise<{
+        maxSteps?: number;
+    } | null>;
+    consumeToolCallStep(turnConfig: {
+        maxSteps?: number;
+    } | null, name: string, replyId: string | null): string | null;
+    fireHook(name: keyof AgentHookMap, ...args: unknown[]): void;
+    drainHooks(): Promise<void>;
+    pushMessages(...msgs: Message[]): void;
+    beginReply(replyId: string): void;
+    cancelReply(): void;
+    chainTurn(p: Promise<void>): void;
+};
+export declare function buildCtx(opts: {
+    id: string;
+    agent: string;
+    client: ClientSink;
+    agentConfig: AgentConfig;
+    executeTool: ExecuteTool;
+    hooks: AgentHooks | undefined;
+    log: Logger;
+    maxHistory?: number | undefined;
+}): S2sSessionCtx;
+export type { AgentHookMap, AgentHooks } from "./hooks.ts";
+export { callResolveTurnConfig, createAgentHooks } from "./hooks.ts";
 export { buildSystemPrompt } from "./system-prompt.ts";
 /**
  * A voice session managing the Speech-to-Speech connection for one client.
@@ -20,27 +75,16 @@ export { buildSystemPrompt } from "./system-prompt.ts";
  * @internal Exported for use by `ws-handler.ts`, `server.ts`, and `direct-executor.ts`.
  */
 export type Session = {
-    /** Open the S2S connection and fire the `onConnect` hook. */
     start(): Promise<void>;
-    /** Gracefully shut down: wait for in-flight turns, close the S2S socket, fire `onDisconnect`. */
     stop(): Promise<void>;
-    /** Forward raw PCM audio from the client microphone to the S2S connection. */
     onAudio(data: Uint8Array): void;
-    /** Called when the client has finished setting up its audio pipeline. For S2S sessions this is a no-op since the greeting comes automatically. */
     onAudioReady(): void;
-    /** Handle a client-initiated cancellation (barge-in). Sends a `cancelled` event. */
     onCancel(): void;
-    /** Reset the session: clear conversation history, bump generation counters, reconnect S2S. */
     onReset(): void;
-    /**
-     * Inject conversation history from the client (e.g. on reconnect).
-     * @param incoming - Messages with `{role, content}` fields.
-     */
     onHistory(incoming: readonly {
         role: "user" | "assistant";
         content: string;
     }[]): void;
-    /** Returns a promise that resolves when the current in-flight turn completes, or resolves immediately if no turn is active. */
     waitForTurn(): Promise<void>;
 };
 /** Configuration options for creating a new session. */
@@ -55,36 +99,13 @@ export type S2sSessionOptions = {
     executeTool: ExecuteTool;
     createWebSocket?: CreateS2sWebSocket;
     env?: Record<string, string | undefined>;
-    hookInvoker?: HookInvoker;
+    hooks?: AgentHooks;
     skipGreeting?: boolean;
     logger?: Logger;
-    /** Maximum number of conversation messages to retain. Older messages are
-     *  dropped (sliding window) to bound memory in long-running sessions.
-     *  Defaults to 200. Set to 0 or Infinity to disable trimming. */
     maxHistory?: number;
-    /** Persistence configuration for auto-saving/restoring session data. */
-    persistence?: SessionPersistence;
-    /** Old session ID to resume from. Loads persisted state/messages from KV
-     *  and attempts S2S session resume. */
-    resumeFrom?: string;
 };
 /** @internal Not part of the public API. Exposed for testing only. */
 export declare const _internals: {
     connectS2s: typeof connectS2s;
 };
-/**
- * Create a Speech-to-Speech backed session implementing the {@link Session} interface.
- *
- * Connects to AssemblyAI's S2S WebSocket, configures the system prompt and tools,
- * and wires up event listeners for user transcripts, agent replies, tool calls,
- * barge-ins, and session lifecycle. Manages reconnection on `onReset` via a
- * `connectGeneration` guard that prevents stale connection attempts from overwriting
- * newer ones during rapid resets. A `sessionAbort` AbortController is used to
- * coordinate cleanup on `stop()`.
- *
- * @param opts - Session configuration. See {@link S2sSessionOptions} for all fields
- *   including the agent config, tool schemas, API key, and optional hooks.
- * @returns A {@link Session} with `start`, `stop`, `onAudio`, `onReset`, and other
- *   lifecycle methods.
- */
 export declare function createS2sSession(opts: S2sSessionOptions): Session;