@alexkroman1/aai-cli 5.14.0 → 6.1.0

package/dist/templates/infocom-adventure/agent.test.ts

@@ -0,0 +1,205 @@
+/// <reference types="vite/client" />
+
+import type { ToolContext } from "@alexkroman1/aai";
+import { createToolContext, runTool, withDiscoveredTools } from "@alexkroman1/aai/testing";
+import { describe, expect, test } from "vitest";
+import authoredAgent from "./agent.ts";
+
+/**
+ * The def a DEPLOYED agent runs: authored, plus what `tools/` declares.
+ *
+ * The glob is written HERE rather than reached for from a shared helper because
+ * this file SHIPS: it is what a scaffolded project runs, so it may not import
+ * anything outside its own template, and `import.meta.glob` is expanded against
+ * the file containing it either way. This is the pattern a user writes.
+ */
+const agentDef = withDiscoveredTools(
+  authoredAgent,
+  import.meta.glob("./tools/*.ts", { eager: true }),
+);
+
+import { DEFAULT_GAME_STATE, gameSlot, MAX_HISTORY, REPORTED_HISTORY } from "./shared.ts";
+
+/** A tool by the name the model calls it by, bound to this agent. */
+const run = (name: string, args: Record<string, unknown>, ctx: ToolContext) =>
+  runTool(agentDef, name, args, ctx);
+
+/** Each context owns its OWN slot store, which is what makes two playthroughs
+ *  independent by construction. */
+const makeCtx = () => createToolContext();
+
+// ─── The frozen-vs-draft contract ────────────────────────────────────────────
+//
+// This whole block exists because the template shipped without it and two tools
+// were wrong. `game_state_take` and `game_state_flag` were declared with
+// `gameSlot.tool` — the READING half, whose value is deep-frozen — while
+// pushing to `inventory` and writing into `flags`. Every call threw a
+// `TypeError`, and nothing in the repo executed either body. The declaration is
+// the fix; these are what keep it fixed.
+
+describe("the mutating tools actually mutate", () => {
+  test("game_state_take adds to the inventory and does not double an item", async () => {
+    const ctx = makeCtx();
+
+    const first = (await run("game_state_take", { value: "lantern" }, ctx)) as {
+      inventory: string[];
+    };
+    expect(first.inventory).toEqual(["lantern"]);
+    // The stored value, not the one the body returned — a body handed a frozen
+    // value would have thrown, and a body handed a copy nothing stores would
+    // report success here and leave the slot empty.
+    expect(gameSlot.get(ctx).inventory).toEqual(["lantern"]);
+
+    const again = (await run("game_state_take", { value: "lantern" }, ctx)) as {
+      inventory: string[];
+    };
+    expect(again.inventory).toEqual(["lantern"]);
+  });
+
+  test("game_state_flag records a flag, and a second flag joins the first", async () => {
+    const ctx = makeCtx();
+
+    await run("game_state_flag", { value: "gate_opened" }, ctx);
+    const both = (await run("game_state_flag", { value: "rope_cut" }, ctx)) as {
+      flags: Record<string, boolean>;
+    };
+
+    expect(both.flags).toEqual({ gate_opened: true, rope_cut: true });
+    expect(gameSlot.get(ctx).flags).toEqual({ gate_opened: true, rope_cut: true });
+  });
+
+  test("what a READ is handed is frozen, which is why the two above are updateTool", async () => {
+    const ctx = makeCtx();
+    await run("game_state_take", { value: "lantern" }, ctx);
+
+    const game = gameSlot.get(ctx);
+    // The type refuses this too (`readonly string[]` has no `push`), and the
+    // freeze is what makes the refusal true for a caller with no types.
+    expect(Object.isFrozen(game.inventory)).toBe(true);
+    expect(() => (game.inventory as string[]).push("sword")).toThrow(TypeError);
+  });
+});
+
+// ─── The rest of the eight ───────────────────────────────────────────────────
+
+describe("the adventure's tools", () => {
+  test("drop removes an item and is a no-op for one the player never took", async () => {
+    const ctx = makeCtx();
+    await run("game_state_take", { value: "lantern" }, ctx);
+    await run("game_state_take", { value: "rope" }, ctx);
+
+    const dropped = (await run("game_state_drop", { value: "lantern" }, ctx)) as {
+      inventory: string[];
+    };
+    expect(dropped.inventory).toEqual(["rope"]);
+
+    const nothing = (await run("game_state_drop", { value: "sword" }, ctx)) as {
+      inventory: string[];
+    };
+    expect(nothing.inventory).toEqual(["rope"]);
+  });
+
+  test("move sets the room and counts the move", async () => {
+    const ctx = makeCtx();
+    const moved = (await run("game_state_move", { value: "Echo Chamber" }, ctx)) as {
+      currentRoom: string;
+      moves: number;
+    };
+    expect(moved).toEqual({ currentRoom: "Echo Chamber", moves: 1 });
+    expect(gameSlot.get(ctx).currentRoom).toBe("Echo Chamber");
+  });
+
+  test("score accumulates rather than replacing", async () => {
+    const ctx = makeCtx();
+    await run("game_state_score", { value: 10 }, ctx);
+    const total = (await run("game_state_score", { value: 5 }, ctx)) as { score: number };
+    expect(total.score).toBe(15);
+  });
+
+  test("history logs the command, counts the move, and reports only the recent ones", async () => {
+    const ctx = makeCtx();
+    for (let i = 1; i <= REPORTED_HISTORY + 2; i++) {
+      await run("game_state_history", { value: `command ${i}` }, ctx);
+    }
+
+    const last = (await run("game_state_history", { value: "look" }, ctx)) as {
+      moves: number;
+      recentHistory: string[];
+    };
+    expect(last.moves).toBe(REPORTED_HISTORY + 3);
+    expect(last.recentHistory).toHaveLength(REPORTED_HISTORY);
+    expect(last.recentHistory.at(-1)).toBe("look");
+  });
+
+  test("the history is capped, so a long playthrough does not grow without bound", async () => {
+    const ctx = makeCtx();
+    for (let i = 0; i < MAX_HISTORY + 10; i++) {
+      await run("game_state_history", { value: `command ${i}` }, ctx);
+    }
+    const game = gameSlot.get(ctx);
+    expect(game.history).toHaveLength(MAX_HISTORY);
+    // The cap drops the OLDEST — the newest command is the one a narrator needs.
+    expect(game.history.at(-1)).toBe(`command ${MAX_HISTORY + 9}`);
+    expect(game.moves).toBe(MAX_HISTORY + 10);
+  });
+
+  test("get reports the whole board, with the history trimmed to what a narrator reads", async () => {
+    const ctx = makeCtx();
+    await run("game_state_take", { value: "lantern" }, ctx);
+    await run("game_state_flag", { value: "gate_opened" }, ctx);
+    await run("game_state_move", { value: "Echo Chamber" }, ctx);
+    await run("game_state_score", { value: 7 }, ctx);
+    for (let i = 0; i < REPORTED_HISTORY + 3; i++) {
+      await run("game_state_history", { value: `command ${i}` }, ctx);
+    }
+
+    expect(await run("game_state_get", {}, ctx)).toEqual({
+      currentRoom: "Echo Chamber",
+      inventory: ["lantern"],
+      score: 7,
+      moves: REPORTED_HISTORY + 4,
+      flags: { gate_opened: true },
+      recentHistory: Array.from({ length: REPORTED_HISTORY }, (_, i) => `command ${i + 3}`),
+    });
+  });
+
+  test("restart replaces the whole game, and the fresh room is the one the greeting describes", async () => {
+    const ctx = makeCtx();
+    await run("game_state_take", { value: "lantern" }, ctx);
+    await run("game_state_score", { value: 30 }, ctx);
+    await run("game_state_move", { value: "Echo Chamber" }, ctx);
+
+    const restarted = (await run("game_state_restart", {}, ctx)) as {
+      restarted: boolean;
+      currentRoom: string;
+    };
+    expect(restarted).toEqual({ restarted: true, currentRoom: DEFAULT_GAME_STATE.currentRoom });
+    expect(gameSlot.get(ctx)).toEqual(DEFAULT_GAME_STATE);
+  });
+});
+
+describe("the game is per context", () => {
+  test("a second playthrough starts empty and cannot see the first", async () => {
+    // What this really checks: the state lives in the SLOT and not in a
+    // module-level variable. `createToolContext()` hands each call its own
+    // detached slot store, so the isolation is per CONTEXT — two distinct
+    // session ids would prove nothing extra, and `sessionSlot` could stop
+    // keying by session with this still passing.
+    const one = makeCtx();
+    const two = makeCtx();
+
+    await run("game_state_take", { value: "lantern" }, one);
+    await run("game_state_move", { value: "Echo Chamber" }, one);
+
+    expect(gameSlot.get(two)).toEqual(DEFAULT_GAME_STATE);
+    await run("game_state_take", { value: "rope" }, two);
+    expect(gameSlot.get(one).inventory).toEqual(["lantern"]);
+    expect(gameSlot.get(two).inventory).toEqual(["rope"]);
+  });
+
+  test("the module-level default is cloned, so no session can edit the next one's start", async () => {
+    const ctx = makeCtx();
+    await run("game_state_take", { value: "lantern" }, ctx);
+    expect(DEFAULT_GAME_STATE.inventory).toEqual([]);
+  });
+});

