@alexkroman1/aai-cli 6.11.0 → 8.0.0

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

@@ -1,11 +1,13 @@
 import type { ToolContext } from "@alexkroman1/aai";
 import { isToolFailure } from "@alexkroman1/aai";
-import { createToolContext } from "@alexkroman1/aai/testing";
+import { createToolContext, ok } from "@alexkroman1/aai/testing";
 import { describe, expect, test } from "vitest";
 import type { AuthResult } from "./authenticate.ts";
+import type { StagedResult } from "./pending.ts";
 import type { Address } from "./shared.ts";
-import { retailSlot } from "./store.ts";
+import { callFlow, retailSlot } from "./store.ts";
 import cancelPendingOrder from "./tools/cancel_pending_order.ts";
+import confirmChange from "./tools/confirm_change.ts";
 import exchangeDeliveredOrderItems from "./tools/exchange_delivered_order_items.ts";
 import findUserIdByEmail from "./tools/find_user_id_by_email.ts";
 import findUserIdByNameZip from "./tools/find_user_id_by_name_zip.ts";
@@ -27,27 +29,6 @@ function makeCtx(): ToolContext {
   return createToolContext();
 }
 
-/**
- * The success half of a tool result, or a thrown failure carrying the tool's
- * own message.
- *
- * `ToolDef["execute"]`'s public signature always returns `unknown` — the wire
- * type is fixed so any tool is assignable to `ToolDef`, whatever its body
- * really returns — so every test that reads a field back off a result needed a
- * cast. There were EIGHTEEN of them here, each the same three lines, which is
- * the shape the repo's guides call a missing typed seam: a concentration of
- * identical casts is one narrowing that belongs in one helper, not a cast per
- * assertion. This is that helper, and it is the file's only cast.
- *
- * It also removes the second half of the boilerplate: a `ToolFailure` fails the
- * test HERE, naming what the tool refused, rather than surfacing three lines
- * later as `undefined` on a field nobody assigned.
- */
-function ok<T>(result: unknown): T {
-  if (isToolFailure(result)) throw new Error(`tool refused: ${result.error}`);
-  return result as T;
-}
-
 /** A context already authenticated as `userId`, via the real tool. */
 async function authedCtx(email: string): Promise<ToolContext> {
   const ctx = makeCtx();
@@ -55,6 +36,26 @@ async function authedCtx(email: string): Promise<ToolContext> {
   return ctx;
 }
 
+/**
+ * Stage a change and say yes — the two calls one caller turn now produces.
+ *
+ * Nothing in this template mutates before `confirm_change`, so every spec about
+ * an APPLIED change has to run both halves. That is not helper ceremony: it is
+ * the property under test, and a spec that forgot the second call would find
+ * the store untouched. It asserts the readback exists on the way through,
+ * because a staged change the agent has no sentence for is the one shape that
+ * would let this gate pass while carrying nothing to confirm.
+ */
+async function confirmed<R = unknown>(staged: unknown, ctx: ToolContext): Promise<R> {
+  const stage = ok<StagedResult>(staged);
+  // A throw rather than an `expect`, which biome's `noMisplacedAssertion`
+  // rightly refuses outside a test body. A staged change with no sentence to
+  // read back is the one shape that would let the gate pass while carrying
+  // nothing to confirm, so it stops the spec here rather than downstream.
+  if (stage.read_back.length === 0) throw new Error(`${stage.staged} staged with no readback`);
+  return ok<R>(await confirmChange.execute({}, ctx));
+}
+
 describe("authentication", () => {
   test("find_user_id_by_email is case-insensitive and authenticates the session", async () => {
     const ctx = makeCtx();
@@ -63,6 +64,9 @@ describe("authentication", () => {
     );
     expect(result.user_id).toBe("olivia_ito_3591");
     expect(retailSlot.get(ctx).authenticatedUserId).toBe("olivia_ito_3591");
+    // Two facts, two homes: the store latches WHO, the flow holds WHETHER.
+    // `serving` is a parent now, so an identified call reports its child.
+    expect(callFlow.position(ctx).state).toBe("serving.helping");
   });
 
   test("an unknown email is refused and leaves the session unauthenticated", async () => {
@@ -70,6 +74,9 @@ describe("authentication", () => {
     const result = await findUserIdByEmail.execute({ email: "nobody@example.com" }, ctx);
     expect(isToolFailure(result)).toBe(true);
     expect(retailSlot.get(ctx).authenticatedUserId).toBeNull();
+    // `IDENTIFIED` is not sent when the body answers a `ToolFailure`, so a
+    // lookup that found nobody cannot leave the call one step ahead of itself.
+    expect(callFlow.position(ctx).state).toBe("identifying");
   });
 
   test("find_user_id_by_name_zip is case-insensitive on names and exact on zip", async () => {
@@ -121,6 +128,9 @@ describe("authentication", () => {
     );
     expect(isToolFailure(switched) && switched.error.toLowerCase()).toContain("one customer");
     expect(retailSlot.get(ctx).authenticatedUserId).toBe("olivia_ito_3591");
+    // The tool is legal in `serving` — the refusal comes from `authenticateAs`,
+    // not from the gate — so the call stays exactly where it was.
+    expect(callFlow.position(ctx).state).toBe("serving.helping");
   });
 
   test("switching via name + zip is refused too — both doors, one lock", async () => {
@@ -237,11 +247,12 @@ interface CancelOrderResult {
 describe("cancel_pending_order", () => {
   test("cancels a pending order and credits a gift card immediately", async () => {
     const ctx = await authedCtx("aarav.anderson9752@example.com");
-    const result = ok<CancelOrderResult>(
+    const result = await confirmed<CancelOrderResult>(
       await cancelPendingOrder.execute(
         { order_id: "#W9300146", reason: "ordered by mistake" },
         ctx,
       ),
+      ctx,
     );
     expect(result.status).toBe("cancelled");
     expect(result.refund_immediate).toBe(true);
@@ -256,7 +267,10 @@ describe("cancel_pending_order", () => {
 
   test("appends a matching refund to the payment history", async () => {
     const ctx = await authedCtx("aarav.anderson9752@example.com");
-    await cancelPendingOrder.execute({ order_id: "#W9300146", reason: "no longer needed" }, ctx);
+    await confirmed(
+      await cancelPendingOrder.execute({ order_id: "#W9300146", reason: "no longer needed" }, ctx),
+      ctx,
+    );
     const history = retailSlot.get(ctx).store.orders["#W9300146"]?.payment_history ?? [];
     expect(history).toHaveLength(2);
     expect(history[1]).toMatchObject({
@@ -268,8 +282,9 @@ describe("cancel_pending_order", () => {
 
   test("a non-gift-card refund takes 5-7 days and moves no balance", async () => {
     const ctx = await authedCtx("olivia.ito5204@example.com");
-    const result = ok<CancelOrderResult>(
+    const result = await confirmed<CancelOrderResult>(
       await cancelPendingOrder.execute({ order_id: "#W5442520", reason: "no longer needed" }, ctx),
+      ctx,
     );
     expect(result.refund_immediate).toBe(false);
     expect(result.message).toContain("5 to 7");
@@ -311,7 +326,10 @@ describe("cancel_pending_order", () => {
 
   test("refuses cancelling twice", async () => {
     const ctx = await authedCtx("aarav.anderson9752@example.com");
-    await cancelPendingOrder.execute({ order_id: "#W9300146", reason: "no longer needed" }, ctx);
+    await confirmed(
+      await cancelPendingOrder.execute({ order_id: "#W9300146", reason: "no longer needed" }, ctx),
+      ctx,
+    );
     const second = await cancelPendingOrder.execute(
       { order_id: "#W9300146", reason: "no longer needed" },
       ctx,
@@ -324,11 +342,12 @@ describe("cancel_pending_order", () => {
 
   test("resolves spoken shorthand to the single pending order", async () => {
     const ctx = await authedCtx("aarav.anderson9752@example.com");
-    const result = ok<CancelOrderResult>(
+    const result = await confirmed<CancelOrderResult>(
       await cancelPendingOrder.execute(
         { order_id: "my pending order", reason: "ordered by mistake" },
         ctx,
       ),
+      ctx,
     );
     expect(result.order_id).toBe("#W9300146");
   });
@@ -364,8 +383,9 @@ interface AddressToolResult {
 describe("modify_pending_order_address", () => {
   test("rewrites a pending order's shipping address", async () => {
     const ctx = await authedCtx("aarav.anderson9752@example.com");
-    const result = ok<AddressToolResult>(
+    const result = await confirmed<AddressToolResult>(
       await modifyPendingOrderAddress.execute({ order_id: "#W9300146", ...NEW_ADDRESS }, ctx),
+      ctx,
     );
     expect(result.address).toEqual(NEW_ADDRESS);
     expect(retailSlot.get(ctx).store.orders["#W9300146"]?.address).toEqual(NEW_ADDRESS);
@@ -373,7 +393,10 @@ describe("modify_pending_order_address", () => {
 
   test("leaves the customer's default address untouched", async () => {
     const ctx = await authedCtx("aarav.anderson9752@example.com");
-    await modifyPendingOrderAddress.execute({ order_id: "#W9300146", ...NEW_ADDRESS }, ctx);
+    await confirmed(
+      await modifyPendingOrderAddress.execute({ order_id: "#W9300146", ...NEW_ADDRESS }, ctx),
+      ctx,
+    );
     expect(retailSlot.get(ctx).store.users.aarav_anderson_8794?.address.zip).toBe("19031");
   });
 
@@ -413,14 +436,20 @@ describe("modify_pending_order_address", () => {
 describe("modify_user_address", () => {
   test("rewrites the customer's default address", async () => {
     const ctx = await authedCtx("emma.smith3991@example.com");
-    ok(await modifyUserAddress.execute({ user_id: "emma_smith_8564", ...NEW_ADDRESS }, ctx));
+    await confirmed(
+      await modifyUserAddress.execute({ user_id: "emma_smith_8564", ...NEW_ADDRESS }, ctx),
+      ctx,
+    );
     expect(retailSlot.get(ctx).store.users.emma_smith_8564?.address).toEqual(NEW_ADDRESS);
   });
 
   test("leaves existing orders' addresses untouched", async () => {
     const ctx = await authedCtx("emma.smith3991@example.com");
     const before = structuredClone(retailSlot.get(ctx).store.orders["#W2417020"]?.address);
-    await modifyUserAddress.execute({ user_id: "emma_smith_8564", ...NEW_ADDRESS }, ctx);
+    await confirmed(
+      await modifyUserAddress.execute({ user_id: "emma_smith_8564", ...NEW_ADDRESS }, ctx),
+      ctx,
+    );
     expect(retailSlot.get(ctx).store.orders["#W2417020"]?.address).toEqual(before);
   });
 
@@ -454,7 +483,7 @@ interface ModifyItemsResult {
 describe("modify_pending_order_items", () => {
   test("swaps an item, charges the difference to a gift card, and goes terminal", async () => {
     const ctx = await authedCtx("emma.smith3991@example.com");
-    const result = ok<ModifyItemsResult>(
+    const result = await confirmed<ModifyItemsResult>(
       await modifyPendingOrderItems.execute(
         {
           order_id: "#W2417020",
@@ -464,6 +493,7 @@ describe("modify_pending_order_items", () => {
         },
         ctx,
       ),
+      ctx,
     );
     expect(result.price_difference).toBe(-382.03);
     expect(result.status).toBe("pending (item modified)");
@@ -479,13 +509,16 @@ describe("modify_pending_order_items", () => {
 
   test("records the difference as a refund entry when the new item is cheaper", async () => {
     const ctx = await authedCtx("emma.smith3991@example.com");
-    await modifyPendingOrderItems.execute(
-      {
-        order_id: "#W2417020",
-        item_ids: ["8997785118"],
-        new_item_ids: ["6017636844"],
-        payment_method_id: "gift_card_8541487",
-      },
+    await confirmed(
+      await modifyPendingOrderItems.execute(
+        {
+          order_id: "#W2417020",
+          item_ids: ["8997785118"],
+          new_item_ids: ["6017636844"],
+          payment_method_id: "gift_card_8541487",
+        },
+        ctx,
+      ),
       ctx,
     );
     const history = retailSlot.get(ctx).store.orders["#W2417020"]?.payment_history ?? [];
@@ -498,13 +531,16 @@ describe("modify_pending_order_items", () => {
 
   test("refuses a second modification — the status is terminal", async () => {
     const ctx = await authedCtx("emma.smith3991@example.com");
-    await modifyPendingOrderItems.execute(
-      {
-        order_id: "#W2417020",
-        item_ids: ["8997785118"],
-        new_item_ids: ["6017636844"],
-        payment_method_id: "gift_card_8541487",
-      },
+    await confirmed(
+      await modifyPendingOrderItems.execute(
+        {
+          order_id: "#W2417020",
+          item_ids: ["8997785118"],
+          new_item_ids: ["6017636844"],
+          payment_method_id: "gift_card_8541487",
+        },
+        ctx,
+      ),
       ctx,
     );
     const second = await modifyPendingOrderItems.execute(
@@ -521,13 +557,16 @@ describe("modify_pending_order_items", () => {
 
   test("a modified order can no longer be cancelled", async () => {
     const ctx = await authedCtx("emma.smith3991@example.com");
-    await modifyPendingOrderItems.execute(
-      {
-        order_id: "#W2417020",
-        item_ids: ["8997785118"],
-        new_item_ids: ["6017636844"],
-        payment_method_id: "gift_card_8541487",
-      },
+    await confirmed(
+      await modifyPendingOrderItems.execute(
+        {
+          order_id: "#W2417020",
+          item_ids: ["8997785118"],
+          new_item_ids: ["6017636844"],
+          payment_method_id: "gift_card_8541487",
+        },
+        ctx,
+      ),
       ctx,
     );
     const cancelled = await cancelPendingOrder.execute(
@@ -565,7 +604,7 @@ describe("modify_pending_order_items", () => {
 
   test("the same upgrade succeeds on a payment method with no balance to run out of", async () => {
     const ctx = await authedCtx("anya.garcia2061@example.com");
-    const result = ok<ModifyItemsResult>(
+    const result = await confirmed<ModifyItemsResult>(
       await modifyPendingOrderItems.execute(
         {
           order_id: "#W6436609",
@@ -575,6 +614,7 @@ describe("modify_pending_order_items", () => {
         },
         ctx,
       ),
+      ctx,
     );
     expect(result.price_difference).toBe(167.37);
     const history = retailSlot.get(ctx).store.orders["#W6436609"]?.payment_history ?? [];
@@ -628,11 +668,12 @@ describe("modify_pending_order_payment", () => {
   test("moves an order to a different method, refunding the old one", async () => {
     const ctx = await authedCtx("olivia.ito5204@example.com");
     // #W5442520 is $663.85 on credit_card_9753331. Pay by PayPal instead.
-    const result = ok<ModifyPaymentResult>(
+    const result = await confirmed<ModifyPaymentResult>(
       await modifyPendingOrderPayment.execute(
         { order_id: "#W5442520", payment_method_id: "paypal_8049766" },
         ctx,
       ),
+      ctx,
     );
     expect(result.status).toBe("pending");
 
@@ -653,11 +694,13 @@ describe("modify_pending_order_payment", () => {
   test("refunds a gift card that was the original method", async () => {
     const ctx = await authedCtx("aarav.gonzalez9269@example.com");
     // #W9160732 is $1011.54 on gift_card_5979071 ($96.00). Move to PayPal.
-    const result = await modifyPendingOrderPayment.execute(
-      { order_id: "#W9160732", payment_method_id: "paypal_6121064" },
+    await confirmed(
+      await modifyPendingOrderPayment.execute(
+        { order_id: "#W9160732", payment_method_id: "paypal_6121064" },
+        ctx,
+      ),
       ctx,
     );
-    expect(isToolFailure(result)).toBe(false);
     const card =
       retailSlot.get(ctx).store.users.aarav_gonzalez_5113?.payment_methods.gift_card_5979071;
     expect(card?.source === "gift_card" && card.balance).toBe(1107.54);
@@ -744,7 +787,7 @@ interface ExchangeResult {
 describe("return_delivered_order_items", () => {
   test("requests a return refunded to the original method", async () => {
     const ctx = await authedCtx("harper.brown3965@example.com");
-    const result = ok<ReturnResult>(
+    const result = await confirmed<ReturnResult>(
       await returnDeliveredOrderItems.execute(
         {
           order_id: "#W1840144",
@@ -753,6 +796,7 @@ describe("return_delivered_order_items", () => {
         },
         ctx,
       ),
+      ctx,
     );
     expect(result.status).toBe("return requested");
     const order = retailSlot.get(ctx).store.orders["#W1840144"];
@@ -789,20 +833,25 @@ describe("return_delivered_order_items", () => {
     expect(retailSlot.get(ctx).store.orders["#W1840144"]?.status).toBe("delivered");
   });
 
-  test("returns both copies of a duplicate item and sorts the recorded list", async () => {
+  test("returns both copies of a duplicate item, in the order they were named", async () => {
     const ctx = await authedCtx("harper.brown3965@example.com");
-    const result = await returnDeliveredOrderItems.execute(
-      {
-        order_id: "#W1840144",
-        item_ids: ["8590708195", "6534134392", "8590708195"],
-        payment_method_id: "paypal_2306935",
-      },
+    await confirmed(
+      await returnDeliveredOrderItems.execute(
+        {
+          order_id: "#W1840144",
+          item_ids: ["8590708195", "6534134392", "8590708195"],
+          payment_method_id: "paypal_2306935",
+        },
+        ctx,
+      ),
       ctx,
     );
-    expect(isToolFailure(result)).toBe(false);
+    // Not sorted. tau2 sorted this list to match an expected end state and
+    // nothing compares against one any more, so it holds the caller's own
+    // order — which is the order the readback said them in.
     expect(retailSlot.get(ctx).store.orders["#W1840144"]?.return_items).toEqual([
-      "6534134392",
       "8590708195",
+      "6534134392",
       "8590708195",
     ]);
   });
@@ -832,8 +881,11 @@ describe("return_delivered_order_items", () => {
     );
     expect(isToolFailure(pending)).toBe(true);
 
-    await returnDeliveredOrderItems.execute(
-      { order_id: "#W1840144", item_ids: ["8590708195"], payment_method_id: "paypal_2306935" },
+    await confirmed(
+      await returnDeliveredOrderItems.execute(
+        { order_id: "#W1840144", item_ids: ["8590708195"], payment_method_id: "paypal_2306935" },
+        ctx,
+      ),
       ctx,
     );
     const again = await returnDeliveredOrderItems.execute(
@@ -847,7 +899,7 @@ describe("return_delivered_order_items", () => {
 describe("exchange_delivered_order_items", () => {
   test("records an exchange with a positive price difference", async () => {
     const ctx = await authedCtx("aarav.anderson9752@example.com");
-    const result = ok<ExchangeResult>(
+    const result = await confirmed<ExchangeResult>(
       await exchangeDeliveredOrderItems.execute(
         {
           order_id: "#W4316152",
@@ -857,6 +909,7 @@ describe("exchange_delivered_order_items", () => {
         },
         ctx,
       ),
+      ctx,
     );
     expect(result.price_difference).toBe(3.45);
     expect(result.exchanges).toEqual([
@@ -869,16 +922,16 @@ describe("exchange_delivered_order_items", () => {
     expect(order?.exchange_price_difference).toBe(3.45);
   });
 
-  test("the ANSWER pairs by position even where the stored fields sort separately", async () => {
+  test("the stored fields hold the pairing that was priced, not two sorted sets", async () => {
     // `#W5866402` is the case that makes the difference visible: the two
-    // requested replacements sort into the OTHER order, so the two stored lists
-    // — tau2's `sorted(item_ids)` / `sorted(new_item_ids)`, kept for fidelity
-    // with its expected end states — read as espresso→sneaker if anything
-    // treats them as a pairing. `planItemSwap` priced this positionally, so the
-    // result has to report the pairing that was priced, not the one the sort
-    // produced.
+    // requested replacements sort into the OTHER order. tau2 stored
+    // `sorted(item_ids)` / `sorted(new_item_ids)`, which read as
+    // espresso -> sneaker if anything treated them as a pairing — so the result
+    // had to carry the real pairing separately, and the stored fields were a
+    // trap for the next reader. Nothing is compared against a tau2 end state
+    // any more, so both hold what `planItemSwap` actually priced.
     const ctx = await authedCtx("olivia.ito5204@example.com");
-    const result = ok<ExchangeResult>(
+    const result = await confirmed<ExchangeResult>(
       await exchangeDeliveredOrderItems.execute(
         {
           order_id: "#W5866402",
@@ -888,6 +941,7 @@ describe("exchange_delivered_order_items", () => {
         },
         ctx,
       ),
+      ctx,
     );
 
     expect(result.exchanges).toEqual([
@@ -901,22 +955,24 @@ describe("exchange_delivered_order_items", () => {
       5,
     );
 
-    // The stored fields keep tau2's shape: two sorted SETS, and the second one
-    // really is in the other order.
+    // Positionally aligned with each other AND with `result.exchanges`.
     const order = retailSlot.get(ctx).store.orders["#W5866402"];
     expect(order?.exchange_items).toEqual(["6242772310", "9727387530"]);
-    expect(order?.exchange_new_items).toEqual(["2509076505", "7407838442"]);
+    expect(order?.exchange_new_items).toEqual(["7407838442", "2509076505"]);
   });
 
   test("does NOT move the gift-card balance — it is a request, not a settlement", async () => {
     const ctx = await authedCtx("aarav.anderson9752@example.com");
-    await exchangeDeliveredOrderItems.execute(
-      {
-        order_id: "#W4316152",
-        item_ids: ["7292993796"],
-        new_item_ids: ["3909406921"],
-        payment_method_id: "gift_card_7245904",
-      },
+    await confirmed(
+      await exchangeDeliveredOrderItems.execute(
+        {
+          order_id: "#W4316152",
+          item_ids: ["7292993796"],
+          new_item_ids: ["3909406921"],
+          payment_method_id: "gift_card_7245904",
+        },
+        ctx,
+      ),
       ctx,
     );
     const card =
@@ -926,13 +982,16 @@ describe("exchange_delivered_order_items", () => {
 
   test("leaves the order's items unchanged until the exchange is fulfilled", async () => {
     const ctx = await authedCtx("aarav.anderson9752@example.com");
-    await exchangeDeliveredOrderItems.execute(
-      {
-        order_id: "#W4316152",
-        item_ids: ["7292993796"],
-        new_item_ids: ["3909406921"],
-        payment_method_id: "gift_card_7245904",
-      },
+    await confirmed(
+      await exchangeDeliveredOrderItems.execute(
+        {
+          order_id: "#W4316152",
+          item_ids: ["7292993796"],
+          new_item_ids: ["3909406921"],
+          payment_method_id: "gift_card_7245904",
+        },
+        ctx,
+      ),
       ctx,
     );
     expect(retailSlot.get(ctx).store.orders["#W4316152"]?.items.map((i) => i.item_id)).toEqual([
@@ -943,7 +1002,7 @@ describe("exchange_delivered_order_items", () => {
 
   test("exchanges both copies of a duplicate and doubles the difference", async () => {
     const ctx = await authedCtx("aarav.anderson9752@example.com");
-    const result = ok<ExchangeResult>(
+    const result = await confirmed<ExchangeResult>(
       await exchangeDeliveredOrderItems.execute(
         {
           order_id: "#W4316152",
@@ -953,13 +1012,14 @@ describe("exchange_delivered_order_items", () => {
         },
         ctx,
       ),
+      ctx,
     );
     expect(result.price_difference).toBe(6.9);
   });
 
   test("records a negative difference as a refund direction", async () => {
     const ctx = await authedCtx("olivia.ito5204@example.com");
-    const result = ok<ExchangeResult>(
+    const result = await confirmed<ExchangeResult>(
       await exchangeDeliveredOrderItems.execute(
         {
           order_id: "#W5866402",
@@ -969,6 +1029,7 @@ describe("exchange_delivered_order_items", () => {
         },
         ctx,
       ),
+      ctx,
     );
     expect(result.price_difference).toBe(-40.86);
   });
@@ -1029,13 +1090,16 @@ describe("exchange_delivered_order_items", () => {
     );
     expect(isToolFailure(pending)).toBe(true);
 
-    await exchangeDeliveredOrderItems.execute(
-      {
-        order_id: "#W4316152",
-        item_ids: ["7292993796"],
-        new_item_ids: ["3909406921"],
-        payment_method_id: "gift_card_7245904",
-      },
+    await confirmed(
+      await exchangeDeliveredOrderItems.execute(
+        {
+          order_id: "#W4316152",
+          item_ids: ["7292993796"],
+          new_item_ids: ["3909406921"],
+          payment_method_id: "gift_card_7245904",
+        },
+        ctx,
+      ),
       ctx,
     );
     const again = await exchangeDeliveredOrderItems.execute(
@@ -1052,12 +1116,15 @@ describe("exchange_delivered_order_items", () => {
 
   test("a returned order can no longer be exchanged", async () => {
     const ctx = await authedCtx("aarav.anderson9752@example.com");
-    await returnDeliveredOrderItems.execute(
-      {
-        order_id: "#W4316152",
-        item_ids: ["7292993796"],
-        payment_method_id: "gift_card_7245904",
-      },
+    await confirmed(
+      await returnDeliveredOrderItems.execute(
+        {
+          order_id: "#W4316152",
+          item_ids: ["7292993796"],
+          payment_method_id: "gift_card_7245904",
+        },
+        ctx,
+      ),
       ctx,
     );
     const result = await exchangeDeliveredOrderItems.execute(
@@ -1090,4 +1157,20 @@ describe("transfer_to_human_agents", () => {
     expect(isToolFailure(result)).toBe(false);
     expect(result.transferred).toBe(true);
   });
+
+  test("the handoff is terminal, so the call cannot be worked afterwards", async () => {
+    const ctx = await authedCtx("olivia.ito5204@example.com");
+    ok(await transferToHumanAgents.execute({ summary: "wants a human" }, ctx));
+
+    const at = callFlow.position(ctx);
+    expect(at.state).toBe("transferred");
+    expect(at.done).toBe(true);
+
+    // The policy's "say nothing else after that" used to be enforced by
+    // nothing: every tool stayed callable, so a model that kept going kept
+    // acting on a call it had given away.
+    const refused = await getUserDetails.execute({ user_id: "olivia_ito_3591" }, ctx);
+    expect(isToolFailure(refused)).toBe(true);
+    expect(isToolFailure(refused) && refused.error).toContain('"transferred"');
+  });
 });

package/dist/templates/retail/agent.ts

@@ -1,6 +1,6 @@
 import { agent } from "@alexkroman1/aai";
 import { storeView } from "./shared.ts";
-import { retailSlot } from "./store.ts";
+import { callFlow, gateFor, record, retailSlot } from "./store.ts";
 
 export default agent({
   name: "Retail Support",
@@ -26,4 +26,38 @@ export default agent({
   greeting:
     "Thanks for calling. Before I can look anything up I'll need to find your account — " +
     "what's the email address on it?",
+
+  /**
+   * The activity feed's blocked lines, which no tool wrapper could write.
+   *
+   * `retailTool` records a line per call from INSIDE the body, so it sees every
+   * call the caller's own logic answered — and none that `callFlow` refused,
+   * because a gated refusal short-circuits before the body. The sidebar simply
+   * stopped showing the most interesting calls the model makes: the ones it
+   * tried too early.
+   *
+   * `tool.called` is emitted by the runtime for every call the model makes, so a
+   * hook is the only place that observation is available at all. It is also the
+   * shape of hook this template is here to show: it WRITES the session's state
+   * and it cannot speak — nothing here changes what the agent says, or stops the
+   * refusal still reaching the model. It does neither.
+   *
+   * The gate is evaluated a second time rather than reported by the first,
+   * because the refusal happens later and inside the body. That is one fact read
+   * twice from one source (`gateFor`, which `retailTool` fills), not two copies
+   * of it — and the only cost of the two evaluations disagreeing is a duplicate
+   * or missing sidebar line, never a wrong store.
+   */
+  events: {
+    "tool.called": (event, ctx) => {
+      const when = gateFor(event.toolName);
+      // Not a retail tool, or one this call may run: either way the wrapper owns
+      // the line, and writing one here would double it.
+      if (!when || when.some((state) => callFlow.matches(ctx, state))) return;
+      const at = callFlow.position(ctx);
+      retailSlot.update(ctx, (state) => {
+        record(state, event.toolName, `blocked: call is at ${at.state}`);
+      });
+    },
+  },
 });