@alexkroman1/aai-cli 6.11.0 → 8.0.0

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

@@ -1,9 +1,11 @@
 import { isToolFailure, type ToolContext } from "@alexkroman1/aai";
-import { createToolContext } from "@alexkroman1/aai/testing";
+import { createToolContext, ok, okPosition } from "@alexkroman1/aai/testing";
 import { describe, expect, test } from "vitest";
 import { z } from "zod";
 import {
   authenticatedUser,
+  BEFORE_TRANSFER,
+  callFlow,
   createDefaultState,
   findItem,
   findOrder,
@@ -163,15 +165,16 @@ describe("retailTool", () => {
     name: "echo",
     description: "test tool",
     inputSchema: z.object({ value: z.string() }),
-    requiresAuth: false,
+    when: BEFORE_TRANSFER,
     summary: (args) => `echoed ${args.value}`,
     execute: (args) => ({ echoed: args.value }),
   });
 
   const gated = retailTool({
     name: "gated",
-    description: "test tool needing auth",
+    description: "test tool needing an identified customer",
     inputSchema: z.object({}),
+    when: "serving",
     summary: () => "ran",
     execute: () => ({ ok: true }),
   });
@@ -180,11 +183,15 @@ describe("retailTool", () => {
     name: "failing",
     description: "test tool that returns an error",
     inputSchema: z.object({}),
-    requiresAuth: false,
+    when: BEFORE_TRANSFER,
     summary: () => "should not be used",
     execute: () => ({ error: "nope" }),
   });
 
+  /** Put the call where a `when: "serving"` tool can run, through the flow
+   *  rather than by writing the store — the gate reads the machine. */
+  const serve = (ctx: ToolContext) => callFlow.send(ctx, { type: "IDENTIFIED" });
+
   test("increments callSeq and logs activity on every call", async () => {
     const ctx = makeCtx();
     await echo.execute({ value: "a" }, ctx);
@@ -203,27 +210,45 @@ describe("retailTool", () => {
     expect(retailSlot.get(ctx).callSeq).toBeGreaterThan(first);
   });
 
-  test("defaults to requiring authentication and does not run execute when blocked", async () => {
+  test("a tool gated on serving refuses while the caller is unidentified", async () => {
     const ctx = makeCtx();
     const result = await gated.execute({}, ctx);
-    expect(isToolFailure(result) && result.error).toContain("find_user_id_by_email");
+    expect(isToolFailure(result)).toBe(true);
+    // The refusal is the SDK's, so it names the position and quotes the
+    // state's own instruction — where `requiresAuth` answered one fixed
+    // sentence that could not say where the call was.
+    expect(isToolFailure(result) && result.error).toContain('"identifying"');
+    expect(isToolFailure(result) && result.error).toMatch(/user id/);
   });
 
-  test("a blocked call is still logged and still bumps callSeq", async () => {
+  test("a refused call touches nothing, callSeq included", async () => {
     const ctx = makeCtx();
     await gated.execute({}, ctx);
     const state = retailSlot.get(ctx);
-    expect(state.callSeq).toBe(1);
-    expect(state.activity[0]?.summary).toContain("blocked");
+    // 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([]);
   });
 
-  test("runs once authenticated", async () => {
+  test("runs once the flow says serving", async () => {
     const ctx = makeCtx();
-    retailSlot.update(ctx, (state) => {
-      state.authenticatedUserId = "olivia_ito_3591";
-    });
-    const result = await gated.execute({}, ctx);
-    expect(result).toEqual({ ok: true });
+    serve(ctx);
+    expect(ok(await gated.execute({}, ctx))).toEqual({ ok: true });
+  });
+
+  test("the result carries the position the call landed in", async () => {
+    const ctx = makeCtx();
+    serve(ctx);
+    // `okPosition` rather than a cast to `{ instruction?: string }`: it keeps
+    // 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.helping", done: false });
+    expect(answered.instruction).toMatch(/one identified customer/);
   });
 
   test("an error result is logged as an error, not through summary()", async () => {
@@ -232,6 +257,21 @@ describe("retailTool", () => {
     expect(retailSlot.get(ctx).activity[0]?.summary).toBe("error: nope");
   });
 
+  test("a body that failed does not move the call", async () => {
+    const ctx = makeCtx();
+    const moves = retailTool({
+      name: "moves",
+      description: "test tool that would identify the caller and fails instead",
+      inputSchema: z.object({}),
+      when: BEFORE_TRANSFER,
+      send: { type: "IDENTIFIED" },
+      summary: () => "moved",
+      execute: () => ({ error: "no such customer" }),
+    });
+    expect(isToolFailure(await moves.execute({}, ctx))).toBe(true);
+    expect(callFlow.position(ctx).state).toBe("identifying");
+  });
+
   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);
@@ -249,3 +289,32 @@ describe("retailTool", () => {
     expect(new Set(state.activity.map((a) => a.seq)).size).toBe(state.activity.length);
   });
 });
+
+describe("the call flow", () => {
+  test("a fresh call is identifying, and nothing is latched", () => {
+    const ctx = makeCtx();
+    expect(callFlow.position(ctx).state).toBe("identifying");
+    expect(retailSlot.get(ctx).authenticatedUserId).toBeNull();
+  });
+
+  test("transferred is final, so every tool refuses after the handoff", async () => {
+    const ctx = makeCtx();
+    const anywhere = retailTool({
+      name: "anywhere",
+      description: "legal in every state but the terminal one",
+      inputSchema: z.object({}),
+      when: BEFORE_TRANSFER,
+      summary: () => "ran",
+      execute: () => ({ ok: true }),
+    });
+    expect(ok(await anywhere.execute({}, ctx))).toEqual({ ok: true });
+
+    const at = callFlow.send(ctx, { type: "TRANSFERRED" });
+    expect(at.state).toBe("transferred");
+    expect(at.done).toBe(true);
+
+    const refused = await anywhere.execute({}, ctx);
+    expect(isToolFailure(refused)).toBe(true);
+    expect(isToolFailure(refused) && refused.error).toContain('"transferred"');
+  });
+});

package/dist/templates/retail/store.ts

@@ -1,5 +1,5 @@
 import type { ToolContext, ToolFailure } from "@alexkroman1/aai";
-import { isToolFailure, pushCapped, sessionSlot, toolFailure } from "@alexkroman1/aai";
+import { dialog, isToolFailure, omitUndefined, pushCapped, sessionSlot } from "@alexkroman1/aai";
 import type { z } from "zod";
 import seedJson from "./seed.json";
 import type {
@@ -71,6 +71,108 @@ export function seedStore(): Store {
  */
 export const retailSlot = sessionSlot("retail", createDefaultState);
 
+// ─── The call, as a machine ──────────────────────────────────────────────────
+
+/**
+ * Where this call is, and what may be done from here, as a plain state map.
+ *
+ * A {@link DialogSpec} rather than an XState machine: everything this dialog
+ * says is states, events and an instruction each, which is exactly what a spec
+ * can say. The instruction is a declared field instead of an untyped `meta`
+ * bag, so misspelling it is a compile error rather than a refusal that arrives
+ * with no recovery text. `as const` is what keeps the `on` keys literal, so
+ * `send` below is checked against the events this spec actually declares.
+ *
+ * Three of the policy's sections live here rather than in prose.
+ *
+ * **"Authenticate first."** `identifying`'s instruction names both finder
+ * tools, and ten tools declare `when: "serving"`, so the gate is the SDK's.
+ *
+ * **"Handing off to a human."** The policy says to call
+ * `transfer_to_human_agents` and then say exactly one sentence "and nothing
+ * else" — which nothing checked, so every tool stayed callable after the handoff
+ * and a model that kept going kept acting on a call it had already given away.
+ * `transferred` is a `final` state: no tool declares itself legal there, so
+ * every one of them refuses. `TRANSFERRED` sits on the `serving` PARENT so it
+ * is reachable from either child — a caller asking for a human mid-confirmation
+ * must get one.
+ *
+ * **"Confirm every change out loud."** This was the last rule in the policy
+ * carried by nothing at all, and it is `serving`'s two children now. Nothing in
+ * this template mutates the store except `confirm_change`, which is legal only
+ * in `awaitingConfirmation`, which is reachable only by staging a change. See
+ * `pending.ts` for what that buys and what it still cannot promise.
+ *
+ * **`IDENTIFIED` is deliberately NOT declared on `serving`.** It was, while
+ * `serving` was a leaf, so that a caller repeating their email did not hit an
+ * error. Now that `serving` has children, a self-transition would RE-ENTER it
+ * and reset to `helping` — stranding a staged change that `state.pending` still
+ * holds, which is the one way the position and the store could come to
+ * disagree. An event no active state handles is ignored, and ignoring it is
+ * exactly right: re-identifying the same customer does not move the call.
+ * `authenticateAs` is what refuses a switch to a DIFFERENT customer. Whether
+ * the call is identified and WHO it is identified as are two facts: this holds
+ * the first, `authenticatedUserId` holds the second.
+ */
+const callSpec = {
+  initial: "identifying",
+  states: {
+    identifying: {
+      // The instruction NAMES the two tools, because this sentence is what a
+      // refusal quotes and a refusal is the model's recovery path.
+      instruction:
+        "You do not know who this is yet. Identify the caller with " +
+        "find_user_id_by_email, or find_user_id_by_name_zip if they cannot " +
+        "remember the email. Do this even if they volunteer a user id.",
+      on: { IDENTIFIED: "serving", TRANSFERRED: "transferred" },
+    },
+    serving: {
+      initial: "helping",
+      on: { TRANSFERRED: "transferred" },
+      states: {
+        helping: {
+          instruction:
+            "You are helping one identified customer, and only that one. Nothing is " +
+            "waiting on their word. A tool that changes something only STAGES it and " +
+            "hands you a sentence to read back.",
+          on: { STAGED: "awaitingConfirmation" },
+        },
+        awaitingConfirmation: {
+          instruction:
+            "A change is staged and NOTHING HAS HAPPENED YET. Read the staged sentence " +
+            "back — the order, the items, the amounts, where the money goes — and wait " +
+            "for an explicit yes. Then call confirm_change, or cancel_change if they " +
+            "say no or want to change any part of it.",
+          on: { SETTLED: "helping" },
+        },
+      },
+    },
+    transferred: {
+      final: true,
+      instruction:
+        "The call belongs to a human agent now. Say nothing beyond the transfer " +
+        "sentence, and do nothing else.",
+    },
+  },
+} as const;
+
+/**
+ * The flow. Its own slot key beside {@link retailSlot}: the flow holds the
+ * POSITION and the store holds the customer, the orders, the activity feed and
+ * the staged change itself, because an inspectable {@link PendingAction} is
+ * what `confirm_change` applies. One tool call always moves both — a staging
+ * tool writes `pending` and sends `STAGED` in the same synchronous window.
+ */
+export const callFlow = dialog("call", callSpec);
+
+/** Every state a tool may run in before the call is handed to a human — i.e.
+ *  everything but `transferred`. What the two finders, the three catalog reads
+ *  and the transfer itself declare, so the terminal state gates them without an
+ *  auth gate. `"serving"` matches both of its children, which is what keeps a
+ *  read legal while a change is waiting: a caller who asks "what was the total
+ *  again?" mid-confirmation must be answerable. */
+export const BEFORE_TRANSFER = ["identifying", "serving"] as const;
+
 export function setFocus(
   state: RetailState,
   focus: { orderId?: string; productId?: string },
@@ -128,12 +230,26 @@ export function findPaymentMethod(user: User, methodId: string): PaymentMethod |
 
 // ─── Guards ──────────────────────────────────────────────────────────────────
 
-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.";
-
+/**
+ * The customer on this call.
+ *
+ * The null arm is reachable only if the POSITION and the STORE disagree — the
+ * flow says `serving` while nothing latched a user id — which no code path
+ * produces, since `authenticateAs` is what both writes the id and lets the
+ * `IDENTIFIED` event through. It is kept and reported rather than thrown for the
+ * reason `travel-concierge`'s `cancel_action` keeps its own: this runs mid-call,
+ * and a sentence the model can act on beats an exception. The GATE that a
+ * customer is identified at all is `callFlow`'s, declared per tool as `when`.
+ */
 export function authenticatedUser(state: RetailState): User | ToolFailure {
-  if (!state.authenticatedUserId) return { error: NOT_AUTHENTICATED };
+  if (!state.authenticatedUserId) {
+    return {
+      error:
+        "No customer is latched onto this call yet. Identify them with " +
+        "find_user_id_by_email, or find_user_id_by_name_zip if they cannot " +
+        "remember their email.",
+    };
+  }
   return findUser(state, state.authenticatedUserId);
 }
 
@@ -187,24 +303,52 @@ interface RetailToolSpec<S extends z.ZodType<Record<string, unknown>>, R> {
   /** Required even for no-arg tools — pass `z.object({})`. One code path in the
    *  wrapper is worth more than saving a line at one call site. */
   inputSchema: S;
-  /** Default true. Only the two finder tools and the three catalog tools opt
-   *  out; everything else touches customer data. */
-  requiresAuth?: boolean;
-  summary: (args: z.output<S>, result: R) => string;
   /**
-   * Handed the store as its second argument, and SYNCHRONOUS.
+   * The state(s) this tool may run in, as `callFlow`'s states spell them.
+   *
+   * Replaces the `requiresAuth` boolean this spec used to carry. Nine tools
+   * want `"serving"` — which matches both of its children, so a read and a
+   * staging tool are equally legal while a change waits; the two settling
+   * tools want `"serving.awaitingConfirmation"`; and the two finders, the three
+   * catalog reads and the transfer want {@link BEFORE_TRANSFER}, which is every
+   * state but the terminal one — so "does not need a customer" and "is still
+   * legal after the handoff" stopped being the same claim, and they were never
+   * the same claim.
+   */
+  when: string | readonly string[];
+  /** The event to send once the body has succeeded, for a tool that MOVES the
+   *  call. Twelve do: the two finders send `IDENTIFIED`, the transfer sends
+   *  `TRANSFERRED`, the seven staging tools send `STAGED`, and `confirm_change`
+   *  and `cancel_change` send `SETTLED`. Nothing is sent when the body answers
+   *  a `ToolFailure` — which is what stops a refused stage from moving the call
+   *  into a confirmation with nothing behind it. */
+  send?:
+    | { type: "IDENTIFIED" }
+    | { type: "TRANSFERRED" }
+    | { type: "STAGED" }
+    | { type: "SETTLED" };
+  /**
+   * One line for the activity feed, from the call that SUCCEEDED.
    *
-   * **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.
+   * `R` is the SUCCESS type — `execute` below is declared `R | ToolFailure`, so
+   * the failure arm is matched against `ToolFailure` during inference and never
+   * lands in `R`. That is what lets the fifteen tool files stop writing
+   * `isToolFailure(result) ? "… failed" : …` for a case that cannot arrive: the
+   * wrapper never calls `summary` on a failure and now says so in the type.
    *
-   * ---
+   * `NoInfer` takes this parameter out of the inference race `R` used to be
+   * decided by. It does NOT make the source order irrelevant — `execute` is an
+   * inline arrow whose parameters are contextually typed, so its return type is
+   * inferred in a LATER pass than this signature is checked, and a `summary`
+   * written above it still lands on `unknown`. What changed is that the failure
+   * is now LOUD: with no `isToolFailure` ternary left to swallow it, the wrong
+   * order is a `TS18046` on the first property read rather than a narrowing
+   * that quietly stops meaning anything. So the twelve-line warning this used
+   * to carry is the compiler's job now.
+   */
+  summary: (args: z.output<S>, result: NoInfer<R>) => string;
+  /**
+   * Handed the store as its second argument, and SYNCHRONOUS.
    *
    * **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
@@ -218,10 +362,16 @@ interface RetailToolSpec<S extends z.ZodType<Record<string, unknown>>, R> {
    * 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;
+  execute: (args: z.output<S>, state: RetailState, ctx: ToolContext) => R | ToolFailure;
 }
 
-function record(state: RetailState, name: string, summary: string): void {
+/**
+ * One line of the activity feed, and the `callSeq` bump the sidebar moves on.
+ *
+ * Exported because {@link retailTool} is no longer its only caller: `agent.ts`
+ * records the calls that never reach a body — see {@link gateFor}.
+ */
+export function record(state: RetailState, name: string, summary: string): void {
   state.callSeq += 1;
   pushCapped(
     state.activity,
@@ -231,13 +381,46 @@ function record(state: RetailState, name: string, summary: string): void {
 }
 
 /**
- * Every retail tool is built through this. It owns three things no tool body
- * may re-implement:
+ * Which states each retail tool may run in, by the name the model calls it by.
  *
- * 1. the authentication gate,
- * 2. serialization of the state mutation,
- * 3. the `callSeq` increment + activity entry — the reason the UI moves on
- *    EVERY tool call rather than only when a projected value happens to differ.
+ * Populated as the fifteen `tools/` modules are loaded, because {@link retailTool}
+ * is what every one of them calls. It exists so `agent.ts`'s `tool.called` hook
+ * can ask the SAME question the gate asks — this is one fact evaluated twice, not
+ * two copies of a fact.
+ */
+const TOOL_GATES = new Map<string, readonly string[]>();
+
+/**
+ * The states `name` may run in, or `undefined` for a tool this template did not
+ * declare (a builtin, or anything a future author adds outside the wrapper).
+ */
+export function gateFor(name: string): readonly string[] | undefined {
+  return TOOL_GATES.get(name);
+}
+
+/**
+ * Every retail tool is built through this. It owns two things no tool body may
+ * re-implement:
+ *
+ * 1. the mutation window the body's draft comes from,
+ * 2. the `callSeq` increment + activity entry — the reason the UI moves on
+ *    every tool call rather than only when a projected value happens to differ.
+ *
+ * The third thing it used to own — the authentication gate — is
+ * {@link callFlow}'s now, declared per tool as `when`. What that buys is in the
+ * machine's own doc; what it COST was one line of the activity feed, because a
+ * refused call short-circuits before this wrapper's body runs and so recorded
+ * nothing and bumped no `callSeq`.
+ *
+ * **That line is back, and not from here.** `agent.ts` declares a `tool.called`
+ * hook, which the runtime emits for every call the model makes INCLUDING the
+ * ones the gate goes on to refuse — a place to observe from that a tool wrapper
+ * structurally does not have. See {@link gateFor}.
+ *
+ * **`callFlow.tool` rather than `retailSlot.updateTool`**, so the body opens the
+ * store's window itself. A flow tool's own `execute` is handed `(args, ctx)`;
+ * everything else about a tool body here is unchanged, including that it is
+ * synchronous — the window cannot span an await.
  *
  * `focus` is deliberately left to tool bodies (`setFocus`): it is a UI nicety,
  * not an invariant, and only the body knows what the call was about.
@@ -245,26 +428,26 @@ function record(state: RetailState, name: string, summary: string): void {
 export function retailTool<S extends z.ZodType<Record<string, unknown>>, R>(
   spec: RetailToolSpec<S, R>,
 ) {
-  const requiresAuth = spec.requiresAuth ?? true;
-  // `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({
+  TOOL_GATES.set(spec.name, typeof spec.when === "string" ? [spec.when] : spec.when);
+  return callFlow.tool({
     description: spec.description,
     inputSchema: spec.inputSchema,
-    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;
-    },
+    when: spec.when,
+    // `omitUndefined` rather than a conditional spread: `exactOptionalPropertyTypes`
+    // is on, so an explicit `send: undefined` is not the same as an absent one —
+    // and only three of the fifteen tools declare an event (guard-invariants
+    // rule 2).
+    ...omitUndefined({ send: spec.send }),
+    execute: (args, ctx) =>
+      retailSlot.update(ctx, (state) => {
+        const typedArgs = args as z.output<S>;
+        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,7 +1,7 @@
 import { isToolFailure } from "@alexkroman1/aai";
 import { describe, expect, test } from "vitest";
 import { createDefaultState, findUser } from "./store.ts";
-import { applySwap, assertCanCoverDiff, planItemSwap } from "./swap.ts";
+import { applySwapLines, assertCanCoverDiff, planItemSwap, toSwapLines } from "./swap.ts";
 
 function fixture(orderId: string) {
   const state = createDefaultState();
@@ -152,7 +152,7 @@ describe("assertCanCoverDiff", () => {
   });
 });
 
-describe("applySwap", () => {
+describe("applySwapLines", () => {
   test("each swapped line takes its OWN new price and options", () => {
     const { state, order } = fixture("#W9311069");
     // Two different products in one call — this is what catches the leaked
@@ -165,7 +165,7 @@ describe("applySwap", () => {
       { requireDifferent: true },
     );
     if (isToolFailure(plan)) throw new Error(plan.error);
-    applySwap(order, plan);
+    applySwapLines(order, toSwapLines(plan));
 
     const vacuum = order.items.find((i) => i.item_id === "4725166838");
     const kettle = order.items.find((i) => i.item_id === "3909406921");
@@ -183,7 +183,7 @@ describe("applySwap", () => {
       requireDifferent: true,
     });
     if (isToolFailure(plan)) throw new Error(plan.error);
-    applySwap(order, plan);
+    applySwapLines(order, toSwapLines(plan));
     expect(order.items.map((i) => i.item_id)).toEqual(["3909406921", "7292993796"]);
   });
 });