@alexkroman1/aai 1.0.5 → 1.1.0

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @alexkroman1/aai@1.0.5 build /home/runner/work/agent/agent/packages/aai
+> @alexkroman1/aai@1.1.0 build /home/runner/work/agent/agent/packages/aai
 > tsdown && tsc -p tsconfig.build.json
 
 ℹ tsdown v0.21.7 powered by rolldown v1.0.0-rc.12
@@ -8,13 +8,13 @@
 ℹ target: node22
 ℹ tsconfig: tsconfig.json
 ℹ Build start
-ℹ dist/host/runtime-barrel.js     47.10 kB │ gzip: 14.49 kB
-ℹ dist/sdk/protocol.js             4.83 kB │ gzip:  1.77 kB
-ℹ dist/index.js                    2.49 kB │ gzip:  1.04 kB
-ℹ dist/sdk/manifest-barrel.js      2.19 kB │ gzip:  0.99 kB
-ℹ dist/system-prompt-nik_iavo.js   4.77 kB │ gzip:  2.09 kB
-ℹ dist/constants-VTFoymJ-.js       2.75 kB │ gzip:  1.23 kB
-ℹ dist/types-Cfx_4QDK.js           1.74 kB │ gzip:  0.93 kB
-ℹ dist/ws-upgrade-BeOQ7fXL.js      1.14 kB │ gzip:  0.54 kB
-ℹ 8 files, total: 67.02 kB
-✔ Build complete in 40ms
+ℹ dist/host/runtime-barrel.js       50.02 kB │ gzip: 15.70 kB
+ℹ dist/sdk/protocol.js               4.75 kB │ gzip:  1.76 kB
+ℹ dist/index.js                      2.49 kB │ gzip:  1.04 kB
+ℹ dist/sdk/manifest-barrel.js        0.26 kB │ gzip:  0.17 kB
+ℹ dist/constants-VTFoymJ-.js         2.75 kB │ gzip:  1.23 kB
+ℹ dist/_internal-types-CoDTiBd1.js   2.33 kB │ gzip:  0.99 kB
+ℹ dist/types-Cfx_4QDK.js             1.74 kB │ gzip:  0.93 kB
+ℹ dist/ws-upgrade-BeOQ7fXL.js        1.14 kB │ gzip:  0.54 kB
+ℹ 8 files, total: 65.47 kB
+✔ Build complete in 51ms

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @alexkroman1/aai
 
+## 1.1.0
+
+### Minor Changes
+
+- 5cda7c5: Add ctx.send for real-time tool-to-client events
+
+  Tools can now push arbitrary events to the browser client via `ctx.send(event, data)`. Events flow over the existing WebSocket as `custom_event` messages. The new `useEvent` React hook subscribes to named events. Migrated solo-rpg, pizza-ordering, dispatch-center, and night-owl templates from `useToolResult` to `ctx.send` + `useEvent`.
+
+### Patch Changes
+
+- 41fab1a: Remove dead code: unused exports, wrappers, and test hooks
+
+## 1.0.6
+
 ## 1.0.5
 
 ## 1.0.4

package/dist/_internal-types-CoDTiBd1.js

