@alexkroman1/aai 0.3.0

package/sdk/worker_entry.ts

@@ -0,0 +1,99 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * Worker entry point — shared tool execution logic.
+ *
+ * @module
+ */
+
+import { z } from "zod";
+import type { Kv } from "./kv.ts";
+import type { Message, ToolContext, ToolDef } from "./types.ts";
+
+/**
+ * Maximum time in milliseconds a tool handler may run before being aborted.
+ *
+ * If a tool's `execute` function exceeds this duration, it is cancelled via
+ * `AbortSignal.timeout` and an error message is returned to the LLM.
+ */
+export const TOOL_HANDLER_TIMEOUT = 30_000;
+
+/**
+ * Function signature for executing a tool by name.
+ *
+ * @param name - The tool name to execute.
+ * @param args - Key-value arguments to pass to the tool handler.
+ * @param sessionId - Optional session identifier for stateful tools.
+ * @param messages - Optional conversation history for context-aware tools.
+ * @returns The tool's string result, or an error message string.
+ */
+export type ExecuteTool = (
+  name: string,
+  args: Readonly<Record<string, unknown>>,
+  sessionId?: string,
+  messages?: readonly Message[],
+) => Promise<string>;
+
+/** Options for {@linkcode executeToolCall}. */
+export type ExecuteToolCallOptions = {
+  tool: ToolDef;
+  env: Readonly<Record<string, string>>;
+  sessionId?: string | undefined;
+  state?: unknown;
+  kv?: Kv | undefined;
+  messages?: readonly Message[] | undefined;
+};
+
+/**
+ * Execute a tool call with argument validation, timeout, and error handling.
+ *
+ * Validates the provided arguments against the tool's Zod parameter schema,
+ * constructs a {@linkcode ToolContext}, invokes the tool's `execute` function,
+ * and serializes the result to a string. Errors and timeouts are caught and
+ * returned as `"Error: ..."` strings rather than thrown.
+ *
+ * @param name - The name of the tool being invoked.
+ * @param args - Raw arguments from the LLM to validate and pass to the tool.
+ * @param options - Tool definition, environment, and optional context.
+ * @returns The tool's result serialized as a string, or an error message.
+ */
+export async function executeToolCall(
+  name: string,
+  args: Readonly<Record<string, unknown>>,
+  options: ExecuteToolCallOptions,
+): Promise<string> {
+  const { tool, env, sessionId, state, kv, messages } = options;
+  const schema = tool.parameters ?? z.object({});
+  const parsed = schema.safeParse(args);
+  if (!parsed.success) {
+    const issues = (parsed.error?.issues ?? [])
+      .map((i: z.ZodIssue) => `${i.path.map(String).join(".")}: ${i.message}`)
+      .join(", ");
+    return `Error: Invalid arguments for tool "${name}": ${issues}`;
+  }
+
+  try {
+    const abortSignal = AbortSignal.timeout(TOOL_HANDLER_TIMEOUT);
+    const envCopy = { ...env };
+    const ctx: ToolContext = {
+      sessionId: sessionId ?? "",
+      env: envCopy,
+      abortSignal,
+      state: (state ?? {}) as Record<string, unknown>,
+      get kv(): Kv {
+        if (!kv) throw new Error("KV not available");
+        return kv;
+      },
+      messages: messages ?? [],
+    };
+    const result = await Promise.resolve(tool.execute(parsed.data, ctx));
+    if (result == null) return "null";
+    return typeof result === "string" ? result : JSON.stringify(result);
+  } catch (err: unknown) {
+    if (err instanceof DOMException && err.name === "TimeoutError") {
+      console.warn(`[tool-executor] Tool execution timed out: ${name}`);
+      return `Error: Tool "${name}" timed out after ${TOOL_HANDLER_TIMEOUT}ms`;
+    }
+    console.warn(`[tool-executor] Tool execution failed: ${name}`, err);
+    return `Error: ${err instanceof Error ? err.message : String(err)}`;
+  }
+}

package/sdk/worker_shim.ts

