@alexkroman1/aai 0.12.3 → 1.0.3

package/sdk/schema-alignment.test.ts

@@ -0,0 +1,191 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * Schema–type alignment tests.
+ *
+ * These tests verify that Zod schemas and their derived TypeScript types
+ * stay in sync, and that schemas correctly reject invalid data. When a
+ * new field is added to a type but not its schema (or vice-versa), these
+ * tests break — preventing silent API drift.
+ */
+import { describe, expect, expectTypeOf, test } from "vitest";
+import type { z } from "zod";
+import { type AgentConfig, AgentConfigSchema, ToolSchemaSchema } from "./_internal-types.ts";
+import {
+  type ReadyConfig,
+  ReadyConfigSchema,
+  type TurnConfig,
+  TurnConfigSchema,
+} from "./protocol.ts";
+import { type BuiltinTool, BuiltinToolSchema, type ToolChoice, ToolChoiceSchema } from "./types.ts";
+
+// ── AgentConfigSchema ────────────────────────────────────────────────────
+
+describe("AgentConfigSchema", () => {
+  const valid: AgentConfig = {
+    name: "test-agent",
+    systemPrompt: "Be helpful",
+    greeting: "Hello",
+  };
+
+  test("accepts valid minimal config", () => {
+    expect(AgentConfigSchema.parse(valid)).toEqual(valid);
+  });
+
+  test("accepts full config with all optional fields", () => {
+    const full: AgentConfig = {
+      ...valid,
+      sttPrompt: "Transcribe accurately",
+      maxSteps: 10,
+      toolChoice: "auto",
+      builtinTools: ["web_search", "run_code"],
+    };
+    expect(AgentConfigSchema.parse(full)).toEqual(full);
+  });
+
+  test("rejects empty name", () => {
+    expect(AgentConfigSchema.safeParse({ ...valid, name: "" }).success).toBe(false);
+  });
+
+  test("rejects non-integer maxSteps", () => {
+    expect(AgentConfigSchema.safeParse({ ...valid, maxSteps: 2.5 }).success).toBe(false);
+  });
+
+  test("rejects negative maxSteps", () => {
+    expect(AgentConfigSchema.safeParse({ ...valid, maxSteps: -1 }).success).toBe(false);
+  });
+
+  test("rejects invalid builtinTools", () => {
+    expect(AgentConfigSchema.safeParse({ ...valid, builtinTools: ["not_a_tool"] }).success).toBe(
+      false,
+    );
+  });
+
+  test("type derived from schema matches AgentConfig", () => {
+    expectTypeOf<z.infer<typeof AgentConfigSchema>>().toEqualTypeOf<AgentConfig>();
+  });
+});
+
+// ── ToolSchemaSchema ─────────────────────────────────────────────────────
+
+describe("ToolSchemaSchema", () => {
+  test("accepts valid tool schema", () => {
+    const valid = {
+      name: "get_weather",
+      description: "Get weather",
+      parameters: { type: "object", properties: { city: { type: "string" } } },
+    };
+    expect(ToolSchemaSchema.parse(valid)).toEqual(valid);
+  });
+
+  test("rejects empty name", () => {
+    expect(ToolSchemaSchema.safeParse({ name: "", description: "d", parameters: {} }).success).toBe(
+      false,
+    );
+  });
+
+  test("rejects empty description", () => {
+    expect(ToolSchemaSchema.safeParse({ name: "n", description: "", parameters: {} }).success).toBe(
+      false,
+    );
+  });
+
+  test("ToolSchema is assignable from schema inference", () => {
+    // ToolSchema uses JSONSchema7 for parameters which is more specific than
+    // the runtime schema's Record<string, unknown>. Verify the direction:
+    // a parsed result should be assignable to ToolSchema (narrow → wide).
+    const parsed = ToolSchemaSchema.parse({
+      name: "test",
+      description: "test",
+      parameters: { type: "object" },
+    });
+    // Runtime check: shape matches
+    expect(parsed).toHaveProperty("name");
+    expect(parsed).toHaveProperty("description");
+    expect(parsed).toHaveProperty("parameters");
+  });
+});
+
+// ── TurnConfigSchema ─────────────────────────────────────────────────────
+
+describe("TurnConfigSchema", () => {
+  test("accepts empty config", () => {
+    expect(TurnConfigSchema.parse({})).toEqual({});
+  });
+
+  test("accepts full config", () => {
+    const full: TurnConfig = { maxSteps: 3 };
+    expect(TurnConfigSchema.parse(full)).toEqual(full);
+  });
+
+  test("rejects non-positive maxSteps", () => {
+    expect(TurnConfigSchema.safeParse({ maxSteps: 0 }).success).toBe(false);
+  });
+
+  test("type derived from schema matches TurnConfig", () => {
+    expectTypeOf<z.infer<typeof TurnConfigSchema>>().toEqualTypeOf<TurnConfig>();
+  });
+});
+
+// ── ReadyConfigSchema ────────────────────────────────────────────────────
+
+describe("ReadyConfigSchema", () => {
+  const valid: ReadyConfig = {
+    audioFormat: "pcm16",
+    sampleRate: 16_000,
+    ttsSampleRate: 24_000,
+  };
+
+  test("accepts valid config", () => {
+    expect(ReadyConfigSchema.parse(valid)).toEqual(valid);
+  });
+
+  test("rejects unknown audio format", () => {
+    expect(ReadyConfigSchema.safeParse({ ...valid, audioFormat: "mp3" }).success).toBe(false);
+  });
+
+  test("rejects non-positive sampleRate", () => {
+    expect(ReadyConfigSchema.safeParse({ ...valid, sampleRate: 0 }).success).toBe(false);
+  });
+
+  test("type derived from schema matches ReadyConfig", () => {
+    expectTypeOf<z.infer<typeof ReadyConfigSchema>>().toEqualTypeOf<ReadyConfig>();
+  });
+});
+
+// ── BuiltinTool / ToolChoice drift guards ────────────────────────────────
+
+describe("type ↔ schema alignment", () => {
+  test("BuiltinToolSchema values match BuiltinTool union", () => {
+    // Schema values are the source of truth; if the type adds a member
+    // without updating the schema (or vice versa), TypeScript will error
+    // on the drift guards in types.ts. This test documents the enum values.
+    expect(BuiltinToolSchema.options).toMatchInlineSnapshot(`
+      [
+        "web_search",
+        "visit_webpage",
+        "fetch_json",
+        "run_code",
+      ]
+    `);
+  });
+
+  test("BuiltinTool type equals schema inference", () => {
+    expectTypeOf<z.infer<typeof BuiltinToolSchema>>().toEqualTypeOf<BuiltinTool>();
+  });
+
+  test("ToolChoice type equals schema inference", () => {
+    expectTypeOf<z.infer<typeof ToolChoiceSchema>>().toEqualTypeOf<ToolChoice>();
+  });
+
+  test("ToolChoiceSchema accepts all ToolChoice variants", () => {
+    const variants: ToolChoice[] = ["auto", "required"];
+    for (const v of variants) {
+      expect(ToolChoiceSchema.safeParse(v).success).toBe(true);
+    }
+  });
+
+  test("ToolChoiceSchema rejects invalid variants", () => {
+    expect(ToolChoiceSchema.safeParse("invalid").success).toBe(false);
+    expect(ToolChoiceSchema.safeParse("none").success).toBe(false);
+  });
+});

