@alexkroman1/aai 1.0.6 → 1.1.0

package/sdk/__snapshots__/exports.test.ts.snap

@@ -0,0 +1,77 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`export surface stability > @alexkroman1/aai main export 1`] = `
+[
+  "AGENT_CSP",
+  "BuiltinToolSchema",
+  "DEFAULT_GREETING",
+  "DEFAULT_IDLE_TIMEOUT_MS",
+  "DEFAULT_MAX_HISTORY",
+  "DEFAULT_SESSION_START_TIMEOUT_MS",
+  "DEFAULT_SHUTDOWN_TIMEOUT_MS",
+  "DEFAULT_STT_SAMPLE_RATE",
+  "DEFAULT_SYSTEM_PROMPT",
+  "DEFAULT_TTS_SAMPLE_RATE",
+  "FETCH_TIMEOUT_MS",
+  "MAX_HTML_BYTES",
+  "MAX_MESSAGE_BUFFER_SIZE",
+  "MAX_PAGE_CHARS",
+  "MAX_TOOL_RESULT_CHARS",
+  "MAX_VALUE_SIZE",
+  "MAX_WS_PAYLOAD_BYTES",
+  "RUN_CODE_TIMEOUT_MS",
+  "TOOL_EXECUTION_TIMEOUT_MS",
+  "ToolChoiceSchema",
+  "WS_OPEN",
+  "agent",
+  "errorDetail",
+  "errorMessage",
+  "parseWsUpgradeParams",
+  "tool",
+  "toolError",
+]
+`;
+
+exports[`export surface stability > @alexkroman1/aai/manifest export 1`] = `
+[
+  "AgentConfigSchema",
+  "EMPTY_PARAMS",
+  "ToolSchemaSchema",
+  "agentToolsToSchemas",
+  "toAgentConfig",
+]
+`;
+
+exports[`export surface stability > @alexkroman1/aai/protocol export 1`] = `
+[
+  "ClientEventSchema",
+  "ClientMessageSchema",
+  "KvDelSchema",
+  "KvGetSchema",
+  "KvRequestSchema",
+  "KvSetSchema",
+  "ReadyConfigSchema",
+  "ServerMessageSchema",
+  "SessionErrorCodeSchema",
+  "buildReadyConfig",
+  "lenientParse",
+]
+`;
+
+exports[`export surface stability > @alexkroman1/aai/runtime export 1`] = `
+[
+  "DEFAULT_S2S_CONFIG",
+  "_internals",
+  "buildCtx",
+  "consoleLogger",
+  "createRuntime",
+  "createS2sSession",
+  "createServer",
+  "createUnstorageKv",
+  "executeInIsolate",
+  "executeToolCall",
+  "jsonLogger",
+  "resolveAllBuiltins",
+  "wireSessionSocket",
+]
+`;

package/sdk/__snapshots__/schema-shapes.test.ts.snap