@@ -0,0 +1,170 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * Sandboxed worker entry point for platform mode.
+ *
+ * Called from the bundled `worker.js` inside a Deno Worker with all
+ * permissions false. Monkeypatches `globalThis.fetch` to proxy through
+ * capnweb RPC, creates capnweb-backed KV/vector/WebSocket, and delegates
+ * to a {@linkcode WintercServer} for session management.
+ *
+ * @module
+ */
+
+import {
+  BridgedWebSocket,
+  CapnwebEndpoint,
+  type CapnwebPort,
+  createBridgedS2sWebSocket,
+} from "./capnweb.ts";
+import type { Kv } from "./kv.ts";
+import type { CreateS2sWebSocket } from "./s2s.ts";
+import type { AgentDef } from "./types.ts";
+import { createWintercServer, type WintercServer } from "./winterc_server.ts";
+
+declare const self: {
+  postMessage(msg: unknown, transfer?: Transferable[]): void;
+  onmessage: ((ev: MessageEvent) => any) | null; // eslint-disable-line @typescript-eslint/no-explicit-any
+};
+
+/**
+ * Initialize a sandboxed worker with the given agent definition.
+ *
+ * Sets up capnweb RPC, monkeypatches fetch, creates capability stubs,
+ * and waits for the host to send initialization data before creating
+ * the WinterTC server.
+ */
+export function initWorker(agent: AgentDef): void {
+  const endpoint = new CapnwebEndpoint(self as CapnwebPort);
+
+  // ─── Monkeypatch fetch to proxy through host ────────────────────────────
+  globalThis.fetch = async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+    let url: string;
+    let method = "GET";
+    let headers: Record<string, string> = {};
+    let body: string | undefined;
+
+    if (typeof input === "string") {
+      url = input;
+    } else if (input instanceof URL) {
+      url = input.toString();
+    } else {
+      url = input.url;
+      method = input.method;
+      headers = Object.fromEntries(input.headers);
+      if (input.body) {
+        body = await new Response(input.body).text();
+      }
+    }
+
+    if (init?.method) method = init.method;
+    if (init?.headers) {
+      headers = Object.fromEntries(new Headers(init.headers as HeadersInit));
+    }
+    if (init?.body !== undefined) {
+      body = typeof init.body === "string" ? init.body : String(init.body);
+    }
+
+    const result = (await endpoint.call("host.fetch", [url, method, headers, body])) as {
+      status: number;
+      headers: Record<string, string>;
+      body: string;
+    };
+
+    return new Response(result.body, {
+      status: result.status,
+      headers: result.headers,
+    });
+  };
+
+  // ─── Capnweb-backed KV ─────────────────────────────────────────────────
+  const kv: Kv = {
+    async get<T = unknown>(key: string): Promise<T | null> {
+      return (await endpoint.call("host.kv", ["get", key])) as T | null;
+    },
+    async set(key: string, value: unknown, options?: { expireIn?: number }): Promise<void> {
+      await endpoint.call("host.kv", ["set", key, value, options?.expireIn]);
+    },
+    async delete(key: string): Promise<void> {
+      await endpoint.call("host.kv", ["del", key]);
+    },
+    async list<T = unknown>(
+      prefix: string,
+      options?: { limit?: number; reverse?: boolean },
+    ): Promise<{ key: string; value: T }[]> {
+      return (await endpoint.call("host.kv", [
+        "list",
+        prefix,
+        options?.limit,
+        options?.reverse,
+      ])) as { key: string; value: T }[];
+    },
+  };
+
+  // ─── Capnweb-backed vector search ──────────────────────────────────────
+  const vectorSearch = async (query: string, topK: number): Promise<string> => {
+    return (await endpoint.call("host.vectorSearch", [query, topK])) as string;
+  };
+
+  // ─── Capnweb-backed S2S WebSocket factory ──────────────────────────────
+  const createWebSocket: CreateS2sWebSocket = (url, opts) => {
+    const { port1, port2 } = new MessageChannel();
+    endpoint.notify("host.createWebSocket", [url, JSON.stringify(opts.headers)], [port2]);
+    return createBridgedS2sWebSocket(port1);
+  };
+
+  // ─── RPC handlers ──────────────────────────────────────────────────────
+
+  let wintercServer: WintercServer | null = null;
+
+  // Handle init from host — creates the WinterTC server
+  endpoint.handle("worker.init", (args) => {
+    const [env, clientHtml] = args as [Record<string, string>, string | undefined];
+
+    wintercServer = createWintercServer({
+      agent,
+      env,
+      kv,
+      vectorSearch,
+      createWebSocket,
+      clientHtml,
+    });
+
+    return "ok";
+  });
+
+  // Handle HTTP request forwarding
+  endpoint.handle("worker.fetch", async (args) => {
+    if (!wintercServer) throw new Error("Worker not initialized");
+    const [url, method, headers, body] = args as [
+      string,
+      string,
+      Record<string, string>,
+      string | undefined,
+    ];
+
+    const request = new Request(url, {
+      method,
+      headers,
+      ...(body ? { body } : {}),
+    });
+
+    const response = await wintercServer.fetch(request);
+    return {
+      status: response.status,
+      headers: Object.fromEntries(response.headers),
+      body: await response.text(),
+    };
+  });
+
+  // Handle new WebSocket client connection — port transferred from host
+  endpoint.handle("worker.handleWebSocket", (_args, ports) => {
+    if (!wintercServer) throw new Error("Worker not initialized");
+    const [skipGreeting] = _args as [boolean | undefined];
+    const port = ports[0];
+    if (!port) throw new Error("No port transferred");
+
+    const ws = new BridgedWebSocket(port);
+    wintercServer.handleWebSocket(ws, { skipGreeting });
+    return "ok";
+  });
+}

