@alexkroman1/aai 0.8.8 → 0.9.1

package/dist/session.js

@@ -0,0 +1,312 @@
+import { DEFAULT_INSTRUCTIONS } from "./types.js";
+import { errorMessage } from "./_utils.js";
+import { HOOK_TIMEOUT_MS } from "./protocol.js";
+import { consoleLogger } from "./runtime.js";
+import { connectS2s, defaultCreateS2sWebSocket } from "./s2s.js";
+//#region session.ts
+const _internals = { connectS2s };
+/** Create an S2S-backed session with the same interface as the STT+LLM+TTS session. */
+function createS2sSession(opts) {
+	const { id, agent, client, toolSchemas, apiKey, s2sConfig, executeTool, createWebSocket = defaultCreateS2sWebSocket, hookInvoker, logger: log = consoleLogger } = opts;
+	const agentConfig = opts.skipGreeting ? {
+		...opts.agentConfig,
+		greeting: ""
+	} : opts.agentConfig;
+	const systemPrompt = buildSystemPrompt(agentConfig, {
+		hasTools: toolSchemas.length > 0 || (agentConfig.builtinTools?.length ?? 0) > 0,
+		voice: true
+	});
+	const s2sTools = toolSchemas.map((ts) => ({
+		type: "function",
+		name: ts.name,
+		description: ts.description,
+		parameters: ts.parameters
+	}));
+	let s2s = null;
+	const sessionAbort = new AbortController();
+	let toolCallCount = 0;
+	let turnPromise = null;
+	let conversationMessages = [];
+	let pendingTools = [];
+	async function resolveTurnConfig() {
+		if (!hookInvoker) return null;
+		return await hookInvoker.resolveTurnConfig(id, HOOK_TIMEOUT_MS);
+	}
+	function fireHook(name, fn) {
+		if (!hookInvoker) return;
+		try {
+			fn(hookInvoker).catch((err) => {
+				log.warn(`${name} hook failed`, { err: errorMessage(err) });
+			});
+		} catch (err) {
+			log.warn(`${name} hook failed`, { err: errorMessage(err) });
+		}
+	}
+	/** Check if a tool call should be refused due to turn config limits. Returns a result string to short-circuit, or null. */
+	function checkTurnLimits(turnConfig, name) {
+		const maxSteps = turnConfig?.maxSteps ?? agentConfig.maxSteps;
+		toolCallCount++;
+		if (maxSteps !== void 0 && toolCallCount > maxSteps) {
+			log.info("maxSteps exceeded, refusing tool call", {
+				toolCallCount,
+				maxSteps
+			});
+			return "Maximum tool steps reached. Please respond to the user now.";
+		}
+		if (turnConfig?.activeTools && !turnConfig.activeTools.includes(name)) {
+			log.info("Tool filtered by activeTools", { name });
+			return JSON.stringify({ error: `Tool "${name}" is not available at this step.` });
+		}
+		return null;
+	}
+	async function handleToolCall(detail) {
+		const { call_id, name, args: parsedArgs } = detail;
+		client.event({
+			type: "tool_call_start",
+			toolCallId: call_id,
+			toolName: name,
+			args: parsedArgs
+		});
+		let turnConfig;
+		try {
+			turnConfig = await resolveTurnConfig();
+		} catch (err) {
+			const msg = `resolveTurnConfig hook error: ${errorMessage(err)}`;
+			log.error(msg);
+			pendingTools.push({
+				call_id,
+				result: msg
+			});
+			client.event({
+				type: "tool_call_done",
+				toolCallId: call_id,
+				result: msg
+			});
+			return;
+		}
+		const refused = checkTurnLimits(turnConfig, name);
+		if (refused !== null) {
+			pendingTools.push({
+				call_id,
+				result: refused
+			});
+			client.event({
+				type: "tool_call_done",
+				toolCallId: call_id,
+				result: refused
+			});
+			return;
+		}
+		fireHook("onStep", (h) => h.onStep(id, {
+			stepNumber: toolCallCount - 1,
+			toolCalls: [{
+				toolName: name,
+				args: parsedArgs
+			}],
+			text: ""
+		}, HOOK_TIMEOUT_MS));
+		log.info("S2S tool call", {
+			tool: name,
+			call_id,
+			args: parsedArgs,
+			agent
+		});
+		let result;
+		try {
+			result = await executeTool(name, parsedArgs, id, conversationMessages);
+		} catch (err) {
+			const msg = errorMessage(err);
+			log.error("Tool execution failed", {
+				tool: name,
+				error: msg
+			});
+			result = JSON.stringify({ error: msg });
+		}
+		log.info("S2S tool result", {
+			tool: name,
+			call_id,
+			resultLength: result.length
+		});
+		pendingTools.push({
+			call_id,
+			result
+		});
+		client.event({
+			type: "tool_call_done",
+			toolCallId: call_id,
+			result
+		});
+	}
+	/** Wire all S2S events to the client sink, hooks, and session state. */
+	function setupListeners(handle) {
+		handle.on("ready", ({ session_id }) => {
+			log.info("S2S session ready", { session_id });
+		});
+		handle.on("session_expired", () => {
+			log.info("S2S session expired");
+			handle.close();
+		});
+		handle.on("speech_started", () => client.event({ type: "speech_started" }));
+		handle.on("speech_stopped", () => client.event({ type: "speech_stopped" }));
+		handle.on("user_transcript_delta", ({ text }) => {
+			client.event({
+				type: "transcript",
+				text,
+				isFinal: false
+			});
+		});
+		handle.on("user_transcript", ({ text }) => {
+			log.info("S2S user transcript", { text });
+			client.event({
+				type: "transcript",
+				text,
+				isFinal: true
+			});
+			client.event({
+				type: "turn",
+				text
+			});
+			conversationMessages.push({
+				role: "user",
+				content: text
+			});
+			fireHook("onTurn", (h) => h.onTurn(id, text, HOOK_TIMEOUT_MS));
+		});
+		handle.on("reply_started", () => {
+			toolCallCount = 0;
+		});
+		handle.on("audio", ({ audio }) => {
+			client.playAudioChunk(audio);
+		});
+		handle.on("agent_transcript_delta", ({ text }) => {
+			client.event({
+				type: "chat_delta",
+				text
+			});
+		});
+		handle.on("agent_transcript", ({ text }) => {
+			client.event({
+				type: "chat",
+				text
+			});
+			conversationMessages.push({
+				role: "assistant",
+				content: text
+			});
+		});
+		handle.on("tool_call", (detail) => {
+			const p = handleToolCall(detail).catch((err) => {
+				log.error("Tool call handler failed", { err: errorMessage(err) });
+			});
+			turnPromise = (turnPromise ?? Promise.resolve()).then(() => p);
+		});
+		handle.on("reply_done", ({ status }) => {
+			if (status === "interrupted") {
+				log.info("S2S reply interrupted (barge-in)");
+				pendingTools = [];
+				client.event({ type: "cancelled" });
+			} else if (pendingTools.length > 0) {
+				for (const tool of pendingTools) s2s?.sendToolResult(tool.call_id, tool.result);
+				pendingTools = [];
+			} else {
+				client.playAudioDone();
+				client.event({ type: "tts_done" });
+			}
+		});
+		handle.on("error", ({ code, message }) => {
+			log.error("S2S error", {
+				code,
+				message
+			});
+			client.event({
+				type: "error",
+				code: "internal",
+				message
+			});
+			handle.close();
+		});
+		handle.on("close", () => {
+			log.info("S2S closed");
+			s2s = null;
+		});
+	}
+	async function connectAndSetup() {
+		try {
+			const handle = await _internals.connectS2s({
+				apiKey,
+				config: s2sConfig,
+				createWebSocket,
+				logger: log
+			});
+			setupListeners(handle);
+			handle.updateSession({
+				system_prompt: systemPrompt,
+				tools: s2sTools,
+				...agentConfig.greeting ? { greeting: agentConfig.greeting } : {}
+			});
+			s2s = handle;
+		} catch (err) {
+			const msg = errorMessage(err);
+			log.error("S2S connect failed", { error: msg });
+			client.event({
+				type: "error",
+				code: "internal",
+				message: msg
+			});
+		}
+	}
+	return {
+		async start() {
+			fireHook("onConnect", (h) => h.onConnect(id, HOOK_TIMEOUT_MS));
+			await connectAndSetup();
+		},
+		async stop() {
+			if (sessionAbort.signal.aborted) return;
+			sessionAbort.abort();
+			if (turnPromise) await turnPromise;
+			s2s?.close();
+			fireHook("onDisconnect", (h) => h.onDisconnect(id, HOOK_TIMEOUT_MS));
+		},
+		onAudio(data) {
+			s2s?.sendAudio(data);
+		},
+		onAudioReady() {},
+		onCancel() {
+			client.event({ type: "cancelled" });
+		},
+		onReset() {
+			conversationMessages = [];
+			toolCallCount = 0;
+			turnPromise = null;
+			pendingTools = [];
+			s2s?.close();
+			client.event({ type: "reset" });
+			connectAndSetup().catch((err) => {
+				log.error("S2S reset reconnect failed", { error: errorMessage(err) });
+			});
+		},
+		onHistory(incoming) {
+			for (const msg of incoming) conversationMessages.push({
+				role: msg.role,
+				content: msg.text
+			});
+		},
+		waitForTurn() {
+			return turnPromise ?? Promise.resolve();
+		}
+	};
+}
+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";
+function buildSystemPrompt(config, opts) {
+	const { hasTools } = opts;
+	const agentInstructions = config.instructions && config.instructions !== DEFAULT_INSTRUCTIONS ? `\n\nAgent-Specific Instructions:\n${config.instructions}` : "";
+	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." : "";
+	return DEFAULT_INSTRUCTIONS + `\n\nToday's date is ${(/* @__PURE__ */ new Date()).toLocaleDateString("en-US", {
+		weekday: "long",
+		year: "numeric",
+		month: "long",
+		day: "numeric"
+	})}.` + agentInstructions + toolPreamble + (opts.voice ? VOICE_RULES : "");
+}
+//#endregion
+export { _internals, buildSystemPrompt, createS2sSession };

