@alexkroman1/aai-cli 5.1.1 → 5.2.0

package/dist/templates/pipeline-simple/agent.ts

@@ -0,0 +1,13 @@
+import { agent, assemblyAIPipeline } from "@alexkroman1/aai";
+import { anthropic } from "@alexkroman1/aai/llm";
+
+export default agent({
+  name: "pipeline-simple",
+  greeting: "Hi! I'm running in pipeline mode. What can I help with?",
+  // The preset fills all three stages with AssemblyAI, billed to the one key
+  // a published agent is guaranteed to have. Spread it, then override the one
+  // stage you want elsewhere — here the LLM. Anything not overridden stays
+  // AssemblyAI, so swapping a stage never means restating the other two.
+  ...assemblyAIPipeline(),
+  llm: anthropic({ model: "claude-haiku-4-5" }),
+});

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

@@ -0,0 +1,235 @@
+import type { Db, ToolContext, ToolDef } from "@alexkroman1/aai";
+import { describe, expect, test } from "vitest";
+import agentDef from "./agent.ts";
+import { calculateTotal, 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,
+    send: (event, data) => {
+      sent.push({ event, data });
+    },
+  };
+  return { 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);
+}
+
+const margherita: Omit<Pizza, "id"> = {
+  size: "medium",
+  crust: "regular",
+  toppings: [],
+  quantity: 1,
+};
+
+// ─── 1. Pure pricing ─────────────────────────────────────────────────────────
+
+describe("pricing (shared.ts)", () => {
+  test("base price + crust upcharge + toppings, times quantity", () => {
+    const p: Pizza = {
+      id: 1,
+      size: "large", // 14.99
+      crust: "stuffed", // +2.00
+      toppings: ["pepperoni", "mushrooms"], // 1.50 + 1.00
+      quantity: 2,
+    };
+    expect(pizzaPrice(p)).toBeCloseTo((14.99 + 2.0 + 1.5 + 1.0) * 2, 5);
+  });
+
+  test("cheese-only pizza costs base + crust", () => {
+    expect(pizzaPrice({ id: 1, ...margherita })).toBeCloseTo(11.99, 5);
+  });
+
+  test("unknown topping falls back to the $1.00 default", () => {
+    const known = pizzaPrice({ id: 1, ...margherita, toppings: ["onions"] }); // $1.00 topping
+    const unknown = pizzaPrice({ id: 1, ...margherita, toppings: ["dragonfruit"] });
+    expect(unknown).toBeCloseTo(known, 5);
+  });
+
+  test("calculateTotal sums all pizzas (empty order = 0)", () => {
+    expect(calculateTotal([])).toBe(0);
+    const a: Pizza = { id: 1, size: "small", crust: "thin", toppings: [], quantity: 1 };
+    const b: Pizza = { id: 2, size: "small", crust: "thin", toppings: [], quantity: 3 };
+    expect(calculateTotal([a, b])).toBeCloseTo(8.99 * 4, 5);
+  });
+
+  test("add_pizza schema defaults quantity to 1 and rejects non-positive quantities", () => {
+    const schema = getTool("add_pizza").parameters;
+    if (!schema) throw new Error("add_pizza has no parameters schema");
+    const parsed = schema.parse({ size: "small", crust: "thin", toppings: [] });
+    expect(parsed.quantity).toBe(1);
+    expect(() =>
+      schema.parse({ size: "small", crust: "thin", toppings: [], quantity: 0 }),
+    ).toThrow();
+    expect(() =>
+      schema.parse({ size: "small", crust: "thin", toppings: [], quantity: 1.5 }),
+    ).toThrow();
+  });
+});
+
+// ─── 2. Tool flow round-trip ─────────────────────────────────────────────────
+
+describe("tool flow (add → update → remove → place_order)", () => {
+  test("full ordering round-trip keeps state, totals, and IDs consistent", async () => {
+    const { ctx } = makeCtx();
+
+    // Empty order guards
+    expect(await run("view_order", {}, ctx)).toEqual({ message: "The order is empty." });
+    expect(await run("place_order", {}, ctx)).toEqual({ error: "Cannot place an empty order." });
+
+    // Add two pizzas — IDs increment
+    const first = (await run(
+      "add_pizza",
+      { size: "large", crust: "thin", toppings: ["pepperoni"], quantity: 1 },
+      ctx,
+    )) as { added: Pizza; orderTotal: string; itemCount: number };
+    expect(first.added.id).toBe(1);
+    expect(first.itemCount).toBe(1);
+    expect(first.orderTotal).toBe(`$${(14.99 + 1.5).toFixed(2)}`);
+
+    const second = (await run(
+      "add_pizza",
+      { size: "small", crust: "stuffed", toppings: [], quantity: 2 },
+      ctx,
+    )) as { added: Pizza; itemCount: number };
+    expect(second.added.id).toBe(2);
+    expect(second.itemCount).toBe(2);
+
+    // Update only the provided fields
+    const updated = (await run("update_pizza", { pizza_id: 2, quantity: 1 }, ctx)) as {
+      updated: Pizza;
+    };
+    expect(updated.updated).toMatchObject({ id: 2, size: "small", crust: "stuffed", quantity: 1 });
+    expect(await run("update_pizza", { pizza_id: 99, quantity: 1 }, ctx)).toEqual({
+      error: "Pizza not found in the order.",
+    });
+
+    // Remove the first pizza
+    const removed = (await run("remove_pizza", { pizza_id: 1 }, ctx)) as {
+      removed: Pizza;
+      itemCount: number;
+    };
+    expect(removed.removed.id).toBe(1);
+    expect(removed.itemCount).toBe(1);
+    expect(await run("remove_pizza", { pizza_id: 1 }, ctx)).toEqual({
+      error: "Pizza not found in the order.",
+    });
+
+    // Name + place the order
+    await run("set_customer_name", { name: "Alex" }, ctx);
+    const placed = (await run("place_order", {}, ctx)) as {
+      orderNumber: number;
+      customerName: string;
+      pizzas: number;
+      total: string;
+    };
+    expect(placed.customerName).toBe("Alex");
+    expect(placed.pizzas).toBe(1);
+    expect(placed.total).toBe(`$${(8.99 + 2.0).toFixed(2)}`);
+
+    // The cart is cleared after placing — a follow-up order starts fresh.
+    expect(await run("view_order", {}, ctx)).toEqual({ message: "The order is empty." });
+    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");
+
+    await run(
+      "add_pizza",
+      { size: "large", crust: "thin", toppings: ["bacon"], quantity: 1 },
+      sessionA,
+    );
+    await run("set_customer_name", { name: "Alice" }, sessionA);
+
+    expect(await run("view_order", {}, sessionB)).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 {
+      customerName: string;
+      pizzas: number;
+    };
+    // Session B never sees session A'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[] };
+    expect(viewA.pizzas).toHaveLength(1);
+  });
+});
+
+// ─── 3. The projection contract with client.tsx ─────────────────────────────
+//
+// `syncState: orderView` is now the ONLY thing the sidebar reads, which makes
+// the contract a pure function of state rather than an if/else chain over
+// event shapes. What used to need six event-shape assertions is three.
+
+describe("orderView projection", () => {
+  test("reflects the live cart", async () => {
+    const { ctx } = makeCtx();
+    await run(
+      "add_pizza",
+      { size: "large", crust: "stuffed", toppings: ["pepperoni", "extra_cheese"], quantity: 2 },
+      ctx,
+    );
+
+    const view = orderView(ctx.state as StateSlot);
+    expect(view.orderPlaced).toBe(false);
+    const item = view.pizzas[0];
+    if (!item) throw new Error("no pizza in the projection");
+    // The client renders these fields directly and calls pizzaPrice on them.
+    expect(item).toMatchObject({
+      id: 1,
+      size: "large",
+      crust: "stuffed",
+      toppings: ["pepperoni", "extra_cheese"],
+      quantity: 2,
+    });
+    expect(view.total).toBe(`$${pizzaPrice(item).toFixed(2)}`);
+  });
+
+  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();
+    await run("add_pizza", { size: "small", crust: "thin", toppings: [], quantity: 1 }, ctx);
+    await run("place_order", {}, ctx);
+
+    const view = orderView(ctx.state as StateSlot);
+    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 });
+  });
+});

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