package/sdk/ws_handler.ts

@@ -0,0 +1,190 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * WebSocket session lifecycle handler.
+ *
+ * Cross-runtime: accepts a Logger parameter instead of importing `@std/log`.
+ * Audio validation is inlined (no dependency on server-side schemas).
+ *
+ * @module
+ */
+
+import type { ClientMessage, ClientSink, ReadyConfig } from "./protocol.ts";
+import { ClientMessageSchema } from "./protocol.ts";
+import type { Logger } from "./runtime.ts";
+import { consoleLogger } from "./runtime.ts";
+import type { Session } from "./session.ts";
+
+/**
+ * Minimal WebSocket interface accepted by {@linkcode wireSessionSocket}.
+ *
+ * Satisfied by the standard `WebSocket`, `BridgedWebSocket` (capnweb),
+ * and the `ws` npm package's WebSocket.
+ */
+export type SessionWebSocket = {
+  readonly readyState: number;
+  send(data: string | ArrayBuffer | Uint8Array): void;
+  addEventListener(type: string, listener: EventListenerOrEventListenerObject): void;
+};
+
+/** Max size for a single audio chunk from the browser (1 MB). */
+const MAX_AUDIO_CHUNK_BYTES = 1_048_576;
+
+/** Validate a PCM16 audio chunk: non-empty, within size bounds, even byte length. */
+function isValidAudioChunk(data: Uint8Array): boolean {
+  return (
+    data.byteLength > 0 && data.byteLength <= MAX_AUDIO_CHUNK_BYTES && data.byteLength % 2 === 0
+  );
+}
+
+/** Options for wiring a WebSocket to a session. */
+export type WsSessionOptions = {
+  /** Map of active sessions (session is added on open, removed on close). */
+  sessions: Map<string, Session>;
+  /** Factory function to create a session for a given ID and client sink. */
+  createSession: (sessionId: string, client: ClientSink) => Session;
+  /** Protocol config sent to the client immediately on connect. */
+  readyConfig: ReadyConfig;
+  /** Additional key-value pairs included in log messages. */
+  logContext?: Record<string, string>;
+  /** Callback invoked when the WebSocket connection opens. */
+  onOpen?: () => void;
+  /** Callback invoked when the WebSocket connection closes. */
+  onClose?: () => void;
+  /** Logger instance. Defaults to console. */
+  logger?: Logger;
+};
+
+/**
+ * Creates a {@linkcode ClientSink} backed by a plain WebSocket.
+ *
+ * Text events are sent as JSON text frames; audio chunks are sent as
+ * binary frames (zero-copy).
+ */
+function createClientSink(ws: SessionWebSocket): ClientSink {
+  return {
+    get open() {
+      return ws.readyState === 1;
+    },
+    event(e) {
+      if (ws.readyState === 1) {
+        ws.send(JSON.stringify(e));
+      }
+    },
+    playAudioChunk(chunk) {
+      if (ws.readyState === 1) {
+        ws.send(chunk);
+      }
+    },
+    playAudioDone() {
+      if (ws.readyState === 1) {
+        ws.send(JSON.stringify({ type: "audio_done" }));
+      }
+    },
+  };
+}
+
+/**
+ * Attaches session lifecycle handlers to a native WebSocket using
+ * plain JSON text frames and binary audio frames.
+ *
+ * Connection flow:
+ * 1. WebSocket opens → server sends `{ type: "config", ...ReadyConfig }`
+ * 2. Client sets up audio → sends `{ type: "audio_ready" }`
+ * 3. If reconnecting → client sends `{ type: "history", messages: [...] }`
+ */
+export function wireSessionSocket(ws: SessionWebSocket, opts: WsSessionOptions): void {
+  const { sessions, logger: log = consoleLogger } = opts;
+  const sessionId = crypto.randomUUID();
+  const sid = sessionId.slice(0, 8);
+  const ctx = opts.logContext ?? {};
+
+  let session: Session | null = null;
+
+  ws.addEventListener("open", () => {
+    opts.onOpen?.();
+    log.info("Session connected", { ...ctx, sid });
+
+    const client = createClientSink(ws);
+    session = opts.createSession(sessionId, client);
+    sessions.set(sessionId, session);
+
+    // Send config immediately — zero RTT
+    ws.send(JSON.stringify({ type: "config", ...opts.readyConfig }));
+
+    void session.start();
+    log.info("Session ready", { ...ctx, sid });
+  });
+
+  ws.addEventListener("message", (event: Event) => {
+    if (!session) return;
+    const msgEvent = event as MessageEvent;
+    const { data } = msgEvent;
+
+    // Binary frame → raw PCM16 audio
+    if (data instanceof ArrayBuffer) {
+      const chunk = new Uint8Array(data);
+      if (!isValidAudioChunk(chunk)) {
+        log.warn("Invalid audio chunk, dropping", {
+          ...ctx,
+          sid,
+          bytes: chunk.byteLength,
+          aligned: chunk.byteLength % 2 === 0,
+        });
+        return;
+      }
+      session.onAudio(chunk);
+      return;
+    }
+
+    // Text frame → JSON message
+    if (typeof data !== "string") return;
+    let json: unknown;
+    try {
+      json = JSON.parse(data);
+    } catch {
+      log.warn("Invalid JSON from client", { ...ctx, sid });
+      return;
+    }
+
+    const parsed = ClientMessageSchema.safeParse(json);
+    if (!parsed.success) {
+      log.warn("Invalid client message", {
+        ...ctx,
+        sid,
+        error: parsed.error.message,
+      });
+      return;
+    }
+
+    const msg: ClientMessage = parsed.data;
+    switch (msg.type) {
+      case "audio_ready":
+        session.onAudioReady();
+        break;
+      case "cancel":
+        session.onCancel();
+        break;
+      case "reset":
+        session.onReset();
+        break;
+      case "history":
+        session.onHistory(msg.messages);
+        break;
+    }
+  });
+
+  ws.addEventListener("close", () => {
+    log.info("Session disconnected", { ...ctx, sid });
+    if (session) {
+      void session.stop().finally(() => {
+        sessions.delete(sessionId);
+      });
+    }
+    opts.onClose?.();
+  });
+
+  ws.addEventListener("error", (event) => {
+    const msg = event instanceof ErrorEvent ? event.message : "WebSocket error";
+    log.error("WebSocket error", { ...ctx, sid, error: msg });
+  });
+}