package/dist/tsdown.config.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("tsdown").UserConfig;
+export default _default;

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

@@ -1,12 +1,13 @@
 /**
  * Core type definitions for the AAI agent SDK.
- *
- * @module
  */
-import type { z } from "zod";
+import { z } from "zod";
 import type { Kv } from "./kv.ts";
 import type { VectorStore } from "./vector.ts";
-/** Result of the {@linkcode AgentOptions.onBeforeStep} hook. */
+/**
+ * Result of the {@link AgentOptions.onBeforeStep} hook.
+ * @public
+ */
 export type BeforeStepResult = {
     activeTools?: string[];
 } | undefined;
@@ -22,6 +23,8 @@ export type BeforeStepResult = {
  * - `"run_code"` — Execute JavaScript in a sandbox for calculations and data processing.
  * - `"vector_search"` — Search the agent's RAG knowledge base for relevant documents.
  * - `"memory"` — Persistent KV memory: save_memory, recall_memory, list_memories, forget_memory.
+ *
+ * @public
  */
 export type BuiltinTool = "web_search" | "visit_webpage" | "fetch_json" | "run_code" | "vector_search" | "memory";
 /**
@@ -40,7 +43,9 @@ export type ToolChoice = "auto" | "required" | "none" | {
  * A single message in the conversation history.
  *
  * Messages are passed to tool `execute` functions via
- * {@linkcode ToolContext.messages} to provide conversation context.
+ * {@link ToolContext.messages} to provide conversation context.
+ *
+ * @public
  */
 export type Message = {
     /** The role of the message sender. */
@@ -54,7 +59,7 @@ export type Message = {
  * Provides access to the session environment, state, KV store, and
  * conversation history from within a tool's execute handler.
  *
- * @typeParam S The shape of per-session state created by the agent's
+ * @typeParam S - The shape of per-session state created by the agent's
  *   `state` factory. Defaults to `Record<string, unknown>`.
  *
  * @example
@@ -71,12 +76,12 @@ export type Message = {
  *   },
  * };
  * ```
+ *
+ * @public
  */
 export type ToolContext<S = Record<string, unknown>> = {
     /** Environment variables declared in the agent config. */
     env: Readonly<Record<string, string>>;
-    /** Signal that aborts when the tool execution times out. */
-    abortSignal: AbortSignal;
     /** Mutable per-session state created by the agent's `state` factory. */
     state: S;
     /** Key-value store scoped to this agent deployment. */
@@ -89,13 +94,15 @@ export type ToolContext<S = Record<string, unknown>> = {
 /**
  * Context passed to lifecycle hooks (`onConnect`, `onTurn`, etc.).
  *
- * Same as {@linkcode ToolContext} but without `messages` or `abortSignal`,
- * since hooks run outside the tool execution flow.
+ * Same as {@link ToolContext} but without `messages`, since hooks
+ * run outside the tool execution flow.
  *
- * @typeParam S The shape of per-session state created by the agent's
+ * @typeParam S - The shape of per-session state created by the agent's
  *   `state` factory. Defaults to `Record<string, unknown>`.
+ *
+ * @public
  */
-export type HookContext<S = Record<string, unknown>> = Omit<ToolContext<S>, "abortSignal" | "messages">;
+export type HookContext<S = Record<string, unknown>> = Omit<ToolContext<S>, "messages">;
 /**
  * Definition of a custom tool that the agent can invoke.
  *
@@ -103,8 +110,8 @@ export type HookContext<S = Record<string, unknown>> = Omit<ToolContext<S>, "abo
  * description (shown to the LLM), optional Zod parameters schema, and an
  * `execute` function that runs inside the sandboxed worker.
  *
- * @typeParam P A Zod object schema describing the tool's parameters.
- *   Defaults to `any` so tools without parameters don't need an explicit
+ * @typeParam P - A Zod object schema describing the tool's parameters.
+ *   Defaults to `ZodObject<ZodRawShape>` so tools without parameters don't need an explicit
  *   type argument.
  *
  * @example
@@ -125,6 +132,8 @@ export type HookContext<S = Record<string, unknown>> = Omit<ToolContext<S>, "abo
  *
  * const params = z.object({ city: z.string() });
  * ```
+ *
+ * @public
  */
 export type ToolDef<P extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, S = Record<string, unknown>> = {
     /** Human-readable description shown to the LLM. */
@@ -158,13 +167,17 @@ export type ToolDef<P extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawS
  *   },
  * });
  * ```
+ *
+ * @public
  */
-export declare function tool<P extends z.ZodObject<z.ZodRawShape>, S = any>(def: ToolDef<P, S>): ToolDef<P, S>;
+export declare function tool<P extends z.ZodObject<z.ZodRawShape>, S = Record<string, unknown>>(def: ToolDef<P, S>): ToolDef<P, S>;
 /**
  * Information about a completed agentic step, passed to the `onStep` hook.
  *
  * Each turn may consist of multiple steps (up to `maxSteps`). A step
  * represents one LLM invocation that may include tool calls and text output.
+ *
+ * @public
  */
 export type StepInfo = {
     /** 1-based step index within the current turn. */
@@ -178,12 +191,12 @@ export type StepInfo = {
     text: string;
 };
 /**
- * Options passed to {@linkcode defineAgent} to configure an agent.
+ * Options passed to {@link defineAgent} to configure an agent.
  *
  * Only `name` is required; all other fields have sensible defaults.
  *
- * @typeParam S The shape of per-session state returned by the `state`
- *   factory. Defaults to `any`.
+ * @typeParam S - The shape of per-session state returned by the `state`
+ *   factory. Defaults to `Record<string, unknown>`.
  *
  * @example
  * ```ts
