@alexkroman1/aai-cli 5.4.0 → 5.5.0

package/dist/templates/retail/shared.ts

@@ -0,0 +1,430 @@
+// ─── Store types ─────────────────────────────────────────────────────────────
+// Field names are tau2's snake_case verbatim, because `seed.json` is tau2's
+// records unmodified. Renaming them here would mean transforming 107 KB of
+// data on every session start for cosmetics.
+
+export interface Address {
+  address1: string;
+  address2: string;
+  city: string;
+  state: string;
+  country: string;
+  zip: string;
+}
+
+export interface GiftCard {
+  source: "gift_card";
+  id: string;
+  balance: number;
+}
+export interface PayPal {
+  source: "paypal";
+  id: string;
+}
+export interface CreditCard {
+  source: "credit_card";
+  id: string;
+  brand: string;
+  last_four: string;
+}
+export type PaymentMethod = GiftCard | PayPal | CreditCard;
+
+export interface Variant {
+  item_id: string;
+  options: Record<string, string>;
+  available: boolean;
+  price: number;
+}
+
+export interface Product {
+  name: string;
+  product_id: string;
+  variants: Record<string, Variant>;
+}
+
+export interface OrderItem {
+  name: string;
+  product_id: string;
+  item_id: string;
+  price: number;
+  options: Record<string, string>;
+}
+
+/** tau2's exact status strings. `pending (item modified)` is terminal — see
+ *  `modify_pending_order_items`. */
+export type OrderStatus =
+  | "pending"
+  | "pending (item modified)"
+  | "processed"
+  | "delivered"
+  | "cancelled"
+  | "return requested"
+  | "exchange requested";
+
+export interface OrderPayment {
+  transaction_type: "payment" | "refund";
+  amount: number;
+  payment_method_id: string;
+}
+
+export interface Fulfillment {
+  tracking_id: string[];
+  item_ids: string[];
+}
+
+export interface Order {
+  order_id: string;
+  user_id: string;
+  address: Address;
+  items: OrderItem[];
+  status: OrderStatus;
+  fulfillments?: Fulfillment[];
+  payment_history: OrderPayment[];
+  cancel_reason?: string;
+  return_items?: string[];
+  return_payment_method_id?: string;
+  exchange_items?: string[];
+  exchange_new_items?: string[];
+  exchange_payment_method_id?: string;
+  exchange_price_difference?: number;
+}
+
+export interface User {
+  user_id: string;
+  name: { first_name: string; last_name: string };
+  address: Address;
+  email: string;
+  payment_methods: Record<string, PaymentMethod>;
+  orders: string[];
+}
+
+export interface Store {
+  products: Record<string, Product>;
+  users: Record<string, User>;
+  orders: Record<string, Order>;
+}
+
+// ─── Session state ───────────────────────────────────────────────────────────
+
+export interface ActivityEntry {
+  seq: number;
+  tool: string;
+  summary: string;
+  at: number;
+}
+
+/** Capped in state, not just in the projection — an uncapped list would grow
+ *  the pushed payload for the length of the call. */
+export const MAX_ACTIVITY = 10;
+
+export interface RetailState {
+  store: Store;
+  /** Set by the two finder tools. Null until the caller is identified. */
+  authenticatedUserId: string | null;
+  /** Monotonic. Every tool call increments it, which is what guarantees the
+   *  projection differs and therefore gets pushed — `syncState` sends only
+   *  when the projected result changed. */
+  callSeq: number;
+  activity: ActivityEntry[];
+  focus: { orderId?: string; productId?: string };
+}
+
+export type StateSlot = { retail?: RetailState };
+
+// ─── View types — exactly what crosses the wire ──────────────────────────────
+
+export interface PaymentMethodView {
+  id: string;
+  source: PaymentMethod["source"];
+  label: string;
+  /** Gift cards only. */
+  balance?: number;
+}
+
+export interface OrderItemView {
+  name: string;
+  itemId: string;
+  options: Record<string, string>;
+  price: number;
+}
+
+export interface OrderView {
+  orderId: string;
+  status: OrderStatus;
+  total: number;
+  items: OrderItemView[];
+  address: Address;
+}
+
+export interface CustomerView {
+  userId: string;
+  name: string;
+  email: string;
+  address: Address;
+  paymentMethods: PaymentMethodView[];
+}
+
+/** What else one item in the focused order could become. This is what makes an
+ *  exchange sayable — without it "exchange the kettle" has no target. */
+export interface SwapOptionView {
+  itemId: string;
+  itemName: string;
+  currentOptions: Record<string, string>;
+  alternatives: { itemId: string; options: Record<string, string>; price: number }[];
+}
+
+export interface StoreView {
+  customer: CustomerView | null;
+  orders: OrderView[];
+  focus: { orderId?: string; productId?: string };
+  /** Populated only for the focused order. */
+  swapOptions: SwapOptionView[];
+  callSeq: number;
+  activity: ActivityEntry[];
+  scriptBullets: string[];
+  productCount: number;
+}
+
+export const MAX_SWAP_ITEMS = 3;
+export const MAX_SWAP_ALTERNATIVES = 4;
+
+// ─── Demo personas ───────────────────────────────────────────────────────────
+
+export interface DemoPersona {
+  name: string;
+  email: string;
+  zip: string;
+  /** The one interesting thing about this customer, so a user can pick the path
+   *  they want to exercise instead of guessing. */
+  hint: string;
+}
+
+/**
+ * The character-select screen. A first-time user has no email to give, so
+ * without this the agent cannot be driven at all.
+ *
+ * A CONSTANT, not a projection of `store.users`: reading it out of the store
+ * would put five unauthenticated customers' emails into the projection, which
+ * is the one thing `storeView` exists to prevent. The duplication with
+ * `seed.json` is deliberate and `shared.test.ts` pins the two together.
+ */
+export const DEMO_PERSONAS: readonly DemoPersona[] = [
+  {
+    name: "Emma Smith",
+    email: "emma.smith3991@example.com",
+    zip: "10192",
+    hint: "Simplest path — single-item orders, $62.00 gift card.",
+  },
+  {
+    name: "Olivia Ito",
+    email: "olivia.ito5204@example.com",
+    zip: "80218",
+    hint: "Three pending orders, all three payment types. Try switching an order's payment method.",
+  },
+  {
+    name: "Aarav Anderson",
+    email: "aarav.anderson9752@example.com",
+    zip: "19031",
+    hint: "One gift card holding $17.00. A pricier exchange gets refused; one order has the same kettle twice.",
+  },
+  {
+    name: "Anya Garcia",
+    email: "anya.garcia2061@example.com",
+    zip: "19036",
+    hint: "$51.00 gift card — upgrading the laptop in her pending order costs more than it holds.",
+  },
+  {
+    name: "Harper Brown",
+    email: "harper.brown3965@example.com",
+    zip: "76112",
+    hint: "No gift card, so a refund can only go back to PayPal.",
+  },
+  {
+    name: "Aarav Gonzalez",
+    email: "aarav.gonzalez9269@example.com",
+    zip: "78268",
+    hint: "Shares a first name with Aarav Anderson — the zip is what tells them apart.",
+  },
+] as const;
+
+// ─── Projection ──────────────────────────────────────────────────────────────
+
+function paymentLabel(method: PaymentMethod): string {
+  if (method.source === "gift_card") return "Gift card";
+  if (method.source === "paypal") return "PayPal";
+  return `${method.brand} ending ${method.last_four}`;
+}
+
+function paymentMethodView(method: PaymentMethod): PaymentMethodView {
+  return {
+    id: method.id,
+    source: method.source,
+    label: paymentLabel(method),
+    ...(method.source === "gift_card" ? { balance: method.balance } : {}),
+  };
+}
+
+/** Net of payments minus refunds — what the customer has actually paid. Items
+ *  can't be summed instead: a modified order's items no longer match what was
+ *  charged. */
+export function orderTotal(order: Order): number {
+  const net = order.payment_history.reduce(
+    (sum, p) => sum + (p.transaction_type === "payment" ? p.amount : -p.amount),
+    0,
+  );
+  return Math.round(net * 100) / 100;
+}
+
+function orderView(order: Order): OrderView {
+  return {
+    orderId: order.order_id,
+    status: order.status,
+    total: orderTotal(order),
+    address: order.address,
+    items: order.items.map((i) => ({
+      name: i.name,
+      itemId: i.item_id,
+      options: i.options,
+      price: i.price,
+    })),
+  };
+}
+
+/**
+ * What else each item in the focused order could become — the data that makes
+ * an exchange sayable. Only available variants, only the focused order, and
+ * capped on both axes so the payload stays bounded.
+ */
+function swapOptionsFor(state: RetailState, order: Order | undefined): SwapOptionView[] {
+  if (!order) return [];
+  return order.items.slice(0, MAX_SWAP_ITEMS).map((item) => {
+    const product = state.store.products[item.product_id];
+    const alternatives = Object.values(product?.variants ?? {})
+      .filter((variant) => variant.available && variant.item_id !== item.item_id)
+      .sort((a, b) => Math.abs(a.price - item.price) - Math.abs(b.price - item.price))
+      .slice(0, MAX_SWAP_ALTERNATIVES)
+      .map((variant) => ({
+        itemId: variant.item_id,
+        options: variant.options,
+        price: variant.price,
+      }));
+    return {
+      itemId: item.item_id,
+      itemName: item.name,
+      currentOptions: item.options,
+      alternatives,
+    };
+  });
+}
+
+/** The `syncState` projection — the entire contract with `client.tsx`.
+ *
+ *  Only the authenticated customer is projected. The other five seeded
+ *  customers' emails, addresses, and payment methods never leave the server,
+ *  which is why `syncState` takes a projection rather than a boolean. */
+export function storeView(slot: StateSlot): StoreView {
+  const state = slot.retail;
+  const userId = state?.authenticatedUserId ?? null;
+  const user = userId ? state?.store.users[userId] : undefined;
+  const focusedOrderId = state?.focus.orderId;
+  // Gated on `user`: an order is only ever projected for the customer on the
+  // call, so a stale focus from before authentication cannot leak one.
+  const focusedOrder =
+    state && user && focusedOrderId && user.orders.includes(focusedOrderId)
+      ? state.store.orders[focusedOrderId]
+      : undefined;
+
+  return {
+    customer: user
+      ? {
+          userId: user.user_id,
+          name: `${user.name.first_name} ${user.name.last_name}`,
+          email: user.email,
+          address: user.address,
+          paymentMethods: Object.values(user.payment_methods).map(paymentMethodView),
+        }
+      : null,
+    orders: user
+      ? user.orders
+          .map((id) => state?.store.orders[id])
+          .filter((o): o is Order => o !== undefined)
+          .map(orderView)
+      : [],
+    // The orderId half is gated the same way `focusedOrder` is above: a focus
+    // left over from another customer's session (or from before
+    // authentication) must not surface that order's id in the view, even
+    // though its details were already withheld from `orders`/`swapOptions`.
+    focus: {
+      ...(focusedOrder && focusedOrderId ? { orderId: focusedOrderId } : {}),
+      ...(state?.focus.productId ? { productId: state.focus.productId } : {}),
+    },
+    swapOptions: state ? swapOptionsFor(state, focusedOrder) : [],
+    callSeq: state?.callSeq ?? 0,
+    activity: state?.activity.slice(-MAX_ACTIVITY) ?? [],
+    scriptBullets: buildScriptBullets(state),
+    productCount: Object.keys(state?.store.products ?? {}).length,
+  };
+}
+
+// ─── Script bullets ──────────────────────────────────────────────────────────
+
+const MAX_BULLETS = 6;
+
+/**
+ * Generated from the caller's own orders, not a fixed list. A capability list
+ * that offers actions the data can't support — "return an item" to someone
+ * with no delivered order — is worse than no list.
+ */
+export function buildScriptBullets(state: RetailState | undefined): string[] {
+  const userId = state?.authenticatedUserId;
+  const user = userId ? state?.store.users[userId] : undefined;
+
+  // Pre-auth: only the two ways in. The personas panel (a constant, rendered
+  // straight from DEMO_PERSONAS) covers WHICH customer to be.
+  if (!(state && user)) {
+    const first = DEMO_PERSONAS[0];
+    return [
+      `"My email is ${first?.email ?? ""}"`,
+      `"I'm ${first?.name ?? ""}, zip ${first?.zip ?? ""}"`,
+    ];
+  }
+
+  const orders = user.orders
+    .map((id) => state.store.orders[id])
+    .filter((o): o is Order => o !== undefined);
+  const pending = orders.filter((o) => o.status === "pending");
+  const delivered = orders.filter((o) => o.status === "delivered");
+
+  const bullets: string[] = [];
+
+  if (pending.length === 1) {
+    bullets.push('"Cancel my pending order"');
+  } else if (pending.length > 1) {
+    bullets.push(`"Cancel my first pending order" (${pending.length} pending)`);
+  }
+  if (pending.length > 0) {
+    bullets.push('"Change the shipping address on my pending order"');
+  }
+  if (pending.length > 0 && Object.keys(user.payment_methods).length > 1) {
+    bullets.push('"Switch that order to my other payment method"');
+  }
+
+  const deliveredItem = delivered[0]?.items[0];
+  if (deliveredItem) {
+    bullets.push(`"Return the ${deliveredItem.name}"`);
+    // Name a real alternative option. "Exchange it for a different option" is
+    // not something a caller can act on — they need words to say.
+    const alternative = Object.values(
+      state.store.products[deliveredItem.product_id]?.variants ?? {},
+    ).find((variant) => variant.available && variant.item_id !== deliveredItem.item_id);
+    bullets.push(
+      alternative
+        ? `"Exchange the ${deliveredItem.name} for the ${Object.values(alternative.options).join(" ")} one"`
+        : `"Exchange the ${deliveredItem.name}"`,
+    );
+  }
+
+  bullets.push('"Update my default address"');
+
+  return bullets.slice(0, MAX_BULLETS);
+}