@@ -0,0 +1,61 @@
+import { i as ToolChoiceSchema, t as BuiltinToolSchema } from "./types-Cfx_4QDK.js";
+import { z } from "zod";
+//#region sdk/_internal-types.ts
+/**
+* Zod schema for serializable agent configuration sent over the wire.
+*
+* This is the JSON-safe subset of the agent definition that can be
+* transmitted between the worker and the host process via structured clone.
+*/
+const AgentConfigSchema = z.object({
+	name: z.string().min(1),
+	systemPrompt: z.string(),
+	greeting: z.string(),
+	sttPrompt: z.string().optional(),
+	maxSteps: z.number().int().positive().optional(),
+	toolChoice: ToolChoiceSchema.optional(),
+	builtinTools: z.array(BuiltinToolSchema).readonly().optional(),
+	idleTimeoutMs: z.number().nonnegative().optional()
+});
+/** Extract the serializable {@link AgentConfig} subset from a source object. */
+function toAgentConfig(src) {
+	const config = {
+		name: src.name,
+		systemPrompt: src.systemPrompt,
+		greeting: src.greeting
+	};
+	if (src.sttPrompt !== void 0) config.sttPrompt = src.sttPrompt;
+	if (src.maxSteps !== void 0) config.maxSteps = src.maxSteps;
+	if (src.toolChoice !== void 0) config.toolChoice = src.toolChoice;
+	if (src.builtinTools) config.builtinTools = [...src.builtinTools];
+	if (src.idleTimeoutMs !== void 0) config.idleTimeoutMs = src.idleTimeoutMs;
+	return config;
+}
+/**
+* Zod schema for serialized tool definitions sent over the wire.
+*
+* `parameters` must be a valid JSON Schema object (with `type`, `properties`,
+* etc.) — the Vercel AI SDK wraps it via `jsonSchema()`.
+*/
+const ToolSchemaSchema = z.object({
+	name: z.string().min(1),
+	description: z.string().min(1),
+	parameters: z.record(z.string(), z.unknown())
+});
+/** Empty Zod object schema used as default when tools have no parameters. */
+const EMPTY_PARAMS = z.object({});
+/**
+* Convert agent tool definitions to JSON Schema format for wire transport.
+*
+* Transforms the Zod-based `parameters` of each tool into a plain JSON Schema
+* object suitable for structured clone / JSON serialization.
+*/
+function agentToolsToSchemas(tools) {
+	return Object.entries(tools).map(([name, def]) => ({
+		name,
+		description: def.description,
+		parameters: z.toJSONSchema(def.parameters ?? EMPTY_PARAMS)
+	}));
+}
+//#endregion
+export { toAgentConfig as a, agentToolsToSchemas as i, EMPTY_PARAMS as n, ToolSchemaSchema as r, AgentConfigSchema as t };

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

@@ -89,27 +89,3 @@ export declare class MockWebSocket extends EventTarget {
      */
     sentJson(): Record<string, unknown>[];
 }
-/**
- * Replace `globalThis.WebSocket` with {@link MockWebSocket} for testing.
- *
- * Returns a handle that tracks all created mock sockets and can restore the
- * original `WebSocket` constructor. Supports the `using` declaration via
- * `Symbol.dispose` for automatic cleanup.
- *
- * @returns An object with `created` array, `lastWs` getter, `restore()`, and `[Symbol.dispose]()`.
- *
- * @example
- * ```ts
- * using mock = installMockWebSocket();
- * const session = new Session("wss://example.com");
- * const ws = mock.lastWs!;
- * ws.simulateMessage(JSON.stringify({ type: "ready" }));
- * // mock automatically restores WebSocket when disposed
- * ```
- */
-export declare function installMockWebSocket(): {
-    restore: () => void;
-    created: MockWebSocket[];
-    get lastWs(): MockWebSocket | null;
-    [Symbol.dispose]: () => void;
-};

package/dist/host/runtime-barrel.d.ts

@@ -6,7 +6,6 @@
 export * from "./builtin-tools.ts";
 export * from "./runtime.ts";
 export * from "./runtime-config.ts";
-export * from "./s2s.ts";
 export * from "./server.ts";
 export * from "./session.ts";
 export * from "./session-ctx.ts";

package/dist/host/runtime-barrel.js

@@ -1,7 +1,8 @@
 import { a as DEFAULT_SHUTDOWN_TIMEOUT_MS, c as FETCH_TIMEOUT_MS, d as MAX_PAGE_CHARS, f as MAX_TOOL_RESULT_CHARS, g as TOOL_EXECUTION_TIMEOUT_MS, h as RUN_CODE_TIMEOUT_MS, l as MAX_HTML_BYTES, m as MAX_WS_PAYLOAD_BYTES, o as DEFAULT_STT_SAMPLE_RATE, p as MAX_VALUE_SIZE, s as DEFAULT_TTS_SAMPLE_RATE, t as AGENT_CSP } from "../constants-VTFoymJ-.js";