@@ -0,0 +1,187 @@
+// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html
+
+exports[`manifest schema shapes > AgentConfigSchema shape 1`] = `
+[
+  "builtinTools",
+  "greeting",
+  "idleTimeoutMs",
+  "maxSteps",
+  "name",
+  "sttPrompt",
+  "systemPrompt",
+  "toolChoice",
+]
+`;
+
+exports[`manifest schema shapes > ToolSchemaSchema shape 1`] = `
+[
+  "description",
+  "name",
+  "parameters",
+]
+`;
+
+exports[`protocol schema shapes > ClientEventSchema option shapes 1`] = `
+{
+  "agent_transcript": [
+    "text",
+    "type",
+  ],
+  "cancelled": [
+    "type",
+  ],
+  "custom_event": [
+    "data",
+    "event",
+    "type",
+  ],
+  "error": [
+    "code",
+    "message",
+    "type",
+  ],
+  "idle_timeout": [
+    "type",
+  ],
+  "reply_done": [
+    "type",
+  ],
+  "reset": [
+    "type",
+  ],
+  "speech_started": [
+    "type",
+  ],
+  "speech_stopped": [
+    "type",
+  ],
+  "tool_call": [
+    "args",
+    "toolCallId",
+    "toolName",
+    "type",
+  ],
+  "tool_call_done": [
+    "result",
+    "toolCallId",
+    "type",
+  ],
+  "user_transcript": [
+    "text",
+    "turnOrder",
+    "type",
+  ],
+}
+`;
+
+exports[`protocol schema shapes > ClientMessageSchema option shapes 1`] = `
+{
+  "audio_ready": [
+    "type",
+  ],
+  "cancel": [
+    "type",
+  ],
+  "history": [
+    "messages",
+    "type",
+  ],
+  "reset": [
+    "type",
+  ],
+}
+`;
+
+exports[`protocol schema shapes > KvDelSchema shape 1`] = `
+[
+  "key",
+  "op",
+]
+`;
+
+exports[`protocol schema shapes > KvGetSchema shape 1`] = `
+[
+  "key",
+  "op",
+]
+`;
+
+exports[`protocol schema shapes > KvSetSchema shape 1`] = `
+[
+  "expireIn",
+  "key",
+  "op",
+  "value",
+]
+`;
+
+exports[`protocol schema shapes > ReadyConfigSchema shape 1`] = `
+[
+  "audioFormat",
+  "sampleRate",
+  "ttsSampleRate",
+]
+`;
+
+exports[`protocol schema shapes > ServerMessageSchema option shapes 1`] = `
+{
+  "agent_transcript": [
+    "text",
+    "type",
+  ],
+  "audio_done": [
+    "type",
+  ],
+  "cancelled": [
+    "type",
+  ],
+  "config": [
+    "audioFormat",
+    "sampleRate",
+    "sessionId",
+    "ttsSampleRate",
+    "type",
+  ],
+  "custom_event": [
+    "data",
+    "event",
+    "type",
+  ],
+  "error": [
+    "code",
+    "message",
+    "type",
+  ],
+  "idle_timeout": [
+    "type",
+  ],
+  "reply_done": [
+    "type",
+  ],
+  "reset": [
+    "type",
+  ],
+  "speech_started": [
+    "type",
+  ],
+  "speech_stopped": [
+    "type",
+  ],
+  "tool_call": [
+    "args",
+    "toolCallId",
+    "toolName",
+    "type",
+  ],
+  "tool_call_done": [
+    "result",
+    "toolCallId",
+    "type",
+  ],
+  "user_transcript": [
+    "text",
+    "turnOrder",
+    "type",
+  ],
+}
+`;

package/sdk/_test-matchers.test.ts

@@ -0,0 +1,75 @@
+// Copyright 2025 the AAI authors. MIT license.
+
+import { describe, expect, it } from "vitest";
+import "./_test-matchers.ts";
+
+describe("toBeValidClientEvent", () => {
+  it("passes for a valid event", () => {
+    expect({ type: "speech_started" }).toBeValidClientEvent();
+  });
+
+  it("passes for a valid event with fields", () => {
+    expect({
+      type: "user_transcript",
+      text: "hello world",
+    }).toBeValidClientEvent();
+  });
+
+  it("fails for an invalid event", () => {
+    expect(() => {
+      expect({ type: "not_a_real_event" }).toBeValidClientEvent();
+    }).toThrow(/expected value to be a valid ClientEvent/);
+  });
+
+  it("fails for a missing type field", () => {
+    expect(() => {
+      expect({ text: "no type" }).toBeValidClientEvent();
+    }).toThrow(/expected value to be a valid ClientEvent/);
+  });
+});
+
+describe("toContainEvent", () => {
+  const events = [
+    { type: "speech_started" },
+    { type: "user_transcript", text: "hello" },
+    { type: "tool_call", toolCallId: "tc1", toolName: "search", args: { q: "test" } },
+    { type: "reply_done" },
+  ];
+
+  it("finds a matching event by type", () => {
+    expect(events).toContainEvent("speech_started");
+  });
+
+  it("finds a matching event with fields", () => {
+    expect(events).toContainEvent("tool_call", { toolName: "search" });
+  });
+
+  it("matches a subset of fields", () => {
+    expect(events).toContainEvent("tool_call", {
+      toolName: "search",
+      args: { q: "test" },
+    });
+  });
+
+  it("fails when event type is not found", () => {
+    expect(() => {
+      expect(events).toContainEvent("cancelled");
+    }).toThrow(/expected array to contain event of type "cancelled"/);
+  });
+
+  it("fails when fields do not match", () => {
+    expect(() => {
+      expect(events).toContainEvent("tool_call", { toolName: "visit_webpage" });
+    }).toThrow(/expected array to contain event of type "tool_call"/);
+  });
+
+  it("fails when received value is not an array", () => {
+    expect(() => {
+      expect("not-an-array").toContainEvent("speech_started");
+    }).toThrow(/expected an array of events/);
+  });
+
+  it("supports .not negation", () => {
+    expect(events).not.toContainEvent("cancelled");
+  });
+});