package/dist/templates/retail/store.test.ts

@@ -0,0 +1,256 @@
+import type { ToolContext } from "@alexkroman1/aai";
+import { describe, expect, test } from "vitest";
+import { z } from "zod";
+import {
+  authenticatedUser,
+  createDefaultState,
+  findItem,
+  findOrder,
+  findPaymentMethod,
+  findProduct,
+  findUser,
+  findVariant,
+  getState,
+  isError,
+  isGiftCard,
+  money,
+  requireOwnOrder,
+  retailTool,
+} from "./store.ts";
+
+let sessionCounter = 0;
+
+function makeCtx(): ToolContext {
+  return {
+    sessionId: `test-session-${++sessionCounter}`,
+    send: () => {},
+    env: {},
+    state: {},
+    messages: [],
+  } as unknown as ToolContext;
+}
+
+describe("session state", () => {
+  test("getState seeds lazily and returns the same object on re-entry", () => {
+    const ctx = makeCtx();
+    const a = getState(ctx);
+    const b = getState(ctx);
+    expect(a).toBe(b);
+    expect(a.authenticatedUserId).toBeNull();
+    expect(a.callSeq).toBe(0);
+    expect(Object.keys(a.store.orders)).toHaveLength(22);
+  });
+
+  test("each session gets its own deep copy — a mutation cannot leak across sessions", () => {
+    const first = getState(makeCtx());
+    const order = first.store.orders["#W9300146"];
+    if (!order) throw new Error("fixture missing");
+    order.status = "cancelled";
+    const giftCard = first.store.users.aarav_anderson_8794?.payment_methods.gift_card_7245904;
+    if (giftCard?.source === "gift_card") giftCard.balance = 0;
+
+    const second = getState(makeCtx());
+    expect(second.store.orders["#W9300146"]?.status).toBe("pending");
+    const fresh = second.store.users.aarav_anderson_8794?.payment_methods.gift_card_7245904;
+    expect(fresh?.source === "gift_card" && fresh.balance).toBe(17);
+  });
+});
+
+describe("money", () => {
+  test("rounds to two decimals", () => {
+    expect(money(3.005)).toBe(3.01);
+    expect(money(0.1 + 0.2)).toBe(0.3);
+    expect(money(-40.860_000_000_000_014)).toBe(-40.86);
+  });
+});
+
+describe("lookups", () => {
+  test("findUser resolves and reports a miss by id", () => {
+    const state = createDefaultState();
+    expect(isError(findUser(state, "olivia_ito_3591"))).toBe(false);
+    const miss = findUser(state, "nobody_1");
+    expect(isError(miss) && miss.error).toContain("nobody_1");
+  });
+
+  test("findOrder resolves and reports a miss", () => {
+    const state = createDefaultState();
+    const order = findOrder(state, "#W5866402");
+    expect(isError(order)).toBe(false);
+    expect(isError(order) ? null : order.status).toBe("delivered");
+    expect(isError(findOrder(state, "#W0000000"))).toBe(true);
+  });
+
+  test("findProduct and findVariant resolve within one product", () => {
+    const state = createDefaultState();
+    const product = findProduct(state, "9832717871");
+    if (isError(product)) throw new Error(product.error);
+    expect(product.name).toBe("Tea Kettle");
+    const variant = findVariant(product, "3909406921");
+    expect(isError(variant) ? null : variant.price).toBe(98.25);
+    // A real item id, but of a different product.
+    expect(isError(findVariant(product, "4725166838"))).toBe(true);
+  });
+
+  test("findItem scans every product and returns both product and variant", () => {
+    const state = createDefaultState();
+    const found = findItem(state, "3909406921");
+    if (isError(found)) throw new Error(found.error);
+    expect(found.product.product_id).toBe("9832717871");
+    expect(found.variant.price).toBe(98.25);
+    expect(isError(findItem(state, "0000000000"))).toBe(true);
+  });
+
+  test("findPaymentMethod resolves on the owning user only", () => {
+    const state = createDefaultState();
+    const olivia = findUser(state, "olivia_ito_3591");
+    if (isError(olivia)) throw new Error(olivia.error);
+    expect(isError(findPaymentMethod(olivia, "gift_card_7794233"))).toBe(false);
+    // aarav's card is not olivia's.
+    expect(isError(findPaymentMethod(olivia, "gift_card_7245904"))).toBe(true);
+  });
+
+  test("isGiftCard narrows", () => {
+    const state = createDefaultState();
+    const olivia = findUser(state, "olivia_ito_3591");
+    if (isError(olivia)) throw new Error(olivia.error);
+    const card = olivia.payment_methods.gift_card_7794233;
+    const paypal = olivia.payment_methods.paypal_8049766;
+    expect(card && isGiftCard(card)).toBe(true);
+    expect(paypal && isGiftCard(paypal)).toBe(false);
+  });
+});
+
+describe("ownership and authentication guards", () => {
+  test("authenticatedUser errors before authentication", () => {
+    const state = createDefaultState();
+    const result = authenticatedUser(state);
+    expect(isError(result) && result.error.toLowerCase()).toContain("find_user_id_by_email");
+  });
+
+  test("requireOwnOrder refuses another customer's order without revealing it", () => {
+    const state = createDefaultState();
+    state.authenticatedUserId = "olivia_ito_3591";
+    const result = requireOwnOrder(state, "#W4316152"); // aarav's
+    expect(isError(result)).toBe(true);
+    if (!isError(result)) throw new Error("expected refusal");
+    expect(result.error).not.toContain("aarav");
+    expect(result.error).not.toContain("Tea Kettle");
+  });
+
+  test("requireOwnOrder gives the same shape of answer for an unknown order — no existence oracle", () => {
+    const state = createDefaultState();
+    state.authenticatedUserId = "olivia_ito_3591";
+    const foreignId = "#W4316152";
+    const missingId = "#W0000000";
+    const foreign = requireOwnOrder(state, foreignId);
+    const missing = requireOwnOrder(state, missingId);
+    expect(isError(foreign) && isError(missing)).toBe(true);
+    if (!(isError(foreign) && isError(missing))) throw new Error("expected refusals");
+    // Structural, not literal, equality: the messages legitimately differ by
+    // the id the caller themselves passed in (that's not information about
+    // the store — they already knew it), so comparing byte-for-byte would be
+    // unsatisfiable by any implementation that echoes the id back for repair
+    // retries, as every sibling lookup in this file does. Normalizing the id
+    // out asserts the actual guarantee: no wording distinguishes "belongs to
+    // someone else" from "doesn't exist".
+    const shape = (msg: string, id: string) => msg.replace(id, "<ID>");
+    expect(shape(foreign.error, foreignId)).toBe(shape(missing.error, missingId));
+  });
+
+  test("requireOwnOrder resolves the caller's own order", () => {
+    const state = createDefaultState();
+    state.authenticatedUserId = "olivia_ito_3591";
+    const result = requireOwnOrder(state, "#W5866402");
+    expect(isError(result) ? null : result.order_id).toBe("#W5866402");
+  });
+});
+
+describe("retailTool", () => {
+  const echo = retailTool({
+    name: "echo",
+    description: "test tool",
+    inputSchema: z.object({ value: z.string() }),
+    requiresAuth: false,
+    summary: (args) => `echoed ${args.value}`,
+    execute: (args) => ({ echoed: args.value }),
+  });
+
+  const gated = retailTool({
+    name: "gated",
+    description: "test tool needing auth",
+    inputSchema: z.object({}),
+    summary: () => "ran",
+    execute: () => ({ ok: true }),
+  });
+
+  const failing = retailTool({
+    name: "failing",
+    description: "test tool that returns an error",
+    inputSchema: z.object({}),
+    requiresAuth: false,
+    summary: () => "should not be used",
+    execute: () => ({ error: "nope" }),
+  });
+
+  test("increments callSeq and logs activity on every call", async () => {
+    const ctx = makeCtx();
+    await echo.execute({ value: "a" }, ctx);
+    await echo.execute({ value: "b" }, ctx);
+    const state = getState(ctx);
+    expect(state.callSeq).toBe(2);
+    expect(state.activity.map((a) => a.summary)).toEqual(["echoed a", "echoed b"]);
+    expect(state.activity.map((a) => a.tool)).toEqual(["echo", "echo"]);
+  });
+
+  test("a repeated identical call still changes the projection", async () => {
+    const ctx = makeCtx();
+    await echo.execute({ value: "same" }, ctx);
+    const first = getState(ctx).callSeq;
+    await echo.execute({ value: "same" }, ctx);
+    expect(getState(ctx).callSeq).toBeGreaterThan(first);
+  });
+
+  test("defaults to requiring authentication and does not run execute when blocked", async () => {
+    const ctx = makeCtx();
+    const result = await gated.execute({}, ctx);
+    expect(isError(result) && result.error).toContain("find_user_id_by_email");
+  });
+
+  test("a blocked call is still logged and still bumps callSeq", async () => {
+    const ctx = makeCtx();
+    await gated.execute({}, ctx);
+    const state = getState(ctx);
+    expect(state.callSeq).toBe(1);
+    expect(state.activity[0]?.summary).toContain("blocked");
+  });
+
+  test("runs once authenticated", async () => {
+    const ctx = makeCtx();
+    getState(ctx).authenticatedUserId = "olivia_ito_3591";
+    const result = await gated.execute({}, ctx);
+    expect(result).toEqual({ ok: true });
+  });
+
+  test("an error result is logged as an error, not through summary()", async () => {
+    const ctx = makeCtx();
+    await failing.execute({}, ctx);
+    expect(getState(ctx).activity[0]?.summary).toBe("error: nope");
+  });
+
+  test("activity is capped so a long call cannot grow the payload", async () => {
+    const ctx = makeCtx();
+    for (let i = 0; i < 15; i++) await echo.execute({ value: String(i) }, ctx);
+    const state = getState(ctx);
+    expect(state.callSeq).toBe(15);
+    expect(state.activity).toHaveLength(10);
+    expect(state.activity[0]?.summary).toBe("echoed 5");
+  });
+
+  test("concurrent calls serialize — no lost increments", async () => {
+    const ctx = makeCtx();
+    await Promise.all(Array.from({ length: 8 }, (_, i) => echo.execute({ value: String(i) }, ctx)));
+    const state = getState(ctx);
+    expect(state.callSeq).toBe(8);
+    expect(new Set(state.activity.map((a) => a.seq)).size).toBe(state.activity.length);
+  });
+});