@alexkroman1/aai-cli 6.11.0 → 8.0.0

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

@@ -1,17 +1,21 @@
 import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
-import { OrderIdField, resolveOrder } from "../resolve.ts";
-import { authenticatedUser, money, retailTool, setFocus } from "../store.ts";
-import { assertCanCoverDiff, planItemSwap } from "../swap.ts";
+import { stageAction } from "../pending.ts";
+import { OrderIdField } from "../resolve.ts";
+import { retailTool, setFocus } from "../store.ts";
+import { planExchange } from "../swap.ts";
 
 export default retailTool({
   name: "exchange_delivered_order_items",
+  when: "serving",
+  send: { type: "STAGED" },
   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 " +
-    "item they want exchanged before you call this, read the whole list and the price difference " +
-    "back, and get an explicit yes. No new order is needed — the customer gets an email explaining " +
-    "how to send the originals back.",
+    "STAGE an exchange of items in a delivered order for different options of the SAME products — " +
+    "this does NOT request anything. Only a 'delivered' order can be exchanged, and only once, so " +
+    "remind the caller to name EVERY item they want exchanged before you call this. The whole " +
+    "list and the price difference come back as a sentence to read to them; nothing happens until " +
+    "you hear an explicit yes and call confirm_change. No new order is needed — the customer gets " +
+    "an email explaining how to send the originals back.",
   inputSchema: z.object({
     order_id: OrderIdField,
     item_ids: z
@@ -28,65 +32,16 @@ export default retailTool({
       .describe("Method to charge or refund the price difference"),
   }),
   execute: (args, state) => {
-    const user = authenticatedUser(state);
-    if (isToolFailure(user)) return user;
-
-    const order = resolveOrder(state, args.order_id);
-    if (isToolFailure(order)) return order;
-    setFocus(state, { orderId: order.order_id });
-
-    if (order.status !== "delivered") {
-      return {
-        error: `Order ${order.order_id} is ${order.status}. Only a delivered order can be exchanged, and only once.`,
-      };
-    }
-
-    // requireDifferent is false: tau2 permits a same-item entry here, and a
-    // zero-difference exchange is harmless on a delivered order.
-    const plan = planItemSwap(state, order, args.item_ids, args.new_item_ids, {
-      requireDifferent: false,
-    });
+    const plan = planExchange(
+      state,
+      args.order_id,
+      args.item_ids,
+      args.new_item_ids,
+      args.payment_method_id,
+    );
     if (isToolFailure(plan)) return plan;
-
-    const blocked = assertCanCoverDiff(user, args.payment_method_id, plan.diff);
-    if (blocked) return blocked;
-
-    // No balance moves and no items change: this records a REQUEST. The money
-    // and the item swap settle when the originals come back.
-    order.status = "exchange requested";
-    // SORTED INDEPENDENTLY, verbatim from tau2 (`order.exchange_items =
-    // sorted(item_ids)` / `sorted(new_item_ids)`, the same shape
-    // `return_delivered_order_items` uses one list of) — kept because
-    // `seed.json` is tau2's data and these fields are what a tau2 task's
-    // expected end state is compared against. They are therefore two SETS of
-    // ids, not a pairing: sorting each list separately permutes the second
-    // against the first whenever the caller named more than one item.
-    //
-    // Which is why the ANSWER carries `exchanges` instead. `planItemSwap`
-    // priced this positionally, so returning the two sorted lists as if they
-    // lined up told the caller a pairing the quote was not for — the one thing
-    // this result must not do, since the model reads it back down a phone.
-    order.exchange_items = [...args.item_ids].sort();
-    order.exchange_new_items = [...args.new_item_ids].sort();
-    order.exchange_payment_method_id = args.payment_method_id;
-    order.exchange_price_difference = plan.diff;
-
-    return {
-      order_id: order.order_id,
-      status: order.status,
-      price_difference: plan.diff,
-      // The pairing AS PRICED, per line, in the order the caller gave it.
-      exchanges: plan.pairs.map((pair) => ({
-        item_id: pair.item.item_id,
-        new_item_id: pair.newVariant.item_id,
-        price_difference: money(pair.newVariant.price - pair.item.price),
-      })),
-      message:
-        plan.diff > 0
-          ? `Exchange requested on ${order.order_id}. $${plan.diff.toFixed(2)} will be charged to ${args.payment_method_id}. An email with return instructions is on its way.`
-          : `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.`,
-    };
+    setFocus(state, { orderId: plan.orderId });
+    return stageAction(state, { kind: "exchange_delivered_order_items", plan });
   },
-  summary: (_args, result) =>
-    isToolFailure(result) ? "exchange failed" : `exchange requested on ${result.order_id}`,
+  summary: (_args, result) => `staged: ${result.read_back}`,
 });

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

@@ -1,39 +1,27 @@
 import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
-import { AddressFields, formatAddress, toAddress } from "../address.ts";
-import { OrderIdField, resolveOrder } from "../resolve.ts";
+import { AddressFields, planOrderAddress } from "../address.ts";
+import { stageAction } from "../pending.ts";
+import { OrderIdField } from "../resolve.ts";
 import { retailTool, setFocus } from "../store.ts";
 
 export default retailTool({
   name: "modify_pending_order_address",
+  when: "serving",
+  send: { type: "STAGED" },
   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.",
+    "STAGE a change to a pending order's shipping address — this does NOT change it. The new " +
+    "address comes back as a sentence to read to the caller; nothing happens until you hear an " +
+    "explicit yes and call confirm_change. This does not touch the customer's default address.",
   inputSchema: z.object({
     order_id: OrderIdField,
     ...AddressFields,
   }),
   execute: (args, state) => {
-    const order = resolveOrder(state, args.order_id);
-    if (isToolFailure(order)) return order;
-    setFocus(state, { orderId: order.order_id });
-
-    // Any pending variant is fine here — unlike cancel and modify-items, which
-    // require exactly 'pending'. Re-addressing a modified order is harmless.
-    if (!order.status.startsWith("pending")) {
-      return {
-        error: `Order ${order.order_id} is ${order.status}, and only a pending order's address can be changed.`,
-      };
-    }
-
-    order.address = toAddress(args);
-    return {
-      order_id: order.order_id,
-      status: order.status,
-      address: order.address,
-      message: `Order ${order.order_id} now ships to ${formatAddress(order.address)}.`,
-    };
+    const plan = planOrderAddress(state, args.order_id, args);
+    if (isToolFailure(plan)) return plan;
+    setFocus(state, { orderId: plan.orderId });
+    return stageAction(state, { kind: "modify_pending_order_address", plan });
   },
-  summary: (_args, result) =>
-    isToolFailure(result) ? "address change failed" : `re-addressed ${result.order_id}`,
+  summary: (_args, result) => `staged: ${result.read_back}`,
 });

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

@@ -1,17 +1,22 @@
 import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
-import { OrderIdField, resolveOrder } from "../resolve.ts";
-import { authenticatedUser, isGiftCard, money, retailTool, setFocus } from "../store.ts";
-import { applySwap, assertCanCoverDiff, planItemSwap } from "../swap.ts";
+import { stageAction } from "../pending.ts";
+import { OrderIdField } from "../resolve.ts";
+import { retailTool, setFocus } from "../store.ts";
+import { planModifyItems } from "../swap.ts";
 
 export default retailTool({
   name: "modify_pending_order_items",
+  when: "serving",
+  send: { type: "STAGED" },
   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 " +
-    "modified at all. Collect EVERY item the caller wants changed into one call, read the whole " +
-    "list and the price difference back, and get an explicit yes first. The item and replacement " +
-    "lists are positional and must be the same length.",
+    "STAGE a change of items in a pending order to different options of the SAME products — this " +
+    "does NOT change anything. It can only ever be done ONCE per order and is irreversible: " +
+    "afterwards the order can no longer be cancelled or modified at all. So collect EVERY item " +
+    "the caller wants changed into one call — ask them 'is that everything you want to change?' " +
+    "explicitly first. The whole list and the price difference come back as a sentence to read " +
+    "to them; nothing happens until you hear an explicit yes and call confirm_change. The item " +
+    "and replacement lists are positional and must be the same length.",
   inputSchema: z.object({
     order_id: OrderIdField,
     item_ids: z
@@ -28,60 +33,16 @@ export default retailTool({
       .describe("Method to charge or refund the price difference, e.g. 'gift_card_0000000'"),
   }),
   execute: (args, state) => {
-    const user = authenticatedUser(state);
-    if (isToolFailure(user)) return user;
-
-    const order = resolveOrder(state, args.order_id);
-    if (isToolFailure(order)) return order;
-    setFocus(state, { orderId: order.order_id });
-
-    // Exactly 'pending'. A 'pending (item modified)' order has already used its
-    // one modification, which is what makes this action terminal.
-    if (order.status !== "pending") {
-      return {
-        error: `Order ${order.order_id} is ${order.status}. Items can only be changed while an order is exactly 'pending', and only once.`,
-      };
-    }
-
-    const plan = planItemSwap(state, order, args.item_ids, args.new_item_ids, {
-      requireDifferent: true,
-    });
+    const plan = planModifyItems(
+      state,
+      args.order_id,
+      args.item_ids,
+      args.new_item_ids,
+      args.payment_method_id,
+    );
     if (isToolFailure(plan)) return plan;
-
-    const blocked = assertCanCoverDiff(user, args.payment_method_id, plan.diff);
-    if (blocked) return blocked;
-
-    const method = user.payment_methods[args.payment_method_id];
-    if (method && isGiftCard(method)) {
-      method.balance = money(method.balance - plan.diff);
-    }
-    order.payment_history.push({
-      transaction_type: plan.diff > 0 ? "payment" : "refund",
-      amount: money(Math.abs(plan.diff)),
-      payment_method_id: args.payment_method_id,
-    });
-
-    applySwap(order, plan);
-    order.status = "pending (item modified)";
-
-    return {
-      order_id: order.order_id,
-      status: order.status,
-      price_difference: plan.diff,
-      items: order.items.map((item) => ({
-        name: item.name,
-        item_id: item.item_id,
-        options: item.options,
-        price: item.price,
-      })),
-      message:
-        plan.diff > 0
-          ? `Done. $${plan.diff.toFixed(2)} was charged to ${args.payment_method_id}. This order can no longer be modified or cancelled.`
-          : `Done. $${Math.abs(plan.diff).toFixed(2)} is being refunded to ${args.payment_method_id}. This order can no longer be modified or cancelled.`,
-    };
+    setFocus(state, { orderId: plan.orderId });
+    return stageAction(state, { kind: "modify_pending_order_items", plan });
   },
-  summary: (_args, result) =>
-    isToolFailure(result)
-      ? "item change failed"
-      : `modified ${result.order_id} (${result.price_difference >= 0 ? "+" : ""}${result.price_difference})`,
+  summary: (_args, result) => `staged: ${result.read_back}`,
 });

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

@@ -1,21 +1,20 @@
 import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
-import { OrderIdField, resolveOrder } from "../resolve.ts";
-import {
-  authenticatedUser,
-  findPaymentMethod,
-  isGiftCard,
-  money,
-  retailTool,
-  setFocus,
-} from "../store.ts";
+import { planPayment } from "../payment.ts";
+import { stageAction } from "../pending.ts";
+import { OrderIdField } from "../resolve.ts";
+import { retailTool, setFocus } from "../store.ts";
 
 export default retailTool({
   name: "modify_pending_order_payment",
+  when: "serving",
+  send: { type: "STAGED" },
   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 " +
-    "method is refunded. Read the change back and get an explicit yes before calling this.",
+    "STAGE a change to which payment method a pending order is charged to — this does NOT change " +
+    "it. The new method must be different from the current one, and a gift card must hold enough " +
+    "to cover the whole order; the original method is refunded. The change comes back as a " +
+    "sentence to read to the caller; nothing happens until you hear an explicit yes and call " +
+    "confirm_change.",
   inputSchema: z.object({
     order_id: OrderIdField,
     payment_method_id: z
@@ -24,71 +23,10 @@ export default retailTool({
       .describe("The new payment method id, e.g. 'gift_card_0000000'"),
   }),
   execute: (args, state) => {
-    const user = authenticatedUser(state);
-    if (isToolFailure(user)) return user;
-
-    const order = resolveOrder(state, args.order_id);
-    if (isToolFailure(order)) return order;
-    setFocus(state, { orderId: order.order_id });
-
-    if (!order.status.startsWith("pending")) {
-      return {
-        error: `Order ${order.order_id} is ${order.status}, and only a pending order's payment method can be changed.`,
-      };
-    }
-
-    const newMethod = findPaymentMethod(user, args.payment_method_id);
-    if (isToolFailure(newMethod)) return newMethod;
-
-    const original = order.payment_history[0];
-    if (order.payment_history.length !== 1 || original?.transaction_type !== "payment") {
-      return {
-        error: `Order ${order.order_id} does not have exactly one payment on record, so its payment method cannot be changed.`,
-      };
-    }
-    if (original.payment_method_id === args.payment_method_id) {
-      return {
-        error: `Order ${order.order_id} is already paid with ${args.payment_method_id}. The new method must be different.`,
-      };
-    }
-
-    const amount = original.amount;
-    if (isGiftCard(newMethod) && newMethod.balance < amount) {
-      return {
-        error: `Gift card ${args.payment_method_id}'s balance ($${newMethod.balance.toFixed(2)}) does not cover the $${amount.toFixed(2)} order total.`,
-      };
-    }
-
-    order.payment_history.push(
-      {
-        transaction_type: "payment",
-        amount,
-        payment_method_id: args.payment_method_id,
-      },
-      {
-        transaction_type: "refund",
-        amount,
-        payment_method_id: original.payment_method_id,
-      },
-    );
-
-    if (isGiftCard(newMethod)) {
-      newMethod.balance = money(newMethod.balance - amount);
-    }
-    const oldMethod = user.payment_methods[original.payment_method_id];
-    if (oldMethod && isGiftCard(oldMethod)) {
-      oldMethod.balance = money(oldMethod.balance + amount);
-    }
-
-    return {
-      order_id: order.order_id,
-      status: order.status,
-      amount,
-      paid_with: args.payment_method_id,
-      refunded_to: original.payment_method_id,
-      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}.`,
-    };
+    const plan = planPayment(state, args.order_id, args.payment_method_id);
+    if (isToolFailure(plan)) return plan;
+    setFocus(state, { orderId: plan.orderId });
+    return stageAction(state, { kind: "modify_pending_order_payment", plan });
   },
-  summary: (_args, result) =>
-    isToolFailure(result) ? "payment change failed" : `re-paid ${result.order_id}`,
+  summary: (_args, result) => `staged: ${result.read_back}`,
 });

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

@@ -1,29 +1,26 @@
 import { isToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
-import { AddressFields, formatAddress, toAddress } from "../address.ts";
-import { requireOwnUser, retailTool } from "../store.ts";
+import { AddressFields, planUserAddress } from "../address.ts";
+import { stageAction } from "../pending.ts";
+import { retailTool } from "../store.ts";
 
 export default retailTool({
   name: "modify_user_address",
+  when: "serving",
+  send: { type: "STAGED" },
   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 " +
-    "order — use modify_pending_order_address for that.",
+    "STAGE a change to the customer's default address, used for future orders — this does NOT " +
+    "change it. The new address comes back as a sentence to read to the caller; nothing happens " +
+    "until you hear an explicit yes and call confirm_change. This does not change the address on " +
+    "any existing order — use modify_pending_order_address for that.",
   inputSchema: z.object({
     user_id: z.string().max(100).describe("The user id, e.g. 'sara_doe_496'"),
     ...AddressFields,
   }),
   execute: (args, state) => {
-    const user = requireOwnUser(state, args.user_id);
-    if (isToolFailure(user)) return user;
-
-    user.address = toAddress(args);
-    return {
-      user_id: user.user_id,
-      address: user.address,
-      message: `Default address updated to ${formatAddress(user.address)}. Existing orders keep their own shipping addresses.`,
-    };
+    const plan = planUserAddress(state, args.user_id, args);
+    if (isToolFailure(plan)) return plan;
+    return stageAction(state, { kind: "modify_user_address", plan });
   },
-  summary: (_args, result) =>
-    isToolFailure(result) ? "profile address change failed" : `re-addressed ${result.user_id}`,
+  summary: (_args, result) => `staged: ${result.read_back}`,
 });