package/dist/templates/infocom-adventure/agent.ts

@@ -1,117 +1,14 @@
-import { agent, tool } from "@alexkroman1/aai";
-import { z } from "zod";
-import { gameSlot, recordCommand } from "./shared.ts";
-import systemPrompt from "./system-prompt.md?raw";
+import { agent } from "@alexkroman1/aai";
 
 export default agent({
   name: "Cavern Adventure",
+  // The world exists before the first command, so a resumed connection has
+  // something to project rather than an empty state object.
   // A narrator wants a narrative voice; everything else stays on the
   // default all-AssemblyAI pipeline.
   voice: "paul",
-  systemPrompt,
   // The opening scene here must agree with DEFAULT_GAME_STATE.currentRoom
   // (shared.ts) and the world map in system-prompt.md.
   greeting:
     "Welcome, adventurer. You are standing at the mouth of a weathered cave at the edge of a pine forest. A cold wind carries the smell of damp stone up from the darkness below. A rusted lantern hangs from an iron hook beside the entrance. What would you like to do?",
-
-  tools: {
-    game_state_drop: tool({
-      description: "Remove an item from the player's inventory.",
-      inputSchema: z.object({
-        value: z.string().describe("Item name to drop"),
-      }),
-      async execute(args, ctx) {
-        const g = gameSlot.get(ctx);
-        g.inventory = g.inventory.filter((i) => i !== args.value);
-        return { inventory: g.inventory };
-      },
-    }),
-
-    game_state_flag: tool({
-      description: "Set a game flag to true, used for tracking puzzle and event state.",
-      inputSchema: z.object({
-        value: z.string().describe("Flag name to set"),
-      }),
-      async execute(args, ctx) {
-        const g = gameSlot.get(ctx);
-        g.flags[args.value] = true;
-        return { flags: g.flags };
-      },
-    }),
-
-    game_state_get: tool({
-      description:
-        "Read the current game state including inventory, current room, score, moves, flags, and recent history.",
-      async execute(_args, ctx) {
-        const g = gameSlot.get(ctx);
-        return {
-          currentRoom: g.currentRoom,
-          inventory: g.inventory,
-          score: g.score,
-          moves: g.moves,
-          flags: g.flags,
-          recentHistory: g.history.slice(-5),
-        };
-      },
-    }),
-
-    game_state_history: tool({
-      description: "Log a player command to the history and increment the move counter.",
-      inputSchema: z.object({
-        value: z.string().describe("Command text to log"),
-      }),
-      async execute(args, ctx) {
-        const g = gameSlot.get(ctx);
-        recordCommand(g, args.value);
-        g.moves++;
-        return { moves: g.moves, recentHistory: g.history.slice(-5) };
-      },
-    }),
-
-    game_state_move: tool({
-      description: "Move the player to a new room and increment the move counter.",
-      inputSchema: z.object({
-        value: z.string().describe("Room name to move to"),
-      }),
-      async execute(args, ctx) {
-        const g = gameSlot.get(ctx);
-        g.currentRoom = args.value;
-        g.moves++;
-        return { currentRoom: g.currentRoom, moves: g.moves };
-      },
-    }),
-
-    game_state_restart: tool({
-      description:
-        "Reset the game to the beginning: empty inventory, zero score and moves, all flags cleared. Use when the player asks to restart, quit, or start a new game.",
-      async execute(_args, ctx) {
-        const g = gameSlot.reset(ctx);
-        return { restarted: true, currentRoom: g.currentRoom };
-      },
-    }),
-
-    game_state_score: tool({
-      description: "Add points to the player's score.",
-      inputSchema: z.object({
-        value: z.number().describe("Points to add"),
-      }),
-      async execute(args, ctx) {
-        const g = gameSlot.get(ctx);
-        g.score += args.value;
-        return { score: g.score };
-      },
-    }),
-
-    game_state_take: tool({
-      description: "Add an item to the player's inventory.",
-      inputSchema: z.object({
-        value: z.string().describe("Item name to take"),
-      }),
-      async execute(args, ctx) {
-        const g = gameSlot.get(ctx);
-        if (!g.inventory.includes(args.value)) g.inventory.push(args.value);
-        return { inventory: g.inventory };
-      },
-    }),
-  },
 });

