@alexkroman1/aai-cli 5.13.2 → 5.14.0

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

@@ -1,6 +1,6 @@
 import { agent, tool } from "@alexkroman1/aai";
 import { z } from "zod";
-import { getGameState, resetGameState } from "./shared.ts";
+import { gameSlot, recordCommand } from "./shared.ts";
 import systemPrompt from "./system-prompt.md?raw";
 
 export default agent({
@@ -21,7 +21,7 @@ export default agent({
         value: z.string().describe("Item name to drop"),
       }),
       async execute(args, ctx) {
-        const g = getGameState(ctx);
+        const g = gameSlot.get(ctx);
         g.inventory = g.inventory.filter((i) => i !== args.value);
         return { inventory: g.inventory };
       },
@@ -33,7 +33,7 @@ export default agent({
         value: z.string().describe("Flag name to set"),
       }),
       async execute(args, ctx) {
-        const g = getGameState(ctx);
+        const g = gameSlot.get(ctx);
         g.flags[args.value] = true;
         return { flags: g.flags };
       },
@@ -43,7 +43,7 @@ export default agent({
       description:
         "Read the current game state including inventory, current room, score, moves, flags, and recent history.",
       async execute(_args, ctx) {
-        const g = getGameState(ctx);
+        const g = gameSlot.get(ctx);
         return {
           currentRoom: g.currentRoom,
           inventory: g.inventory,
@@ -61,8 +61,8 @@ export default agent({
         value: z.string().describe("Command text to log"),
       }),
       async execute(args, ctx) {
-        const g = getGameState(ctx);
-        g.history.push(args.value);
+        const g = gameSlot.get(ctx);
+        recordCommand(g, args.value);
         g.moves++;
         return { moves: g.moves, recentHistory: g.history.slice(-5) };
       },
@@ -74,7 +74,7 @@ export default agent({
         value: z.string().describe("Room name to move to"),
       }),
       async execute(args, ctx) {
-        const g = getGameState(ctx);
+        const g = gameSlot.get(ctx);
         g.currentRoom = args.value;
         g.moves++;
         return { currentRoom: g.currentRoom, moves: g.moves };
@@ -85,7 +85,7 @@ export default agent({
       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 = resetGameState(ctx);
+        const g = gameSlot.reset(ctx);
         return { restarted: true, currentRoom: g.currentRoom };
       },
     }),
@@ -96,7 +96,7 @@ export default agent({
         value: z.number().describe("Points to add"),
       }),
       async execute(args, ctx) {
-        const g = getGameState(ctx);
+        const g = gameSlot.get(ctx);
         g.score += args.value;
         return { score: g.score };
       },
@@ -108,7 +108,7 @@ export default agent({
         value: z.string().describe("Item name to take"),
       }),
       async execute(args, ctx) {
-        const g = getGameState(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,7 +1,6 @@
 import "@alexkroman1/aai-ui/styles.css";
 import type { ChatMessage } from "@alexkroman1/aai-ui";
-import { client, useSession } from "@alexkroman1/aai-ui";
-import { useEffect, useRef } from "react";
+import { AutoScroll, client, useSession } from "@alexkroman1/aai-ui";
 
 const CSS = `
 @keyframes ic-flicker {
@@ -55,17 +54,6 @@ const CYAN = "#00ccff";
 
 function InfocomAdventure() {
   const session = useSession();
-  const bottom = useRef<HTMLDivElement>(null);
-
-  // Bumps whenever a message lands or the live transcript changes, so the
-  // view follows the conversation instead of scrolling once on mount.
-  const contentVersion = session.messages.length + (session.userTranscript?.length ?? 0);
-  useEffect(() => {
-    // Never true — contentVersion only drives the dependency array, and this
-    // reference keeps the exhaustive-deps lint satisfied.
-    if (contentVersion < 0) return;
-    bottom.current?.scrollIntoView({ behavior: "smooth" });
-  }, [contentVersion]);
 
   const stateLabel =
     session.state === "listening"
@@ -184,8 +172,9 @@ function InfocomAdventure() {
           )}
 
           {/* Messages */}
-          <div
-            className="ic-messages flex-1 overflow-y-auto p-5"
+          <AutoScroll
+            scrollClassName="ic-messages overflow-y-auto"
+            contentClassName="p-5"
             style={{ scrollbarWidth: "thin", scrollbarColor: `${GREEN} #001a00` }}
           >
             {session.messages.map((msg: ChatMessage, i: number) => (
@@ -211,8 +200,7 @@ function InfocomAdventure() {
                 {session.userTranscript === "" ? "..." : session.userTranscript}
               </div>
             )}
-            <div ref={bottom} />
-          </div>
+          </AutoScroll>
 
           {/* Footer controls */}
           <div

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

@@ -1,4 +1,4 @@
-import type { ToolContext } from "@alexkroman1/aai";
+import { pushCapped, type SlotStateOf, sessionSlot } from "@alexkroman1/aai";
 
 export type GameState = {
   inventory: string[];
@@ -18,21 +18,24 @@ export const DEFAULT_GAME_STATE: GameState = {
   history: [],
 };
 
+/**
+ * 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.
+ */
+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.
-type StateSlot = { game?: GameState };
+// 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));
 
-/** The session's live game. Mutations to the returned object stick — it is
- *  the object stored in `ctx.state`. */
-export function getGameState(ctx: ToolContext): GameState {
-  const slot = ctx.state as StateSlot;
-  slot.game ??= structuredClone(DEFAULT_GAME_STATE);
-  return slot.game;
-}
+export type StateSlot = SlotStateOf<typeof gameSlot>;
 
-export function resetGameState(ctx: ToolContext): GameState {
-  const slot = ctx.state as StateSlot;
-  slot.game = structuredClone(DEFAULT_GAME_STATE);
-  return slot.game;
+/** Log a player command, holding {@link MAX_HISTORY}. */
+export function recordCommand(game: GameState, command: string): void {
+  pushCapped(game.history, command, MAX_HISTORY);
 }

package/dist/templates/pizza-ordering/agent.test.ts

@@ -1,34 +1,25 @@
-import type { Db, ToolContext, ToolDef } from "@alexkroman1/aai";
+import type { ToolContext, ToolDef } from "@alexkroman1/aai";
+import { createToolContext } from "@alexkroman1/aai/testing";
 import { describe, expect, test } from "vitest";
 import agentDef from "./agent.ts";
-import { calculateTotal, orderView, type Pizza, pizzaPrice, type StateSlot } from "./shared.ts";
+import {
+  calculateTotal,
+  orderSlot,
+  orderView,
+  type Pizza,
+  pizzaPrice,
+  type StateSlot,
+} from "./shared.ts";
 
 // ─── Test doubles ────────────────────────────────────────────────────────────
 
-/** This template keeps its cart in ctx.state — the db must never be touched. */
-const noDb: Db = {
-  query: () => Promise.reject(new Error("db not used by this template")),
-};
-
-/** ToolContext stub: per-session ctx.state, and captured ctx.send events.
- *  Each stub is one session — the cart is session-scoped by construction. */
-function makeCtx(sessionId = "session-a") {
-  const sent: Array<{ event: string; data: unknown }> = [];
-  const ctx: ToolContext = {
-    env: {},
-    state: {},
-    db: noDb,
-    generate: () => Promise.reject(new Error("generate not available in tests")),
-    messages: [],
-    sessionId,
-    // Never aborts — a test has no turn to cancel. `ctx.signal` is always
-    // present at runtime, so a stub supplies one rather than omitting it.
-    signal: new AbortController().signal,
-    send: (event, data) => {
-      sent.push({ event, data });
-    },
-  };
-  return { ctx, sent };
+/** Each context is one session — the cart is session-scoped by construction,
+ *  and `createToolContext` mints a distinct session id per call. Its default
+ *  `db` rejects every query, which is right here: this template keeps its cart
+ *  in ctx.state and must never touch storage. */
+function makeCtx(sessionId?: string) {
+  const ctx = createToolContext<StateSlot>(sessionId ? { sessionId } : {});
+  return { ctx, sent: ctx.sent };
 }
 
 function getTool(name: string): ToolDef {
@@ -204,7 +195,7 @@ describe("orderView projection", () => {
       ctx,
     );
 
-    const view = orderView(ctx.state as StateSlot);
+    const view = orderView(orderSlot.read(ctx.state));
     expect(view.orderPlaced).toBe(false);
     const item = view.pizzas[0];
     if (!item) throw new Error("no pizza in the projection");
@@ -226,15 +217,20 @@ describe("orderView projection", () => {
     await run("add_pizza", { size: "small", crust: "thin", toppings: [], quantity: 1 }, ctx);
     await run("place_order", {}, ctx);
 
-    const view = orderView(ctx.state as StateSlot);
+    const view = orderView(orderSlot.read(ctx.state));
     expect(view.orderPlaced).toBe(true);
     expect(view.pizzas).toEqual([]);
     expect(view.estimatedMinutes).toBe(20);
     expect(view.total).toMatch(/^\$\d+\.\d{2}$/);
   });
 
-  test("an untouched session projects an empty cart, not undefined", async () => {
-    // The client renders before any tool has run; `state.order` is absent.
-    expect(orderView({})).toMatchObject({ pizzas: [], total: "$0.00", orderPlaced: false });
+  test("an untouched session projects an empty cart, not undefined", () => {
+    // The client renders before any tool has run, so `state.order` is absent —
+    // this is exactly the value `client.tsx` hoists as its fallback.
+    expect(orderSlot.projection(orderView)(undefined)).toMatchObject({
+      pizzas: [],
+      total: "$0.00",
+      orderPlaced: false,
+    });
   });
 });

package/dist/templates/pizza-ordering/agent.ts

@@ -4,8 +4,8 @@ import {
   CRUSTS,
   calculateTotal,
   formatPrice,
-  getOrder,
   menuText,
+  orderSlot,
   orderView,
   type Pizza,
   resetOrder,
@@ -24,7 +24,7 @@ export default agent({
   // The cart, pushed to the client after every tool call. Replaces a
   // `ctx.send("order", ...)` in each of the five order tools, and the
   // event-diffing the client had to do to rebuild the cart from them.
-  syncState: orderView,
+  syncState: orderSlot.projection(orderView),
   // The menu section is generated from MENU so the prompt can never quote a
   // price the pricing code doesn't charge.
   systemPrompt: `${systemPrompt}\n${menuText()}`,
@@ -43,7 +43,7 @@ export default agent({
         quantity: z.number().int().min(1).default(1),
       }),
       async execute(args, ctx) {
-        const order = getOrder(ctx);
+        const order = orderSlot.get(ctx);
 
         const pizza: Pizza = {
           id: order.nextId,
@@ -67,7 +67,7 @@ export default agent({
       description:
         "Place the final order. Use when the customer confirms they are done and ready to order.",
       async execute(_args, ctx) {
-        const order = getOrder(ctx);
+        const order = orderSlot.get(ctx);
         const pizzas = order.pizzas;
         if (pizzas.length === 0) return { error: "Cannot place an empty order." };
 
@@ -96,7 +96,7 @@ export default agent({
         pizza_id: z.number().describe("The pizza ID to remove"),
       }),
       async execute(args, ctx) {
-        const order = getOrder(ctx);
+        const order = orderSlot.get(ctx);
         const idx = order.pizzas.findIndex((p) => p.id === args.pizza_id);
         if (idx === -1) return { error: "Pizza not found in the order." };
 
@@ -116,7 +116,7 @@ export default agent({
         name: z.string(),
       }),
       async execute(args, ctx) {
-        getOrder(ctx).customerName = args.name;
+        orderSlot.get(ctx).customerName = args.name;
         return { name: args.name };
       },
     }),
@@ -131,7 +131,7 @@ export default agent({
         quantity: z.number().int().min(1).optional(),
       }),
       async execute(args, ctx) {
-        const order = getOrder(ctx);
+        const order = orderSlot.get(ctx);
         const idx = order.pizzas.findIndex((p) => p.id === args.pizza_id);
         if (idx === -1) return { error: "Pizza not found in the order." };
 
@@ -153,7 +153,7 @@ export default agent({
     view_order: tool({
       description: "View the current order summary with all pizzas and total price.",
       async execute(_args, ctx) {
-        const pizzas = getOrder(ctx).pizzas;
+        const pizzas = orderSlot.get(ctx).pizzas;
         if (pizzas.length === 0) return { message: "The order is empty." };
 
         return {

package/dist/templates/pizza-ordering/client.tsx

@@ -1,11 +1,11 @@
 import "@alexkroman1/aai-ui/styles.css";
 import { client, useAgentState, useTheme } from "@alexkroman1/aai-ui";
 import type { OrderView } from "./shared.ts";
-import { formatPrice, orderView, pizzaPrice } from "./shared.ts";
+import { formatPrice, orderSlot, orderView, pizzaPrice } from "./shared.ts";
 
 // Derived from the projection so a new OrderView field can't silently miss
-// the pre-first-tool-call render.
-const EMPTY_ORDER = orderView({});
+// the pre-first-tool-call render — `projection` runs it over an empty cart.
+const EMPTY_ORDER: OrderView = orderSlot.projection(orderView)(undefined);
 
 function PizzaIcon({ size }: { size: string }) {
   const dim = size === "small" ? 36 : size === "large" ? 52 : 44;
@@ -30,7 +30,7 @@ function OrderSidebar() {
   // tool call. This replaced ~45 lines that rebuilt the cart by diffing
   // added/removed/updated events — where one missed event desynced the view
   // for the rest of the session.
-  const order = useAgentState<OrderView>() ?? EMPTY_ORDER;
+  const order = useAgentState<OrderView>(EMPTY_ORDER);
 
   if (order.orderPlaced) {
     return (

package/dist/templates/pizza-ordering/shared.ts

@@ -1,4 +1,4 @@
-import type { ToolContext } from "@alexkroman1/aai";
+import { type SlotStateOf, sessionSlot, type ToolContext } from "@alexkroman1/aai";
 
 export const SIZES = ["small", "medium", "large"] as const;
 export const CRUSTS = ["thin", "regular", "thick", "stuffed"] as const;
@@ -89,19 +89,14 @@ export interface OrderState {
   placed?: { orderNumber: number; total: string; estimatedMinutes: number };
 }
 
-export type StateSlot = { order?: OrderState };
-
-function emptyOrder(): OrderState {
+export function emptyOrder(): OrderState {
   return { pizzas: [], nextId: 1, customerName: null };
 }
 
-/** The session's live cart. Mutations to the returned object stick — it is
- *  the object stored in `ctx.state`. */
-export function getOrder(ctx: ToolContext): OrderState {
-  const slot = ctx.state as StateSlot;
-  slot.order ??= emptyOrder();
-  return slot.order;
-}
+/** The session's cart, as one typed slot inside `ctx.state`. */
+export const orderSlot = sessionSlot("order", emptyOrder);
+
+export type StateSlot = SlotStateOf<typeof orderSlot>;
 
 /**
  * Clear the cart after checkout so a follow-up order starts fresh. The
@@ -110,12 +105,11 @@ export function getOrder(ctx: ToolContext): OrderState {
  * order that was just submitted.
  */
 export function resetOrder(ctx: ToolContext, placed?: OrderState["placed"]): void {
-  const slot = ctx.state as StateSlot;
-  slot.order = { ...emptyOrder(), ...(placed ? { placed } : {}) };
+  orderSlot.set(ctx, { ...emptyOrder(), ...(placed ? { placed } : {}) });
 }
 
 /**
- * What the browser sees. A projection rather than the raw slot: the client
+ * What the browser sees. A projection rather than the raw state: the client
  * needs the cart and its total, and `syncState` is where you decide what
  * leaves the server.
  */
@@ -127,13 +121,13 @@ export interface OrderView {
   estimatedMinutes?: number;
 }
 
-export function orderView(state: StateSlot): OrderView {
-  const order = state.order;
-  const pizzas = order?.pizzas ?? [];
-  const placed = order?.placed;
+/** Takes the cart itself, not the slot — `orderSlot.projection` supplies a real
+ *  one even before the first tool call, so there is nothing to optional-chain. */
+export function orderView(order: OrderState): OrderView {
+  const placed = order.placed;
   return {
-    pizzas,
-    total: placed?.total ?? formatPrice(calculateTotal(pizzas)),
+    pizzas: order.pizzas,
+    total: placed?.total ?? formatPrice(calculateTotal(order.pizzas)),
     orderPlaced: Boolean(placed),
     ...(placed
       ? { orderNumber: placed.orderNumber, estimatedMinutes: placed.estimatedMinutes }