@alexkroman1/aai-cli 6.11.0 → 8.0.0

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

@@ -0,0 +1,196 @@
+import type { ToolContext } from "@alexkroman1/aai";
+import { isToolFailure } from "@alexkroman1/aai";
+import { createToolContext, ok, okPosition } from "@alexkroman1/aai/testing";
+import { describe, expect, test } from "vitest";
+import type { StagedResult } from "./pending.ts";
+import { retailSlot } from "./store.ts";
+import cancelChange from "./tools/cancel_change.ts";
+import cancelPendingOrder from "./tools/cancel_pending_order.ts";
+import confirmChange from "./tools/confirm_change.ts";
+import findUserIdByEmail from "./tools/find_user_id_by_email.ts";
+import getOrderDetails from "./tools/get_order_details.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";
+
+/** Aarav Anderson: one pending order (#W9300146, $153.23 on a gift card) and
+ *  one delivered order (#W4316152), which is every shape these cases need. */
+async function aaravCtx(): Promise<ToolContext> {
+  const ctx = createToolContext();
+  ok(await findUserIdByEmail.execute({ email: "aarav.anderson9752@example.com" }, ctx));
+  return ctx;
+}
+
+const stageCancel = (ctx: ToolContext) =>
+  cancelPendingOrder.execute({ order_id: "#W9300146", reason: "no longer needed" }, ctx);
+
+describe("staging", () => {
+  test("a staging tool changes NOTHING and moves the call to awaitingConfirmation", async () => {
+    const ctx = await aaravCtx();
+    const before = structuredClone(retailSlot.get(ctx).store.orders["#W9300146"]);
+
+    const staged = okPosition<StagedResult>(await stageCancel(ctx));
+
+    expect(staged.state).toBe("serving.awaitingConfirmation");
+    expect(staged.result.staged).toBe("cancel_pending_order");
+    // The whole claim of this template's policy section, as one assertion: the
+    // tool that used to cancel and refund on its first call now does neither.
+    expect(retailSlot.get(ctx).store.orders["#W9300146"]).toEqual(before);
+    const card =
+      retailSlot.get(ctx).store.users.aarav_anderson_8794?.payment_methods.gift_card_7245904;
+    expect(card?.source === "gift_card" && card.balance).toBe(17);
+  });
+
+  test("the readback names the order, the items, the amount and where the money goes", async () => {
+    const ctx = await aaravCtx();
+    const staged = ok<StagedResult>(await stageCancel(ctx));
+    expect(staged.read_back).toContain("#W9300146");
+    expect(staged.read_back).toContain("153.23");
+    expect(staged.read_back).toContain("gift_card_7245904");
+    expect(staged.read_back).toContain("no longer needed");
+  });
+
+  test("the result says out loud that nothing has happened", async () => {
+    const ctx = await aaravCtx();
+    const staged = ok<StagedResult>(await stageCancel(ctx));
+    expect(staged.message).toContain("NOTHING HAS CHANGED YET");
+    expect(staged.message).toContain("confirm_change");
+  });
+
+  test("a second stage is refused, and the refusal names the one already waiting", async () => {
+    const ctx = await aaravCtx();
+    ok(await stageCancel(ctx));
+
+    // A DIFFERENT change, so this is not a repeat of the first call.
+    const second = await modifyUserAddress.execute(
+      {
+        user_id: "aarav_anderson_8794",
+        address1: "1 A St",
+        address2: "",
+        city: "Springfield",
+        state: "OR",
+        country: "USA",
+        zip: "97477",
+      },
+      ctx,
+    );
+    expect(isToolFailure(second)).toBe(true);
+    // Naming the waiting sentence is why the staging tools are gated on
+    // `serving` rather than on `serving.helping`: a state's instruction is
+    // static and could only have said which STATE the call is in.
+    expect(isToolFailure(second) && second.error).toContain("#W9300146");
+    expect(isToolFailure(second) && second.error).toContain("cancel_change");
+    expect(retailSlot.get(ctx).store.users.aarav_anderson_8794?.address.city).not.toBe(
+      "Springfield",
+    );
+  });
+});
+
+describe("confirming", () => {
+  test("confirm_change applies the staged change and returns to helping", async () => {
+    const ctx = await aaravCtx();
+    ok(await stageCancel(ctx));
+
+    const done = okPosition<{ confirmed: string; status: string }>(
+      await confirmChange.execute({}, ctx),
+    );
+    expect(done.state).toBe("serving.helping");
+    expect(done.result.confirmed).toBe("cancel_pending_order");
+    expect(retailSlot.get(ctx).store.orders["#W9300146"]?.status).toBe("cancelled");
+    expect(retailSlot.get(ctx).pending).toBeNull();
+  });
+
+  test("confirm_change with nothing staged is refused by the GATE, before its body", async () => {
+    const ctx = await aaravCtx();
+    const result = await confirmChange.execute({}, ctx);
+    expect(isToolFailure(result)).toBe(true);
+    // The SDK writes this refusal from `when` plus the state's instruction, so
+    // it says where the call is rather than merely that this was not allowed —
+    // and the body, which is the only thing in the template that mutates, never
+    // ran to find out.
+    expect(isToolFailure(result) && result.error).toContain("serving.helping");
+    expect(isToolFailure(result) && result.error).toContain("STAGES");
+  });
+
+  test("confirming twice is refused — the second call has nothing staged", async () => {
+    const ctx = await aaravCtx();
+    ok(await stageCancel(ctx));
+    ok(await confirmChange.execute({}, ctx));
+
+    const again = await confirmChange.execute({}, ctx);
+    expect(isToolFailure(again)).toBe(true);
+    // One cancellation, one refund: a double-apply would have credited the card
+    // twice, which is the failure a "did we already do this?" flag gets wrong.
+    const card =
+      retailSlot.get(ctx).store.users.aarav_anderson_8794?.payment_methods.gift_card_7245904;
+    expect(card?.source === "gift_card" && card.balance).toBe(170.23);
+  });
+});
+
+describe("cancelling a staged change", () => {
+  test("cancel_change drops it, changes nothing, and frees the call", async () => {
+    const ctx = await aaravCtx();
+    ok(await stageCancel(ctx));
+
+    const dropped = okPosition<{ dropped: string | null; message: string }>(
+      await cancelChange.execute({}, ctx),
+    );
+    expect(dropped.state).toBe("serving.helping");
+    expect(dropped.result.dropped).toBe("cancel_pending_order");
+    expect(dropped.result.message).toContain("#W9300146");
+    expect(retailSlot.get(ctx).store.orders["#W9300146"]?.status).toBe("pending");
+    expect(retailSlot.get(ctx).pending).toBeNull();
+  });
+
+  test("a corrected change can be staged straight after", async () => {
+    const ctx = await aaravCtx();
+    ok(await stageCancel(ctx));
+    ok(await cancelChange.execute({}, ctx));
+
+    // The caller changed their mind about which order — the very thing
+    // `cancel_change` exists for.
+    const restaged = ok<StagedResult>(
+      await returnDeliveredOrderItems.execute(
+        {
+          order_id: "#W4316152",
+          item_ids: ["7292993796"],
+          payment_method_id: "gift_card_7245904",
+        },
+        ctx,
+      ),
+    );
+    expect(restaged.staged).toBe("return_delivered_order_items");
+  });
+});
+
+describe("what stays legal while a change waits", () => {
+  test("a read is still answerable — 'what was the total again?'", async () => {
+    const ctx = await aaravCtx();
+    ok(await stageCancel(ctx));
+    // `when: "serving"` matches both children, which is what makes this work.
+    const read = okPosition<{ order_id: string }>(
+      await getOrderDetails.execute({ order_id: "#W9300146" }, ctx),
+    );
+    expect(read.result.order_id).toBe("#W9300146");
+    // A read does not settle anything, so the change is still waiting.
+    expect(read.state).toBe("serving.awaitingConfirmation");
+  });
+
+  test("a caller can still ask for a human, and everything refuses afterwards", async () => {
+    const ctx = await aaravCtx();
+    ok(await stageCancel(ctx));
+
+    const transferred = okPosition(
+      await transferToHumanAgents.execute({ summary: "wants a human" }, ctx),
+    );
+    // `TRANSFERRED` is declared on the `serving` PARENT, which is what lets it
+    // fire from inside the confirmation.
+    expect(transferred.state).toBe("transferred");
+    expect(transferred.done).toBe(true);
+
+    // Including the two settling tools: a call given away cannot be finished.
+    expect(isToolFailure(await confirmChange.execute({}, ctx))).toBe(true);
+    expect(isToolFailure(await cancelChange.execute({}, ctx))).toBe(true);
+    expect(retailSlot.get(ctx).store.orders["#W9300146"]?.status).toBe("pending");
+  });
+});