@@ -204,6 +217,8 @@ export type StepInfo = {
  *   },
  * });
  * ```
+ *
+ * @public
  */
 export type AgentOptions<S = Record<string, unknown>> = {
     /** Display name for the agent. */
@@ -218,7 +233,7 @@ export type AgentOptions<S = Record<string, unknown>> = {
      * Maximum agentic loop iterations per turn. Can be a static number or
      * a function that receives the hook context and returns a number.
      *
-     * @default {5}
+     * @defaultValue 5
      */
     maxSteps?: number | ((ctx: HookContext<S>) => number);
     /** How the LLM should choose tools. */
@@ -265,9 +280,9 @@ export declare const DEFAULT_INSTRUCTIONS: string;
 export declare const DEFAULT_GREETING: string;
 /**
  * Agent definition with all defaults applied, returned by
- * {@linkcode defineAgent}.
+ * {@link defineAgent}.
  *
- * Unlike {@linkcode AgentOptions}, every field here is resolved to its
+ * Unlike {@link AgentOptions}, every field here is resolved to its
  * final value — no optional fields with implicit defaults remain.
  */
 export type AgentDef = {
@@ -280,7 +295,7 @@ export type AgentDef = {
     builtinTools?: readonly BuiltinTool[];
     activeTools?: readonly string[];
     tools: Readonly<Record<string, ToolDef>>;
-    state?: () => unknown;
+    state?: () => Record<string, unknown>;
     onConnect?: AgentOptions["onConnect"];
     onDisconnect?: AgentOptions["onDisconnect"];
     onError?: AgentOptions["onError"];
@@ -292,12 +307,14 @@ export type AgentDef = {
  * Create an agent definition from the given options, applying sensible defaults.
  *
  * This is the main entry point for defining a voice agent. The returned
- * {@linkcode AgentDef} is consumed by the AAI server at deploy time.
+ * `AgentDef` is consumed by the AAI server at deploy time.
  *
- * @param options Configuration for the agent including name, instructions,
+ * @param options - Configuration for the agent including name, instructions,
  *   tools, hooks, and other settings.
  * @returns A fully resolved agent definition with all defaults applied.
  *
+ * @public
+ *
  * @example Basic agent with a custom tool
  * ```ts
  * import { defineAgent } from "aai";