package/sdk/system-prompt.test.ts

@@ -0,0 +1,111 @@
+// Copyright 2025 the AAI authors. MIT license.
+
+import { afterEach, beforeEach, describe, expect, test, vi } from "vitest";
+import { makeConfig } from "../host/_test-utils.ts";
+import { buildSystemPrompt } from "./system-prompt.ts";
+import { DEFAULT_SYSTEM_PROMPT } from "./types.ts";
+
+describe("buildSystemPrompt", () => {
+  beforeEach(() => {
+    vi.useFakeTimers();
+    // Pin to Wednesday, January 15, 2025
+    vi.setSystemTime(new Date("2025-01-15T12:00:00Z"));
+  });
+
+  afterEach(() => {
+    vi.useRealTimers();
+  });
+
+  test("starts with DEFAULT_SYSTEM_PROMPT when no custom instructions", () => {
+    const result = buildSystemPrompt(makeConfig(), { hasTools: false });
+    expect(result.startsWith(DEFAULT_SYSTEM_PROMPT)).toBe(true);
+  });
+
+  test("does not include agent-specific instructions section for default instructions", () => {
+    const result = buildSystemPrompt(makeConfig(), { hasTools: false });
+    expect(result).not.toContain("Agent-Specific Instructions:");
+  });
+
+  test("appends custom agent instructions", () => {
+    const custom = "You are a pirate. Always speak like one.";
+    const result = buildSystemPrompt(makeConfig({ systemPrompt: custom }), { hasTools: false });
+    expect(result).toContain("Agent-Specific Instructions:");
+    expect(result).toContain(custom);
+  });
+
+  test("includes tool preamble when hasTools is true", () => {
+    const result = buildSystemPrompt(makeConfig(), { hasTools: true });
+    expect(result).toContain("ALWAYS say a brief natural phrase BEFORE the tool call");
+  });
+
+  test("omits tool preamble when hasTools is false", () => {
+    const result = buildSystemPrompt(makeConfig(), { hasTools: false });
+    expect(result).not.toContain("ALWAYS say a brief natural phrase BEFORE the tool call");
+  });
+
+  test("appends voice rules when voice is true", () => {
+    const result = buildSystemPrompt(makeConfig(), { hasTools: false, voice: true });
+    expect(result).toContain("CRITICAL OUTPUT RULES");
+    expect(result).toContain("NEVER use markdown");
+  });
+
+  test("omits voice rules when voice is false", () => {
+    const result = buildSystemPrompt(makeConfig(), { hasTools: false, voice: false });
+    expect(result).not.toContain("CRITICAL OUTPUT RULES");
+  });
+
+  test("omits voice rules when voice is undefined", () => {
+    const result = buildSystemPrompt(makeConfig(), { hasTools: false });
+    expect(result).not.toContain("CRITICAL OUTPUT RULES");
+  });
+
+  test("includes correctly formatted date string", () => {
+    const result = buildSystemPrompt(makeConfig(), { hasTools: false });
+    expect(result).toContain("Today's date is Wednesday, January 15, 2025.");
+  });
+
+  test("date format uses en-US locale with weekday, month, day, and year", () => {
+    // Advance to a different date to verify format consistency
+    vi.setSystemTime(new Date("2025-12-31T12:00:00Z"));
+    const result = buildSystemPrompt(makeConfig(), { hasTools: false });
+    expect(result).toContain("Today's date is Wednesday, December 31, 2025.");
+  });
+
+  test("voice + hasTools includes both voice rules and tool preamble", () => {
+    const result = buildSystemPrompt(makeConfig(), { hasTools: true, voice: true });
+    expect(result).toContain("CRITICAL OUTPUT RULES");
+    expect(result).toContain("ALWAYS say a brief natural phrase BEFORE the tool call");
+  });
+
+  test("custom instructions + voice + tools includes all sections", () => {
+    const result = buildSystemPrompt(makeConfig({ systemPrompt: "Be concise." }), {
+      hasTools: true,
+      voice: true,
+    });
+    expect(result).toContain("Agent-Specific Instructions:");
+    expect(result).toContain("Be concise.");
+    expect(result).toContain("CRITICAL OUTPUT RULES");
+    expect(result).toContain("ALWAYS say a brief natural phrase BEFORE the tool call");
+  });
+
+  test("sections appear in correct order", () => {
+    const result = buildSystemPrompt(makeConfig({ systemPrompt: "Custom rules." }), {
+      hasTools: true,
+      voice: true,
+    });
+    const dateIdx = result.indexOf("Today's date is");
+    const instructionsIdx = result.indexOf("Agent-Specific Instructions:");
+    const toolIdx = result.indexOf("ALWAYS say a brief natural phrase");
+    const voiceIdx = result.indexOf("CRITICAL OUTPUT RULES");
+
+    expect(dateIdx).toBeGreaterThan(0);
+    expect(instructionsIdx).toBeGreaterThan(dateIdx);
+    expect(toolIdx).toBeGreaterThan(instructionsIdx);
+    expect(voiceIdx).toBeGreaterThan(toolIdx);
+  });
+
+  test("empty custom instructions treated same as default", () => {
+    const result = buildSystemPrompt(makeConfig({ systemPrompt: "" }), { hasTools: false });
+    expect(result).not.toContain("Agent-Specific Instructions:");
+  });
+});

