@alexkroman1/aai 0.12.2 → 1.0.2

package/dist/{isolate → sdk}/_internal-types.d.ts

@@ -11,7 +11,7 @@ import { type ToolDef } from "./types.ts";
  * Function signature for executing a tool by name.
  *
  * Used by session.ts to invoke tools, by direct-executor.ts and
- * _harness-runtime.ts to implement the execution.
+ * harness-runtime.ts to implement the execution.
  */
 export type ExecuteTool = (name: string, args: Readonly<Record<string, unknown>>, sessionId?: string, messages?: readonly Message[]) => Promise<string>;
 /**
@@ -22,18 +22,14 @@ export type ExecuteTool = (name: string, args: Readonly<Record<string, unknown>>
  */
 export declare const AgentConfigSchema: z.ZodObject<{
     name: z.ZodString;
-    instructions: z.ZodString;
+    systemPrompt: z.ZodString;
     greeting: z.ZodString;
     sttPrompt: z.ZodOptional<z.ZodString>;
     maxSteps: z.ZodOptional<z.ZodNumber>;
-    toolChoice: z.ZodOptional<z.ZodUnion<readonly [z.ZodEnum<{
+    toolChoice: z.ZodOptional<z.ZodEnum<{
         auto: "auto";
         required: "required";
-        none: "none";
-    }>, z.ZodObject<{
-        type: z.ZodLiteral<"tool">;
-        toolName: z.ZodString;
-    }, z.core.$strip>]>>;
+    }>>;
     builtinTools: z.ZodOptional<z.ZodReadonly<z.ZodArray<z.ZodEnum<{
         web_search: "web_search";
         visit_webpage: "visit_webpage";
@@ -51,10 +47,10 @@ export type AgentConfig = z.infer<typeof AgentConfigSchema>;
  */
 export interface AgentConfigSource {
     name: string;
-    instructions: string;
+    systemPrompt: string;
     greeting: string;
     sttPrompt?: string | undefined;
-    maxSteps?: number | ((...args: never[]) => number) | undefined;
+    maxSteps?: number | undefined;
     toolChoice?: AgentConfig["toolChoice"] | undefined;
     builtinTools?: Readonly<AgentConfig["builtinTools"]> | undefined;
     idleTimeoutMs?: number | undefined;

package/dist/{isolate → sdk}/constants.d.ts

@@ -8,8 +8,6 @@
 export declare const DEFAULT_STT_SAMPLE_RATE = 16000;
 /** Default sample rate for text-to-speech audio in Hz. */
 export declare const DEFAULT_TTS_SAMPLE_RATE = 24000;
-/** Default timeout for agent lifecycle hooks (onConnect, onTurn, etc). */
-export declare const HOOK_TIMEOUT_MS = 5000;
 /** Default timeout for tool execution in the worker. */
 export declare const TOOL_EXECUTION_TIMEOUT_MS = 30000;
 /** Timeout for session.start() (S2S connection setup). */
@@ -30,10 +28,14 @@ export declare const MAX_PAGE_CHARS = 10000;
 export declare const MAX_HTML_BYTES = 200000;
 /** Maximum value size for KV store entries (bytes). */
 export declare const MAX_VALUE_SIZE = 65536;
-/** Maximum glob pattern length to prevent ReDoS. */
-export declare const MAX_GLOB_PATTERN_LENGTH = 1024;
 /** Maximum conversation messages to retain (sliding window). */
 export declare const DEFAULT_MAX_HISTORY = 200;
+/** Maximum WebSocket message payload size (bytes, 1 MiB). */
+export declare const MAX_WS_PAYLOAD_BYTES: number;
+/** Maximum messages buffered while session.start() is pending. */
+export declare const MAX_MESSAGE_BUFFER_SIZE = 100;
+/** WebSocket readyState value indicating the connection is open. */
+export declare const WS_OPEN = 1;
 /**
  * Content-Security-Policy applied to agent UI pages (both self-hosted and
  * platform). Single source of truth — used by `secureHeaders` middleware

package/dist/sdk/define.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Helper functions for defining agents and tools with full type inference.
+ */
+import type { z } from "zod";
+import { type AgentDef, type BuiltinTool, type ToolChoice, type ToolContext, type ToolDef } from "./types.ts";
+/**
+ * Define a tool with typed parameters and execute function.
+ *
+ * Identity function for type inference — returns the input unchanged.
+ * Follows the Vercel AI SDK `tool()` pattern.
+ *
+ * @example
+ * ```ts
+ * import { tool } from "@alexkroman1/aai";
+ * import { z } from "zod";
+ *
+ * const greet = tool({
+ *   description: "Greet someone by name",
+ *   parameters: z.object({ name: z.string() }),
+ *   execute: ({ name }) => `Hello, ${name}!`,
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare function tool<P extends z.ZodObject<z.ZodRawShape>>(def: {
+    description: string;
+    parameters?: P;
+    execute(args: z.infer<P>, ctx: ToolContext): Promise<unknown> | unknown;
+}): ToolDef<P>;
+/**
+ * Define an agent with tools, system prompt, and configuration.
+ *
+ * Applies sensible defaults for omitted fields. Export as the default
+ * export of your `agent.ts` file.
+ *
+ * @example
+ * ```ts
+ * import { agent, tool } from "@alexkroman1/aai";
+ * import { z } from "zod";
+ *
+ * const myTool = tool({
+ *   description: "Echo a message",
+ *   parameters: z.object({ message: z.string() }),
+ *   execute: ({ message }) => message,
+ * });
+ *
+ * export default agent({
+ *   name: "Echo Agent",
+ *   tools: { echo: myTool },
+ * });
+ * ```
+ *
+ * @public
+ */
+export declare function agent(def: {
+    name: string;
+    systemPrompt?: string;
+    greeting?: string;
+    tools?: Record<string, ToolDef>;
+    builtinTools?: BuiltinTool[];
+    maxSteps?: number;
+    toolChoice?: ToolChoice;
+    sttPrompt?: string;
+    idleTimeoutMs?: number;
+}): AgentDef;

package/dist/{isolate → sdk}/kv.d.ts

@@ -1,38 +1,10 @@
 /**
  * Key-value storage interface and shared utilities.
  */
-/**
- * A single key-value entry returned by {@link Kv.list}.
- *
- * @typeParam T - The type of the stored value. Defaults to `unknown`.
- *
- * @public
- */
-export type KvEntry<T = unknown> = {
-    /** The key under which the value is stored. */
-    key: string;
-    /** The deserialized value. */
-    value: T;
-};
-/**
- * Options for listing keys from the KV store.
- *
- * Used with {@link Kv.list} and {@link Kv.keys} to control filtering,
- * ordering, and pagination.
- *
- * @public
- */
-export type KvListOptions = {
-    /** Maximum number of entries to return. */
-    limit?: number;
-    /** Return entries in reverse key order. */
-    reverse?: boolean;
-};
 /**
  * Async key-value store interface used by agents.
  *
- * Agents access the KV store via `ToolContext.kv` or
- * `HookContext.kv`. Values are JSON-serialized and stored as
+ * Agents access the KV store via `ToolContext.kv`. Values are JSON-serialized and stored as
  * strings with an optional TTL.
  *
  * @example
@@ -78,26 +50,6 @@ export type Kv = {
      * @param keys - A single key or array of keys to delete. No-op for keys that do not exist.
      */
     delete(keys: string | string[]): Promise<void>;
-    /**
-     * List entries whose keys start with the given prefix.
-     *
-     * Results are sorted by key in ascending lexicographic order by default.
-     *
-     * @typeParam T - The expected type of the stored values.
-     * @param prefix - Key prefix to filter by. Use `""` to list all entries.
-     * @param options - Optional pagination and ordering settings.
-     * @returns An array of matching {@link KvEntry} objects.
-     */
-    list<T = unknown>(prefix: string, options?: KvListOptions): Promise<KvEntry<T>[]>;
-    /**
-     * List all keys, optionally filtered by a prefix or glob-style pattern.
-     *
-     * @param pattern - Optional prefix string or glob pattern (e.g. `"user:*"`).
-     *   A pattern without wildcards (`*`) is treated as a prefix match.
-     *   If omitted, all keys are returned.
-     * @returns An array of matching key strings.
-     */
-    keys(pattern?: string): Promise<string[]>;
     /**
      * Close the KV store, releasing any resources (intervals, database handles).
      *

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

@@ -0,0 +1,8 @@
+/**
+ * Manifest barrel — agent manifest parsing and tool schema conversion.
+ *
+ * Used by aai-cli (scanner, bundler) and aai-server (tests).
+ */
+export * from "./_internal-types.ts";
+export * from "./manifest.ts";
+export * from "./system-prompt.ts";

package/dist/sdk/manifest-barrel.js

@@ -0,0 +1,52 @@
+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 };

package/dist/sdk/manifest.d.ts

@@ -0,0 +1,50 @@
+/**
+ * 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.
+ */
+/**
+ * Tool definition as it appears in the serialized manifest JSON.
+ *
+ * This is the JSON-safe representation. Compare with `ToolDef` (in types.ts)
+ * which uses Zod schemas for parameters — `agentToolsToSchemas()` in
+ * `_internal-types.ts` converts ToolDef → ToolSchema (JSON Schema) for transport.
+ */
+export type ToolManifest = {
+    description: string;
+    parameters?: Record<string, unknown> | undefined;
+};
+/** Normalized agent manifest — all optional fields resolved to defaults. */
+export type Manifest = {
+    /** Agent display name (from `agent({ name: "..." })`). */
+    name: string;
+    /** System prompt sent to the LLM. Defaults to {@link DEFAULT_SYSTEM_PROMPT}. */
+    systemPrompt: string;
+    /** Initial greeting spoken to the user on connect. Defaults to {@link DEFAULT_GREETING}. */
+    greeting: string;
+    /** Optional prompt hint for the STT engine (improves transcription of domain terms). */
+    sttPrompt?: string | undefined;
+    /** Enabled built-in tools: `web_search`, `visit_webpage`, `fetch_json`, `run_code`. */
+    builtinTools: string[];
+    /** Max tool calls per LLM reply. Prevents runaway loops. Default: 5. */
+    maxSteps: number;
+    /** `"auto"` = LLM decides when to use tools; `"required"` = always call a tool. */
+    toolChoice: "auto" | "required";
+    /** Idle timeout in ms before auto-closing the session. `undefined` = use default (5 min). */
+    idleTimeoutMs?: number | undefined;
+    /** CSS custom properties for agent UI theming. */
+    theme?: Record<string, string> | undefined;
+    /** Custom tool definitions keyed by tool name. */
+    tools: Record<string, ToolManifest>;
+};
+/**
+ * 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
+ */
+export declare function parseManifest(input: unknown): Manifest;

package/dist/{isolate → sdk}/protocol.d.ts

@@ -10,6 +10,53 @@ import { z } from "zod";
  * 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
+ * rolling upgrades) from genuinely malformed messages.
+ *
+ * Return value when `ok: false`:
+ * - `malformed: true` — message doesn't even have a `{ type: string }` shape;
+ *   likely corrupt data, should warn
+ * - `malformed: false` — has a valid `type` field but the type is unrecognised;
+ *   safe to ignore (e.g. new message type from a newer server version)
+ */
+export declare function lenientParse<T>(schema: z.ZodType<T>, json: unknown): {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    malformed: boolean;
+    error: string;
+};
+/** Zod schema for the KV "get" operation. */
+export declare const KvGetSchema: z.ZodObject<{
+    op: z.ZodLiteral<"get">;
+    key: z.ZodString;
+}, z.core.$strip>;
+/** Zod schema for the KV "set" operation. */
+export declare const KvSetSchema: z.ZodObject<{
+    op: z.ZodLiteral<"set">;
+    key: z.ZodString;
+    value: z.ZodUnknown;
+    expireIn: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+/** Zod schema for the KV "del" operation. */
+export declare const KvDelSchema: z.ZodObject<{
+    op: z.ZodLiteral<"del">;
+    key: z.ZodString;
+}, z.core.$strip>;
 /** Zod schema for KV operation requests from the worker to the host. */
 export declare const KvRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     op: z.ZodLiteral<"get">;
@@ -17,19 +64,11 @@ export declare const KvRequestSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>, z.ZodObject<{
     op: z.ZodLiteral<"set">;
     key: z.ZodString;
-    value: z.ZodString;
+    value: z.ZodUnknown;
     expireIn: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>, z.ZodObject<{
     op: z.ZodLiteral<"del">;
     key: z.ZodString;
-}, z.core.$strip>, z.ZodObject<{
-    op: z.ZodLiteral<"list">;
-    prefix: z.ZodString;
-    limit: z.ZodOptional<z.ZodNumber>;
-    reverse: z.ZodOptional<z.ZodBoolean>;
-}, z.core.$strip>, z.ZodObject<{
-    op: z.ZodLiteral<"keys">;
-    pattern: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>], "op">;
 /** KV operation request — discriminated union on the `op` field. */
 export type KvRequest = z.infer<typeof KvRequestSchema>;
@@ -39,11 +78,11 @@ export type KvRequest = z.infer<typeof KvRequestSchema>;
  */
 export declare const SessionErrorCodeSchema: z.ZodEnum<{
     tool: "tool";
+    connection: "connection";
     stt: "stt";
     llm: "llm";
     tts: "tts";
     protocol: "protocol";
-    connection: "connection";
     audio: "audio";
     internal: "internal";
 }>;
@@ -59,22 +98,14 @@ export declare const ClientEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"speech_stopped">;
 }, z.core.$strip>, z.ZodObject<{
-    type: z.ZodLiteral<"transcript">;
+    type: z.ZodLiteral<"user_transcript">;
     text: z.ZodString;
-    isFinal: z.ZodBoolean;
     turnOrder: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>, z.ZodObject<{
-    type: z.ZodLiteral<"turn">;
+    type: z.ZodLiteral<"agent_transcript">;
     text: z.ZodString;
-    turnOrder: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>, z.ZodObject<{
-    type: z.ZodLiteral<"chat">;
-    text: z.ZodString;
-}, z.core.$strip>, z.ZodObject<{
-    type: z.ZodLiteral<"chat_delta">;
-    text: z.ZodString;
-}, z.core.$strip>, z.ZodObject<{
-    type: z.ZodLiteral<"tool_call_start">;
+    type: z.ZodLiteral<"tool_call">;
     toolCallId: z.ZodString;
     toolName: z.ZodString;
     args: z.ZodRecord<z.ZodString, z.ZodUnknown>;
@@ -83,7 +114,7 @@ export declare const ClientEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     toolCallId: z.ZodString;
     result: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
-    type: z.ZodLiteral<"tts_done">;
+    type: z.ZodLiteral<"reply_done">;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"cancelled">;
 }, z.core.$strip>, z.ZodObject<{
@@ -94,11 +125,11 @@ export declare const ClientEventSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"error">;
     code: z.ZodEnum<{
         tool: "tool";
+        connection: "connection";
         stt: "stt";
         llm: "llm";
         tts: "tts";
         protocol: "protocol";
-        connection: "connection";
         audio: "audio";
         internal: "internal";
     }>;
@@ -147,22 +178,14 @@ export declare const ServerMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"speech_stopped">;
 }, z.core.$strip>, z.ZodObject<{
-    type: z.ZodLiteral<"transcript">;
-    text: z.ZodString;
-    isFinal: z.ZodBoolean;
-    turnOrder: z.ZodOptional<z.ZodNumber>;
-}, z.core.$strip>, z.ZodObject<{
-    type: z.ZodLiteral<"turn">;
+    type: z.ZodLiteral<"user_transcript">;
     text: z.ZodString;
     turnOrder: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>, z.ZodObject<{
-    type: z.ZodLiteral<"chat">;
+    type: z.ZodLiteral<"agent_transcript">;
     text: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
-    type: z.ZodLiteral<"chat_delta">;
-    text: z.ZodString;
-}, z.core.$strip>, z.ZodObject<{
-    type: z.ZodLiteral<"tool_call_start">;
+    type: z.ZodLiteral<"tool_call">;
     toolCallId: z.ZodString;
     toolName: z.ZodString;
     args: z.ZodRecord<z.ZodString, z.ZodUnknown>;
@@ -171,7 +194,7 @@ export declare const ServerMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     toolCallId: z.ZodString;
     result: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
-    type: z.ZodLiteral<"tts_done">;
+    type: z.ZodLiteral<"reply_done">;
 }, z.core.$strip>, z.ZodObject<{
     type: z.ZodLiteral<"cancelled">;
 }, z.core.$strip>, z.ZodObject<{
@@ -182,11 +205,11 @@ export declare const ServerMessageSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
     type: z.ZodLiteral<"error">;
     code: z.ZodEnum<{
         tool: "tool";
+        connection: "connection";
         stt: "stt";
         llm: "llm";
         tts: "tts";
         protocol: "protocol";
-        connection: "connection";
         audio: "audio";
         internal: "internal";
     }>;

package/dist/sdk/protocol.js

@@ -0,0 +1,163 @@
+import { f as MAX_TOOL_RESULT_CHARS } from "../constants-VTFoymJ-.js";
+import { z } from "zod";
+//#region sdk/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";
+/**
+* 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).
+*/
+const MessageEnvelopeSchema = z.object({ type: z.string() }).passthrough();
+/**
+* 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
+* rolling upgrades) from genuinely malformed messages.
+*
+* Return value when `ok: false`:
+* - `malformed: true` — message doesn't even have a `{ type: string }` shape;
+*   likely corrupt data, should warn
+* - `malformed: false` — has a valid `type` field but the type is unrecognised;
+*   safe to ignore (e.g. new message type from a newer server version)
+*/
+function lenientParse(schema, json) {
+	const result = schema.safeParse(json);
+	if (result.success) return {
+		ok: true,
+		data: result.data
+	};
+	return {
+		ok: false,
+		malformed: !MessageEnvelopeSchema.safeParse(json).success,
+		error: result.error.message
+	};
+}
+/** Zod schema for the KV "get" operation. */
+const KvGetSchema = z.object({
+	op: z.literal("get"),
+	key: z.string().min(1)
+});
+/** Zod schema for the KV "set" operation. */
+const KvSetSchema = z.object({
+	op: z.literal("set"),
+	key: z.string().min(1),
+	value: z.unknown(),
+	expireIn: z.number().int().positive().optional()
+});
+/** Zod schema for the KV "del" operation. */
+const KvDelSchema = z.object({
+	op: z.literal("del"),
+	key: z.string().min(1)
+});
+/** Zod schema for KV operation requests from the worker to the host. */
+const KvRequestSchema = z.discriminatedUnion("op", [
+	KvGetSchema,
+	KvSetSchema,
+	KvDelSchema
+]);
+/**
+* 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) });
+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("user_transcript"),
+		text: z.string(),
+		turnOrder
+	}),
+	z.object({
+		type: z.literal("agent_transcript"),
+		text: z.string()
+	}),
+	z.object({
+		type: z.literal("tool_call"),
+		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("reply_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, KvDelSchema, KvGetSchema, KvRequestSchema, KvSetSchema, MessageEnvelopeSchema, ReadyConfigSchema, ServerMessageSchema, SessionErrorCodeSchema, TurnConfigSchema, buildReadyConfig, lenientParse };

package/dist/{isolate → sdk}/system-prompt.d.ts

@@ -5,10 +5,10 @@ import type { AgentConfig } from "./_internal-types.ts";
 /**
  * Build the system prompt sent to the LLM from the agent configuration.
  *
- * Assembles the default instructions, today's date, agent-specific instructions,
+ * 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, instructions, etc.).
+ * @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
@@ -18,4 +18,5 @@ import type { AgentConfig } from "./_internal-types.ts";
 export declare function buildSystemPrompt(config: AgentConfig, opts: {
     hasTools: boolean;
     voice?: boolean;
+    toolGuidance?: readonly string[] | undefined;
 }): string;