@alexkroman1/aai-cli 6.10.1 → 7.0.0

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,89 @@ 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: this dialog said three
+ * states, two events and an instruction each, which is exactly what a spec can
+ * say — and the `setup({ types: {} as { events: … } })` block it used to carry
+ * restated the two event names already written in the `on` maps. The
+ * instruction is a declared field now 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.
+ *
+ * The policy's first two sections — "Authenticate first" and "Handing off to a
+ * human" — used to be prose plus a boolean. `requiresAuth` was that boolean:
+ * fifteen tools declared it (five opting out), the wrapper below read it, and a
+ * refusal answered one fixed sentence. Three things change by declaring the
+ * states instead.
+ *
+ * **`transferred` is a real terminal state, and it was not enforced at all.**
+ * 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 would keep acting on a
+ * call it had already given away. It is a `final` state now: no tool declares
+ * itself legal there, so every one of them refuses.
+ *
+ * **The refusal quotes the state.** `when` names where a tool may run and the
+ * SDK writes the sentence, so the message is one thing rather than a constant
+ * threaded through a wrapper — and it says where the call actually is, which
+ * "Not authenticated" could not.
+ *
+ * **The position rides every result.** A flow tool answers the author's value
+ * wrapped in the position it landed in, so the stage and its instruction reach
+ * the model on every call rather than only when the prompt is still in context.
+ *
+ * `IDENTIFIED` is declared on `serving` as well, because a caller repeating
+ * their email must not hit an error — see `authenticateAs`, which is what
+ * refuses a switch to a DIFFERENT customer. Whether the flow 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 — the same
+      // job the removed `NOT_AUTHENTICATED` constant did, now attached to the
+      // state that means it.
+      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: {
+      instruction:
+        "You are helping one identified customer, and only that one. Say what you " +
+        "are about to change — the order, the items, the amounts, where the money " +
+        "goes — and wait for an explicit yes before you call anything that changes it.",
+      on: { IDENTIFIED: "serving", TRANSFERRED: "transferred" },
+    },
+    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 and the activity feed.
+ */
+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 five formerly `requiresAuth: false`
+ *  tools declare, so the terminal state gates them without an auth gate. */
+export const BEFORE_TRANSFER = ["identifying", "serving"] as const;
+
 export function setFocus(
   state: RetailState,
   focus: { orderId?: string; productId?: string },
@@ -128,12 +211,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 +284,42 @@ 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.
    *
-   * **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.
+   * Replaces the `requiresAuth` boolean this spec used to carry. Ten tools want
+   * `"serving"`; 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. Three do: the two finders send `IDENTIFIED`, the transfer sends
+   *  `TRANSFERRED`. Nothing is sent when the body answers a `ToolFailure`. */
+  send?: { type: "IDENTIFIED" } | { type: "TRANSFERRED" };
+  /**
+   * One line for the activity feed, from the call that SUCCEEDED.
+   *
+   * `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,7 +333,7 @@ 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 {
@@ -231,13 +346,26 @@ 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:
+ * 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.
  *
- * 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.
+ * 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 COSTS is one line of the activity feed: a refused
+ * call short-circuits before this wrapper's body runs, so a blocked call no
+ * longer records `blocked: not authenticated` and no longer bumps `callSeq`.
+ * That is the right trade — the refusal reaches the model, which the sidebar
+ * line never did, and it carries the state and its instruction rather than one
+ * fixed sentence.
+ *
+ * **`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 +373,25 @@ 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({
+  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/system-prompt.md

@@ -3,12 +3,20 @@ customer on the phone. You can help them cancel or modify pending orders,
 return or exchange delivered orders, update their default address, and answer
 questions about their own profile, orders and our products.
 
+# Where the call is
+
+Every tool answers with the stage this call is in and what that stage expects
+next. Read it — it is the shortest true statement of what you may do, and you do
+not have to remember it between turns. A tool that is not available yet refuses
+outright and tells you what has to happen first.
+
 # Authenticate first
 
 Before anything else, identify who you are talking to by finding their user id
 — by email (`find_user_id_by_email`), or by first name, last name and zip code
 (`find_user_id_by_name_zip`) if they cannot remember the email. Do this **even
-if the caller volunteers their user id**.
+if the caller volunteers their user id**. Until you have, every other tool will
+refuse.
 
 Prefer email. Fall back to name + zip only when they cannot recall the address
 on the account.
@@ -45,7 +53,8 @@ speak; when you speak, do not also make a tool call.
 Transfer only if the caller explicitly asks for a human, or their request
 cannot be handled with your tools and this policy. Call
 `transfer_to_human_agents` first, then say exactly: "You are being transferred
-to a human agent. Please hold on." Say nothing else after that.
+to a human agent. Please hold on." Say nothing else after that. The call is over
+for you at that point, and every tool will refuse — including that one.
 
 # Speaking on the phone
 

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

@@ -9,6 +9,7 @@ const CANCEL_REASONS = ["no longer needed", "ordered by mistake"] as const;
 
 export default retailTool({
   name: "cancel_pending_order",
+  when: "serving",
   description:
     "Cancel a pending order. Only an order whose status is exactly 'pending' can be cancelled — " +
     "check the status first. The reason must be either 'no longer needed' or 'ordered by mistake'. " +
@@ -70,6 +71,5 @@ export default retailTool({
       }`,
     };
   },
-  summary: (_args, result) =>
-    isToolFailure(result) ? "cancel failed" : `cancelled ${result.order_id}`,
+  summary: (_args, result) => `cancelled ${result.order_id}`,
 });

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

@@ -6,6 +6,7 @@ import { assertCanCoverDiff, planItemSwap } from "../swap.ts";
 
 export default retailTool({
   name: "exchange_delivered_order_items",
+  when: "serving",
   description:
     "Request an exchange of items in a delivered order for different options of the SAME products. " +
     "Only a 'delivered' order can be exchanged, and only once. Remind the caller to name EVERY " +
@@ -87,6 +88,5 @@ export default retailTool({
           : `Exchange requested on ${order.order_id}. $${Math.abs(plan.diff).toFixed(2)} will be refunded to ${args.payment_method_id}. An email with return instructions is on its way.`,
     };
   },
-  summary: (_args, result) =>
-    isToolFailure(result) ? "exchange failed" : `exchange requested on ${result.order_id}`,
+  summary: (_args, result) => `exchange requested on ${result.order_id}`,
 });

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

@@ -1,7 +1,6 @@
-import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
 import { authenticateAs } from "../authenticate.ts";
-import { retailTool } from "../store.ts";
+import { BEFORE_TRANSFER, retailTool } from "../store.ts";
 
 export default retailTool({
   name: "find_user_id_by_email",
@@ -12,7 +11,12 @@ export default retailTool({
   inputSchema: z.object({
     email: z.string().max(200).describe("The customer's email, e.g. 'something@example.com'"),
   }),
-  requiresAuth: false,
+  // Legal in `serving` too: a caller repeating their email must not hit an
+  // error, and `authenticateAs` is what refuses a switch to a DIFFERENT
+  // customer. The `IDENTIFIED` event is not sent on that refusal — a flow tool
+  // sends nothing when its body answers a `ToolFailure`.
+  when: BEFORE_TRANSFER,
+  send: { type: "IDENTIFIED" },
   execute: (args, state) => {
     const target = args.email.trim().toLowerCase();
     const match = Object.values(state.store.users).find(
@@ -23,6 +27,5 @@ export default retailTool({
     }
     return authenticateAs(state, match);
   },
-  summary: (_args, result) =>
-    isToolFailure(result) ? "lookup failed" : `identified ${result.user_id}`,
+  summary: (_args, result) => `identified ${result.user_id}`,
 });

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

@@ -1,7 +1,6 @@
-import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
 import { authenticateAs } from "../authenticate.ts";
-import { retailTool } from "../store.ts";
+import { BEFORE_TRANSFER, retailTool } from "../store.ts";
 
 export default retailTool({
   name: "find_user_id_by_name_zip",
@@ -13,7 +12,8 @@ export default retailTool({
     last_name: z.string().max(100).describe("Last name, e.g. 'Doe'"),
     zip: z.string().max(20).describe("Zip code, e.g. '12345'"),
   }),
-  requiresAuth: false,
+  when: BEFORE_TRANSFER,
+  send: { type: "IDENTIFIED" },
   execute: (args, state) => {
     const first = args.first_name.trim().toLowerCase();
     const last = args.last_name.trim().toLowerCase();
@@ -31,6 +31,5 @@ export default retailTool({
     }
     return authenticateAs(state, match);
   },
-  summary: (_args, result) =>
-    isToolFailure(result) ? "lookup failed" : `identified ${result.user_id}`,
+  summary: (_args, result) => `identified ${result.user_id}`,
 });

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

@@ -1,6 +1,6 @@
 import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
-import { findItem, retailTool } from "../store.ts";
+import { BEFORE_TRANSFER, findItem, retailTool } from "../store.ts";
 
 export default retailTool({
   name: "get_item_details",
@@ -10,7 +10,7 @@ export default retailTool({
   inputSchema: z.object({
     item_id: z.string().max(60).describe("The item id, e.g. '1008292230'"),
   }),
-  requiresAuth: false,
+  when: BEFORE_TRANSFER,
   execute: (args, state) => {
     const found = findItem(state, args.item_id);
     if (isToolFailure(found)) return found;
@@ -23,6 +23,5 @@ export default retailTool({
       available: found.variant.available,
     };
   },
-  summary: (_args, result) =>
-    isToolFailure(result) ? "item read failed" : `read item ${result.item_id}`,
+  summary: (_args, result) => `read item ${result.item_id}`,
 });

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

@@ -1,11 +1,11 @@
-import { isToolFailure } from "@alexkroman1/aai";
-import { omitUndefined } from "@alexkroman1/aai/utils";
+import { isToolFailure, omitUndefined } from "@alexkroman1/aai";
 import { z } from "zod";
 import { OrderIdField, resolveOrder } from "../resolve.ts";
 import { retailTool, setFocus } from "../store.ts";
 
 export default retailTool({
   name: "get_order_details",
+  when: "serving",
   description:
     "Get the status and full details of one of the authenticated customer's orders. Accepts the " +
     "order id (e.g. '#W0000000' — note the leading '#'), or a spoken reference such as " +
@@ -33,6 +33,5 @@ export default retailTool({
       ...(order.cancel_reason ? { cancel_reason: order.cancel_reason } : {}),
     };
   },
-  summary: (_args, result) =>
-    isToolFailure(result) ? "order read failed" : `read ${result.order_id}`,
+  summary: (_args, result) => `read ${result.order_id}`,
 });

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

@@ -1,6 +1,6 @@
 import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
-import { findProduct, retailTool, setFocus } from "../store.ts";
+import { BEFORE_TRANSFER, findProduct, retailTool, setFocus } from "../store.ts";
 
 export default retailTool({
   name: "get_product_details",
@@ -10,7 +10,7 @@ export default retailTool({
   inputSchema: z.object({
     product_id: z.string().max(60).describe("The product id, e.g. '6086499569'"),
   }),
-  requiresAuth: false,
+  when: BEFORE_TRANSFER,
   execute: (args, state) => {
     const product = findProduct(state, args.product_id);
     if (isToolFailure(product)) return product;
@@ -26,6 +26,5 @@ export default retailTool({
       })),
     };
   },
-  summary: (_args, result) =>
-    isToolFailure(result) ? "product read failed" : `read product ${result.name}`,
+  summary: (_args, result) => `read product ${result.name}`,
 });

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

@@ -4,6 +4,7 @@ import { requireOwnUser, retailTool } from "../store.ts";
 
 export default retailTool({
   name: "get_user_details",
+  when: "serving",
   description:
     "Get the authenticated customer's profile: name, email, default address, payment methods " +
     "(with gift-card balances) and their order ids with each order's status.",
@@ -32,6 +33,5 @@ export default retailTool({
       })),
     };
   },
-  summary: (_args, result) =>
-    isToolFailure(result) ? "profile read failed" : `read profile ${result.user_id}`,
+  summary: (_args, result) => `read profile ${result.user_id}`,
 });

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

@@ -1,6 +1,5 @@
-import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
-import { retailTool } from "../store.ts";
+import { BEFORE_TRANSFER, retailTool } from "../store.ts";
 
 export default retailTool({
   name: "list_all_product_types",
@@ -10,13 +9,14 @@ export default retailTool({
   // Empty schema rather than omitting it: the wrapper has one code path, and
   // that is where the per-call UI-update invariant lives.
   inputSchema: z.object({}),
-  requiresAuth: false,
+  // The catalogue is not customer data, so it needs no identified caller — but
+  // it is still off limits once the call belongs to a human.
+  when: BEFORE_TRANSFER,
   execute: (_args, state) => {
     const entries = Object.values(state.store.products)
       .map((product) => [product.name, product.product_id] as const)
       .sort(([a], [b]) => a.localeCompare(b));
     return { count: entries.length, products: Object.fromEntries(entries) };
   },
-  summary: (_args, result) =>
-    isToolFailure(result) ? "catalog read failed" : `listed ${result.count} product types`,
+  summary: (_args, result) => `listed ${result.count} product types`,
 });

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

@@ -6,6 +6,7 @@ import { retailTool, setFocus } from "../store.ts";
 
 export default retailTool({
   name: "modify_pending_order_address",
+  when: "serving",
   description:
     "Change the shipping address of a pending order. Read the new address back to the caller and " +
     "get an explicit yes before calling this. This does not change the customer's default address.",
@@ -34,6 +35,5 @@ export default retailTool({
       message: `Order ${order.order_id} now ships to ${formatAddress(order.address)}.`,
     };
   },
-  summary: (_args, result) =>
-    isToolFailure(result) ? "address change failed" : `re-addressed ${result.order_id}`,
+  summary: (_args, result) => `re-addressed ${result.order_id}`,
 });

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

@@ -6,6 +6,7 @@ import { applySwap, assertCanCoverDiff, planItemSwap } from "../swap.ts";
 
 export default retailTool({
   name: "modify_pending_order_items",
+  when: "serving",
   description:
     "Change items in a pending order to different options of the SAME products. This can be done " +
     "ONCE per order and is irreversible — afterwards the order can no longer be cancelled or " +
@@ -81,7 +82,5 @@ export default retailTool({
     };
   },
   summary: (_args, result) =>
-    isToolFailure(result)
-      ? "item change failed"
-      : `modified ${result.order_id} (${result.price_difference >= 0 ? "+" : ""}${result.price_difference})`,
+    `modified ${result.order_id} (${result.price_difference >= 0 ? "+" : ""}${result.price_difference})`,
 });

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

@@ -12,6 +12,7 @@ import {
 
 export default retailTool({
   name: "modify_pending_order_payment",
+  when: "serving",
   description:
     "Change which payment method a pending order is charged to. The new method must be different " +
     "from the current one, and a gift card must hold enough to cover the whole order. The original " +
@@ -89,6 +90,5 @@ export default retailTool({
       message: `Order ${order.order_id} is now charged to ${args.payment_method_id}, and $${amount.toFixed(2)} is going back to ${original.payment_method_id}.`,
     };
   },
-  summary: (_args, result) =>
-    isToolFailure(result) ? "payment change failed" : `re-paid ${result.order_id}`,
+  summary: (_args, result) => `re-paid ${result.order_id}`,
 });

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

@@ -5,6 +5,7 @@ import { requireOwnUser, retailTool } from "../store.ts";
 
 export default retailTool({
   name: "modify_user_address",
+  when: "serving",
   description:
     "Change the customer's default address, used for future orders. Read the new address back and " +
     "get an explicit yes before calling this. This does not change the address on any existing " +
@@ -24,6 +25,5 @@ export default retailTool({
       message: `Default address updated to ${formatAddress(user.address)}. Existing orders keep their own shipping addresses.`,
     };
   },
-  summary: (_args, result) =>
-    isToolFailure(result) ? "profile address change failed" : `re-addressed ${result.user_id}`,
+  summary: (_args, result) => `re-addressed ${result.user_id}`,
 });

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

@@ -11,6 +11,7 @@ import {
 
 export default retailTool({
   name: "return_delivered_order_items",
+  when: "serving",
   description:
     "Request a return of items from a delivered order. Only a 'delivered' order can be returned, " +
     "and only once. The refund must go to the order's ORIGINAL payment method or to one of the " +
@@ -87,6 +88,5 @@ export default retailTool({
       message: `Return requested on ${order.order_id} for ${names}. The customer will get an email with return instructions, and the refund goes to ${args.payment_method_id} once the items arrive.`,
     };
   },
-  summary: (_args, result) =>
-    isToolFailure(result) ? "return failed" : `return requested on ${result.order_id}`,
+  summary: (_args, result) => `return requested on ${result.order_id}`,
 });

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

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { retailTool } from "../store.ts";
+import { BEFORE_TRANSFER, retailTool } from "../store.ts";
 
 export default retailTool({
   name: "transfer_to_human_agents",
@@ -10,9 +10,13 @@ export default retailTool({
   inputSchema: z.object({
     summary: z.string().max(2000).describe("A short summary of the caller's issue for the human"),
   }),
-  // No authentication: someone who cannot be identified is exactly who needs a
-  // human, and blocking the escape hatch behind the gate would trap them.
-  requiresAuth: false,
+  // Legal before the handoff from either side: someone who cannot be identified
+  // is exactly who needs a human, and blocking the escape hatch behind an auth
+  // gate would trap them. `TRANSFERRED` is the one transition into the terminal
+  // state, which is what makes "say nothing else after this" enforced rather
+  // than asked for — every tool, this one included, refuses afterwards.
+  when: BEFORE_TRANSFER,
+  send: { type: "TRANSFERRED" },
   summary: () => "transferred to a human agent",
   execute: (args) => ({
     transferred: true,