package/sdk/system-prompt.ts

@@ -0,0 +1,74 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * System prompt builder for S2S sessions.
+ */
+
+import type { AgentConfig } from "./_internal-types.ts";
+import { DEFAULT_SYSTEM_PROMPT } from "./types.ts";
+
+function getFormattedDate(): string {
+  return 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:\n" +
+  "Your 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.
+ */
+export function buildSystemPrompt(
+  config: AgentConfig,
+  opts: { hasTools: boolean; voice?: boolean; toolGuidance?: readonly string[] | undefined },
+): string {
+  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")}`
+      : "";
+
+  const today = getFormattedDate();
+
+  return (
+    DEFAULT_SYSTEM_PROMPT +
+    `\n\nToday's date is ${today}.` +
+    agentInstructions +
+    toolPreamble +
+    guidance +
+    (opts.voice ? VOICE_RULES : "")
+  );
+}

package/sdk/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "extends": "../../../tsconfig.json",
+  "compilerOptions": {
+    "types": [],
+    "lib": ["ESNext", "DOM"],
+    "noEmit": true,
+    "incremental": true,
+    "tsBuildInfoFile": "../../../.tsbuildinfo/aai-sdk.tsbuildinfo"
+  },
+  "include": ["./**/*.ts"],
+  "exclude": ["**/*.test.ts", "**/*.test-d.ts"]
+}

