@alexkroman1/aai-cli 5.13.2 → 6.1.0

package/dist/templates/retail/store.ts

@@ -1,5 +1,5 @@
-import type { ToolContext } from "@alexkroman1/aai";
-import { createKeyedLock, tool, withLock } from "@alexkroman1/aai";
+import type { ToolContext, ToolFailure } from "@alexkroman1/aai";
+import { isToolFailure, pushCapped, sessionSlot, toolFailure } from "@alexkroman1/aai";
 import type { z } from "zod";
 import seedJson from "./seed.json";
 import type {
@@ -8,12 +8,11 @@ import type {
   PaymentMethod,
   Product,
   RetailState,
-  StateSlot,
   Store,
   User,
   Variant,
 } from "./shared.ts";
-import { MAX_ACTIVITY } from "./shared.ts";
+import { emptyRetailState, MAX_ACTIVITY } from "./shared.ts";
 
 /**
  * The JSON import's inferred type has `status: string` where `Order` wants a
@@ -23,12 +22,6 @@ import { MAX_ACTIVITY } from "./shared.ts";
  */
 const SEED = seedJson as unknown as Store;
 
-export type ErrorResult = { error: string };
-
-export function isError(value: unknown): value is ErrorResult {
-  return typeof value === "object" && value !== null && "error" in value;
-}
-
 /** Round to cents. Gift-card balances and price differences are compared for
  *  equality, and raw float arithmetic makes that a coin toss. */
 export function money(n: number): number {
@@ -45,23 +38,39 @@ export function isGiftCard(method: PaymentMethod): method is GiftCard {
  *  module-level object shared by every session in the process, so a mutation
  *  without it would let one caller's cancellation show up in another's. */
 export function createDefaultState(): RetailState {
-  return {
-    store: structuredClone(SEED),
-    authenticatedUserId: null,
-    callSeq: 0,
-    activity: [],
-    focus: {},
-  };
+  return { ...emptyRetailState(), store: seedStore() };
 }
 
-/** The session's live store. Mutations to the returned object stick — it is
- *  the object held in `ctx.state`. */
-export function getState(ctx: ToolContext): RetailState {
-  const slot = ctx.state as StateSlot;
-  slot.retail ??= createDefaultState();
-  return slot.retail;
+/**
+ * A pristine deep copy of the seed store.
+ *
+ * Exported so a caller needs no cast of its own. `shared.test.ts` had written
+ * `structuredClone(seedJson) as unknown as Store` twice — a second and third
+ * copy of the narrowing this module already owns, each of which would keep
+ * compiling if `Store` grew a field the JSON does not carry. The one cast is
+ * `SEED`'s above, and `seed.test.ts` is what makes it honest.
+ */
+export function seedStore(): Store {
+  return structuredClone(SEED);
 }
 
+/**
+ * The session's store, as one typed slot.
+ *
+ * Every tool goes through `retailSlot.updateTool` (via `retailTool`), so every
+ * tool body is handed a mutable draft of the whole store and mutates it in
+ * place: the ~106 KB of catalogue here is exactly the state a functional replace
+ * would make unwritable without hand-built spread chains three levels deep.
+ * What makes that safe is that the window is SYNCHRONOUS — the LLM loop runs a
+ * step's tool calls concurrently, and a draft that cannot span an await cannot
+ * interleave with another one.
+ *
+ * No `after` hook — unlike dispatch-center, this store has no derived field to
+ * recalculate, and its one growth cap (`activity`) is held on append by
+ * `record` below.
+ */
+export const retailSlot = sessionSlot("retail", createDefaultState);
+
 export function setFocus(
   state: RetailState,
   focus: { orderId?: string; productId?: string },
@@ -71,15 +80,15 @@ export function setFocus(
 
 // ─── Lookups ─────────────────────────────────────────────────────────────────
 
-export function findUser(state: RetailState, userId: string): User | ErrorResult {
+export function findUser(state: RetailState, userId: string): User | ToolFailure {
   return state.store.users[userId] ?? { error: `User ${userId} not found.` };
 }
 
-export function findOrder(state: RetailState, orderId: string): Order | ErrorResult {
+export function findOrder(state: RetailState, orderId: string): Order | ToolFailure {
   return state.store.orders[orderId] ?? { error: `Order ${orderId} not found.` };
 }
 
-export function findProduct(state: RetailState, productId: string): Product | ErrorResult {
+export function findProduct(state: RetailState, productId: string): Product | ToolFailure {
   return (
     state.store.products[productId] ?? {
       error: `Product ${productId} not found. Note a product id is not an item id.`,
@@ -87,7 +96,7 @@ export function findProduct(state: RetailState, productId: string): Product | Er
   );
 }
 
-export function findVariant(product: Product, itemId: string): Variant | ErrorResult {
+export function findVariant(product: Product, itemId: string): Variant | ToolFailure {
   return (
     product.variants[itemId] ?? {
       error: `Item ${itemId} is not a variant of ${product.name} (${product.product_id}).`,
@@ -99,7 +108,7 @@ export function findVariant(product: Product, itemId: string): Variant | ErrorRe
 export function findItem(
   state: RetailState,
   itemId: string,
-): { product: Product; variant: Variant } | ErrorResult {
+): { product: Product; variant: Variant } | ToolFailure {
   for (const product of Object.values(state.store.products)) {
     const variant = product.variants[itemId];
     if (variant) return { product, variant };
@@ -107,7 +116,7 @@ export function findItem(
   return { error: `Item ${itemId} not found. Note an item id is not a product id.` };
 }
 
-export function findPaymentMethod(user: User, methodId: string): PaymentMethod | ErrorResult {
+export function findPaymentMethod(user: User, methodId: string): PaymentMethod | ToolFailure {
   return (
     user.payment_methods[methodId] ?? {
       error: `Payment method ${methodId} is not on this customer's profile. Available: ${Object.keys(
@@ -123,7 +132,7 @@ const NOT_AUTHENTICATED =
   "Not authenticated. Identify the customer first with find_user_id_by_email, " +
   "or find_user_id_by_name_zip if they cannot remember their email.";
 
-export function authenticatedUser(state: RetailState): User | ErrorResult {
+export function authenticatedUser(state: RetailState): User | ToolFailure {
   if (!state.authenticatedUserId) return { error: NOT_AUTHENTICATED };
   return findUser(state, state.authenticatedUserId);
 }
@@ -139,9 +148,9 @@ export function authenticatedUser(state: RetailState): User | ErrorResult {
  * matches every sibling lookup (`findUser`, `findOrder`, `findProduct`, …),
  * which all echo the id precisely so an LLM can target a repair retry.
  */
-export function requireOwnOrder(state: RetailState, orderId: string): Order | ErrorResult {
+export function requireOwnOrder(state: RetailState, orderId: string): Order | ToolFailure {
   const user = authenticatedUser(state);
-  if (isError(user)) return user;
+  if (isToolFailure(user)) return user;
   const order = state.store.orders[orderId];
   if (!order || order.user_id !== user.user_id) {
     return { error: `Order ${orderId} was not found on this customer's account.` };
@@ -149,32 +158,6 @@ export function requireOwnOrder(state: RetailState, orderId: string): Order | Er
   return order;
 }
 
-// ─── Serialized state updates ────────────────────────────────────────────────
-
-const sessionLock = createKeyedLock();
-
-/**
- * Serialized update of the session's store.
- *
- * The LLM loop can execute parallel tool calls, and a mutator may be async —
- * two interleaving async mutators can each observe the other's half-applied
- * changes. Holding the session's key runs each update against the previous
- * one's finished result. `createKeyedLock` is the SDK's primitive for exactly
- * this; the hand-rolled promise chain it replaced also had to remember to drop
- * each key's entry by ownership once idle.
- *
- * NOT exported, unlike dispatch-center's equivalent. `retailTool` is the only
- * caller, so a tool body cannot re-enter it — which would wait on a key only
- * the outer call can release, i.e. deadlock. A hazard you can't reach beats a
- * hazard you documented.
- */
-function updateState<R>(
-  ctx: ToolContext,
-  mutator: (state: RetailState) => R | Promise<R>,
-): Promise<R> {
-  return withLock(sessionLock, ctx.sessionId, async () => mutator(getState(ctx)));
-}
-
 // ─── The tool wrapper ────────────────────────────────────────────────────────
 
 interface RetailToolSpec<S extends z.ZodType<Record<string, unknown>>, R> {
@@ -188,15 +171,43 @@ interface RetailToolSpec<S extends z.ZodType<Record<string, unknown>>, R> {
    *  out; everything else touches customer data. */
   requiresAuth?: boolean;
   summary: (args: z.output<S>, result: R) => string;
-  execute: (args: z.output<S>, ctx: ToolContext) => R | Promise<R>;
+  /**
+   * Handed the store as its second argument, and SYNCHRONOUS.
+   *
+   * **Declare it BEFORE `summary` in the object literal.** TS infers this
+   * wrapper's generic `R` from `execute`'s return type and processes an object
+   * literal's properties in SOURCE ORDER, so with `summary` written first its
+   * `result` parameter has nothing to infer from and silently falls back to
+   * `unknown` — every `isToolFailure(result) ? … : result.order_id` in the
+   * fifteen tool files then stops compiling, or worse, stops meaning anything.
+   * It lives here rather than in each tool file because it is a property of
+   * this type: the same four lines were pasted into eight of the fifteen and
+   * pointed at from five more, which is a rule maintained in fourteen places.
+   *
+   * ---
+   *
+   * **The draft is passed in rather than re-read**, which is the one change the
+   * durable store forced on this template. The body used to open with
+   * `retailSlot.get(ctx)`; under the draft write model that returns the value as
+   * it was BEFORE this call, frozen, so a body that mutated it would be writing
+   * to something nothing was going to store. Passing it removes the possibility
+   * rather than documenting it.
+   *
+   * Synchronous for the same reason: the window cannot span an await — see
+   * {@link SessionSlot.update}. Every tool here is a pure function of the store,
+   * so none of them wants to; a tool that DID would await outside the wrapper and
+   * call `retailSlot.update` itself, the way `plan-and-execute`'s do.
+   */
+  execute: (args: z.output<S>, state: RetailState, ctx: ToolContext) => R;
 }
 
 function record(state: RetailState, name: string, summary: string): void {
   state.callSeq += 1;
-  state.activity.push({ seq: state.callSeq, tool: name, summary, at: Date.now() });
-  if (state.activity.length > MAX_ACTIVITY) {
-    state.activity = state.activity.slice(-MAX_ACTIVITY);
-  }
+  pushCapped(
+    state.activity,
+    { seq: state.callSeq, tool: name, summary, at: Date.now() },
+    MAX_ACTIVITY,
+  );
 }
 
 /**
@@ -215,23 +226,25 @@ export function retailTool<S extends z.ZodType<Record<string, unknown>>, R>(
   spec: RetailToolSpec<S, R>,
 ) {
   const requiresAuth = spec.requiresAuth ?? true;
-  return tool({
+  // `updateTool` rather than `tool` + a hand-written `retailSlot.update`: it runs
+  // the body inside the slot's mutation window and hands it the draft, so this
+  // wrapper is left with only what is specific to THIS agent.
+  return retailSlot.updateTool({
     description: spec.description,
     inputSchema: spec.inputSchema,
-    execute: (args, ctx) =>
-      updateState(ctx, async (state) => {
-        const typedArgs = args as z.output<S>;
-        if (requiresAuth && !state.authenticatedUserId) {
-          record(state, spec.name, "blocked: not authenticated");
-          return { error: NOT_AUTHENTICATED };
-        }
-        const result = await spec.execute(typedArgs, ctx);
-        record(
-          state,
-          spec.name,
-          isError(result) ? `error: ${result.error}` : spec.summary(typedArgs, result),
-        );
-        return result;
-      }),
+    execute: (args, state, ctx) => {
+      const typedArgs = args as z.output<S>;
+      if (requiresAuth && !state.authenticatedUserId) {
+        record(state, spec.name, "blocked: not authenticated");
+        return toolFailure(NOT_AUTHENTICATED);
+      }
+      const result = spec.execute(typedArgs, state, ctx);
+      record(
+        state,
+        spec.name,
+        isToolFailure(result) ? `error: ${result.error}` : spec.summary(typedArgs, result),
+      );
+      return result;
+    },
   });
 }

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

@@ -1,5 +1,6 @@
+import { isToolFailure } from "@alexkroman1/aai";
 import { describe, expect, test } from "vitest";
-import { createDefaultState, findUser, isError } from "./store.ts";
+import { createDefaultState, findUser } from "./store.ts";
 import { applySwap, assertCanCoverDiff, planItemSwap } from "./swap.ts";
 
 function fixture(orderId: string) {
@@ -15,7 +16,7 @@ describe("planItemSwap", () => {
     const plan = planItemSwap(state, order, ["1304426904"], ["4725166838"], {
       requireDifferent: true,
     });
-    if (isError(plan)) throw new Error(plan.error);
+    if (isToolFailure(plan)) throw new Error(plan.error);
     expect(plan.diff).toBe(36.32);
     expect(plan.pairs).toHaveLength(1);
     expect(plan.pairs[0]?.newVariant.item_id).toBe("4725166838");
@@ -26,7 +27,7 @@ describe("planItemSwap", () => {
     const plan = planItemSwap(state, order, ["6242772310"], ["6200867091"], {
       requireDifferent: true,
     });
-    expect(isError(plan) ? null : plan.diff).toBe(-40.86);
+    expect(isToolFailure(plan) ? null : plan.diff).toBe(-40.86);
   });
 
   test("handles a duplicate item id swapped twice", () => {
@@ -38,7 +39,7 @@ describe("planItemSwap", () => {
       ["3909406921", "3909406921"],
       { requireDifferent: true },
     );
-    if (isError(plan)) throw new Error(plan.error);
+    if (isToolFailure(plan)) throw new Error(plan.error);
     expect(plan.diff).toBe(6.9);
     expect(plan.pairs.map((p) => p.index)).toEqual([0, 1]);
   });
@@ -48,7 +49,7 @@ describe("planItemSwap", () => {
     const plan = planItemSwap(state, order, ["7292993796"], ["3909406921"], {
       requireDifferent: true,
     });
-    if (isError(plan)) throw new Error(plan.error);
+    if (isToolFailure(plan)) throw new Error(plan.error);
     expect(plan.pairs).toHaveLength(1);
     expect(plan.diff).toBe(3.45);
   });
@@ -62,7 +63,7 @@ describe("planItemSwap", () => {
       ["3909406921", "3909406921", "3909406921"],
       { requireDifferent: true },
     );
-    expect(isError(plan) && plan.error).toContain("7292993796");
+    expect(isToolFailure(plan) && plan.error).toContain("7292993796");
   });
 
   test("refuses mismatched list lengths", () => {
@@ -70,12 +71,14 @@ describe("planItemSwap", () => {
     const plan = planItemSwap(state, order, ["7292993796"], ["3909406921", "3738831434"], {
       requireDifferent: true,
     });
-    expect(isError(plan) && plan.error.toLowerCase()).toContain("same number");
+    expect(isToolFailure(plan) && plan.error.toLowerCase()).toContain("same number");
   });
 
   test("refuses an empty swap", () => {
     const { state, order } = fixture("#W4316152");
-    expect(isError(planItemSwap(state, order, [], [], { requireDifferent: true }))).toBe(true);
+    expect(isToolFailure(planItemSwap(state, order, [], [], { requireDifferent: true }))).toBe(
+      true,
+    );
   });
 
   test("refuses an item the order does not contain", () => {
@@ -83,7 +86,7 @@ describe("planItemSwap", () => {
     const plan = planItemSwap(state, order, ["1304426904"], ["4725166838"], {
       requireDifferent: true,
     });
-    expect(isError(plan)).toBe(true);
+    expect(isToolFailure(plan)).toBe(true);
   });
 
   test("refuses a target of a different product", () => {
@@ -91,7 +94,7 @@ describe("planItemSwap", () => {
     const plan = planItemSwap(state, order, ["7292993796"], ["4725166838"], {
       requireDifferent: true,
     });
-    expect(isError(plan) && plan.error).toContain("Tea Kettle");
+    expect(isToolFailure(plan) && plan.error).toContain("Tea Kettle");
   });
 
   test("refuses an unavailable target", () => {
@@ -99,7 +102,7 @@ describe("planItemSwap", () => {
     const plan = planItemSwap(state, order, ["7292993796"], ["6454334990"], {
       requireDifferent: true,
     });
-    expect(isError(plan) && plan.error.toLowerCase()).toContain("not available");
+    expect(isToolFailure(plan) && plan.error.toLowerCase()).toContain("not available");
   });
 
   test("requireDifferent refuses a no-op swap; exchange allows it", () => {
@@ -107,11 +110,11 @@ describe("planItemSwap", () => {
     const strict = planItemSwap(state, order, ["7292993796"], ["7292993796"], {
       requireDifferent: true,
     });
-    expect(isError(strict)).toBe(true);
+    expect(isToolFailure(strict)).toBe(true);
     const loose = planItemSwap(state, order, ["7292993796"], ["7292993796"], {
       requireDifferent: false,
     });
-    expect(isError(loose) ? null : loose.diff).toBe(0);
+    expect(isToolFailure(loose) ? null : loose.diff).toBe(0);
   });
 });
 
@@ -119,7 +122,7 @@ describe("assertCanCoverDiff", () => {
   function aarav() {
     const state = createDefaultState();
     const user = findUser(state, "aarav_anderson_8794");
-    if (isError(user)) throw new Error(user.error);
+    if (isToolFailure(user)) throw new Error(user.error);
     return user;
   }
 
@@ -140,7 +143,7 @@ describe("assertCanCoverDiff", () => {
   test("does not gate a non-gift-card method on any balance", () => {
     const state = createDefaultState();
     const olivia = findUser(state, "olivia_ito_3591");
-    if (isError(olivia)) throw new Error(olivia.error);
+    if (isToolFailure(olivia)) throw new Error(olivia.error);
     expect(assertCanCoverDiff(olivia, "credit_card_9753331", 100_000)).toBeNull();
   });
 
@@ -161,7 +164,7 @@ describe("applySwap", () => {
       ["4725166838", "3909406921"],
       { requireDifferent: true },
     );
-    if (isError(plan)) throw new Error(plan.error);
+    if (isToolFailure(plan)) throw new Error(plan.error);
     applySwap(order, plan);
 
     const vacuum = order.items.find((i) => i.item_id === "4725166838");
@@ -179,7 +182,7 @@ describe("applySwap", () => {
     const plan = planItemSwap(state, order, ["7292993796"], ["3909406921"], {
       requireDifferent: true,
     });
-    if (isError(plan)) throw new Error(plan.error);
+    if (isToolFailure(plan)) throw new Error(plan.error);
     applySwap(order, plan);
     expect(order.items.map((i) => i.item_id)).toEqual(["3909406921", "7292993796"]);
   });

package/dist/templates/retail/swap.ts

@@ -1,13 +1,6 @@
+import { isToolFailure, type ToolFailure } from "@alexkroman1/aai";
 import type { Order, OrderItem, RetailState, User, Variant } from "./shared.ts";
-import {
-  type ErrorResult,
-  findPaymentMethod,
-  findProduct,
-  findVariant,
-  isError,
-  isGiftCard,
-  money,
-} from "./store.ts";
+import { findPaymentMethod, findProduct, findVariant, isGiftCard, money } from "./store.ts";
 
 export interface SwapPair {
   /** Index into `order.items`. Matching by index rather than by "first item
@@ -37,7 +30,7 @@ export function planItemSwap(
   itemIds: string[],
   newItemIds: string[],
   opts: { requireDifferent: boolean },
-): SwapPlan | ErrorResult {
+): SwapPlan | ToolFailure {
   if (itemIds.length === 0) {
     return { error: "No items were listed to change." };
   }
@@ -89,10 +82,10 @@ export function planItemSwap(
     consumed.add(index);
 
     const product = findProduct(state, item.product_id);
-    if (isError(product)) return product;
+    if (isToolFailure(product)) return product;
 
     const newVariant = findVariant(product, newItemId);
-    if (isError(newVariant)) {
+    if (isToolFailure(newVariant)) {
       return {
         error: `${newItemId} is not an option of ${product.name} (${product.product_id}). An item can only be changed to a different option of the same product — you cannot change a ${product.name} into something else.`,
       };
@@ -114,9 +107,9 @@ export function planItemSwap(
  * Gate the price difference on the chosen payment method. Only a gift card has
  * a balance to run out of; a negative difference is a refund and never gated.
  */
-export function assertCanCoverDiff(user: User, methodId: string, diff: number): ErrorResult | null {
+export function assertCanCoverDiff(user: User, methodId: string, diff: number): ToolFailure | null {
   const method = findPaymentMethod(user, methodId);
-  if (isError(method)) return method;
+  if (isToolFailure(method)) return method;
   if (isGiftCard(method) && method.balance < diff) {
     return {
       error: `Gift card ${methodId}'s balance ($${method.balance.toFixed(2)}) does not cover the $${diff.toFixed(2)} difference. Ask for another payment method.`,

package/dist/templates/retail/tools/cancel_pending_order.ts

@@ -1,12 +1,13 @@
+import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
 import { creditRefund, REFUND_DELAY_NOTE, REFUND_IMMEDIATE_NOTE } from "../refund.ts";
 import { resolveOrder } from "../resolve.ts";
-import { authenticatedUser, getState, isError, retailTool, setFocus } from "../store.ts";
+import { authenticatedUser, retailTool, setFocus } from "../store.ts";
 
 /** tau2 accepts exactly these two. Anything else is refused. */
 const CANCEL_REASONS = ["no longer needed", "ordered by mistake"] as const;
 
-export const cancelPendingOrder = retailTool({
+export default retailTool({
   name: "cancel_pending_order",
   description:
     "Cancel a pending order. Only an order whose status is exactly 'pending' can be cancelled — " +
@@ -22,17 +23,12 @@ export const cancelPendingOrder = retailTool({
       .enum(CANCEL_REASONS)
       .describe("Either 'no longer needed' or 'ordered by mistake' — no other reason is accepted"),
   }),
-  // `execute` before `summary`: TS infers the wrapper's generic `R` from
-  // `execute`'s return type, and processes object literal properties in
-  // source order — with `summary` first, `result` in its signature can't be
-  // inferred and silently falls back to `unknown`.
-  execute: (args, ctx) => {
-    const state = getState(ctx);
+  execute: (args, state) => {
     const user = authenticatedUser(state);
-    if (isError(user)) return user;
+    if (isToolFailure(user)) return user;
 
     const order = resolveOrder(state, args.order_id);
-    if (isError(order)) return order;
+    if (isToolFailure(order)) return order;
     setFocus(state, { orderId: order.order_id });
 
     if (order.status !== "pending") {
@@ -78,5 +74,5 @@ export const cancelPendingOrder = retailTool({
     };
   },
   summary: (_args, result) =>
-    "error" in result ? "cancel failed" : `cancelled ${result.order_id}`,
+    isToolFailure(result) ? "cancel failed" : `cancelled ${result.order_id}`,
 });

package/dist/templates/retail/tools/exchange_delivered_order_items.ts

@@ -1,9 +1,10 @@
+import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
 import { resolveOrder } from "../resolve.ts";
-import { authenticatedUser, getState, isError, retailTool, setFocus } from "../store.ts";
+import { authenticatedUser, money, retailTool, setFocus } from "../store.ts";
 import { assertCanCoverDiff, planItemSwap } from "../swap.ts";
 
-export const exchangeDeliveredOrderItems = retailTool({
+export default retailTool({
   name: "exchange_delivered_order_items",
   description:
     "Request an exchange of items in a delivered order for different options of the SAME products. " +
@@ -29,17 +30,12 @@ export const exchangeDeliveredOrderItems = retailTool({
       .max(80)
       .describe("Method to charge or refund the price difference"),
   }),
-  // `execute` before `summary`: TS infers the wrapper's generic `R` from
-  // `execute`'s return type, and processes object literal properties in
-  // source order — with `summary` first, `result` in its signature can't be
-  // inferred and silently falls back to `unknown`.
-  execute: (args, ctx) => {
-    const state = getState(ctx);
+  execute: (args, state) => {
     const user = authenticatedUser(state);
-    if (isError(user)) return user;
+    if (isToolFailure(user)) return user;
 
     const order = resolveOrder(state, args.order_id);
-    if (isError(order)) return order;
+    if (isToolFailure(order)) return order;
     setFocus(state, { orderId: order.order_id });
 
     if (order.status !== "delivered") {
@@ -53,7 +49,7 @@ export const exchangeDeliveredOrderItems = retailTool({
     const plan = planItemSwap(state, order, args.item_ids, args.new_item_ids, {
       requireDifferent: false,
     });
-    if (isError(plan)) return plan;
+    if (isToolFailure(plan)) return plan;
 
     const blocked = assertCanCoverDiff(user, args.payment_method_id, plan.diff);
     if (blocked) return blocked;
@@ -61,6 +57,18 @@ export const exchangeDeliveredOrderItems = retailTool({
     // No balance moves and no items change: this records a REQUEST. The money
     // and the item swap settle when the originals come back.
     order.status = "exchange requested";
+    // SORTED INDEPENDENTLY, verbatim from tau2 (`order.exchange_items =
+    // sorted(item_ids)` / `sorted(new_item_ids)`, the same shape
+    // `return_delivered_order_items` uses one list of) — kept because
+    // `seed.json` is tau2's data and these fields are what a tau2 task's
+    // expected end state is compared against. They are therefore two SETS of
+    // ids, not a pairing: sorting each list separately permutes the second
+    // against the first whenever the caller named more than one item.
+    //
+    // Which is why the ANSWER carries `exchanges` instead. `planItemSwap`
+    // priced this positionally, so returning the two sorted lists as if they
+    // lined up told the caller a pairing the quote was not for — the one thing
+    // this result must not do, since the model reads it back down a phone.
     order.exchange_items = [...args.item_ids].sort();
     order.exchange_new_items = [...args.new_item_ids].sort();
     order.exchange_payment_method_id = args.payment_method_id;
@@ -70,8 +78,12 @@ export const exchangeDeliveredOrderItems = retailTool({
       order_id: order.order_id,
       status: order.status,
       price_difference: plan.diff,
-      exchange_items: order.exchange_items,
-      exchange_new_items: order.exchange_new_items,
+      // The pairing AS PRICED, per line, in the order the caller gave it.
+      exchanges: plan.pairs.map((pair) => ({
+        item_id: pair.item.item_id,
+        new_item_id: pair.newVariant.item_id,
+        price_difference: money(pair.newVariant.price - pair.item.price),
+      })),
       message:
         plan.diff > 0
           ? `Exchange requested on ${order.order_id}. $${plan.diff.toFixed(2)} will be charged to ${args.payment_method_id}. An email with return instructions is on its way.`
@@ -79,5 +91,5 @@ export const exchangeDeliveredOrderItems = retailTool({
     };
   },
   summary: (_args, result) =>
-    "error" in result ? "exchange failed" : `exchange requested on ${result.order_id}`,
+    isToolFailure(result) ? "exchange failed" : `exchange requested on ${result.order_id}`,
 });

package/dist/templates/retail/tools/find_user_id_by_email.ts

@@ -1,8 +1,9 @@
+import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
 import { authenticateAs } from "../authenticate.ts";
-import { getState, retailTool } from "../store.ts";
+import { retailTool } from "../store.ts";
 
-export const findUserIdByEmail = retailTool({
+export default retailTool({
   name: "find_user_id_by_email",
   description:
     "Find a customer's user id by their email address. This is how you authenticate the caller — " +
@@ -12,12 +13,7 @@ export const findUserIdByEmail = retailTool({
     email: z.string().max(200).describe("The customer's email, e.g. 'something@example.com'"),
   }),
   requiresAuth: false,
-  // `execute` must come before `summary` in this object literal: TS infers the
-  // wrapper's generic `R` from `execute`'s return type, and processes object
-  // literal properties in source order — with `summary` first, `result` in its
-  // signature can't be inferred and silently falls back to `unknown`.
-  execute: (args, ctx) => {
-    const state = getState(ctx);
+  execute: (args, state) => {
     const target = args.email.trim().toLowerCase();
     const match = Object.values(state.store.users).find(
       (user) => user.email.toLowerCase() === target,
@@ -28,5 +24,5 @@ export const findUserIdByEmail = retailTool({
     return authenticateAs(state, match);
   },
   summary: (_args, result) =>
-    "error" in result ? "lookup failed" : `identified ${result.user_id}`,
+    isToolFailure(result) ? "lookup failed" : `identified ${result.user_id}`,
 });

package/dist/templates/retail/tools/find_user_id_by_name_zip.ts

@@ -1,8 +1,9 @@
+import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
 import { authenticateAs } from "../authenticate.ts";
-import { getState, retailTool } from "../store.ts";
+import { retailTool } from "../store.ts";
 
-export const findUserIdByNameZip = retailTool({
+export default retailTool({
   name: "find_user_id_by_name_zip",
   description:
     "Find a customer's user id by first name, last name and zip code. Use this only when the " +
@@ -13,10 +14,7 @@ export const findUserIdByNameZip = retailTool({
     zip: z.string().max(20).describe("Zip code, e.g. '12345'"),
   }),
   requiresAuth: false,
-  // `execute` before `summary`: see find_user_id_by_email.ts for why the order
-  // is load-bearing for the generic `result` type in `summary`.
-  execute: (args, ctx) => {
-    const state = getState(ctx);
+  execute: (args, state) => {
     const first = args.first_name.trim().toLowerCase();
     const last = args.last_name.trim().toLowerCase();
     const zip = args.zip.replace(/\D/g, "");
@@ -34,5 +32,5 @@ export const findUserIdByNameZip = retailTool({
     return authenticateAs(state, match);
   },
   summary: (_args, result) =>
-    "error" in result ? "lookup failed" : `identified ${result.user_id}`,
+    isToolFailure(result) ? "lookup failed" : `identified ${result.user_id}`,
 });