@alexkroman1/aai-cli 5.13.2 → 5.14.0

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

@@ -1,4 +1,5 @@
-import type { ToolContext } from "@alexkroman1/aai";
+import { isToolFailure, type ToolContext } from "@alexkroman1/aai";
+import { createToolContext } from "@alexkroman1/aai/testing";
 import { describe, expect, test } from "vitest";
 import { z } from "zod";
 import {
@@ -10,31 +11,23 @@ import {
   findProduct,
   findUser,
   findVariant,
-  getState,
-  isError,
   isGiftCard,
   money,
   requireOwnOrder,
+  retailSlot,
   retailTool,
+  type StateSlot,
 } from "./store.ts";
 
-let sessionCounter = 0;
-
-function makeCtx(): ToolContext {
-  return {
-    sessionId: `test-session-${++sessionCounter}`,
-    send: () => {},
-    env: {},
-    state: {},
-    messages: [],
-  } as unknown as ToolContext;
+function makeCtx(): ToolContext<StateSlot> {
+  return createToolContext<StateSlot>();
 }
 
 describe("session state", () => {
-  test("getState seeds lazily and returns the same object on re-entry", () => {
+  test("the slot seeds lazily and returns the same object on re-entry", () => {
     const ctx = makeCtx();
-    const a = getState(ctx);
-    const b = getState(ctx);
+    const a = retailSlot.get(ctx);
+    const b = retailSlot.get(ctx);
     expect(a).toBe(b);
     expect(a.authenticatedUserId).toBeNull();
     expect(a.callSeq).toBe(0);
@@ -42,14 +35,14 @@ describe("session state", () => {
   });
 
   test("each session gets its own deep copy — a mutation cannot leak across sessions", () => {
-    const first = getState(makeCtx());
+    const first = retailSlot.get(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());
+    const second = retailSlot.get(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);
@@ -67,52 +60,52 @@ describe("money", () => {
 describe("lookups", () => {
   test("findUser resolves and reports a miss by id", () => {
     const state = createDefaultState();
-    expect(isError(findUser(state, "olivia_ito_3591"))).toBe(false);
+    expect(isToolFailure(findUser(state, "olivia_ito_3591"))).toBe(false);
     const miss = findUser(state, "nobody_1");
-    expect(isError(miss) && miss.error).toContain("nobody_1");
+    expect(isToolFailure(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);
+    expect(isToolFailure(order)).toBe(false);
+    expect(isToolFailure(order) ? null : order.status).toBe("delivered");
+    expect(isToolFailure(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);
+    if (isToolFailure(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);
+    expect(isToolFailure(variant) ? null : variant.price).toBe(98.25);
     // A real item id, but of a different product.
-    expect(isError(findVariant(product, "4725166838"))).toBe(true);
+    expect(isToolFailure(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);
+    if (isToolFailure(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);
+    expect(isToolFailure(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);
+    if (isToolFailure(olivia)) throw new Error(olivia.error);
+    expect(isToolFailure(findPaymentMethod(olivia, "gift_card_7794233"))).toBe(false);
     // aarav's card is not olivia's.
-    expect(isError(findPaymentMethod(olivia, "gift_card_7245904"))).toBe(true);
+    expect(isToolFailure(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);
+    if (isToolFailure(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);
@@ -124,15 +117,15 @@ 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");
+    expect(isToolFailure(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(isToolFailure(result)).toBe(true);
+    if (!isToolFailure(result)) throw new Error("expected refusal");
     expect(result.error).not.toContain("aarav");
     expect(result.error).not.toContain("Tea Kettle");
   });
@@ -144,8 +137,8 @@ describe("ownership and authentication guards", () => {
     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");
+    expect(isToolFailure(foreign) && isToolFailure(missing)).toBe(true);
+    if (!(isToolFailure(foreign) && isToolFailure(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
@@ -161,7 +154,7 @@ describe("ownership and authentication guards", () => {
     const state = createDefaultState();
     state.authenticatedUserId = "olivia_ito_3591";
     const result = requireOwnOrder(state, "#W5866402");
-    expect(isError(result) ? null : result.order_id).toBe("#W5866402");
+    expect(isToolFailure(result) ? null : result.order_id).toBe("#W5866402");
   });
 });
 
@@ -196,7 +189,7 @@ describe("retailTool", () => {
     const ctx = makeCtx();
     await echo.execute({ value: "a" }, ctx);
     await echo.execute({ value: "b" }, ctx);
-    const state = getState(ctx);
+    const state = retailSlot.get(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"]);
@@ -205,28 +198,28 @@ describe("retailTool", () => {
   test("a repeated identical call still changes the projection", async () => {
     const ctx = makeCtx();
     await echo.execute({ value: "same" }, ctx);
-    const first = getState(ctx).callSeq;
+    const first = retailSlot.get(ctx).callSeq;
     await echo.execute({ value: "same" }, ctx);
-    expect(getState(ctx).callSeq).toBeGreaterThan(first);
+    expect(retailSlot.get(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");
+    expect(isToolFailure(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);
+    const state = retailSlot.get(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";
+    retailSlot.get(ctx).authenticatedUserId = "olivia_ito_3591";
     const result = await gated.execute({}, ctx);
     expect(result).toEqual({ ok: true });
   });
@@ -234,13 +227,13 @@ describe("retailTool", () => {
   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");
+    expect(retailSlot.get(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);
+    const state = retailSlot.get(ctx);
     expect(state.callSeq).toBe(15);
     expect(state.activity).toHaveLength(10);
     expect(state.activity[0]?.summary).toBe("echoed 5");
@@ -249,7 +242,7 @@ describe("retailTool", () => {
   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);
+    const state = retailSlot.get(ctx);
     expect(state.callSeq).toBe(8);
     expect(new Set(state.activity.map((a) => a.seq)).size).toBe(state.activity.length);
   });

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, type SlotStateOf, sessionSlot, tool } 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,22 +38,24 @@ 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: structuredClone(SEED) };
 }
 
-/** 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;
-}
+/**
+ * The session's store, as one typed slot inside `ctx.state`.
+ *
+ * Every mutating tool goes through `retailSlot.update` (via `retailTool`),
+ * which serializes per session: the LLM loop can run a step's tool calls
+ * concurrently, and two interleaving async mutators would each observe the
+ * other's half-applied changes.
+ *
+ * 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 type StateSlot = SlotStateOf<typeof retailSlot>;
 
 export function setFocus(
   state: RetailState,
@@ -71,15 +66,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 +82,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 +94,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 +102,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 +118,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 +134,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 +144,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> {
@@ -193,10 +162,11 @@ interface RetailToolSpec<S extends z.ZodType<Record<string, unknown>>, 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,
+  );
 }
 
 /**
@@ -218,8 +188,12 @@ export function retailTool<S extends z.ZodType<Record<string, unknown>>, R>(
   return tool({
     description: spec.description,
     inputSchema: spec.inputSchema,
+    // `retailSlot.update` is the only caller of the serialized region in this
+    // template, which is what keeps `update`'s non-reentrancy unreachable: a
+    // tool body cannot nest another `update` on this slot, because tool bodies
+    // are `spec.execute` and always run INSIDE this one.
     execute: (args, ctx) =>
-      updateState(ctx, async (state) => {
+      retailSlot.update(ctx, async (state) => {
         const typedArgs = args as z.output<S>;
         if (requiresAuth && !state.authenticatedUserId) {
           record(state, spec.name, "blocked: not authenticated");
@@ -229,7 +203,7 @@ export function retailTool<S extends z.ZodType<Record<string, unknown>>, R>(
         record(
           state,
           spec.name,
-          isError(result) ? `error: ${result.error}` : spec.summary(typedArgs, result),
+          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,7 +1,8 @@
+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, retailSlot, 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;
@@ -27,12 +28,12 @@ export const cancelPendingOrder = retailTool({
   // 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);
+    const state = retailSlot.get(ctx);
     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") {