@alexkroman1/aai-cli 5.14.0 → 6.1.0

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

@@ -1,36 +1,37 @@
-import type { ToolContext, ToolDef } from "@alexkroman1/aai";
-import { createToolContext } from "@alexkroman1/aai/testing";
+/// <reference types="vite/client" />
+
+import type { ToolContext } from "@alexkroman1/aai";
+import { createToolContext, runTool, toolOf, withDiscoveredTools } from "@alexkroman1/aai/testing";
 import { describe, expect, test } from "vitest";
-import agentDef from "./agent.ts";
-import {
-  calculateTotal,
-  orderSlot,
-  orderView,
-  type Pizza,
-  pizzaPrice,
-  type StateSlot,
-} from "./shared.ts";
+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 { calculateTotal, orderSlot, orderView, type Pizza, pizzaPrice } from "./shared.ts";
 
 // ─── Test doubles ────────────────────────────────────────────────────────────
 
-/** 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 {
-  const def = agentDef.tools[name];
-  if (!def) throw new Error(`tool ${name} not defined on agent`);
-  return def;
-}
-
-async function run(name: string, args: Record<string, unknown>, ctx: ToolContext) {
-  return await getTool(name).execute(args, ctx);
-}
+/** Each context owns its OWN slot store, so two contexts are two carts. Its
+ *  default `db` rejects every query, which is right here: this template keeps
+ *  its cart in a session slot and must never touch storage. */
+const makeCtx = (): ToolContext => createToolContext();
+
+/** A tool by the name the model calls it by, bound to this agent. The lookup
+ *  and its "no such tool" message are `runTool`'s (`@alexkroman1/aai/testing`);
+ *  what is local is only which agent they run against. */
+const run = (name: string, args: Record<string, unknown>, ctx: ToolContext) =>
+  runTool(agentDef, name, args, ctx);
 
 const margherita: Omit<Pizza, "id"> = {
   size: "medium",
@@ -71,7 +72,7 @@ describe("pricing (shared.ts)", () => {
   });
 
   test("add_pizza schema defaults quantity to 1 and rejects non-positive quantities", async () => {
-    const schema = getTool("add_pizza").inputSchema;
+    const schema = toolOf(agentDef, "add_pizza").inputSchema;
     if (!schema) throw new Error("add_pizza has no input schema");
     // Validate through the Standard Schema contract — the vendor-neutral
     // interface every inputSchema carries.
@@ -90,7 +91,7 @@ describe("pricing (shared.ts)", () => {
 
 describe("tool flow (add → update → remove → place_order)", () => {
   test("full ordering round-trip keeps state, totals, and IDs consistent", async () => {
-    const { ctx } = makeCtx();
+    const ctx = makeCtx();
 
     // Empty order guards
     expect(await run("view_order", {}, ctx)).toEqual({ message: "The order is empty." });
@@ -151,31 +152,35 @@ describe("tool flow (add → update → remove → place_order)", () => {
     expect(await run("place_order", {}, ctx)).toEqual({ error: "Cannot place an empty order." });
   });
 
-  test("carts are scoped per session — two sessions never share pizzas or names", async () => {
-    // ctx.state is per-session by construction — each session has its own.
-    const { ctx: sessionA } = makeCtx("session-a");
-    const { ctx: sessionB } = makeCtx("session-b");
+  test("two independent contexts never share pizzas or names", async () => {
+    // What this really checks, and it is worth checking: the cart lives in the
+    // SLOT and not in a module-level variable. `createToolContext()` hands each
+    // call its own detached slot store, so passing two distinct session ids
+    // would prove nothing extra — the isolation is per store, and the store is
+    // per context. A template that cached its order in a module would fail here.
+    const firstCall = makeCtx();
+    const secondCall = makeCtx();
 
     await run(
       "add_pizza",
       { size: "large", crust: "thin", toppings: ["bacon"], quantity: 1 },
-      sessionA,
+      firstCall,
     );
-    await run("set_customer_name", { name: "Alice" }, sessionA);
+    await run("set_customer_name", { name: "Alice" }, firstCall);
 
-    expect(await run("view_order", {}, sessionB)).toEqual({ message: "The order is empty." });
+    expect(await run("view_order", {}, secondCall)).toEqual({ message: "The order is empty." });
 
-    await run("add_pizza", { size: "small", crust: "thin", toppings: [], quantity: 1 }, sessionB);
-    const placedB = (await run("place_order", {}, sessionB)) as {
+    await run("add_pizza", { size: "small", crust: "thin", toppings: [], quantity: 1 }, secondCall);
+    const placedB = (await run("place_order", {}, secondCall)) as {
       customerName: string;
       pizzas: number;
     };
-    // Session B never sees session A's customer name or pizzas.
+    // The second context never sees the first's customer name or pizzas.
     expect(placedB.customerName).toBe("Guest");
     expect(placedB.pizzas).toBe(1);
 
-    // Session A's cart survives session B's checkout untouched.
-    const viewA = (await run("view_order", {}, sessionA)) as { pizzas: unknown[] };
+    // And the first context's cart survives the second's checkout untouched.
+    const viewA = (await run("view_order", {}, firstCall)) as { pizzas: unknown[] };
     expect(viewA.pizzas).toHaveLength(1);
   });
 });
@@ -188,14 +193,14 @@ describe("tool flow (add → update → remove → place_order)", () => {
 
 describe("orderView projection", () => {
   test("reflects the live cart", async () => {
-    const { ctx } = makeCtx();
+    const ctx = makeCtx();
     await run(
       "add_pizza",
       { size: "large", crust: "stuffed", toppings: ["pepperoni", "extra_cheese"], quantity: 2 },
       ctx,
     );
 
-    const view = orderView(orderSlot.read(ctx.state));
+    const view = orderView(orderSlot.get(ctx));
     expect(view.orderPlaced).toBe(false);
     const item = view.pizzas[0];
     if (!item) throw new Error("no pizza in the projection");
@@ -213,11 +218,11 @@ describe("orderView projection", () => {
   test("survives checkout, which clears the cart but keeps the confirmation", async () => {
     // The reason `placed` lives in state at all: the cart is emptied on
     // checkout, and the UI still has to show the order that was just placed.
-    const { ctx } = makeCtx();
+    const ctx = makeCtx();
     await run("add_pizza", { size: "small", crust: "thin", toppings: [], quantity: 1 }, ctx);
     await run("place_order", {}, ctx);
 
-    const view = orderView(orderSlot.read(ctx.state));
+    const view = orderView(orderSlot.get(ctx));
     expect(view.orderPlaced).toBe(true);
     expect(view.pizzas).toEqual([]);
     expect(view.estimatedMinutes).toBe(20);

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

@@ -1,26 +1,17 @@
-import { agent, tool } from "@alexkroman1/aai";
-import { z } from "zod";
-import {
-  CRUSTS,
-  calculateTotal,
-  formatPrice,
-  menuText,
-  orderSlot,
-  orderView,
-  type Pizza,
-  resetOrder,
-  SIZES,
-} from "./shared.ts";
+import { agent } from "@alexkroman1/aai";
+import { menuText, orderSlot, orderView } from "./shared.ts";
 import systemPrompt from "./system-prompt.md?raw";
 
-const sizes = z.enum(SIZES);
-const crusts = z.enum(CRUSTS);
-
-// The in-progress order lives in `ctx.state` (see shared.ts) — per-session by
-// construction, so concurrent customers each get their own cart.
+// The in-progress order lives in one `sessionSlot` (see shared.ts) —
+// per-session by construction, so concurrent customers each get their own cart.
+// The six tools that read and write it are the six files in `tools/`: a file
+// there IS a tool, named by its own filename, so nothing registers them here.
 
 export default agent({
   name: "Pizza Palace",
+  // `orderSlot.state` IS the `() => ({ [slot.key]: slot.create() })` factory,
+  // so the session's cart exists before the first tool call — which is what a
+  // resumed connection needs to have something to project.
   // 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.
@@ -30,144 +21,4 @@ export default agent({
   systemPrompt: `${systemPrompt}\n${menuText()}`,
   greeting:
     "Welcome to Pizza Palace. I can help you build your perfect pizza. What would you like to order?",
-
-  tools: {
-    add_pizza: tool({
-      description: "Add a pizza to the order. Use when the customer has decided on a pizza.",
-      inputSchema: z.object({
-        size: sizes,
-        crust: crusts,
-        toppings: z
-          .array(z.string())
-          .describe("List of topping names, e.g. ['pepperoni', 'mushrooms']"),
-        quantity: z.number().int().min(1).default(1),
-      }),
-      async execute(args, ctx) {
-        const order = orderSlot.get(ctx);
-
-        const pizza: Pizza = {
-          id: order.nextId,
-          size: args.size,
-          crust: args.crust,
-          toppings: args.toppings,
-          quantity: args.quantity,
-        };
-        order.pizzas.push(pizza);
-        order.nextId++;
-
-        return {
-          added: pizza,
-          orderTotal: formatPrice(calculateTotal(order.pizzas)),
-          itemCount: order.pizzas.length,
-        };
-      },
-    }),
-
-    place_order: tool({
-      description:
-        "Place the final order. Use when the customer confirms they are done and ready to order.",
-      async execute(_args, ctx) {
-        const order = orderSlot.get(ctx);
-        const pizzas = order.pizzas;
-        if (pizzas.length === 0) return { error: "Cannot place an empty order." };
-
-        const customerName = order.customerName ?? "Guest";
-        const total = formatPrice(calculateTotal(pizzas));
-        const orderNumber = Math.floor(1000 + Math.random() * 9000);
-
-        const estimatedMinutes = 15 + pizzas.length * 5;
-        // The order is submitted — clear the cart so a follow-up order starts
-        // fresh, but keep the confirmation in state so the UI can show it.
-        resetOrder(ctx, { orderNumber, total, estimatedMinutes });
-
-        return {
-          orderNumber,
-          customerName,
-          pizzas: pizzas.length,
-          total,
-          estimatedMinutes,
-        };
-      },
-    }),
-
-    remove_pizza: tool({
-      description: "Remove a pizza from the order by its ID.",
-      inputSchema: z.object({
-        pizza_id: z.number().describe("The pizza ID to remove"),
-      }),
-      async execute(args, 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." };
-
-        const [removed] = order.pizzas.splice(idx, 1);
-
-        return {
-          removed,
-          orderTotal: formatPrice(calculateTotal(order.pizzas)),
-          itemCount: order.pizzas.length,
-        };
-      },
-    }),
-
-    set_customer_name: tool({
-      description: "Set the customer name for the order.",
-      inputSchema: z.object({
-        name: z.string(),
-      }),
-      async execute(args, ctx) {
-        orderSlot.get(ctx).customerName = args.name;
-        return { name: args.name };
-      },
-    }),
-
-    update_pizza: tool({
-      description: "Update an existing pizza in the order. Only provided fields are changed.",
-      inputSchema: z.object({
-        pizza_id: z.number(),
-        size: sizes.optional(),
-        crust: crusts.optional(),
-        toppings: z.array(z.string()).optional(),
-        quantity: z.number().int().min(1).optional(),
-      }),
-      async execute(args, 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." };
-
-        const pizza: Pizza = { ...order.pizzas[idx]! };
-        if (args.size !== undefined) pizza.size = args.size;
-        if (args.crust !== undefined) pizza.crust = args.crust;
-        if (args.toppings !== undefined) pizza.toppings = args.toppings;
-        if (args.quantity !== undefined) pizza.quantity = args.quantity;
-
-        order.pizzas[idx] = pizza;
-
-        return {
-          updated: pizza,
-          orderTotal: formatPrice(calculateTotal(order.pizzas)),
-        };
-      },
-    }),
-
-    view_order: tool({
-      description: "View the current order summary with all pizzas and total price.",
-      async execute(_args, ctx) {
-        const pizzas = orderSlot.get(ctx).pizzas;
-        if (pizzas.length === 0) return { message: "The order is empty." };
-
-        return {
-          pizzas: pizzas.map((p) => ({
-            id: p.id,
-            description: `${p.quantity}x ${p.size} ${p.crust} crust with ${p.toppings.length > 0 ? p.toppings.join(", ") : "cheese only"}`,
-            size: p.size,
-            crust: p.crust,
-            toppings: p.toppings,
-            quantity: p.quantity,
-          })),
-          orderTotal: formatPrice(calculateTotal(pizzas)),
-        };
-      },
-    }),
-  },
 });

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

@@ -1,4 +1,4 @@
-import { type SlotStateOf, sessionSlot, type ToolContext } from "@alexkroman1/aai";
+import { type DeepReadonly, sessionSlot } from "@alexkroman1/aai";
 
 export const SIZES = ["small", "medium", "large"] as const;
 export const CRUSTS = ["thin", "regular", "thick", "stuffed"] as const;
@@ -33,7 +33,7 @@ export const MENU = {
   },
 } as const;
 
-export function calculateTotal(pizzas: Pizza[]): number {
+export function calculateTotal(pizzas: readonly ReadonlyPizza[]): number {
   return pizzas.reduce((total, pizza) => total + pizzaPrice(pizza), 0);
 }
 
@@ -62,7 +62,7 @@ export function menuText(): string {
   ].join("\n");
 }
 
-export function pizzaPrice(p: Pizza): number {
+export function pizzaPrice(p: ReadonlyPizza): number {
   const base = MENU.sizes[p.size];
   const crust = MENU.crusts[p.crust];
   const toppings = p.toppings.reduce(
@@ -73,9 +73,9 @@ export function pizzaPrice(p: Pizza): number {
 }
 
 // ── Order state ──────────────────────────────────────────────────────────────
-// The in-progress order is session-scoped scratch, so it lives in `ctx.state`
-// (the agent's per-session mutable state) — concurrent customers each get
-// their own cart, and an abandoned cart vanishes with its session.
+// The in-progress order is session-scoped scratch, so it lives in one
+// `sessionSlot` keyed per session — concurrent customers each get their own
+// cart.
 
 export interface OrderState {
   pizzas: Pizza[];
@@ -93,19 +93,40 @@ export function emptyOrder(): OrderState {
   return { pizzas: [], nextId: 1, customerName: null };
 }
 
-/** The session's cart, as one typed slot inside `ctx.state`. */
+/** The session's cart, as one typed slot. */
 export const orderSlot = sessionSlot("order", emptyOrder);
 
-export type StateSlot = SlotStateOf<typeof orderSlot>;
+/**
+ * A pizza as a READ hands it out, and the cart likewise: deep-frozen, and typed
+ * to say so.
+ *
+ * `pizzaPrice` and `calculateTotal` take the readonly shape because they are
+ * pure and are called from both halves of the slot — a mutable `Pizza` still
+ * satisfies it, so an `updateTool` draft passes unchanged, while a helper that
+ * WOULD have mutated stops compiling instead of throwing on its first call.
+ */
+export type ReadonlyPizza = DeepReadonly<Pizza>;
+export type FrozenOrderState = DeepReadonly<OrderState>;
 
 /**
  * Clear the cart after checkout so a follow-up order starts fresh. The
  * `placed` confirmation is passed through, because the UI is still showing
  * it — clearing the pizzas is what "reset" means here, not forgetting the
  * order that was just submitted.
+ *
+ * It takes the DRAFT, not the context, and that is the shape to copy. It used to
+ * call `orderSlot.set(ctx, …)` — which is a second write to the same slot from
+ * inside a mutating tool body, so the draft stored on the way out overwrote it
+ * and the cart was never cleared. `slot.set` refuses that outright now; a helper
+ * called from inside a mutation mutates what it was handed.
  */
-export function resetOrder(ctx: ToolContext, placed?: OrderState["placed"]): void {
-  orderSlot.set(ctx, { ...emptyOrder(), ...(placed ? { placed } : {}) });
+export function resetOrder(order: OrderState, placed?: OrderState["placed"]): void {
+  const fresh = emptyOrder();
+  order.pizzas = fresh.pizzas;
+  order.nextId = fresh.nextId;
+  order.customerName = fresh.customerName;
+  if (placed) order.placed = placed;
+  else delete order.placed;
 }
 
 /**
@@ -114,7 +135,9 @@ export function resetOrder(ctx: ToolContext, placed?: OrderState["placed"]): voi
  * leaves the server.
  */
 export interface OrderView {
-  pizzas: Pizza[];
+  /** Readonly, because the projection hands the client the slot's own list
+   *  rather than a copy — see {@link ReadonlyPizza}. */
+  pizzas: readonly ReadonlyPizza[];
   total: string;
   orderPlaced: boolean;
   orderNumber?: number;
@@ -123,7 +146,7 @@ export interface OrderView {
 
 /** 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 {
+export function orderView(order: FrozenOrderState): OrderView {
   const placed = order.placed;
   return {
     pizzas: order.pizzas,

package/dist/templates/pizza-ordering/tools/add_pizza.ts

@@ -0,0 +1,31 @@
+import { z } from "zod";
+import { CRUSTS, calculateTotal, formatPrice, orderSlot, type Pizza, SIZES } from "../shared.ts";
+
+export default orderSlot.updateTool({
+  description: "Add a pizza to the order. Use when the customer has decided on a pizza.",
+  inputSchema: z.object({
+    size: z.enum(SIZES),
+    crust: z.enum(CRUSTS),
+    toppings: z
+      .array(z.string())
+      .describe("List of topping names, e.g. ['pepperoni', 'mushrooms']"),
+    quantity: z.number().int().min(1).default(1),
+  }),
+  execute(args, order) {
+    const pizza: Pizza = {
+      id: order.nextId,
+      size: args.size,
+      crust: args.crust,
+      toppings: args.toppings,
+      quantity: args.quantity,
+    };
+    order.pizzas.push(pizza);
+    order.nextId++;
+
+    return {
+      added: pizza,
+      orderTotal: formatPrice(calculateTotal(order.pizzas)),
+      itemCount: order.pizzas.length,
+    };
+  },
+});

package/dist/templates/pizza-ordering/tools/place_order.ts

@@ -0,0 +1,22 @@
+import { toolFailure } from "@alexkroman1/aai";
+import { calculateTotal, formatPrice, orderSlot, resetOrder } from "../shared.ts";
+
+export default orderSlot.updateTool({
+  description:
+    "Place the final order. Use when the customer confirms they are done and ready to order.",
+  execute(_args, order) {
+    const pizzas = order.pizzas;
+    if (pizzas.length === 0) return toolFailure("Cannot place an empty order.");
+
+    const customerName = order.customerName ?? "Guest";
+    const total = formatPrice(calculateTotal(pizzas));
+    const orderNumber = Math.floor(1000 + Math.random() * 9000);
+
+    const estimatedMinutes = 15 + pizzas.length * 5;
+    // The order is submitted — clear the cart so a follow-up order starts
+    // fresh, but keep the confirmation in state so the UI can show it.
+    resetOrder(order, { orderNumber, total, estimatedMinutes });
+
+    return { orderNumber, customerName, pizzas: pizzas.length, total, estimatedMinutes };
+  },
+});

package/dist/templates/pizza-ordering/tools/remove_pizza.ts

@@ -0,0 +1,22 @@
+import { toolFailure } from "@alexkroman1/aai";
+import { z } from "zod";
+import { calculateTotal, formatPrice, orderSlot } from "../shared.ts";
+
+export default orderSlot.updateTool({
+  description: "Remove a pizza from the order by its ID.",
+  inputSchema: z.object({
+    pizza_id: z.number().describe("The pizza ID to remove"),
+  }),
+  execute(args, order) {
+    const idx = order.pizzas.findIndex((p) => p.id === args.pizza_id);
+    if (idx === -1) return toolFailure("Pizza not found in the order.");
+
+    const [removed] = order.pizzas.splice(idx, 1);
+
+    return {
+      removed,
+      orderTotal: formatPrice(calculateTotal(order.pizzas)),
+      itemCount: order.pizzas.length,
+    };
+  },
+});

package/dist/templates/pizza-ordering/tools/set_customer_name.ts

@@ -0,0 +1,13 @@
+import { z } from "zod";
+import { orderSlot } from "../shared.ts";
+
+export default orderSlot.updateTool({
+  description: "Set the customer name for the order.",
+  inputSchema: z.object({
+    name: z.string(),
+  }),
+  execute(args, order) {
+    order.customerName = args.name;
+    return { name: args.name };
+  },
+});

package/dist/templates/pizza-ordering/tools/update_pizza.ts

@@ -0,0 +1,28 @@
+import { toolFailure } from "@alexkroman1/aai";
+import { z } from "zod";
+import { CRUSTS, calculateTotal, formatPrice, orderSlot, type Pizza, SIZES } from "../shared.ts";
+
+export default orderSlot.updateTool({
+  description: "Update an existing pizza in the order. Only provided fields are changed.",
+  inputSchema: z.object({
+    pizza_id: z.number(),
+    size: z.enum(SIZES).optional(),
+    crust: z.enum(CRUSTS).optional(),
+    toppings: z.array(z.string()).optional(),
+    quantity: z.number().int().min(1).optional(),
+  }),
+  execute(args, order) {
+    const idx = order.pizzas.findIndex((p) => p.id === args.pizza_id);
+    if (idx === -1) return toolFailure("Pizza not found in the order.");
+
+    const pizza: Pizza = { ...order.pizzas[idx]! };
+    if (args.size !== undefined) pizza.size = args.size;
+    if (args.crust !== undefined) pizza.crust = args.crust;
+    if (args.toppings !== undefined) pizza.toppings = args.toppings;
+    if (args.quantity !== undefined) pizza.quantity = args.quantity;
+
+    order.pizzas[idx] = pizza;
+
+    return { updated: pizza, orderTotal: formatPrice(calculateTotal(order.pizzas)) };
+  },
+});

package/dist/templates/pizza-ordering/tools/view_order.ts

@@ -0,0 +1,21 @@
+import { calculateTotal, formatPrice, orderSlot } from "../shared.ts";
+
+export default orderSlot.tool({
+  description: "View the current order summary with all pizzas and total price.",
+  execute(_args, order) {
+    const pizzas = order.pizzas;
+    if (pizzas.length === 0) return { message: "The order is empty." };
+
+    return {
+      pizzas: pizzas.map((p) => ({
+        id: p.id,
+        description: `${p.quantity}x ${p.size} ${p.crust} crust with ${p.toppings.length > 0 ? p.toppings.join(", ") : "cheese only"}`,
+        size: p.size,
+        crust: p.crust,
+        toppings: p.toppings,
+        quantity: p.quantity,
+      })),
+      orderTotal: formatPrice(calculateTotal(pizzas)),
+    };
+  },
+});