package/dist/templates/retail/pending.ts

@@ -0,0 +1,137 @@
+/**
+ * The change waiting on the caller's word — what is staged, and what applying
+ * it does.
+ *
+ * Retail's policy has always said "confirm every change out loud … never act on
+ * an implied yes", and for a long time the only thing carrying that was prose:
+ * the sentence sat in the system prompt and in seven tool descriptions, and
+ * `cancel_pending_order` cancelled and refunded on its first call whether or not
+ * a word had been said. A rule enforced by asking a model nicely is not a rule.
+ *
+ * It is a MECHANISM now, and the mechanism is two halves that need each other:
+ *
+ * 1. **No tool mutates.** The seven changing tools validate everything, price
+ *    it, write a {@link PendingAction} here and return the sentence to read
+ *    back. `confirm_change` is the only thing in the template that writes to
+ *    the store.
+ * 2. **`confirm_change` is gated on a STATE.** `callFlow`'s
+ *    `serving.awaitingConfirmation` (`store.ts`) is reachable only by staging,
+ *    so confirming a change nobody staged is refused by the SDK before the body
+ *    runs — and the refusal says where the call is and what has to happen first.
+ *
+ * The half that is not enforceable stays honest about it: nothing here can know
+ * that the agent really SAID the sentence, or that the caller really answered
+ * yes. What the gate buys is that a change cannot happen in the same turn it was
+ * described in — the model has to come back for a second call, with the caller's
+ * answer in between — which is the property the prose could not have.
+ *
+ * Adapted from `travel-concierge`, whose `stageAction`/`confirm_action` pair is
+ * the same shape one domain over. The difference worth noting: its plans are
+ * re-derived at confirm time, and these are computed once at stage time and held
+ * as primitives. That is deliberate — see `cancel.ts`. A "yes" must never be
+ * followed by a refusal.
+ */
+
+import type { ToolFailure } from "@alexkroman1/aai";
+import type { OrderAddressPlan, UserAddressPlan } from "./address.ts";
+import { applyOrderAddress, applyUserAddress } from "./address.ts";
+import { applyCancel, type CancelPlan } from "./cancel.ts";
+import { applyPayment, type PaymentPlan } from "./payment.ts";
+import { applyReturn, type ReturnPlan } from "./returns.ts";
+import type { RetailState } from "./shared.ts";
+import type { ExchangePlan, ModifyItemsPlan } from "./swap.ts";
+import { applyExchange, applyModifyItems } from "./swap.ts";
+
+/**
+ * A validated, priced, not-yet-applied change.
+ *
+ * `kind` is the NAME OF THE TOOL that staged it, so the activity feed, the
+ * sidebar and every refusal can say which change is waiting in the same words
+ * the model called it by.
+ */
+export type PendingAction =
+  | { kind: "cancel_pending_order"; plan: CancelPlan }
+  | { kind: "modify_pending_order_address"; plan: OrderAddressPlan }
+  | { kind: "modify_pending_order_items"; plan: ModifyItemsPlan }
+  | { kind: "modify_pending_order_payment"; plan: PaymentPlan }
+  | { kind: "modify_user_address"; plan: UserAddressPlan }
+  | { kind: "return_delivered_order_items"; plan: ReturnPlan }
+  | { kind: "exchange_delivered_order_items"; plan: ExchangePlan };
+
+/** What a staging tool answers with: the sentence, and nothing done yet. */
+export interface StagedResult {
+  staged: PendingAction["kind"];
+  read_back: string;
+  message: string;
+}
+
+/**
+ * Put a change in front of the caller.
+ *
+ * A SECOND stage is refused rather than queued, and the refusal names the
+ * sentence already waiting — which is the whole reason the staging tools are
+ * gated on `serving` (either child) rather than on `serving.helping`. A state
+ * gate could only say "you are at serving.awaitingConfirmation", a state's
+ * instruction being static; this can say *which* change is waiting, which is
+ * what lets the model settle that one and re-stage the other. Same resolution
+ * as `travel-concierge`, and for the same reason.
+ */
+export function stageAction(state: RetailState, action: PendingAction): StagedResult | ToolFailure {
+  const waiting = state.pending;
+  if (waiting) {
+    return {
+      error:
+        `A change is already waiting on the caller's yes: "${waiting.plan.readBack}". ` +
+        "Settle that one with confirm_change or cancel_change, then stage this one.",
+    };
+  }
+  state.pending = action;
+  return {
+    staged: action.kind,
+    read_back: action.plan.readBack,
+    message:
+      `NOTHING HAS CHANGED YET. Read this back to the caller — "${action.plan.readBack}" — ` +
+      "and wait for an explicit yes. Then call confirm_change, or cancel_change if they say no.",
+  };
+}
+
+/**
+ * Perform the staged change.
+ *
+ * Total: every plan was validated against this same store, and nothing between
+ * staging and confirming can invalidate one — `confirm_change` and
+ * `cancel_change` are the only tools legal in `awaitingConfirmation`, and
+ * neither is a mutation the other's plan depends on. That totality is the
+ * point. An `applyAction` that could fail would mean a caller saying yes and
+ * hearing "actually, no", which is exactly the outcome staging exists to
+ * prevent.
+ */
+export function applyAction(state: RetailState, action: PendingAction) {
+  switch (action.kind) {
+    case "cancel_pending_order":
+      return applyCancel(state, action.plan);
+    case "modify_pending_order_address":
+      return applyOrderAddress(state, action.plan);
+    case "modify_pending_order_items":
+      return applyModifyItems(state, action.plan);
+    case "modify_pending_order_payment":
+      return applyPayment(state, action.plan);
+    case "modify_user_address":
+      return applyUserAddress(state, action.plan);
+    case "return_delivered_order_items":
+      return applyReturn(state, action.plan);
+    case "exchange_delivered_order_items":
+      return applyExchange(state, action.plan);
+    default: {
+      // Unreachable: the seven arms above exhaust `PendingAction`, and this
+      // ASSIGNMENT is what keeps that true — an eighth member of the union
+      // stops compiling here rather than falling silently through to a change
+      // nobody applies. It exists because biome's `useDefaultSwitchClause`
+      // wants an arm, not because a call can reach it, which is why it throws
+      // rather than answering the `ToolFailure` the rest of this template
+      // prefers: there is no live call on this path to recover.
+      const unreachable: never = action;
+      throw new Error(`No apply for staged action ${JSON.stringify(unreachable)}`);
+    }
+  }
+}

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