+import { r as DEFAULT_SYSTEM_PROMPT } from "../types-Cfx_4QDK.js";
 import { i as toolError, n as errorDetail, r as errorMessage, t as parseWsUpgradeParams } from "../ws-upgrade-BeOQ7fXL.js";
 import { ClientMessageSchema, buildReadyConfig, lenientParse } from "../sdk/protocol.js";
-import { a as agentToolsToSchemas, o as toAgentConfig, r as EMPTY_PARAMS, t as buildSystemPrompt } from "../system-prompt-nik_iavo.js";
+import { a as toAgentConfig, i as agentToolsToSchemas, n as EMPTY_PARAMS } from "../_internal-types-CoDTiBd1.js";
 import { z } from "zod";
 import { convert } from "html-to-text";
 import vm from "node:vm";
@@ -384,6 +385,37 @@ const DEFAULT_S2S_CONFIG = {
 	outputSampleRate: DEFAULT_TTS_SAMPLE_RATE
 };
 //#endregion
+//#region sdk/system-prompt.ts
+function getFormattedDate() {
+	return (/* @__PURE__ */ new Date()).toLocaleDateString("en-US", {
+		weekday: "long",
+		year: "numeric",
+		month: "long",
+		day: "numeric"
+	});
+}
+const VOICE_RULES = "\n\nCRITICAL OUTPUT RULES — you MUST follow these for EVERY response:\nYour response will be spoken aloud by a TTS system and displayed as plain text.\n- NEVER use markdown: no **, no *, no _, no #, no `, no [](), no ---\n- NEVER use bullet points (-, *, •) or numbered lists (1., 2.)\n- NEVER use code blocks or inline code\n- NEVER mention tools, search, APIs, or technical failures to the user. If a tool returns no results, just answer naturally without explaining why.\n- Write exactly as you would say it out loud to a friend\n- Use short conversational sentences. To list things, say \"First,\" \"Next,\" \"Finally,\"\n- Keep responses concise — 1 to 3 sentences max";
+/**
+* Build the system prompt sent to the LLM from the agent configuration.
+*
+* Assembles the default system prompt, today's date, agent-specific instructions,
+* and optional sections for tool usage preamble and voice output rules.
+*
+* @param config - The serializable agent configuration (name, systemPrompt, etc.).
+* @param opts.hasTools - When `true`, appends a preamble instructing the LLM to
+*   speak a brief phrase before each tool call to fill silence.
+* @param opts.voice - When `true`, appends strict voice-specific output rules
+*   (no markdown, no bullet points, conversational tone, concise responses).
+* @returns The assembled system prompt string.
+*/
+function buildSystemPrompt(config, opts) {
+	const { hasTools } = opts;
+	const agentInstructions = config.systemPrompt && config.systemPrompt !== DEFAULT_SYSTEM_PROMPT ? `\n\nAgent-Specific Instructions:\n${config.systemPrompt}` : "";
+	const toolPreamble = hasTools ? "\n\nWhen you decide to use a tool, ALWAYS say a brief natural phrase BEFORE the tool call (e.g. \"Let me look that up\" or \"One moment while I check\"). This fills silence while the tool executes. Keep preambles to one short sentence." : "";
+	const guidance = opts.toolGuidance && opts.toolGuidance.length > 0 ? `\n\nBuilt-in Tool Usage:\n${opts.toolGuidance.join("\n")}` : "";
+	return DEFAULT_SYSTEM_PROMPT + `\n\nToday's date is ${getFormattedDate()}.` + agentInstructions + toolPreamble + guidance + (opts.voice ? VOICE_RULES : "");
+}
+//#endregion
 //#region host/s2s.ts
 const uint8ToBase64 = (bytes) => Buffer.from(bytes).toString("base64");
 const base64ToUint8 = (base64) => new Uint8Array(Buffer.from(base64, "base64"));