package/dist/templates/infocom-adventure/client.tsx

@@ -1,6 +1,6 @@
 import "@alexkroman1/aai-ui/styles.css";
-import type { ChatMessage } from "@alexkroman1/aai-ui";
-import { AutoScroll, client, useSession } from "@alexkroman1/aai-ui";
+import type { AgentState, ChatMessage } from "@alexkroman1/aai-ui";
+import { AutoScroll, client, useSession, useUserTranscript } from "@alexkroman1/aai-ui";
 
 const CSS = `
 @keyframes ic-flicker {
@@ -52,8 +52,31 @@ const GREEN_DIM = "#00aa2a";
 const GREEN_DARK = "#003300";
 const CYAN = "#00ccff";
 
+// The cursor dot's colour per session state, as an EXHAUSTIVE map rather than an
+// if-chain with a grey default.
+//
+// The palette is this template's own — every client here paints the same six
+// states in its own colours, so the SDK has nothing to share but the union. What
+// the SDK does own is `AgentState`, and `satisfies Record<AgentState, string>`
+// is what borrows it: a state added there stops compiling here, where the
+// `state === "…"` chain this replaced answered a new state with a silent grey
+// badge in three separate files and no way to notice.
+const STATE_COLORS = {
+  disconnected: GREEN_DARK,
+  connecting: GREEN_DARK,
+  ready: GREEN_DARK,
+  listening: GREEN,
+  thinking: CYAN,
+  speaking: "#ffaa00",
+  error: GREEN_DARK,
+} satisfies Record<AgentState, string>;
+
 function InfocomAdventure() {
   const session = useSession();
+  // `speaking` and `text` in place of a `userTranscript !== null` check: `null`
+  // is silence and `""` is speech detected with no words back yet, and reading
+  // them as one falsy value hides the indicator at the start of every turn.
+  const { speaking, text: userTranscript } = useUserTranscript();
 
   const stateLabel =
     session.state === "listening"
@@ -70,14 +93,7 @@ function InfocomAdventure() {
 
   const msgCount = session.messages.filter((m: ChatMessage) => m.role === "user").length;
 
-  const dotColor =
-    session.state === "listening"
-      ? GREEN
-      : session.state === "speaking"
-        ? "#ffaa00"
-        : session.state === "thinking"
-          ? CYAN
-          : GREEN_DARK;
+  const dotColor = STATE_COLORS[session.state];
 
   if (!session.started) {
     return (
@@ -192,12 +208,12 @@ function InfocomAdventure() {
                 {msg.content}
               </div>
             ))}
-            {session.userTranscript !== null && (
+            {speaking && (
               <div
                 className="ic-transcript italic"
                 style={{ color: "#007a1e", textShadow: "0 0 5px rgba(0,255,65,0.15)" }}
               >
-                {session.userTranscript === "" ? "..." : session.userTranscript}
+                {userTranscript}
               </div>
             )}
           </AutoScroll>

package/dist/templates/infocom-adventure/shared.ts

@@ -1,4 +1,4 @@
-import { pushCapped, type SlotStateOf, sessionSlot } from "@alexkroman1/aai";
+import { pushCapped, sessionSlot } from "@alexkroman1/aai";
 
 export type GameState = {
   inventory: string[];
@@ -20,20 +20,37 @@ export const DEFAULT_GAME_STATE: GameState = {
 
 /**
  * How many player commands the game remembers. The history is append-only and
- * lives in `ctx.state` for the length of the call, so it needs a cap — and
- * only the last few are ever read (`game_state_get` reports five), so the
- * older ones are cost without a reader.
+ * rides in the slot's stored value for the length of the call, so it needs a
+ * cap — and only the last few are ever read (`game_state_get` reports five), so
+ * the older ones are cost without a reader.
  */
 export const MAX_HISTORY = 50;
 
-// The game lives in `ctx.state`, the agent's per-session mutable state — each
-// session is its own playthrough, so concurrent players never see each
-// other's game and a fresh session starts a fresh adventure. The clone is
-// load-bearing: `DEFAULT_GAME_STATE` is one module-level object shared by
-// every session in the process.
-export const gameSlot = sessionSlot("game", () => structuredClone(DEFAULT_GAME_STATE));
+/**
+ * How many of those commands a tool reports back to the model.
+ *
+ * Named because two tools answer with it (`game_state_get` and
+ * `game_state_history`), and they live in separate files now — an inline `-5`
+ * in each is a number that can disagree with itself.
+ */
+export const REPORTED_HISTORY = 5;
 
-export type StateSlot = SlotStateOf<typeof gameSlot>;
+// The game lives in one `sessionSlot`, keyed per session — each session is its
+// own playthrough, so concurrent players never see each other's game and a
+// fresh session starts a fresh adventure. The clone is load-bearing:
+// `DEFAULT_GAME_STATE` is one module-level object shared by every session in
+// the process.
+//
+// Every tool here is declared through the slot, and WHICH HALF is the decision
+// to get right: `gameSlot.tool` hands the body a deep-frozen value and
+// `gameSlot.updateTool` hands it a draft that is stored when the body returns.
+// `game_state_take` and `game_state_flag` were declared with the reading half
+// while pushing to `inventory` and writing to `flags` — a `TypeError` on the
+// first call and every call, once `freezeStorable` deep-froze what a read hands
+// out. It is a compile error now, which is the reason to declare a tool through
+// the slot at all rather than reaching for `gameSlot.get(ctx)` inside a
+// `tool()`.
+export const gameSlot = sessionSlot("game", () => structuredClone(DEFAULT_GAME_STATE));
 
 /** Log a player command, holding {@link MAX_HISTORY}. */
 export function recordCommand(game: GameState, command: string): void {

package/dist/templates/infocom-adventure/tools/game_state_drop.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import { gameSlot } from "../shared.ts";
+
+export default gameSlot.updateTool({
+  description: "Remove an item from the player's inventory.",
+  inputSchema: z.object({
+    value: z.string().describe("Item name to drop"),
+  }),
+  execute(args, game) {
+    game.inventory = game.inventory.filter((i) => i !== args.value);
+    return { inventory: game.inventory };
+  },
+});

package/dist/templates/infocom-adventure/tools/game_state_flag.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import { gameSlot } from "../shared.ts";
+
+export default gameSlot.updateTool({
+  description: "Set a game flag to true, used for tracking puzzle and event state.",
+  inputSchema: z.object({
+    value: z.string().describe("Flag name to set"),
+  }),
+  execute(args, game) {
+    game.flags[args.value] = true;
+    return { flags: game.flags };
+  },
+});

package/dist/templates/infocom-adventure/tools/game_state_get.ts

@@ -0,0 +1,16 @@
+import { gameSlot, REPORTED_HISTORY } from "../shared.ts";
+
+export default gameSlot.tool({
+  description:
+    "Read the current game state including inventory, current room, score, moves, flags, and recent history.",
+  execute(_args, game) {
+    return {
+      currentRoom: game.currentRoom,
+      inventory: game.inventory,
+      score: game.score,
+      moves: game.moves,
+      flags: game.flags,
+      recentHistory: game.history.slice(-REPORTED_HISTORY),
+    };
+  },
+});

package/dist/templates/infocom-adventure/tools/game_state_history.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+import { gameSlot, REPORTED_HISTORY, recordCommand } from "../shared.ts";
+
+export default gameSlot.updateTool({
+  description: "Log a player command to the history and increment the move counter.",
+  inputSchema: z.object({
+    value: z.string().describe("Command text to log"),
+  }),
+  execute(args, game) {
+    recordCommand(game, args.value);
+    game.moves++;
+    return { moves: game.moves, recentHistory: game.history.slice(-REPORTED_HISTORY) };
+  },
+});

package/dist/templates/infocom-adventure/tools/game_state_move.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+import { gameSlot } from "../shared.ts";
+
+export default gameSlot.updateTool({
+  description: "Move the player to a new room and increment the move counter.",
+  inputSchema: z.object({
+    value: z.string().describe("Room name to move to"),
+  }),
+  execute(args, game) {
+    game.currentRoom = args.value;
+    game.moves++;
+    return { currentRoom: game.currentRoom, moves: game.moves };
+  },
+});

package/dist/templates/infocom-adventure/tools/game_state_restart.ts

@@ -0,0 +1,13 @@
+import { gameSlot } from "../shared.ts";
+
+export default gameSlot.tool({
+  description:
+    "Reset the game to the beginning: empty inventory, zero score and moves, all flags cleared. Use when the player asks to restart, quit, or start a new game.",
+  // The one tool here that does NOT want the live value: it replaces it. The
+  // slot is still what defines the tool, so the state type comes from the same
+  // place as every sibling's rather than from an annotation on `ctx`.
+  execute(_args, _game, ctx) {
+    const fresh = gameSlot.reset(ctx);
+    return { restarted: true, currentRoom: fresh.currentRoom };
+  },
+});

package/dist/templates/infocom-adventure/tools/game_state_score.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import { gameSlot } from "../shared.ts";
+
+export default gameSlot.updateTool({
+  description: "Add points to the player's score.",
+  inputSchema: z.object({
+    value: z.number().describe("Points to add"),
+  }),
+  execute(args, game) {
+    game.score += args.value;
+    return { score: game.score };
+  },
+});

package/dist/templates/infocom-adventure/tools/game_state_take.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import { gameSlot } from "../shared.ts";
+
+export default gameSlot.updateTool({
+  description: "Add an item to the player's inventory.",
+  inputSchema: z.object({
+    value: z.string().describe("Item name to take"),
+  }),
+  execute(args, game) {
+    if (!game.inventory.includes(args.value)) game.inventory.push(args.value);
+    return { inventory: game.inventory };
+  },
+});