@@ -0,0 +1,174 @@
+import { agent, assemblyAIPipeline, tool } from "@alexkroman1/aai";
+import { z } from "zod";
+import {
+  CRUSTS,
+  calculateTotal,
+  formatPrice,
+  getOrder,
+  menuText,
+  orderView,
+  type Pizza,
+  resetOrder,
+  SIZES,
+} 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.
+
+export default agent({
+  name: "Pizza Palace",
+  ...assemblyAIPipeline(),
+  // 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,
+  // 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()}`,
+  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.",
+      parameters: 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 = getOrder(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 = getOrder(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.",
+      parameters: z.object({
+        pizza_id: z.number().describe("The pizza ID to remove"),
+      }),
+      async execute(args, ctx) {
+        const order = getOrder(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.",
+      parameters: z.object({
+        name: z.string(),
+      }),
+      async execute(args, ctx) {
+        getOrder(ctx).customerName = args.name;
+        return { name: args.name };
+      },
+    }),
+
+    update_pizza: tool({
+      description: "Update an existing pizza in the order. Only provided fields are changed.",
+      parameters: 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 = getOrder(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 = getOrder(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/client.tsx

@@ -0,0 +1,120 @@
+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";
+
+// Derived from the projection so a new OrderView field can't silently miss
+// the pre-first-tool-call render.
+const EMPTY_ORDER = orderView({});
+
+function PizzaIcon({ size }: { size: string }) {
+  const dim = size === "small" ? 36 : size === "large" ? 52 : 44;
+  return (
+    <svg width={dim} height={dim} viewBox="0 0 100 100" className="shrink-0">
+      <circle cx="50" cy="50" r="48" fill="#F4C542" stroke="#D4A017" strokeWidth="3" />
+      <circle cx="50" cy="50" r="42" fill="#E8A025" />
+      <circle cx="35" cy="35" r="7" fill="#C0392B" opacity="0.9" />
+      <circle cx="60" cy="30" r="6" fill="#C0392B" opacity="0.9" />
+      <circle cx="55" cy="55" r="7" fill="#C0392B" opacity="0.9" />
+      <circle cx="30" cy="58" r="6" fill="#C0392B" opacity="0.9" />
+      <circle cx="65" cy="65" r="5" fill="#C0392B" opacity="0.9" />
+      <circle cx="45" cy="68" r="4" fill="#27AE60" opacity="0.7" />
+      <circle cx="70" cy="42" r="4" fill="#27AE60" opacity="0.7" />
+    </svg>
+  );
+}
+
+function OrderSidebar() {
+  const theme = useTheme();
+  // The agent's own cart, projected by `syncState` and pushed after every
+  // 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;
+
+  if (order.orderPlaced) {
+    return (
+      <div
+        className="flex flex-col items-center gap-4 p-6 text-center"
+        style={{ color: theme.text }}
+      >
+        <div className="text-5xl">&#10003;</div>
+        <h2 className="text-lg font-bold">Order Placed</h2>
+        {order.orderNumber && <p className="opacity-70">Order #{order.orderNumber}</p>}
+        <p className="font-bold text-xl" style={{ color: theme.primary }}>
+          {order.total}
+        </p>
+        {order.estimatedMinutes && (
+          <p className="opacity-60 text-sm">Ready in ~{order.estimatedMinutes} minutes</p>
+        )}
+      </div>
+    );
+  }
+
+  if (order.pizzas.length === 0) {
+    return (
+      <div className="flex flex-col items-center gap-3 p-6 text-center opacity-50">
+        <PizzaIcon size="large" />
+        <p className="text-sm" style={{ color: theme.text }}>
+          Your order is empty. Tell me what you'd like.
+        </p>
+      </div>
+    );
+  }
+
+  return (
+    <div className="flex flex-col gap-3 p-4" style={{ color: theme.text }}>
+      <h3 className="text-sm font-bold opacity-60 uppercase tracking-wide">Your Order</h3>
+      {order.pizzas.map((p) => (
+        <div
+          key={p.id}
+          className="flex items-center gap-3 p-3 rounded-lg"
+          style={{ background: theme.surface }}
+        >
+          <PizzaIcon size={p.size} />
+          <div className="flex-1 min-w-0">
+            <p className="text-sm font-medium">
+              {p.quantity > 1 ? `${p.quantity}x ` : ""}
+              {p.size.charAt(0).toUpperCase() + p.size.slice(1)} {p.crust} crust
+            </p>
+            <p className="opacity-60 text-xs truncate">
+              {p.toppings.length > 0
+                ? p.toppings.map((t) => t.replace("_", " ")).join(", ")
+                : "cheese only"}
+            </p>
+          </div>
+          <p className="text-sm font-bold whitespace-nowrap" style={{ color: theme.primary }}>
+            {formatPrice(pizzaPrice(p))}
+          </p>
+        </div>
+      ))}
+      <div
+        className="flex justify-between items-center pt-3 mt-1 border-t"
+        style={{ borderColor: theme.border }}
+      >
+        <span className="font-bold">Total</span>
+        <span className="font-bold text-lg" style={{ color: theme.primary }}>
+          {order.total}
+        </span>
+      </div>
+    </div>
+  );
+}
+
+client({
+  name: "Pizza Palace",
+  sidebar: OrderSidebar,
+  theme: {
+    bg: "#1a1008",
+    primary: "#E8A025",
+    text: "#f5f0e8",
+    surface: "#2a1f10",
+    border: "#3d2e18",
+  },
+  tools: {
+    add_pizza: { icon: "\u{1F355}", label: "Adding pizza" },
+    remove_pizza: { icon: "\u{1F5D1}", label: "Removing pizza" },
+    update_pizza: { icon: "\u{270F}", label: "Updating pizza" },
+    place_order: { icon: "\u{2705}", label: "Placing order" },
+  },
+});

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

@@ -0,0 +1,142 @@
+import type { ToolContext } from "@alexkroman1/aai";
+
+export const SIZES = ["small", "medium", "large"] as const;
+export const CRUSTS = ["thin", "regular", "thick", "stuffed"] as const;
+
+export interface Pizza {
+  id: number;
+  size: (typeof SIZES)[number];
+  crust: (typeof CRUSTS)[number];
+  toppings: string[];
+  quantity: number;
+}
+
+export const MENU = {
+  sizes: { small: 8.99, medium: 11.99, large: 14.99 },
+  crusts: { thin: 0, regular: 0, thick: 1.0, stuffed: 2.0 },
+  toppings: {
+    pepperoni: 1.5,
+    sausage: 1.5,
+    mushrooms: 1.0,
+    onions: 1.0,
+    green_peppers: 1.0,
+    black_olives: 1.0,
+    bacon: 2.0,
+    ham: 1.5,
+    pineapple: 1.0,
+    jalapenos: 1.0,
+    extra_cheese: 1.5,
+    spinach: 1.0,
+    tomatoes: 1.0,
+    anchovies: 1.5,
+    chicken: 2.0,
+  },
+} as const;
+
+export function calculateTotal(pizzas: Pizza[]): number {
+  return pizzas.reduce((total, pizza) => total + pizzaPrice(pizza), 0);
+}
+
+/** The one money format. Tool results, the projection, and the sidebar all
+ *  show prices through this, so they can never disagree on rounding. */
+export function formatPrice(amount: number): string {
+  return `$${amount.toFixed(2)}`;
+}
+
+/**
+ * The menu as prompt prose, generated from `MENU` so the agent can never
+ * quote a price the pricing code doesn't charge.
+ */
+export function menuText(): string {
+  const price = (amount: number, upcharge = false) =>
+    amount === 0 ? "free" : `${upcharge ? "+" : ""}${formatPrice(amount)}`;
+  const list = (items: Record<string, number>, upcharge = false) =>
+    Object.entries(items)
+      .map(([name, amount]) => `${name.replaceAll("_", " ")} (${price(amount, upcharge)})`)
+      .join(", ");
+  return [
+    "Menu info:",
+    `- Sizes: ${list(MENU.sizes)}`,
+    `- Crusts: ${list(MENU.crusts, true)}`,
+    `- Toppings: ${list(MENU.toppings)}`,
+  ].join("\n");
+}
+
+export function pizzaPrice(p: Pizza): number {
+  const base = MENU.sizes[p.size];
+  const crust = MENU.crusts[p.crust];
+  const toppings = p.toppings.reduce(
+    (sum, t) => sum + (MENU.toppings[t as keyof typeof MENU.toppings] ?? 1.0),
+    0,
+  );
+  return (base + crust + toppings) * p.quantity;
+}
+
+// ── 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.
+
+export interface OrderState {
+  pizzas: Pizza[];
+  nextId: number;
+  customerName: string | null;
+  /**
+   * The confirmation, once checkout happens. In state rather than only in
+   * `place_order`'s return value because the UI has to keep showing it after
+   * the cart is cleared — and `syncState` can only project what state holds.
+   */
+  placed?: { orderNumber: number; total: string; estimatedMinutes: number };
+}
+
+export type StateSlot = { order?: OrderState };
+
+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;
+}
+
+/**
+ * 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.
+ */
+export function resetOrder(ctx: ToolContext, placed?: OrderState["placed"]): void {
+  const slot = ctx.state as StateSlot;
+  slot.order = { ...emptyOrder(), ...(placed ? { placed } : {}) };
+}
+
+/**
+ * What the browser sees. A projection rather than the raw slot: the client
+ * needs the cart and its total, and `syncState` is where you decide what
+ * leaves the server.
+ */
+export interface OrderView {
+  pizzas: Pizza[];
+  total: string;
+  orderPlaced: boolean;
+  orderNumber?: number;
+  estimatedMinutes?: number;
+}
+
+export function orderView(state: StateSlot): OrderView {
+  const order = state.order;
+  const pizzas = order?.pizzas ?? [];
+  const placed = order?.placed;
+  return {
+    pizzas,
+    total: placed?.total ?? formatPrice(calculateTotal(pizzas)),
+    orderPlaced: Boolean(placed),
+    ...(placed
+      ? { orderNumber: placed.orderNumber, estimatedMinutes: placed.estimatedMinutes }
+      : {}),
+  };
+}