package/sdk/_test-matchers.ts

@@ -0,0 +1,73 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * Custom Vitest matchers for AAI domain types.
+ *
+ * Registered via `expect.extend()` — add this file to the vitest `setupFiles`
+ * for the `aai` project so matchers are available in every test.
+ */
+
+import { isDeepStrictEqual } from "node:util";
+import { expect } from "vitest";
+import { ClientEventSchema } from "./protocol.ts";
+
+type MatcherResult = { pass: boolean; message: () => string };
+
+// ─── Matcher implementations ────────────────────────────────────────────────
+
+function toBeValidClientEvent(received: unknown): MatcherResult {
+  const result = ClientEventSchema.safeParse(received);
+  return {
+    pass: result.success,
+    message: () =>
+      result.success
+        ? "expected value NOT to be a valid ClientEvent, but it parsed successfully"
+        : `expected value to be a valid ClientEvent\n\nZod errors:\n${result.error.issues.map((i) => `  - ${i.path.join(".")}: ${i.message}`).join("\n")}`,
+  };
+}
+
+function toContainEvent(
+  received: unknown,
+  type: string,
+  fields?: Record<string, unknown>,
+): MatcherResult {
+  if (!Array.isArray(received)) {
+    return {
+      pass: false,
+      message: () => `expected an array of events, but received ${typeof received}`,
+    };
+  }
+
+  const match = received.some((event: Record<string, unknown>) => {
+    if (event?.type !== type) return false;
+    if (!fields) return true;
+    return Object.entries(fields).every(([key, value]) => isDeepStrictEqual(event[key], value));
+  });
+
+  return {
+    pass: match,
+    message: () =>
+      match
+        ? `expected array NOT to contain event of type "${type}"${fields ? ` with fields ${JSON.stringify(fields)}` : ""}`
+        : `expected array to contain event of type "${type}"${fields ? ` with fields ${JSON.stringify(fields)}` : ""}\n\nReceived event types: [${received.map((e: Record<string, unknown>) => `"${e?.type}"`).join(", ")}]`,
+  };
+}
+
+// ─── Register matchers ──────────────────────────────────────────────────────
+
+expect.extend({
+  toBeValidClientEvent,
+  toContainEvent,
+});
+
+// ─── Type augmentation ──────────────────────────────────────────────────────
+
+declare module "vitest" {
+  interface Assertion<T> {
+    toBeValidClientEvent(): void;
+    toContainEvent(type: string, fields?: Record<string, unknown>): void;
+  }
+  interface AsymmetricMatchersContaining {
+    toBeValidClientEvent(): void;
+    toContainEvent(type: string, fields?: Record<string, unknown>): void;
+  }
+}

package/sdk/exports.test.ts