package/templates/_shared/.env.example

@@ -0,0 +1,5 @@
+# Set secrets on the server with: aai env add <NAME>
+# Pull secret names here for local reference: aai env pull
+#
+# ASSEMBLYAI_API_KEY is managed globally by the CLI (~/.config/aai/).
+# Add any additional secrets your agent needs below:

package/templates/_shared/package.json

@@ -0,0 +1,17 @@
+{
+  "type": "module",
+  "scripts": {
+    "dev": "aai dev",
+    "build": "aai deploy --dry-run",
+    "deploy": "aai deploy"
+  },
+  "dependencies": {
+    "@alexkroman1/aai": "^0.3",
+    "preact": "^10",
+    "@preact/signals": "^2",
+    "zod": "^4"
+  },
+  "devDependencies": {
+    "typescript": "^5"
+  }
+}

package/templates/code-interpreter/agent.ts

@@ -0,0 +1,27 @@
+import { defineAgent } from "@alexkroman1/aai";
+
+export default defineAgent({
+  name: "Coda",
+  instructions:
+    `You are Coda, a problem-solving assistant who answers questions by writing and running JavaScript code.
+
+CRITICAL RULES:
+- You MUST use the run_code tool for ANY question involving math, counting, string manipulation, data processing, logic, or anything that benefits from exact computation.
+- NEVER do mental math or estimate. Always write code and report the exact result.
+- Use console.log() to output intermediate steps. The last expression is captured automatically.
+- If the code throws an error, fix it and try again.
+- Explain what the code does briefly, then give the answer.
+- Keep your spoken responses short — just say what the code found.
+
+Examples of questions you MUST use code for:
+- "What is 127 times 849?" → run_code
+- "How many prime numbers are there below 1000?" → run_code
+- "Reverse the string 'hello world'" → run_code
+- "What's the 50th fibonacci number?" → run_code
+- "Sort these numbers: 42, 17, 93, 8, 55" → run_code
+- "What day of the week was January 1st, 2000?" → run_code
+- "Convert 255 to binary" → run_code`,
+  greeting:
+    "Hey, I'm Coda. I solve problems by writing and running code. Try asking me something like, what's the 50th fibonacci number, or what day of the week was January 1st 2000.",
+  builtinTools: ["run_code"],
+});

package/templates/code-interpreter/client.tsx

@@ -0,0 +1,2 @@
+import { App, mount } from "@alexkroman1/aai/ui";
+mount(App);