@alexkroman1/aai-cli 5.14.0 → 6.1.0

package/dist/templates/retail/agent.ts

@@ -1,22 +1,6 @@
 import { agent } from "@alexkroman1/aai";
 import { storeView } from "./shared.ts";
-import { retailSlot, type StateSlot } from "./store.ts";
-import systemPrompt from "./system-prompt.md?raw";
-import { cancelPendingOrder } from "./tools/cancel_pending_order.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";
-import { getItemDetails } from "./tools/get_item_details.ts";
-import { getOrderDetails } from "./tools/get_order_details.ts";
-import { getProductDetails } from "./tools/get_product_details.ts";
-import { getUserDetails } from "./tools/get_user_details.ts";
-import { listAllProductTypes } from "./tools/list_all_product_types.ts";
-import { modifyPendingOrderAddress } from "./tools/modify_pending_order_address.ts";
-import { modifyPendingOrderItems } from "./tools/modify_pending_order_items.ts";
-import { modifyPendingOrderPayment } from "./tools/modify_pending_order_payment.ts";
-import { modifyUserAddress } from "./tools/modify_user_address.ts";
-import { returnDeliveredOrderItems } from "./tools/return_delivered_order_items.ts";
-import { transferToHumanAgents } from "./tools/transfer_to_human_agents.ts";
+import { retailSlot } from "./store.ts";
 
 export default agent({
   name: "Retail Support",
@@ -25,12 +9,10 @@ export default agent({
   // filled from the all-AssemblyAI pipeline at parse time. Only `stt` is
   // overridden below; `llm` and `tts` take the defaults.
 
-  // The store lives in ctx.state, one pristine copy per session — callers must
-  // not see each other's cancellations. Declaring `state` (rather than letting
-  // the slot install itself on first access) means the session's store exists
-  // before the first tool call, so a resumed connection has something to
-  // project; the slot owns the shape either way.
-  state: (): StateSlot => ({ [retailSlot.key]: retailSlot.create() }),
+  // The store lives in one `sessionSlot` (`store.ts`), a pristine copy per
+  // session — callers must not see each other's cancellations. Nothing declares
+  // it here: the slot installs itself on first access, and its `projection`
+  // below is what gives a session that has run no tool something to render.
 
   // One projection pushed after every tool call. It is a projection, not a
   // flag, because the state holds all six seeded customers and only the
@@ -41,26 +23,7 @@ export default agent({
   // inside one utterance ("W seven six seven … eight oh seven two"). The default
   // pipeline's `max_turn_silence` already tolerates that; reach for
   // `assemblyAIStt({ maxTurnSilenceMs })` only if your callers pause longer.
-  systemPrompt,
   greeting:
     "Thanks for calling. Before I can look anything up I'll need to find your account — " +
     "what's the email address on it?",
-
-  tools: {
-    cancel_pending_order: cancelPendingOrder,
-    exchange_delivered_order_items: exchangeDeliveredOrderItems,
-    find_user_id_by_email: findUserIdByEmail,
-    find_user_id_by_name_zip: findUserIdByNameZip,
-    get_item_details: getItemDetails,
-    get_order_details: getOrderDetails,
-    get_product_details: getProductDetails,
-    get_user_details: getUserDetails,
-    list_all_product_types: listAllProductTypes,
-    modify_pending_order_address: modifyPendingOrderAddress,
-    modify_pending_order_items: modifyPendingOrderItems,
-    modify_pending_order_payment: modifyPendingOrderPayment,
-    modify_user_address: modifyUserAddress,
-    return_delivered_order_items: returnDeliveredOrderItems,
-    transfer_to_human_agents: transferToHumanAgents,
-  },
 });

package/dist/templates/retail/client.tsx

@@ -1,6 +1,12 @@
 import "@alexkroman1/aai-ui/styles.css";
-import type { ChatMessage } from "@alexkroman1/aai-ui";
-import { AutoScroll, client, useAgentState, useSession } from "@alexkroman1/aai-ui";
+import type { AgentState, ChatMessage } from "@alexkroman1/aai-ui";
+import {
+  AutoScroll,
+  client,
+  useAgentState,
+  useSession,
+  useUserTranscript,
+} from "@alexkroman1/aai-ui";
 import type { ReactNode } from "react";
 import type {
   OrderStatus,
@@ -43,12 +49,24 @@ const statusColors: Record<string, string> = {
 // importing it here would ship the whole catalog to the browser.
 const EMPTY_VIEW: StoreView = storeView(emptyRetailState());
 
-function stateColor(state: string): string {
-  if (state === "listening" || state === "ready") return "#16a34a";
-  if (state === "thinking") return "#ca8a04";
-  if (state === "speaking") return "#2563eb";
-  return "#a1a1aa";
-}
+// The dot's colour per session state, as an EXHAUSTIVE map rather than an
+// if-chain with a grey default.
+//
+// The palette is this template's own — every client here paints the same six
+// states in its own colours, so the SDK has nothing to share but the union. What
+// the SDK does own is `AgentState`, and `satisfies Record<AgentState, string>`
+// is what borrows it: a state added there stops compiling here, where the
+// `state === "…"` chain this replaced answered a new state with a silent grey
+// badge in three separate files and no way to notice.
+const STATE_COLORS = {
+  disconnected: "#a1a1aa",
+  connecting: "#a1a1aa",
+  ready: "#16a34a",
+  listening: "#16a34a",
+  thinking: "#ca8a04",
+  speaking: "#2563eb",
+  error: "#a1a1aa",
+} satisfies Record<AgentState, string>;
 
 function Panel({ title, children }: { title: string; children: ReactNode }) {
   return (
@@ -195,6 +213,10 @@ function SwapOptions({ option }: { option: SwapOptionView }) {
 
 function App() {
   const session = useSession();
+  // `speaking` and `text` in place of a `userTranscript !== null` check: `null`
+  // is silence and `""` is speech detected with no words back yet, and reading
+  // them as one falsy value hides the indicator at the start of every turn.
+  const { speaking, text: userTranscript } = useUserTranscript();
   // The agent's own store, projected by `syncState` after every tool call.
   const view = useAgentState<StoreView>(EMPTY_VIEW);
 
@@ -217,7 +239,7 @@ function App() {
             <span
               className="w-2 h-2 rounded-full inline-block"
               style={{
-                background: stateColor(session.state),
+                background: STATE_COLORS[session.state],
                 animation:
                   session.state === "listening"
                     ? "rt-pulse 1.5s ease-in-out infinite"
@@ -279,7 +301,7 @@ function App() {
               ))}
             </AutoScroll>
 
-            {session.userTranscript !== null && (
+            {speaking && (
               <div
                 className="flex items-center px-4 py-2 text-xs italic min-h-8"
                 style={{ background: "#fafafa", borderTop: "1px solid #e4e4e7", color: "#71717a" }}
@@ -288,7 +310,7 @@ function App() {
                   className="w-2 h-2 rounded-full inline-block mr-2"
                   style={{ background: "#16a34a", animation: "rt-pulse 1.5s ease-in-out infinite" }}
                 />
-                {session.userTranscript === "" ? "…" : session.userTranscript}
+                {userTranscript}
               </div>
             )}
             {session.error && (

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

@@ -1,6 +1,9 @@
+/// <reference types="vite/client" />
+
 import { isToolFailure, type ToolContext } from "@alexkroman1/aai";
+import { createToolContext, withDiscoveredTools } from "@alexkroman1/aai/testing";
 import { describe, expect, test } from "vitest";
-import retailAgent from "./agent.ts";
+import authoredAgent from "./agent.ts";
 import { retailSlot } from "./store.ts";
 
 /** Tools that legitimately run before the caller is identified. Everything
@@ -15,18 +18,24 @@ const PUBLIC_TOOLS = new Set([
   "transfer_to_human_agents",
 ]);
 
-const registry = Object.entries(retailAgent.tools ?? {});
+/**
+ * The def a DEPLOYED agent runs: authored, plus what `tools/` declares.
+ *
+ * The glob is written HERE rather than reached for from a shared helper because
+ * this file SHIPS: it is what a scaffolded project runs, so it may not import
+ * anything outside its own template, and `import.meta.glob` is expanded against
+ * the file containing it either way. This is the pattern a user writes.
+ */
+const retailAgent = withDiscoveredTools(
+  authoredAgent,
+  import.meta.glob("./tools/*.ts", { eager: true }),
+);
+const registry = Object.entries(retailAgent.tools);
 
-let sessionCounter = 0;
-function makeCtx(): ToolContext {
-  return {
-    sessionId: `registry-test-${++sessionCounter}`,
-    send: () => {},
-    env: {},
-    state: {},
-    messages: [],
-  } as unknown as ToolContext;
-}
+// `createToolContext()` rather than a cast: it carries a real slot store (the
+// same storability check and freeze the deployed one applies), and each call is a
+// distinct session, which is what these per-tool cases assume.
+const makeCtx = (): ToolContext => createToolContext();
 
 /** Minimal args satisfying each tool's schema. Deliberately plausible-shaped
  *  but wrong — these calls are expected to fail; what is asserted is that they
@@ -175,10 +184,16 @@ describe("agent config", () => {
     expect(typeof retailAgent.syncState).toBe("function");
   });
 
-  test("declares a state factory, so sessions do not share a store", () => {
-    expect(typeof retailAgent.state).toBe("function");
-    const a = retailAgent.state?.();
-    const b = retailAgent.state?.();
+  // The slot owns the default now — there is no `state` factory on the agent to
+  // forget to declare, which is what four of five slot-backed templates used to.
+  // What still has to hold is that the factory really is called per session: the
+  // 107 KB seed is one module-level object, so a shared clone would let one
+  // caller's cancellation show up in another's.
+  test("the slot's factory clones the seed, so sessions do not share a store", () => {
+    const a = retailSlot.create();
+    const b = retailSlot.create();
     expect(a).not.toBe(b);
+    expect(a.store.orders).not.toBe(b.store.orders);
+    expect(a.store).toEqual(b.store);
   });
 });

package/dist/templates/retail/resolve.ts

@@ -1,4 +1,15 @@
-import { isToolFailure, type ToolFailure } from "@alexkroman1/aai";
+/**
+ * Spoken references to this store's things.
+ *
+ * The generic half — reading digits out of an utterance, reading a position out
+ * of one, and the never-guess contract that turns a list of candidates into one
+ * of them or into a failure that lists them — is `resolveOne`, `spokenDigits`
+ * and `spokenOrdinal` (`@alexkroman1/aai`). What stays here is the STORE's
+ * vocabulary: what an order id looks like when a caller reads it aloud, which
+ * words name a status, and what a variant's options are matched against.
+ */
+
+import { isToolFailure, resolveOne, spokenDigits, type ToolFailure } from "@alexkroman1/aai";
 import type { Order, OrderStatus, Product, RetailState } from "./shared.ts";
 import { authenticatedUser } from "./store.ts";
 
@@ -10,27 +21,13 @@ export function normalizeOrderId(spoken: string): string {
 
 /** Item ids are 10 digits; callers read them in groups. */
 export function normalizeItemId(spoken: string): string {
-  return spoken.replace(/\D/g, "");
+  return spokenDigits(spoken);
 }
 
 /** A digit run long enough to be an id rather than an ordinal. */
 const LOOKS_LIKE_ORDER_ID = /\d[\d\s-]{5,}/;
 const LOOKS_LIKE_ITEM_ID = /(?:\d[\s-]*){8,}/;
 
-const ORDINALS: Record<string, number> = {
-  first: 0,
-  "1st": 0,
-  second: 1,
-  "2nd": 1,
-  third: 2,
-  "3rd": 2,
-  fourth: 3,
-  "4th": 3,
-  fifth: 4,
-  "5th": 4,
-  last: -1,
-};
-
 /** Spoken status words → the statuses they select. `pending` deliberately
  *  excludes `pending (item modified)`, which no tool will accept anyway. */
 const STATUS_WORDS: [string, OrderStatus[]][] = [
@@ -72,6 +69,9 @@ export function resolveOrder(state: RetailState, spoken: string): Order | ToolFa
   const statusEntry = STATUS_WORDS.find(([word]) => text.includes(word));
   const candidates = statusEntry ? owned.filter((o) => statusEntry[1].includes(o.status)) : owned;
 
+  // The empty case is the store's to answer, not `resolveOne`'s: "no cancelled
+  // order" is only useful said alongside the statuses this customer DOES have,
+  // which is what lets the model ask its next question without another tool call.
   if (candidates.length === 0) {
     const have = [...new Set(owned.map((o) => o.status))].join(", ");
     return {
@@ -79,28 +79,9 @@ export function resolveOrder(state: RetailState, spoken: string): Order | ToolFa
     };
   }
 
-  const ordinalWord = Object.keys(ORDINALS).find((word) => new RegExp(`\\b${word}\\b`).test(text));
-  if (ordinalWord) {
-    const index = ORDINALS[ordinalWord] ?? 0;
-    const picked = index === -1 ? candidates.at(-1) : candidates[index];
-    if (!picked) {
-      return {
-        error: `There is no ${ordinalWord} such order — the customer has ${candidates.length}: ${candidates
-          .map(describeOrder)
-          .join("; ")}.`,
-      };
-    }
-    return picked;
-  }
-
-  const only = candidates[0];
-  if (candidates.length === 1 && only) return only;
-
-  return {
-    error: `That is ambiguous — ${candidates.length} orders match. Ask which one: ${candidates
-      .map(describeOrder)
-      .join("; ")}.`,
-  };
+  // A position, then exactly-one, then an ambiguity that lists them — and never
+  // a guess, because the consequence here is cancelling the wrong order.
+  return resolveOne(candidates, spoken, { label: "order", describe: describeOrder });
 }
 
 /**
@@ -127,33 +108,16 @@ export function resolveVariantId(
     return itemId;
   }
 
-  const text = spoken.toLowerCase();
   const pool = Object.values(product.variants).filter((v) => !opts.availableOnly || v.available);
 
-  let best = 0;
-  const scored = pool.map((variant) => {
-    const score = Object.values(variant.options).filter((value) =>
-      text.includes(value.toLowerCase()),
-    ).length;
-    best = Math.max(best, score);
-    return { variant, score };
+  // A variant is named by its OPTIONS ("the blue medium"), so the score is how
+  // many of them the caller said. Everything after that — no match, one match, a
+  // tie — is `resolveOne`'s, and a tie is answered rather than broken.
+  const picked = resolveOne(pool, spoken, {
+    label: `${product.name} option`,
+    describe: (v) => `${v.item_id} (${Object.values(v.options).join(", ")})`,
+    score: (variant, text) =>
+      Object.values(variant.options).filter((value) => text.includes(value.toLowerCase())).length,
   });
-
-  if (best === 0) {
-    return {
-      error: `No ${product.name} option matches "${spoken}". Options available: ${pool
-        .map((v) => `${v.item_id} (${Object.values(v.options).join(", ")})`)
-        .join("; ")}.`,
-    };
-  }
-
-  const winners = scored.filter((s) => s.score === best);
-  const winner = winners[0]?.variant;
-  if (winners.length === 1 && winner) return winner.item_id;
-
-  return {
-    error: `"${spoken}" matches ${winners.length} ${product.name} options. Ask which: ${winners
-      .map((s) => `${s.variant.item_id} (${Object.values(s.variant.options).join(", ")})`)
-      .join("; ")}.`,
-  };
+  return isToolFailure(picked) ? picked : picked.item_id;
 }

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

@@ -1,11 +1,12 @@
 import { describe, expect, test } from "vitest";
 import seedJson from "./seed.json";
-import type { RetailState, Store } from "./shared.ts";
+import type { RetailState } from "./shared.ts";
 import { buildScriptBullets, DEMO_PERSONAS, emptyRetailState, storeView } from "./shared.ts";
+import { seedStore } from "./store.ts";
 
 function makeState(authenticatedUserId: string | null): RetailState {
   return {
-    store: structuredClone(seedJson) as unknown as Store,
+    store: seedStore(),
     authenticatedUserId,
     callSeq: 3,
     activity: [{ seq: 3, tool: "get_order_details", summary: "read #W5866402", at: 0 }],
@@ -84,7 +85,7 @@ describe("DEMO_PERSONAS", () => {
   });
 
   test("every persona's email, name and zip match its seed record", () => {
-    const users = Object.values((structuredClone(seedJson) as unknown as Store).users);
+    const users = Object.values(seedStore().users);
     for (const persona of DEMO_PERSONAS) {
       const user = users.find((u) => u.email === persona.email);
       expect.soft(user, `no seeded customer has email ${persona.email}`).toBeDefined();

package/dist/templates/retail/shared.ts

@@ -1,3 +1,5 @@
+import type { DeepReadonly } from "@alexkroman1/aai";
+
 // ─── Store types ─────────────────────────────────────────────────────────────
 // Field names are tau2's snake_case verbatim, because `seed.json` is tau2's
 // records unmodified. Renaming them here would mean transforming 107 KB of
@@ -129,6 +131,18 @@ export interface RetailState {
   focus: { orderId?: string; productId?: string };
 }
 
+/**
+ * The store as a READ hands it out: deep-frozen, and typed to say so.
+ *
+ * The projection and its helpers take this rather than {@link RetailState},
+ * which is the widening a deep-readonly slot forces and the reason it is worth
+ * doing: a mutable state still satisfies it, so `client.tsx` still projects
+ * `emptyRetailState()` and every `retailTool` body still passes its draft,
+ * while a projection helper that WOULD have mutated stops compiling instead of
+ * throwing at its first call.
+ */
+export type FrozenRetailState = DeepReadonly<RetailState>;
+
 /**
  * A pristine, EMPTY store — no seed data.
  *
@@ -266,13 +280,13 @@ export const DEMO_PERSONAS: readonly DemoPersona[] = [
 
 // ─── Projection ──────────────────────────────────────────────────────────────
 
-function paymentLabel(method: PaymentMethod): string {
+function paymentLabel(method: DeepReadonly<PaymentMethod>): string {
   if (method.source === "gift_card") return "Gift card";
   if (method.source === "paypal") return "PayPal";
   return `${method.brand} ending ${method.last_four}`;
 }
 
-function paymentMethodView(method: PaymentMethod): PaymentMethodView {
+function paymentMethodView(method: DeepReadonly<PaymentMethod>): PaymentMethodView {
   return {
     id: method.id,
     source: method.source,
@@ -284,7 +298,7 @@ function paymentMethodView(method: PaymentMethod): PaymentMethodView {
 /** Net of payments minus refunds — what the customer has actually paid. Items
  *  can't be summed instead: a modified order's items no longer match what was
  *  charged. */
-export function orderTotal(order: Order): number {
+export function orderTotal(order: DeepReadonly<Order>): number {
   const net = order.payment_history.reduce(
     (sum, p) => sum + (p.transaction_type === "payment" ? p.amount : -p.amount),
     0,
@@ -292,7 +306,7 @@ export function orderTotal(order: Order): number {
   return Math.round(net * 100) / 100;
 }
 
-function orderView(order: Order): OrderView {
+function orderView(order: DeepReadonly<Order>): OrderView {
   return {
     orderId: order.order_id,
     status: order.status,
@@ -312,7 +326,10 @@ function orderView(order: Order): OrderView {
  * an exchange sayable. Only available variants, only the focused order, and
  * capped on both axes so the payload stays bounded.
  */
-function swapOptionsFor(state: RetailState, order: Order | undefined): SwapOptionView[] {
+function swapOptionsFor(
+  state: FrozenRetailState,
+  order: DeepReadonly<Order> | undefined,
+): SwapOptionView[] {
   if (!order) return [];
   return order.items.slice(0, MAX_SWAP_ITEMS).map((item) => {
     const product = state.store.products[item.product_id];
@@ -344,7 +361,7 @@ function swapOptionsFor(state: RetailState, order: Order | undefined): SwapOptio
  *  real one even before the first tool call, so the optional chaining this
  *  used to carry — which read as security gating and was not — is gone. The
  *  gating that IS security is still here, on `user`. */
-export function storeView(state: RetailState): StoreView {
+export function storeView(state: FrozenRetailState): StoreView {
   const userId = state.authenticatedUserId;
   const user = userId ? state.store.users[userId] : undefined;
   const focusedOrderId = state.focus.orderId;
@@ -396,7 +413,7 @@ const MAX_BULLETS = 6;
  * that offers actions the data can't support — "return an item" to someone
  * with no delivered order — is worse than no list.
  */
-export function buildScriptBullets(state: RetailState): string[] {
+export function buildScriptBullets(state: FrozenRetailState): string[] {
   const userId = state.authenticatedUserId;
   const user = userId ? state.store.users[userId] : undefined;
 

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

@@ -16,11 +16,10 @@ import {
   requireOwnOrder,
   retailSlot,
   retailTool,
-  type StateSlot,
 } from "./store.ts";
 
-function makeCtx(): ToolContext<StateSlot> {
-  return createToolContext<StateSlot>();
+function makeCtx(): ToolContext {
+  return createToolContext();
 }
 
 describe("session state", () => {
@@ -35,12 +34,13 @@ describe("session state", () => {
   });
 
   test("each session gets its own deep copy — a mutation cannot leak across sessions", () => {
-    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;
+    retailSlot.update(makeCtx(), (first) => {
+      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 = retailSlot.get(makeCtx());
     expect(second.store.orders["#W9300146"]?.status).toBe("pending");
@@ -219,7 +219,9 @@ describe("retailTool", () => {
 
   test("runs once authenticated", async () => {
     const ctx = makeCtx();
-    retailSlot.get(ctx).authenticatedUserId = "olivia_ito_3591";
+    retailSlot.update(ctx, (state) => {
+      state.authenticatedUserId = "olivia_ito_3591";
+    });
     const result = await gated.execute({}, ctx);
     expect(result).toEqual({ ok: true });
   });

package/dist/templates/retail/store.ts

@@ -1,5 +1,5 @@
 import type { ToolContext, ToolFailure } from "@alexkroman1/aai";
-import { isToolFailure, pushCapped, type SlotStateOf, sessionSlot, tool } from "@alexkroman1/aai";
+import { isToolFailure, pushCapped, sessionSlot, toolFailure } from "@alexkroman1/aai";
 import type { z } from "zod";
 import seedJson from "./seed.json";
 import type {
@@ -38,16 +38,32 @@ 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 { ...emptyRetailState(), store: structuredClone(SEED) };
+  return { ...emptyRetailState(), store: seedStore() };
 }
 
 /**
- * The session's store, as one typed slot inside `ctx.state`.
+ * A pristine deep copy of the seed store.
  *
- * 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.
+ * 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
@@ -55,8 +71,6 @@ export function createDefaultState(): RetailState {
  */
 export const retailSlot = sessionSlot("retail", createDefaultState);
 
-export type StateSlot = SlotStateOf<typeof retailSlot>;
-
 export function setFocus(
   state: RetailState,
   focus: { orderId?: string; productId?: string },
@@ -157,7 +171,34 @@ 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 {
@@ -185,27 +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,
-    // `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) =>
-      retailSlot.update(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,
-          isToolFailure(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;
+    },
   });
 }