@@ -0,0 +1,31 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * Export surface snapshot tests for all four aai subpath exports.
+ *
+ * These tests catch accidental export additions or removals. If a snapshot
+ * breaks, it signals a potentially breaking API change that should be
+ * reviewed and documented with a changeset.
+ */
+import { describe, expect, test } from "vitest";
+
+describe("export surface stability", () => {
+  test("@alexkroman1/aai main export", async () => {
+    const mod = await import("@alexkroman1/aai");
+    expect(Object.keys(mod).sort()).toMatchSnapshot();
+  });
+
+  test("@alexkroman1/aai/protocol export", async () => {
+    const mod = await import("@alexkroman1/aai/protocol");
+    expect(Object.keys(mod).sort()).toMatchSnapshot();
+  });
+
+  test("@alexkroman1/aai/manifest export", async () => {
+    const mod = await import("@alexkroman1/aai/manifest");
+    expect(Object.keys(mod).sort()).toMatchSnapshot();
+  });
+
+  test("@alexkroman1/aai/runtime export", async () => {
+    const mod = await import("@alexkroman1/aai/runtime");
+    expect(Object.keys(mod).sort()).toMatchSnapshot();
+  });
+});

package/sdk/manifest-barrel.ts

@@ -1,12 +1,18 @@
 // Copyright 2025 the AAI authors. MIT license.
 /**
- * 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).
  */
 
-// biome-ignore-all lint/performance/noReExportAll: barrel file by design
-
-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/sdk/manifest.test.ts

@@ -1,6 +1,9 @@
 // Copyright 2025 the AAI authors. MIT license.