@@ -317,4 +334,3 @@ export type AgentDef = {
  * ```
  */
 export declare function defineAgent<S>(options: AgentOptions<S>): AgentDef;
-//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,139 @@
+import { z } from "zod";
+//#region types.ts
+/**
+* Core type definitions for the AAI agent SDK.
+*/
+/**
+* Identity helper that preserves the Zod schema generic for type inference.
+*
+* When tools are defined inline in `defineAgent({ tools: { ... } })`, the
+* generic `P` gets widened to the base `ZodObject` type, so `args` in
+* `execute` loses its specific shape. Wrapping a tool definition in `tool()`
+* lets TypeScript infer `P` from `parameters` and type `args` correctly.
+*
+* @example
+* ```ts
+* import { defineAgent, tool } from "aai";
+* import { z } from "zod";
+*
+* export default defineAgent({
+*   name: "my-agent",
+*   tools: {
+*     greet: tool({
+*       description: "Greet the user",
+*       parameters: z.object({ name: z.string() }),
+*       execute: ({ name }) => `Hello, ${name}!`, // name is string
+*     }),
+*   },
+* });
+* ```
+*
+* @public
+*/
+function tool(def) {
+	return def;
+}
+/**
+* Default system prompt used when `instructions` is not provided.
+*
+* Optimized for voice-first interactions: short sentences, no visual
+* formatting, confident tone, and concise answers.
+*/
+const DEFAULT_INSTRUCTIONS = `\
+You are AAI, a helpful AI assistant.
+
+Voice-First Rules:
+- Optimize for natural speech. Avoid jargon unless central to the answer. \
+Use short, punchy sentences.
+- Never mention "search results," "sources," or "the provided text." \
+Speak as if the knowledge is your own.
+- No visual formatting. Do not say "bullet point," "bold," or "bracketed one." \
+If you need to list items, say "First," "Next," and "Finally."
+- Start with the most important information. No introductory filler.
+- Be concise. Keep answers to 1-3 sentences. For complex topics, provide a high-level summary.
+- Be confident. Avoid hedging phrases like "It seems that" or "I believe."
+- If you don't have enough information, say so directly rather than guessing.
+- Never use exclamation points. Keep your tone calm and conversational.`;
+/** Default greeting spoken when a session starts. */
+const DEFAULT_GREETING = "Hey there. I'm a voice assistant. What can I help you with?";
+const BuiltinToolSchema = z.enum([
+	"web_search",
+	"visit_webpage",
+	"fetch_json",
+	"run_code",
+	"vector_search",
+	"memory"
+]);
+const ToolChoiceSchema = z.union([z.enum([
+	"auto",
+	"required",
+	"none"
+]), z.object({
+	type: z.literal("tool"),
+	toolName: z.string().min(1)
+})]);
+const ToolDefSchema = z.object({
+	description: z.string().min(1, "Tool description must be non-empty"),
+	parameters: z.custom((val) => val === void 0 || val instanceof z.ZodType, "Expected a Zod schema").optional(),
+	execute: z.function()
+});
+const AgentOptionsSchema = z.object({
+	name: z.string().min(1, "Agent name must be non-empty"),
+	instructions: z.string().optional(),
+	greeting: z.string().optional(),
+	sttPrompt: z.string().optional(),
+	maxSteps: z.union([z.number().int().positive(), z.function()]).optional(),
+	toolChoice: ToolChoiceSchema.optional(),
+	builtinTools: z.array(BuiltinToolSchema).optional(),
+	activeTools: z.array(z.string().min(1)).optional(),
+	tools: z.record(z.string(), ToolDefSchema).optional(),
+	state: z.function().optional(),
+	onConnect: z.function().optional(),
+	onDisconnect: z.function().optional(),
+	onError: z.function().optional(),
+	onTurn: z.function().optional(),
+	onStep: z.function().optional(),
+	onBeforeStep: z.function().optional()
+});
+/**
+* Create an agent definition from the given options, applying sensible defaults.
+*
+* This is the main entry point for defining a voice agent. The returned
+* `AgentDef` is consumed by the AAI server at deploy time.
+*
+* @param options - Configuration for the agent including name, instructions,
+*   tools, hooks, and other settings.
+* @returns A fully resolved agent definition with all defaults applied.
+*
+* @public
+*
+* @example Basic agent with a custom tool
+* ```ts
+* import { defineAgent } from "aai";
+* import { z } from "zod";
+*
+* export default defineAgent({
+*   name: "greeter",
+*   instructions: "You greet people warmly.",
+*   tools: {
+*     greet: {
+*       description: "Greet a user by name",
+*       parameters: z.object({ name: z.string() }),
+*       execute: ({ name }) => `Hello, ${name}!`,
+*     },
+*   },
+* });
+* ```
+*/
+function defineAgent(options) {
+	AgentOptionsSchema.parse(options);
+	return {
+		...options,
+		instructions: options.instructions ?? DEFAULT_INSTRUCTIONS,
+		greeting: options.greeting ?? "Hey there. I'm a voice assistant. What can I help you with?",
+		maxSteps: options.maxSteps ?? 5,
+		tools: options.tools ?? {}
+	};
+}
+//#endregion
+export { DEFAULT_GREETING, DEFAULT_INSTRUCTIONS, defineAgent, tool };