@alexkroman1/aai-cli 7.0.0 → 8.1.0

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

@@ -38,8 +38,8 @@ const registry = Object.entries(retailAgent.tools);
 // distinct session, which is what these per-tool cases assume.
 const makeCtx = (): ToolContext => createToolContext();
 
-/** A context whose call flow is in `serving`, so a `when: "serving"` tool can
- *  reach its body. Moved through the FLOW rather than by writing
+/** A context whose call flow is in `serving.helping`, so a `when: "serving"`
+ *  tool can reach its body. Moved through the FLOW rather than by writing
  *  `authenticatedUserId`, because the gate reads the machine. */
 function servingCtx(): ToolContext {
   const ctx = makeCtx();
@@ -47,11 +47,44 @@ function servingCtx(): ToolContext {
   return ctx;
 }
 
+/** The two tools legal only while a change waits on the caller's yes. */
+const SETTLING_TOOLS = new Set(["cancel_change", "confirm_change"]);
+
+function toolNamed(name: string) {
+  const def = retailAgent.tools[name];
+  if (!def) throw new Error(`no tool named ${name}`);
+  return def;
+}
+
+/**
+ * A context in whatever state `name` needs to reach its BODY.
+ *
+ * The two settling tools are reached by really identifying a caller and really
+ * staging a change, rather than by sending `STAGED` at the machine: they read
+ * `state.pending`, and a position with nothing staged behind it is a state this
+ * template cannot actually be in. Everything else only needs `serving`.
+ */
+async function bodyReachableCtx(name: string): Promise<ToolContext> {
+  if (!SETTLING_TOOLS.has(name)) return servingCtx();
+  const ctx = makeCtx();
+  await toolNamed("find_user_id_by_email").execute(
+    { email: "aarav.anderson9752@example.com" },
+    ctx,
+  );
+  await toolNamed("cancel_pending_order").execute(
+    { order_id: "#W9300146", reason: "no longer needed" },
+    ctx,
+  );
+  return ctx;
+}
+
 /** Minimal args satisfying each tool's schema. Deliberately plausible-shaped
  *  but wrong — these calls are expected to fail; what is asserted is that they
  *  still moved the UI. */
 const SAMPLE_ARGS: Record<string, Record<string, unknown>> = {
+  cancel_change: {},
   cancel_pending_order: { order_id: "#W0000000", reason: "no longer needed" },
+  confirm_change: {},
   exchange_delivered_order_items: {
     order_id: "#W0000000",
     item_ids: ["0000000000"],
@@ -102,10 +135,17 @@ const SAMPLE_ARGS: Record<string, Record<string, unknown>> = {
 };
 
 describe("tool registry", () => {
-  test("registers all fifteen tau2 retail tools", () => {
+  test("registers all seventeen tools", () => {
+    // Fifteen of these are tau2's retail tool set, which this template used to
+    // hold verbatim. `confirm_change` and `cancel_change` are the two it does
+    // not have: tau2's tools apply on their first call, and here nothing does —
+    // see `pending.ts`. Departing from that set is what buys the confirmation
+    // gate, and it is the reason this list is no longer a fidelity claim.
     expect(registry.map(([name]) => name).sort()).toEqual(
       [
+        "cancel_change",
         "cancel_pending_order",
+        "confirm_change",
         "exchange_delivered_order_items",
         "find_user_id_by_email",
         "find_user_id_by_name_zip",
@@ -144,10 +184,11 @@ describe("the UI-update invariant", () => {
   // This is the one that fails if a future tool is built with tool() instead of
   // retailTool(): it would work, and the sidebar would sit still through it.
   test.each(registry)("%s increments callSeq and logs activity", async (name, def) => {
-    // `serving`, so the flow gate is not what these calls are testing: the
-    // point is that a tool which reaches its BODY moves the sidebar. A refused
-    // call deliberately does not — see `store.test.ts`.
-    const ctx = servingCtx();
+    // In whichever state lets the body run, so the flow gate is not what these
+    // calls are testing: the point is that a tool which reaches its BODY moves
+    // the sidebar. A refused call never reaches one — the hook below is what
+    // moves the sidebar for those.
+    const ctx = await bodyReachableCtx(name);
     const before = retailSlot.get(ctx).callSeq;
     await def.execute(SAMPLE_ARGS[name] ?? {}, ctx);
     const state = retailSlot.get(ctx);
@@ -159,12 +200,82 @@ describe("the UI-update invariant", () => {
   test.each(registry)("%s logs its own registry key as its name", async (name, def) => {
     // Catches a copy-paste where the retailTool `name` and the registry key
     // disagree — the activity feed would then attribute calls to the wrong tool.
-    const ctx = servingCtx();
+    const ctx = await bodyReachableCtx(name);
     await def.execute(SAMPLE_ARGS[name] ?? {}, ctx);
     expect(retailSlot.get(ctx).activity.at(-1)?.tool).toBe(name);
   });
 });
 
+describe("the blocked-call hook", () => {
+  /**
+   * A `tool.called`, delivered the way the RUNTIME delivers it.
+   *
+   * The hook is a plain function on the def, so this needs no harness — and
+   * asserting on it here is the only way the blocked lines are covered at all:
+   * they are written by something no tool call executes.
+   */
+  const called = (name: string, ctx: ToolContext) =>
+    retailAgent.events?.["tool.called"]?.(
+      {
+        type: "tool.called",
+        toolCallId: "call_1",
+        toolName: name,
+        args: {},
+        meta: { id: "evt_1", at: 0 },
+      },
+      ctx,
+    );
+
+  test.each(registry.filter(([name]) => !PUBLIC_TOOLS.has(name)))(
+    "%s records a blocked line when the model tries it too early",
+    (name) => {
+      const ctx = makeCtx();
+      called(name, ctx);
+
+      // The regression this closes: the gate moved out of `retailTool` and the
+      // sidebar stopped showing the most interesting calls the model makes.
+      const state = retailSlot.get(ctx);
+      expect(state.callSeq, `${name} recorded no blocked line`).toBe(1);
+      expect(state.activity.at(-1)?.tool).toBe(name);
+      expect(state.activity.at(-1)?.summary).toContain("blocked");
+      expect(state.activity.at(-1)?.summary).toContain("identifying");
+    },
+  );
+
+  test.each(registry.filter(([name]) => PUBLIC_TOOLS.has(name)))(
+    "%s is left to the wrapper, because it is going to run",
+    (name) => {
+      const ctx = makeCtx();
+      called(name, ctx);
+      // The double-count this avoids: a tool that reaches its body records its
+      // own line from inside it, with a real summary.
+      expect(retailSlot.get(ctx).activity, `${name} was double-recorded`).toEqual([]);
+    },
+  );
+
+  test("a tool this template did not declare is ignored", () => {
+    const ctx = makeCtx();
+    called("web_search", ctx);
+    // `gateFor` answers `undefined` for anything not built through `retailTool`
+    // — a builtin, or a tool a future author adds outside the wrapper. Recording
+    // those would put lines in the feed for calls this gate has no opinion on.
+    expect(retailSlot.get(ctx).activity).toEqual([]);
+  });
+
+  test("the same tool stops being blocked once the caller is identified", async () => {
+    const ctx = makeCtx();
+    called("get_user_details", ctx);
+    expect(retailSlot.get(ctx).activity).toHaveLength(1);
+
+    // The hook asks the flow, so it follows the flow: same tool, same session,
+    // no line once the position allows it.
+    const authed = await bodyReachableCtx("get_user_details");
+    const before = retailSlot.get(authed).activity.length;
+    called("get_user_details", authed);
+    expect(retailSlot.get(authed).activity).toHaveLength(before);
+  });
+});
+
 describe("the authentication gate", () => {
   test.each(registry.filter(([name]) => !PUBLIC_TOOLS.has(name)))(
     "%s refuses before the caller is identified",

package/dist/templates/retail/returns.ts

@@ -0,0 +1,102 @@
+/**
+ * Returning items from a delivered order, as a plan and an apply (see
+ * `cancel.ts` for why every mutating action is split that way).
+ */
+
+import { isToolFailure, type ToolFailure } from "@alexkroman1/aai";
+import { resolveOrder } from "./resolve.ts";
+import type { RetailState } from "./shared.ts";
+import { authenticatedUser, findPaymentMethod, isGiftCard } from "./store.ts";
+
+export interface ReturnPlan {
+  readBack: string;
+  orderId: string;
+  /** In the order the caller named them — duplicates are meaningful. */
+  itemIds: string[];
+  /** Item names, positionally aligned with `itemIds`, so the readback and the
+   *  result can name things rather than read ten-digit numbers aloud. */
+  itemNames: string[];
+  paymentMethodId: string;
+}
+
+export function planReturn(
+  state: RetailState,
+  spokenOrderId: string,
+  itemIds: string[],
+  paymentMethodId: string,
+): ReturnPlan | ToolFailure {
+  const user = authenticatedUser(state);
+  if (isToolFailure(user)) return user;
+
+  const order = resolveOrder(state, spokenOrderId);
+  if (isToolFailure(order)) return order;
+
+  if (order.status !== "delivered") {
+    return {
+      error: `Order ${order.order_id} is ${order.status}. Only a delivered order can be returned, and only once.`,
+    };
+  }
+
+  const method = findPaymentMethod(user, paymentMethodId);
+  if (isToolFailure(method)) return method;
+
+  const originalMethodId = order.payment_history[0]?.payment_method_id;
+  if (!isGiftCard(method) && paymentMethodId !== originalMethodId) {
+    return {
+      error: `A refund must go to the original payment method (${originalMethodId}) or to a gift card. ${paymentMethodId} is neither.`,
+    };
+  }
+
+  if (itemIds.length === 0) {
+    return { error: "No items were listed to return." };
+  }
+  const held = new Map<string, number>();
+  for (const item of order.items) {
+    held.set(item.item_id, (held.get(item.item_id) ?? 0) + 1);
+  }
+  const asked = new Map<string, number>();
+  for (const itemId of itemIds) {
+    asked.set(itemId, (asked.get(itemId) ?? 0) + 1);
+  }
+  for (const [itemId, count] of asked) {
+    const available = held.get(itemId) ?? 0;
+    if (count > available) {
+      return {
+        error: `Order ${order.order_id} holds ${available} of item ${itemId}, but ${count} were listed for return.`,
+      };
+    }
+  }
+
+  const itemNames = itemIds.map(
+    (id) => order.items.find((item) => item.item_id === id)?.name ?? id,
+  );
+  return {
+    readBack:
+      `return ${itemNames.join(", ")} from order ${order.order_id}, ` +
+      `with the refund going to ${paymentMethodId}`,
+    orderId: order.order_id,
+    itemIds: [...itemIds],
+    itemNames,
+    paymentMethodId,
+  };
+}
+
+export function applyReturn(state: RetailState, plan: ReturnPlan) {
+  const order = state.store.orders[plan.orderId];
+
+  // In the order the caller named them, not sorted: tau2 sorted this list to
+  // match an expected end state, and nothing compares against one any more.
+  if (order) {
+    order.status = "return requested";
+    order.return_items = [...plan.itemIds];
+    order.return_payment_method_id = plan.paymentMethodId;
+  }
+
+  return {
+    order_id: plan.orderId,
+    status: "return requested" as const,
+    return_items: plan.itemIds,
+    refund_to: plan.paymentMethodId,
+    message: `Return requested on ${plan.orderId} for ${plan.itemNames.join(", ")}. The customer will get an email with return instructions, and the refund goes to ${plan.paymentMethodId} once the items arrive.`,
+  };
+}

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

@@ -11,6 +11,7 @@ function makeState(authenticatedUserId: string | null): RetailState {
     callSeq: 3,
     activity: [{ seq: 3, tool: "get_order_details", summary: "read #W5866402", at: 0 }],
     focus: { orderId: "#W5866402" },
+    pending: null,
   };
 }
 
@@ -196,3 +197,44 @@ describe("buildScriptBullets", () => {
     expect(bullets.length).toBeLessThanOrEqual(6);
   });
 });
+
+describe("the staged change in the projection", () => {
+  function stagedState(authenticatedUserId: string | null): RetailState {
+    const state = makeState(authenticatedUserId);
+    state.pending = {
+      kind: "cancel_pending_order",
+      plan: {
+        readBack: "cancel order #W5866402 and refund $12.00 to gift_card_7794233",
+        orderId: "#W5866402",
+        reason: "no longer needed",
+        refunds: [{ methodId: "gift_card_7794233", amount: 12 }],
+        total: 12,
+      },
+    };
+    return state;
+  }
+
+  test("carries the sentence the agent is supposed to be reading back", () => {
+    const view = storeView(stagedState("olivia_ito_3591"));
+    expect(view.pending?.kind).toBe("cancel_pending_order");
+    expect(view.pending?.readBack).toContain("#W5866402");
+  });
+
+  test("is null when nothing is waiting", () => {
+    expect(storeView(makeState("olivia_ito_3591")).pending).toBeNull();
+  });
+
+  test("is withheld before authentication, like everything else here", () => {
+    // Unreachable in practice — a change cannot be staged before the caller is
+    // identified — but the projection does not lean on that: it gates `pending`
+    // on `user` exactly as it gates the orders it describes.
+    expect(storeView(stagedState(null)).pending).toBeNull();
+  });
+
+  test("the script offers the answer to the question, not a new request", () => {
+    expect(buildScriptBullets(stagedState("olivia_ito_3591"))).toEqual([
+      '"Yes, go ahead"',
+      `"No, don't do that"`,
+    ]);
+  });
+});

package/dist/templates/retail/shared.ts

@@ -1,4 +1,5 @@
 import type { DeepReadonly } from "@alexkroman1/aai";
+import type { PendingAction } from "./pending.ts";
 
 // ─── Store types ─────────────────────────────────────────────────────────────
 // Field names are tau2's snake_case verbatim, because `seed.json` is tau2's
@@ -129,6 +130,15 @@ export interface RetailState {
   callSeq: number;
   activity: ActivityEntry[];
   focus: { orderId?: string; productId?: string };
+  /**
+   * The change waiting on the caller's explicit yes, or null.
+   *
+   * Lives here and not in the flow because `callFlow` holds a POSITION —
+   * "something is waiting" — and this holds the thing itself, which is what
+   * `confirm_change` applies and what the sidebar renders. One tool call always
+   * moves both. See `pending.ts`.
+   */
+  pending: PendingAction | null;
 }
 
 /**
@@ -159,6 +169,7 @@ export function emptyRetailState(): RetailState {
     callSeq: 0,
     activity: [],
     focus: {},
+    pending: null,
   };
 }
 
@@ -204,6 +215,14 @@ export interface SwapOptionView {
   alternatives: { itemId: string; options: Record<string, string>; price: number }[];
 }
 
+/** The staged change, as the browser sees it: what it is and what the agent is
+ *  supposed to be reading back. The plan itself stays on the server — the panel
+ *  only has to show the caller's own words back to them. */
+export interface PendingView {
+  kind: PendingAction["kind"];
+  readBack: string;
+}
+
 export interface StoreView {
   customer: CustomerView | null;
   orders: OrderView[];
@@ -214,6 +233,10 @@ export interface StoreView {
   activity: ActivityEntry[];
   scriptBullets: string[];
   productCount: number;
+  /** Gated on `user` like everything else here: a change staged before the
+   *  caller was identified cannot exist, but the projection does not rely on
+   *  that — it withholds it the same way it withholds their orders. */
+  pending: PendingView | null;
 }
 
 export const MAX_SWAP_ITEMS = 3;
@@ -397,6 +420,10 @@ export function storeView(state: FrozenRetailState): StoreView {
       ...(state.focus.productId ? { productId: state.focus.productId } : {}),
     },
     swapOptions: swapOptionsFor(state, focusedOrder),
+    pending:
+      user && state.pending
+        ? { kind: state.pending.kind, readBack: state.pending.plan.readBack }
+        : null,
     callSeq: state.callSeq,
     activity: state.activity.slice(-MAX_ACTIVITY),
     scriptBullets: buildScriptBullets(state),
@@ -417,6 +444,14 @@ export function buildScriptBullets(state: FrozenRetailState): string[] {
   const userId = state.authenticatedUserId;
   const user = userId ? state.store.users[userId] : undefined;
 
+  // A staged change is a QUESTION the agent has just asked, so while one waits
+  // the only two useful things a caller can say are the answer to it. Offering
+  // "cancel my pending order" here would be offering an action the gate is
+  // about to refuse.
+  if (user && state.pending) {
+    return ['"Yes, go ahead"', '"No, don\'t do that"'];
+  }
+
   // Pre-auth: only the two ways in. The personas panel (a constant, rendered
   // straight from DEMO_PERSONAS) covers WHICH customer to be.
   if (!user) {

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

@@ -225,9 +225,11 @@ describe("retailTool", () => {
     const ctx = makeCtx();
     await gated.execute({}, ctx);
     const state = retailSlot.get(ctx);
-    // The gate short-circuits before the wrapper's body, so a blocked call no
-    // longer records an activity entry — the trade `retailTool`'s doc names.
-    // What it buys is that a refusal cannot half-write the store.
+    // The gate short-circuits before the wrapper's body, so the EXECUTION path
+    // writes nothing at all — which is what makes a refusal unable to half-write
+    // the store. The sidebar line for a blocked call comes from `agent.ts`'s
+    // `tool.called` hook instead, which is a different path and not under test
+    // here: see `registry.test.ts`.
     expect(state.callSeq).toBe(0);
     expect(state.activity).toEqual([]);
   });
@@ -245,7 +247,7 @@ describe("retailTool", () => {
     // the envelope this test is about, and a refusal fails here naming what the
     // flow said instead of reading `undefined` off a field nobody assigned.
     const answered = okPosition<{ ok: boolean }>(await gated.execute({}, ctx));
-    expect(answered).toMatchObject({ state: "serving", done: false });
+    expect(answered).toMatchObject({ state: "serving.helping", done: false });
     expect(answered.instruction).toMatch(/one identified customer/);
   });