package/sdk/types-inference.test.ts

@@ -0,0 +1,122 @@
+// Copyright 2025 the AAI authors. MIT license.
+/**
+ * Type-level tests for AgentDef and ToolDef type inference.
+ *
+ * These use vitest's expectTypeOf to verify that TypeScript correctly
+ * infers parameter types, state types, and context types without
+ * any runtime assertions. A failing type test means a type refactor
+ * broke inference for consumers.
+ */
+import { describe, expectTypeOf, test } from "vitest";
+import { z } from "zod";
+import type { AgentDef, Message, ToolContext, ToolDef } from "./types.ts";
+
+describe("ToolDef type inference", () => {
+  test("infers parameter types in execute args", () => {
+    const _t: ToolDef<z.ZodObject<{ name: z.ZodString; count: z.ZodNumber }>> = {
+      description: "test",
+      parameters: z.object({ name: z.string(), count: z.number() }),
+      execute: (args) => args,
+    };
+
+    // The execute function should receive typed args
+    type Args = Parameters<typeof _t.execute>[0];
+    expectTypeOf<Args>().toEqualTypeOf<{ name: string; count: number }>();
+  });
+
+  test("ToolDef without parameters has unknown args", () => {
+    const _t: ToolDef = {
+      description: "test",
+      execute: (args) => args,
+    };
+
+    type Args = Parameters<typeof _t.execute>[0];
+    // Without parameters, args is inferred from the base ZodObject
+    expectTypeOf<Args>().toBeObject();
+  });
+
+  test("execute receives ToolContext as second arg", () => {
+    const _t: ToolDef<z.ZodObject<{ x: z.ZodString }>> = {
+      description: "test",
+      parameters: z.object({ x: z.string() }),
+      execute: (_args, ctx) => ctx,
+    };
+
+    type Ctx = Parameters<typeof _t.execute>[1];
+    expectTypeOf<Ctx>().toMatchTypeOf<ToolContext>();
+  });
+
+  test("ToolContext provides kv, env, messages", () => {
+    expectTypeOf<ToolContext>().toHaveProperty("kv");
+    expectTypeOf<ToolContext>().toHaveProperty("env");
+    expectTypeOf<ToolContext>().toHaveProperty("messages");
+    expectTypeOf<ToolContext["messages"]>().toEqualTypeOf<readonly Message[]>();
+    expectTypeOf<ToolContext["env"]>().toEqualTypeOf<Readonly<Record<string, string>>>();
+  });
+});
+
+describe("AgentDef type inference", () => {
+  test("satisfies AgentDef type", () => {
+    const agent: AgentDef = {
+      name: "test",
+      systemPrompt: "Be helpful.",
+      greeting: "Hello!",
+      maxSteps: 5,
+      tools: {},
+    };
+    expectTypeOf(agent).toMatchTypeOf<AgentDef>();
+  });
+
+  test("typed state flows through to tools", () => {
+    type MyState = { counter: number; name: string };
+
+    // This should compile without errors — state type flows
+    // through to tool execute context
+    const _agent: AgentDef<MyState> = {
+      name: "typed-state",
+      systemPrompt: "Be helpful.",
+      greeting: "Hello!",
+      maxSteps: 5,
+      state: () => ({ counter: 0, name: "test" }),
+      tools: {
+        inc: {
+          description: "Increment",
+          execute: (_args, ctx) => {
+            expectTypeOf(ctx.state).toEqualTypeOf<MyState>();
+          },
+        },
+      },
+    };
+  });
+
+  test("tools field accepts ToolDef objects", () => {
+    const greet: ToolDef<z.ZodObject<{ name: z.ZodString }>> = {
+      description: "Greet",
+      parameters: z.object({ name: z.string() }),
+      execute: ({ name }: { name: string }) => `Hello, ${name}!`,
+    };
+
+    const agent: AgentDef = {
+      name: "with-tool",
+      systemPrompt: "Be helpful.",
+      greeting: "Hello!",
+      maxSteps: 5,
+      tools: { greet },
+    };
+
+    expectTypeOf(agent.tools).toHaveProperty("greet");
+  });
+
+  test("required fields are present", () => {
+    const agent: AgentDef = {
+      name: "defaults",
+      systemPrompt: "Be helpful.",
+      greeting: "Hello!",
+      maxSteps: 5,
+      tools: {},
+    };
+    expectTypeOf(agent.systemPrompt).toBeString();
+    expectTypeOf(agent.greeting).toBeString();
+    expectTypeOf(agent.tools).toBeObject();
+  });
+});

package/sdk/types.test.ts

@@ -0,0 +1,14 @@
+import { describe, expect, test } from "vitest";
+import { DEFAULT_GREETING, DEFAULT_SYSTEM_PROMPT } from "./types.ts";
+
+describe("constants", () => {
+  test("DEFAULT_SYSTEM_PROMPT is a non-empty string", () => {
+    expect(typeof DEFAULT_SYSTEM_PROMPT).toBe("string");
+    expect(DEFAULT_SYSTEM_PROMPT.length).toBeGreaterThan(0);
+  });
+
+  test("DEFAULT_GREETING is a non-empty string", () => {
+    expect(typeof DEFAULT_GREETING).toBe("string");
+    expect(DEFAULT_GREETING.length).toBeGreaterThan(0);
+  });
+});