@@ -4,11 +4,12 @@ import { isToolFailure, type ToolContext } from "@alexkroman1/aai";
 import { createToolContext, withDiscoveredTools } from "@alexkroman1/aai/testing";
 import { describe, expect, test } from "vitest";
 import authoredAgent from "./agent.ts";
-import { retailSlot } from "./store.ts";
+import { callFlow, retailSlot } from "./store.ts";
 
-/** Tools that legitimately run before the caller is identified. Everything
- *  else must refuse. Listed here so ADDING an unauthenticated tool is a
- *  deliberate edit to this file, not a silent gap. */
+/** Tools that legitimately run before the caller is identified — the six
+ *  declaring `when: BEFORE_TRANSFER`. Everything else must refuse. Listed here
+ *  so ADDING an unauthenticated tool is a deliberate edit to this file, not a
+ *  silent gap. */
 const PUBLIC_TOOLS = new Set([
   "find_user_id_by_email",
   "find_user_id_by_name_zip",
@@ -37,11 +38,53 @@ const registry = Object.entries(retailAgent.tools);
 // distinct session, which is what these per-tool cases assume.
 const makeCtx = (): ToolContext => createToolContext();
 
+/** A context whose call flow is in `serving.helping`, so a `when: "serving"`
+ *  tool can reach its body. Moved through the FLOW rather than by writing
+ *  `authenticatedUserId`, because the gate reads the machine. */
+function servingCtx(): ToolContext {
+  const ctx = makeCtx();
+  callFlow.send(ctx, { type: "IDENTIFIED" });
+  return ctx;
+}
+
+/** The two tools legal only while a change waits on the caller's yes. */
+const SETTLING_TOOLS = new Set(["cancel_change", "confirm_change"]);
+
+function toolNamed(name: string) {
+  const def = retailAgent.tools[name];
+  if (!def) throw new Error(`no tool named ${name}`);
+  return def;
+}
+
+/**
+ * A context in whatever state `name` needs to reach its BODY.
+ *
+ * The two settling tools are reached by really identifying a caller and really
+ * staging a change, rather than by sending `STAGED` at the machine: they read
+ * `state.pending`, and a position with nothing staged behind it is a state this
+ * template cannot actually be in. Everything else only needs `serving`.
+ */
+async function bodyReachableCtx(name: string): Promise<ToolContext> {
+  if (!SETTLING_TOOLS.has(name)) return servingCtx();
+  const ctx = makeCtx();
+  await toolNamed("find_user_id_by_email").execute(
+    { email: "aarav.anderson9752@example.com" },
+    ctx,
+  );
+  await toolNamed("cancel_pending_order").execute(
+    { order_id: "#W9300146", reason: "no longer needed" },
+    ctx,
+  );
+  return ctx;
+}
+
 /** Minimal args satisfying each tool's schema. Deliberately plausible-shaped
  *  but wrong — these calls are expected to fail; what is asserted is that they
  *  still moved the UI. */
 const SAMPLE_ARGS: Record<string, Record<string, unknown>> = {
+  cancel_change: {},
   cancel_pending_order: { order_id: "#W0000000", reason: "no longer needed" },
+  confirm_change: {},
   exchange_delivered_order_items: {
     order_id: "#W0000000",
     item_ids: ["0000000000"],
@@ -92,10 +135,17 @@ const SAMPLE_ARGS: Record<string, Record<string, unknown>> = {
 };
 
 describe("tool registry", () => {
-  test("registers all fifteen tau2 retail tools", () => {
+  test("registers all seventeen tools", () => {
+    // Fifteen of these are tau2's retail tool set, which this template used to
+    // hold verbatim. `confirm_change` and `cancel_change` are the two it does
+    // not have: tau2's tools apply on their first call, and here nothing does —
+    // see `pending.ts`. Departing from that set is what buys the confirmation
+    // gate, and it is the reason this list is no longer a fidelity claim.
     expect(registry.map(([name]) => name).sort()).toEqual(
       [
+        "cancel_change",
         "cancel_pending_order",
+        "confirm_change",
         "exchange_delivered_order_items",
         "find_user_id_by_email",
         "find_user_id_by_name_zip",
@@ -134,7 +184,11 @@ describe("the UI-update invariant", () => {
   // This is the one that fails if a future tool is built with tool() instead of
   // retailTool(): it would work, and the sidebar would sit still through it.
   test.each(registry)("%s increments callSeq and logs activity", async (name, def) => {
-    const ctx = makeCtx();
+    // In whichever state lets the body run, so the flow gate is not what these
+    // calls are testing: the point is that a tool which reaches its BODY moves
+    // the sidebar. A refused call never reaches one — the hook below is what
+    // moves the sidebar for those.
+    const ctx = await bodyReachableCtx(name);
     const before = retailSlot.get(ctx).callSeq;
     await def.execute(SAMPLE_ARGS[name] ?? {}, ctx);
     const state = retailSlot.get(ctx);
@@ -146,12 +200,82 @@ describe("the UI-update invariant", () => {
   test.each(registry)("%s logs its own registry key as its name", async (name, def) => {
     // Catches a copy-paste where the retailTool `name` and the registry key
     // disagree — the activity feed would then attribute calls to the wrong tool.
-    const ctx = makeCtx();
+    const ctx = await bodyReachableCtx(name);
     await def.execute(SAMPLE_ARGS[name] ?? {}, ctx);
     expect(retailSlot.get(ctx).activity.at(-1)?.tool).toBe(name);
   });
 });
 
+describe("the blocked-call hook", () => {
+  /**
+   * A `tool.called`, delivered the way the RUNTIME delivers it.
+   *
+   * The hook is a plain function on the def, so this needs no harness — and
+   * asserting on it here is the only way the blocked lines are covered at all:
+   * they are written by something no tool call executes.
+   */
+  const called = (name: string, ctx: ToolContext) =>
+    retailAgent.events?.["tool.called"]?.(
+      {
+        type: "tool.called",
+        toolCallId: "call_1",
+        toolName: name,
+        args: {},
+        meta: { id: "evt_1", at: 0 },
+      },
+      ctx,
+    );
+
+  test.each(registry.filter(([name]) => !PUBLIC_TOOLS.has(name)))(
+    "%s records a blocked line when the model tries it too early",
+    (name) => {
+      const ctx = makeCtx();
+      called(name, ctx);
+
+      // The regression this closes: the gate moved out of `retailTool` and the
+      // sidebar stopped showing the most interesting calls the model makes.
+      const state = retailSlot.get(ctx);
+      expect(state.callSeq, `${name} recorded no blocked line`).toBe(1);
+      expect(state.activity.at(-1)?.tool).toBe(name);
+      expect(state.activity.at(-1)?.summary).toContain("blocked");
+      expect(state.activity.at(-1)?.summary).toContain("identifying");
+    },
+  );
+
+  test.each(registry.filter(([name]) => PUBLIC_TOOLS.has(name)))(
+    "%s is left to the wrapper, because it is going to run",
+    (name) => {
+      const ctx = makeCtx();
+      called(name, ctx);
+      // The double-count this avoids: a tool that reaches its body records its
+      // own line from inside it, with a real summary.
+      expect(retailSlot.get(ctx).activity, `${name} was double-recorded`).toEqual([]);
+    },
+  );
+
+  test("a tool this template did not declare is ignored", () => {
+    const ctx = makeCtx();
+    called("web_search", ctx);
+    // `gateFor` answers `undefined` for anything not built through `retailTool`
+    // — a builtin, or a tool a future author adds outside the wrapper. Recording
+    // those would put lines in the feed for calls this gate has no opinion on.
+    expect(retailSlot.get(ctx).activity).toEqual([]);
+  });
+
+  test("the same tool stops being blocked once the caller is identified", async () => {
+    const ctx = makeCtx();
+    called("get_user_details", ctx);
+    expect(retailSlot.get(ctx).activity).toHaveLength(1);
+
+    // The hook asks the flow, so it follows the flow: same tool, same session,
+    // no line once the position allows it.
+    const authed = await bodyReachableCtx("get_user_details");
+    const before = retailSlot.get(authed).activity.length;
+    called("get_user_details", authed);
+    expect(retailSlot.get(authed).activity).toHaveLength(before);
+  });
+});
+
 describe("the authentication gate", () => {
   test.each(registry.filter(([name]) => !PUBLIC_TOOLS.has(name)))(
     "%s refuses before the caller is identified",
@@ -159,6 +283,11 @@ describe("the authentication gate", () => {
       const result = await def.execute(SAMPLE_ARGS[name] ?? {}, makeCtx());
       expect(isToolFailure(result), `${name} did not refuse`).toBe(true);
       if (!isToolFailure(result)) return;
+      // The refusal is `callFlow`'s: it names the position, and quotes the
+      // state's instruction — which names the two tools that get out of it.
+      expect(result.error, `${name} refused without naming the position`).toContain(
+        '"identifying"',
+      );
       expect(result.error, `${name} refused for the wrong reason`).toContain(
         "find_user_id_by_email",
       );
@@ -197,3 +326,17 @@ describe("agent config", () => {
     expect(a.store).toEqual(b.store);
   });
 });
+
+describe("the transfer is terminal", () => {
+  test.each(registry)("%s refuses once the call is with a human", async (name, def) => {
+    const ctx = servingCtx();
+    callFlow.send(ctx, { type: "TRANSFERRED" });
+
+    const result = await def.execute(SAMPLE_ARGS[name] ?? {}, ctx);
+    // EVERY tool, the six public ones and `transfer_to_human_agents` itself
+    // included: nothing declares itself legal in the final state. Before the
+    // flow, the policy's "say nothing else after that" was enforced by nothing.
+    expect(isToolFailure(result), `${name} still ran after the handoff`).toBe(true);
+    expect(isToolFailure(result) && result.error, name).toContain('"transferred"');
+  });
+});

package/dist/templates/retail/returns.ts

@@ -0,0 +1,102 @@
+/**
+ * Returning items from a delivered order, as a plan and an apply (see
+ * `cancel.ts` for why every mutating action is split that way).
+ */
+
+import { isToolFailure, type ToolFailure } from "@alexkroman1/aai";
+import { resolveOrder } from "./resolve.ts";
+import type { RetailState } from "./shared.ts";
+import { authenticatedUser, findPaymentMethod, isGiftCard } from "./store.ts";
+
+export interface ReturnPlan {
+  readBack: string;
+  orderId: string;
+  /** In the order the caller named them — duplicates are meaningful. */
+  itemIds: string[];
+  /** Item names, positionally aligned with `itemIds`, so the readback and the
+   *  result can name things rather than read ten-digit numbers aloud. */
+  itemNames: string[];
+  paymentMethodId: string;
+}
+
+export function planReturn(
+  state: RetailState,
+  spokenOrderId: string,
+  itemIds: string[],
+  paymentMethodId: string,
+): ReturnPlan | ToolFailure {
+  const user = authenticatedUser(state);
+  if (isToolFailure(user)) return user;
+
+  const order = resolveOrder(state, spokenOrderId);
+  if (isToolFailure(order)) return order;
+
+  if (order.status !== "delivered") {
+    return {
+      error: `Order ${order.order_id} is ${order.status}. Only a delivered order can be returned, and only once.`,
+    };
+  }
+
+  const method = findPaymentMethod(user, paymentMethodId);
+  if (isToolFailure(method)) return method;
+
+  const originalMethodId = order.payment_history[0]?.payment_method_id;
+  if (!isGiftCard(method) && paymentMethodId !== originalMethodId) {
+    return {
+      error: `A refund must go to the original payment method (${originalMethodId}) or to a gift card. ${paymentMethodId} is neither.`,
+    };
+  }
+
+  if (itemIds.length === 0) {
+    return { error: "No items were listed to return." };
+  }
+  const held = new Map<string, number>();
+  for (const item of order.items) {
+    held.set(item.item_id, (held.get(item.item_id) ?? 0) + 1);
+  }
+  const asked = new Map<string, number>();
+  for (const itemId of itemIds) {
+    asked.set(itemId, (asked.get(itemId) ?? 0) + 1);
+  }
+  for (const [itemId, count] of asked) {
+    const available = held.get(itemId) ?? 0;
+    if (count > available) {
+      return {
+        error: `Order ${order.order_id} holds ${available} of item ${itemId}, but ${count} were listed for return.`,
+      };
+    }
+  }
+
+  const itemNames = itemIds.map(
+    (id) => order.items.find((item) => item.item_id === id)?.name ?? id,
+  );
+  return {
+    readBack:
+      `return ${itemNames.join(", ")} from order ${order.order_id}, ` +
+      `with the refund going to ${paymentMethodId}`,
+    orderId: order.order_id,
+    itemIds: [...itemIds],
+    itemNames,
+    paymentMethodId,
+  };
+}
+
+export function applyReturn(state: RetailState, plan: ReturnPlan) {
+  const order = state.store.orders[plan.orderId];
+
+  // In the order the caller named them, not sorted: tau2 sorted this list to
+  // match an expected end state, and nothing compares against one any more.
+  if (order) {
+    order.status = "return requested";
+    order.return_items = [...plan.itemIds];
+    order.return_payment_method_id = plan.paymentMethodId;
+  }
+
+  return {
+    order_id: plan.orderId,
+    status: "return requested" as const,
+    return_items: plan.itemIds,
+    refund_to: plan.paymentMethodId,
+    message: `Return requested on ${plan.orderId} for ${plan.itemNames.join(", ")}. The customer will get an email with return instructions, and the refund goes to ${plan.paymentMethodId} once the items arrive.`,
+  };
+}