-import { describe, expect, test } from "vitest";
-import { parseManifest } from "./manifest.ts";
+import fc from "fast-check";
+import { describe, expect, expectTypeOf, test } from "vitest";
+import { type Manifest, parseManifest } from "./manifest.ts";
+import type { AgentConfig, ToolSchema } from "./manifest-barrel.ts";
+import { agentToolsToSchemas, toAgentConfig } from "./manifest-barrel.ts";
 
 describe("parseManifest", () => {
   test("minimal manifest requires only name", () => {
@@ -54,3 +57,64 @@ describe("parseManifest", () => {
     expect(() => parseManifest({ name: "X", builtinTools: ["not_a_tool"] })).toThrow();
   });
 });
+
+// ── Property-based tests ─────────────────────────────────────────────────
+
+describe("property: parseManifest", () => {
+  test("valid manifests always parse", () => {
+    const validManifestArb = fc.record({
+      name: fc.string({ minLength: 1 }),
+      systemPrompt: fc.option(fc.string(), { nil: undefined }),
+      greeting: fc.option(fc.string(), { nil: undefined }),
+      maxSteps: fc.option(fc.integer({ min: 1, max: 100 }), { nil: undefined }),
+      toolChoice: fc.option(fc.constantFrom("auto" as const, "required" as const), {
+        nil: undefined,
+      }),
+    });
+
+    fc.assert(
+      fc.property(validManifestArb, (manifest) => {
+        const result = parseManifest(manifest);
+        expect(result.name).toBe(manifest.name);
+        expect(result.maxSteps).toBeGreaterThan(0);
+        expect(["auto", "required"]).toContain(result.toolChoice);
+      }),
+    );
+  });
+
+  test("missing name throws", () => {
+    // Generate objects that never have a `name` field
+    const noNameArb = fc.record({
+      systemPrompt: fc.option(fc.string(), { nil: undefined }),
+      greeting: fc.option(fc.string(), { nil: undefined }),
+      maxSteps: fc.option(fc.integer({ min: 1, max: 100 }), { nil: undefined }),
+    });
+
+    fc.assert(
+      fc.property(noNameArb, (obj) => {
+        expect(() => parseManifest(obj)).toThrow();
+      }),
+    );
+  });
+});
+
+describe("manifest type contracts", () => {
+  test("parseManifest returns Manifest", () => {
+    const result = parseManifest({ name: "test" });
+    expectTypeOf(result).toEqualTypeOf<Manifest>();
+  });
+
+  test("parseManifest accepts unknown input", () => {
+    expectTypeOf(parseManifest).parameter(0).toBeUnknown();
+  });
+
+  test("toAgentConfig returns AgentConfig", () => {
+    const config = toAgentConfig({ name: "test", systemPrompt: "p", greeting: "g" });
+    expectTypeOf(config).toEqualTypeOf<AgentConfig>();
+  });
+
+  test("agentToolsToSchemas returns ToolSchema[]", () => {
+    const schemas = agentToolsToSchemas({});
+    expectTypeOf(schemas).toEqualTypeOf<ToolSchema[]>();
+  });
+});

package/sdk/protocol-compat.test.ts

@@ -15,7 +15,6 @@ import {
   MAX_TOOL_RESULT_CHARS,
 } from "./constants.ts";
 import {
-  AUDIO_FORMAT,
   ClientMessageSchema,
   KvRequestSchema,
   ServerMessageSchema,
@@ -35,7 +34,6 @@ type Fixture = {
   ClientMessage: Record<string, unknown>[];
   KvRequest: Record<string, unknown>[];
   constants: {
-    AUDIO_FORMAT: string;
     DEFAULT_STT_SAMPLE_RATE: number;
     DEFAULT_TTS_SAMPLE_RATE: number;
     MAX_TOOL_RESULT_CHARS: number;
@@ -161,10 +159,6 @@ describe.each(fixtureFiles)("compat fixture: %s", (filename) => {
   // ── Constants stability ─────────────────────────────────────────
 
   describe("constants stability", () => {
-    test("AUDIO_FORMAT unchanged", () => {
-      expect(AUDIO_FORMAT).toBe(fixture.constants.AUDIO_FORMAT);
-    });
-
     test("DEFAULT_STT_SAMPLE_RATE unchanged", () => {
       expect(DEFAULT_STT_SAMPLE_RATE).toBe(fixture.constants.DEFAULT_STT_SAMPLE_RATE);
     });

package/sdk/protocol-snapshot.test.ts

@@ -14,7 +14,6 @@ import {
 } from "./constants.ts";
 import type { ClientEvent, ClientMessage, ServerMessage } from "./protocol.ts";
 import {
-  AUDIO_FORMAT,
   ClientEventSchema,
   ClientMessageSchema,
   KvRequestSchema,
@@ -24,10 +23,6 @@ import {
 // ── Constants ────────────────────────────────────────────────────────────
 
 describe("protocol constants", () => {
-  test("audio format", () => {
-    expect(AUDIO_FORMAT).toMatchInlineSnapshot(`"pcm16"`);
-  });
-
   test("sample rates", () => {
     expect(DEFAULT_STT_SAMPLE_RATE).toMatchInlineSnapshot("16000");
     expect(DEFAULT_TTS_SAMPLE_RATE).toMatchInlineSnapshot("24000");
@@ -77,6 +72,7 @@ describe("server→client event wire format", () => {
     ["reset", { type: "reset" }],
     ["idle_timeout", { type: "idle_timeout" }],
     ["error", { type: "error", code: "stt", message: "Speech recognition failed" }],
+    ["custom_event", { type: "custom_event", event: "game_state", data: { hp: 10 } }],
   ];
 
   test.each(valid)("%s parses successfully", (_label, event) => {
@@ -94,6 +90,12 @@ describe("server→client event wire format", () => {
     ).toBe(false);
   });
 
+  test("rejects custom_event with empty event name", () => {
+    expect(
+      ClientEventSchema.safeParse({ type: "custom_event", event: "", data: null }).success,
+    ).toBe(false);
+  });
+
   test("rejects tool_call_done with oversized result", () => {
     expect(
       ClientEventSchema.safeParse({