@@ -976,7 +1008,10 @@ function buildToolContext(opts) {
 			return kv;
 		},
 		messages: messages ?? [],
-		sessionId: sessionId ?? ""
+		sessionId: sessionId ?? "",
+		send(event, data) {
+			opts.send?.(event, data);
+		}
 	};
 }
 async function executeToolCall(name, args, options) {
@@ -1173,6 +1208,7 @@ function wireSessionSocket(ws, opts) {
 		const client = createClientSink(ws, log);
 		session = opts.createSession(sessionId, client);
 		sessions.set(sessionId, session);
+		opts.onSinkCreated?.(sessionId, client);
 		ws.send(JSON.stringify({
 			type: "config",
 			...opts.readyConfig,
@@ -1267,6 +1303,7 @@ function createRuntime(opts) {
 	const { agent, env, kv = createLocalKv(), createWebSocket, logger = consoleLogger, s2sConfig = DEFAULT_S2S_CONFIG, sessionStartTimeoutMs, shutdownTimeoutMs = DEFAULT_SHUTDOWN_TIMEOUT_MS } = opts;
 	const agentConfig = toAgentConfig(agent);
 	const sessions = /* @__PURE__ */ new Map();
+	const sinkMap = /* @__PURE__ */ new Map();
 	const readyConfig = buildReadyConfig(s2sConfig);
 	let executeTool;
 	let toolSchemas;
@@ -1309,6 +1346,7 @@ function createRuntime(opts) {
 		executeTool = async (name, args, sessionId, messages) => {
 			const tool = allTools[name];
 			if (!tool) return toolError(`Unknown tool: ${name}`);
+			const sink = sinkMap.get(sessionId ?? "");
 			return executeToolCall(name, args, {
 				tool,
 				env: frozenEnv,
@@ -1316,11 +1354,17 @@ function createRuntime(opts) {
 				sessionId: sessionId ?? "",
 				kv,
 				messages,
-				logger
+				logger,
+				send: sink ? (event, data) => sink.event({
+					type: "custom_event",
+					event,
+					data
+				}) : void 0
 			});
 		};
 	}
 	function createSession(sessionOpts) {
+		sinkMap.set(sessionOpts.id, sessionOpts.client);
 		const apiKey = env.ASSEMBLYAI_API_KEY ?? "";
 		return createS2sSession({
 			id: sessionOpts.id,
@@ -1340,6 +1384,7 @@ function createRuntime(opts) {
 	}
 	function startSession(ws, startOpts) {
 		const resumeFrom = startOpts?.resumeFrom;
+		const userOnSessionEnd = startOpts?.onSessionEnd;
 		wireSessionSocket(ws, {
 			sessions,
 			createSession: (sid, client) => createSession({
@@ -1354,7 +1399,11 @@ function createRuntime(opts) {
 			...startOpts?.logContext ? { logContext: startOpts.logContext } : {},
 			...startOpts?.onOpen ? { onOpen: startOpts.onOpen } : {},
 			...startOpts?.onClose ? { onClose: startOpts.onClose } : {},
-			...startOpts?.onSessionEnd ? { onSessionEnd: startOpts.onSessionEnd } : {},
+			...startOpts?.onSinkCreated ? { onSinkCreated: startOpts.onSinkCreated } : {},
+			onSessionEnd: (sid) => {
+				sinkMap.delete(sid);
+				userOnSessionEnd?.(sid);
+			},
 			...sessionStartTimeoutMs !== void 0 ? { sessionStartTimeoutMs } : {},
 			...resumeFrom ? { resumeFrom } : {}
 		});
@@ -1368,6 +1417,7 @@ function createRuntime(opts) {
 			logger.warn(`Shutdown timeout (${shutdownTimeoutMs}ms) exceeded — force-closing ${sessions.size} remaining session(s)`);
 		}
 		sessions.clear();
+		sinkMap.clear();
 	}
 	return {
 		executeTool,
@@ -1515,4 +1565,4 @@ function createServer(options) {
 	};
 }
 //#endregion
-export { DEFAULT_S2S_CONFIG, _internals, buildCtx, connectS2s, consoleLogger, createRuntime, createS2sSession, createServer, createUnstorageKv, defaultCreateS2sWebSocket, executeInIsolate, executeToolCall, jsonLogger, resolveAllBuiltins, wireSessionSocket };
+export { DEFAULT_S2S_CONFIG, _internals, buildCtx, consoleLogger, createRuntime, createS2sSession, createServer, createUnstorageKv, executeInIsolate, executeToolCall, jsonLogger, resolveAllBuiltins, wireSessionSocket };

package/dist/host/runtime.d.ts

@@ -24,6 +24,8 @@ export type SessionStartOptions = {
     onClose?: () => void;
     /** Called with session ID after session cleanup, for guest state cleanup. */
     onSessionEnd?: (sessionId: string) => void;
+    /** Called with session ID and client sink after session setup. Used by sandbox to route custom events. */
+    onSinkCreated?: (sessionId: string, sink: ClientSink) => void;
 };
 /**
  * Common interface for agent runtimes.

package/dist/host/tool-executor.d.ts

@@ -16,5 +16,6 @@ export type ExecuteToolCallOptions = {
     kv?: Kv | undefined;
     messages?: readonly Message[] | undefined;
     logger?: Logger | undefined;
+    send?: ((event: string, data: unknown) => void) | undefined;
 };
 export declare function executeToolCall(name: string, args: Readonly<Record<string, unknown>>, options: ExecuteToolCallOptions): Promise<string>;

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

@@ -38,6 +38,8 @@ export type WsSessionOptions = {
     onClose?: () => void;
     /** Callback invoked with the session ID after session cleanup. */
     onSessionEnd?: (sessionId: string) => void;
+    /** Callback invoked with the session ID and client sink after session setup. */
+    onSinkCreated?: (sessionId: string, sink: ClientSink) => void;
     /** Logger instance. Defaults to console. */
     logger?: Logger;
     /** Timeout in ms for session.start(). Defaults to 10 000 (10s). */

package/dist/sdk/manifest-barrel.d.ts

@@ -1,8 +1,6 @@
 /**
- * Manifest barrel — agent manifest parsing and tool schema conversion.
+ * Manifest barrel — agent config conversion and tool schema handling.
  *
- * Used by aai-cli (scanner, bundler) and aai-server (tests).
+ * Used by aai-cli (bundler) and aai-server (rpc-schemas).
  */
-export * from "./_internal-types.ts";
-export * from "./manifest.ts";
-export * from "./system-prompt.ts";
+export { type AgentConfig, AgentConfigSchema, type AgentConfigSource, agentToolsToSchemas, EMPTY_PARAMS, type ExecuteTool, type ToolSchema, ToolSchemaSchema, toAgentConfig, } from "./_internal-types.ts";

package/dist/sdk/manifest-barrel.js

@@ -1,52 +1,2 @@
-import { r as DEFAULT_SYSTEM_PROMPT, t as BuiltinToolSchema } from "../types-Cfx_4QDK.js";
-import { a as agentToolsToSchemas, i as ToolSchemaSchema, n as AgentConfigSchema, o as toAgentConfig, r as EMPTY_PARAMS, t as buildSystemPrompt } from "../system-prompt-nik_iavo.js";
-import { z } from "zod";
-//#region sdk/manifest.ts
-/**
-* Canonical manifest format for directory-based agents.
-*
-* Flows from build → host → sdk. Validated via Zod at the boundary,
-* then used as a plain typed object throughout the runtime.
-*/
-const ToolManifestSchema = z.object({
-	description: z.string(),
-	parameters: z.record(z.string(), z.unknown()).optional()
-});
-const ManifestSchema = z.object({
-	name: z.string().min(1),
-	systemPrompt: z.string().optional(),
-	greeting: z.string().optional(),
-	sttPrompt: z.string().optional(),
-	builtinTools: z.array(BuiltinToolSchema).optional(),
-	maxSteps: z.number().int().positive().optional(),
-	toolChoice: z.enum(["auto", "required"]).optional(),
-	idleTimeoutMs: z.number().int().positive().optional(),
-	theme: z.record(z.string(), z.string()).optional(),
-	tools: z.record(z.string(), ToolManifestSchema).optional()
-});
-/**
-* Parse and normalize a raw agent manifest, applying defaults for all
-* optional fields. Input is typically the JSON from a bundled agent.ts.
-*
-* Key defaults:
-* - `maxSteps`: 5 — prevents runaway tool-call loops in a single reply
-* - `toolChoice`: "auto" — LLM decides when to use tools vs respond directly
-* - `builtinTools`: [] — no built-in tools unless explicitly opted in
-*/
-function parseManifest(input) {
-	const parsed = ManifestSchema.parse(input);
-	return {
-		name: parsed.name,
-		systemPrompt: parsed.systemPrompt ?? DEFAULT_SYSTEM_PROMPT,
-		greeting: parsed.greeting ?? "Hey there. I'm a voice assistant. What can I help you with?",
-		sttPrompt: parsed.sttPrompt,
-		builtinTools: parsed.builtinTools ?? [],
-		maxSteps: parsed.maxSteps ?? 5,
-		toolChoice: parsed.toolChoice ?? "auto",
-		idleTimeoutMs: parsed.idleTimeoutMs,
-		theme: parsed.theme,
-		tools: parsed.tools ?? {}
-	};
-}
-//#endregion
-export { AgentConfigSchema, EMPTY_PARAMS, ToolSchemaSchema, agentToolsToSchemas, buildSystemPrompt, parseManifest, toAgentConfig };
+import { a as toAgentConfig, i as agentToolsToSchemas, n as EMPTY_PARAMS, r as ToolSchemaSchema, t as AgentConfigSchema } from "../_internal-types-CoDTiBd1.js";
+export { AgentConfigSchema, EMPTY_PARAMS, ToolSchemaSchema, agentToolsToSchemas, toAgentConfig };

package/dist/sdk/protocol.d.ts

@@ -4,23 +4,6 @@
  * Note: this module is for internal use only and should not be used directly.
  */
 import { z } from "zod";
-/**
- * Audio codec identifier used in the wire protocol.
- *
- * All audio frames are 16-bit signed PCM, little-endian, mono.
- */
-export declare const AUDIO_FORMAT = "pcm16";
-/**
- * Minimal envelope schema for two-phase message parsing.
- *
- * When a strict schema (ServerMessageSchema / ClientMessageSchema) rejects a
- * message, this schema determines whether the message is a valid but
- * *unrecognised* type (safe to ignore during rolling upgrades) or genuinely
- * malformed (should be warned about).
- */
-export declare const MessageEnvelopeSchema: z.ZodObject<{
-    type: z.ZodString;
-}, z.core.$loose>;
 /**
  * Two-phase message parse: tries the strict schema first, then falls back to
  * the envelope to distinguish unknown-but-valid types (safe to ignore during
@@ -134,6 +117,10 @@ export declare const ClientEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         internal: "internal";
     }>;
     message: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"custom_event">;
+    event: z.ZodString;
+    data: z.ZodUnknown;
 }, z.core.$strip>], "type">;
 /** Discriminated union of all server→client session events. */
 export type ClientEvent = z.infer<typeof ClientEventSchema>;
@@ -152,8 +139,6 @@ export interface ClientSink {
     /** Signal that TTS audio is complete. */
     playAudioDone(): void;
 }
-/** 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<{
@@ -214,6 +199,10 @@ export declare const ServerMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
         internal: "internal";
     }>;
     message: z.ZodString;
+}, z.core.$strip>, z.ZodObject<{
+    type: z.ZodLiteral<"custom_event">;
+    event: z.ZodString;
+    data: z.ZodUnknown;
 }, z.core.$strip>], "type">;
 /** Server→client text messages (binary frames carry raw PCM16 audio). */
 export type ServerMessage = z.infer<typeof ServerMessageSchema>;
@@ -241,9 +230,3 @@ 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 = z.infer<typeof TurnConfigSchema>;

package/dist/sdk/protocol.js

@@ -116,6 +116,11 @@ const ClientEventSchema = z.discriminatedUnion("type", [
 		type: z.literal("error"),
 		code: SessionErrorCodeSchema,
 		message: z.string()
+	}),
+	z.object({
+		type: z.literal("custom_event"),
+		event: z.string().min(1),
+		data: z.unknown()
 	})
 ]);
 /** Zod schema for {@link ReadyConfig}. */
@@ -157,7 +162,5 @@ function buildReadyConfig(s2sConfig) {
 		ttsSampleRate: s2sConfig.outputSampleRate
 	};
 }
-/** Zod schema for {@link TurnConfig}. */
-const TurnConfigSchema = z.object({ maxSteps: z.number().int().positive().optional() });
 //#endregion
-export { AUDIO_FORMAT, ClientEventSchema, ClientMessageSchema, KvDelSchema, KvGetSchema, KvRequestSchema, KvSetSchema, MessageEnvelopeSchema, ReadyConfigSchema, ServerMessageSchema, SessionErrorCodeSchema, TurnConfigSchema, buildReadyConfig, lenientParse };
+export { ClientEventSchema, ClientMessageSchema, KvDelSchema, KvGetSchema, KvRequestSchema, KvSetSchema, ReadyConfigSchema, ServerMessageSchema, SessionErrorCodeSchema, buildReadyConfig, lenientParse };

package/dist/sdk/types.d.ts

@@ -77,6 +77,8 @@ export type ToolContext<S = Record<string, unknown>> = {
     messages: readonly Message[];
     /** Unique identifier for the current session. Useful for correlating logs across concurrent sessions. */
     sessionId: string;
+    /** Push a custom event to the connected browser client. Fire-and-forget. */
+    send(event: string, data: unknown): void;
 };
 /**
  * Definition of a custom tool that the agent can invoke.

package/host/_mock-ws.ts

@@ -133,53 +133,3 @@ export class MockWebSocket extends EventTarget {
     return this.sent.filter((d): d is string => typeof d === "string").map((s) => JSON.parse(s));
   }
 }
-
-const g: { WebSocket: unknown } = globalThis;
-
-/**
- * Replace `globalThis.WebSocket` with {@link MockWebSocket} for testing.
- *
- * Returns a handle that tracks all created mock sockets and can restore the
- * original `WebSocket` constructor. Supports the `using` declaration via
- * `Symbol.dispose` for automatic cleanup.
- *
- * @returns An object with `created` array, `lastWs` getter, `restore()`, and `[Symbol.dispose]()`.
- *
- * @example
- * ```ts
- * using mock = installMockWebSocket();
- * const session = new Session("wss://example.com");
- * const ws = mock.lastWs!;
- * ws.simulateMessage(JSON.stringify({ type: "ready" }));
- * // mock automatically restores WebSocket when disposed
- * ```
- */
-export function installMockWebSocket(): {
-  restore: () => void;
-  created: MockWebSocket[];
-  get lastWs(): MockWebSocket | null;
-  [Symbol.dispose]: () => void;
-} {
-  const saved = globalThis.WebSocket;
-  const created: MockWebSocket[] = [];
-
-  g.WebSocket = class extends MockWebSocket {
-    constructor(url: string | URL, protocols?: string | string[] | Record<string, unknown>) {
-      super(url, protocols);
-      created.push(this);
-    }
-  };
-
-  return {
-    created,
-    get lastWs() {
-      return created.at(-1) ?? null;
-    },
-    restore() {
-      globalThis.WebSocket = saved;
-    },
-    [Symbol.dispose]() {
-      this.restore();
-    },
-  };
-}

package/host/_test-utils.ts

@@ -25,6 +25,7 @@ export function createMockToolContext(overrides?: Partial<ToolContext>): ToolCon
     kv: {} as never,
     messages: [],
     sessionId: "test-session",
+    send: vi.fn(),
     ...overrides,
   };
 }

package/host/runtime-barrel.ts

@@ -16,7 +16,6 @@
 export * from "./builtin-tools.ts";
 export * from "./runtime.ts";
 export * from "./runtime-config.ts";
-export * from "./s2s.ts";
 export * from "./server.ts";
 export * from "./session.ts";
 export * from "./session-ctx.ts";

package/host/runtime.ts

@@ -36,6 +36,8 @@ export type SessionStartOptions = {
   onClose?: () => void;
   /** Called with session ID after session cleanup, for guest state cleanup. */
   onSessionEnd?: (sessionId: string) => void;
+  /** Called with session ID and client sink after session setup. Used by sandbox to route custom events. */
+  onSinkCreated?: (sessionId: string, sink: ClientSink) => void;
 };
 
 /**
@@ -160,6 +162,7 @@ export function createRuntime(opts: RuntimeOptions): Runtime {
   } = opts;
   const agentConfig = toAgentConfig(agent);
   const sessions = new Map<string, Session>();
+  const sinkMap = new Map<string, ClientSink>();
   const readyConfig: ReadyConfig = buildReadyConfig(s2sConfig);
 
   // When overrides are provided (sandbox mode), skip in-process tool setup
@@ -216,6 +219,7 @@ export function createRuntime(opts: RuntimeOptions): Runtime {
     executeTool = async (name, args, sessionId, messages) => {
       const tool = allTools[name];
       if (!tool) return toolError(`Unknown tool: ${name}`);
+      const sink = sinkMap.get(sessionId ?? "");
       return executeToolCall(name, args, {
         tool,
         env: frozenEnv,
@@ -224,6 +228,7 @@ export function createRuntime(opts: RuntimeOptions): Runtime {
         kv,
         messages,
         logger,
+        send: sink ? (event, data) => sink.event({ type: "custom_event", event, data }) : undefined,
       });
     };
   }
@@ -235,6 +240,7 @@ export function createRuntime(opts: RuntimeOptions): Runtime {
     skipGreeting?: boolean;
     resumeFrom?: string;
   }): Session {
+    sinkMap.set(sessionOpts.id, sessionOpts.client);
     const apiKey = env.ASSEMBLYAI_API_KEY ?? "";
     return createS2sSession({
       id: sessionOpts.id,
@@ -257,6 +263,7 @@ export function createRuntime(opts: RuntimeOptions): Runtime {
 
   function startSession(ws: SessionWebSocket, startOpts?: SessionStartOptions): void {
     const resumeFrom = startOpts?.resumeFrom;
+    const userOnSessionEnd = startOpts?.onSessionEnd;
     wireSessionSocket(ws, {
       sessions,
       createSession: (sid, client) =>
@@ -272,7 +279,11 @@ export function createRuntime(opts: RuntimeOptions): Runtime {
       ...(startOpts?.logContext ? { logContext: startOpts.logContext } : {}),
       ...(startOpts?.onOpen ? { onOpen: startOpts.onOpen } : {}),
       ...(startOpts?.onClose ? { onClose: startOpts.onClose } : {}),
-      ...(startOpts?.onSessionEnd ? { onSessionEnd: startOpts.onSessionEnd } : {}),
+      ...(startOpts?.onSinkCreated ? { onSinkCreated: startOpts.onSinkCreated } : {}),
+      onSessionEnd: (sid) => {
+        sinkMap.delete(sid);
+        userOnSessionEnd?.(sid);
+      },
       ...(sessionStartTimeoutMs !== undefined ? { sessionStartTimeoutMs } : {}),
       ...(resumeFrom ? { resumeFrom } : {}),
     });
@@ -295,6 +306,7 @@ export function createRuntime(opts: RuntimeOptions): Runtime {
       );
     }
     sessions.clear();
+    sinkMap.clear();
   }
 
   return {