@alexkroman1/aai-cli 7.0.0 → 8.0.0

package/dist/templates/redline/agent.eval.test.ts

@@ -0,0 +1,209 @@
+// Copyright 2026 the AAI authors. MIT license.
+// An EVAL for a WORKFLOW APP: does the run actually do the work? Run it with
+// `aai eval`.
+//
+// `agent.test.ts` asserts about the declaration and drives the three steps one
+// at a time. This drives the WHOLE BODY — `redlineFlow` from the top — and the
+// thing it is here to check is the LOOP: the critic returns a verdict, the body
+// breaks on it, and `shipped` says which of the two stopped it. That decision is
+// the whole point of this template, and it is the one thing a per-step spec
+// structurally cannot see.
+//
+// `describeWorkflowEval` picks the providers for you and says which it picked:
+//
+//   * with `ASSEMBLYAI_API_KEY` — a LIVE run: a real model writes, a real model
+//     critiques, and a real model revises if it is asked to. That spends tokens,
+//     and a model is a NOISY instrument — one failure is a question, not a
+//     verdict. Re-run before believing either answer.
+//   * without one — a SCRIPTED run. The body, the loop and the three steps all
+//     really execute; only the gateway is answered in memory.
+//
+// Two of the three cases below are SCRIPTED IN BOTH MODES on purpose, and say so
+// where they are: their claims are about the loop's arithmetic and about what a
+// stage was SHOWN, and a live model cannot be asked to make either of those
+// true — it can only be asked and then have its answer accepted, which is not
+// evidence.
+//
+// WHAT NO EVAL HERE COVERS: durability. Imported through vitest with no bundler
+// in the path, a `"use workflow"` body is an ordinary async function — no
+// journal, no replay, and no per-step retry, so a rate-limited live run FAILS
+// where a deployed one would have ridden it out. The tier that really resumes a
+// run is `aai-cli`'s `dev-workflow.scenario.test.ts`.
+import { installStubStepFetch } from "@alexkroman1/aai/testing/vitest";
+import { describeWorkflowEval } from "@alexkroman1/aai-runtime/eval/vitest";
+import { expect } from "vitest";
+import agentDef, { MAX_ROUNDS, redline } from "./agent.ts";
+
+/** A brief with a word in it nothing else would produce, so the draft is checkable. */
+const BRIEF = "Explain why our on-call rotation is moving to a two-week quokka cycle";
+/** The one point every stage must be shown — `briefBlock` is what carries it. */
+const MUST_COVER = ["Nobody carries the pager two weeks running"];
+
+/** What the writer and the reviser are scripted to hand back. */
+const DRAFT = [
+  "The on-call rotation is moving to a two-week quokka cycle.",
+  "Nobody carries the pager two weeks running: the second week is review and follow-up.",
+].join(" ");
+
+const critique = (verdict: "ship" | "revise", score = 8): string =>
+  JSON.stringify({
+    verdict,
+    score,
+    notes: verdict === "ship" ? [] : ["Say what happens to the handover", "Name the start date"],
+  });
+
+/** One gateway reply, in the envelope `stepGenerate` reads. */
+const reply = (content: string) => ({ body: { choices: [{ message: { content } }] } });
+
+/**
+ * Answer the gateway with `contents`, in order, and record what each stage asked.
+ *
+ * The last reply repeats, matching `stubGateway`'s convention — a loop cannot
+ * know how many calls it will make, and a script that ran out mid-loop would
+ * fail on the script rather than on the code. `installStubStepFetch` rather than
+ * `installStubGateway`: `stepGenerate` goes through the published `stepFetch`
+ * slot, and a published slot BEATS a stubbed global, so stubbing the global here
+ * would test a path production does not take.
+ */
+function scriptGateway(contents: readonly string[]) {
+  let next = 0;
+  const fetched = installStubStepFetch(() => {
+    const content = contents.at(Math.min(next, contents.length - 1)) ?? "";
+    next += 1;
+    return reply(content);
+  });
+  return fetched;
+}
+
+/** Every prompt the gateway was sent, in call order. */
+function promptsOf(fetched: ReturnType<typeof scriptGateway>): string[] {
+  return fetched.calls.map((call) => String(call.body ?? ""));
+}
+
+describeWorkflowEval(agentDef, (test) => {
+  test("runs a round and lets the CRITIC decide whether there is another", async ({
+    app,
+    mode,
+  }) => {
+    // One round in live mode, deliberately: the claim is about the loop's exit,
+    // and three long-form model calls are enough to make it.
+    if (mode === "stub") scriptGateway([DRAFT, critique("ship")]);
+
+    const run = await app.run(redline, {
+      brief: BRIEF,
+      audience: "engineers",
+      rounds: 1,
+      mustCover: MUST_COVER,
+    });
+
+    // The error first, so a failed run names its own reason.
+    expect(run.error).toBeUndefined();
+    expect(run.status).toBe("completed");
+
+    const output = run.output;
+    if (output === undefined) expect.fail("a completed run must carry an output");
+    expect(output.roundsRun).toBe(1);
+    expect(output.rounds).toHaveLength(1);
+
+    const last = output.rounds.at(-1);
+    if (last === undefined) expect.fail("a run of one round must record it");
+    // THE INVARIANT the template exists for: `shipped` is true exactly when the
+    // critic said so, and a shipped round revised nothing after it. Get either
+    // half wrong and the loop spends a model call it did not need, or stops one
+    // short — both of which read as a working run.
+    expect(["ship", "revise"]).toContain(last.critique.verdict);
+    expect(output.shipped).toBe(last.critique.verdict === "ship");
+    if (output.shipped) expect(last.revisedWords).toBeUndefined();
+    else expect(last.revisedWords).toBeTypeOf("number");
+
+    // The score is CLAMPED at the call site rather than by the schema, so a
+    // model answering 11 still lands in range.
+    expect(last.critique.score).toBeGreaterThanOrEqual(1);
+    expect(last.critique.score).toBeLessThanOrEqual(10);
+    expect(last.critique.notes.length).toBeLessThanOrEqual(3);
+
+    // It wrote about the brief it was given, not about writing in general.
+    expect(output.draft).toMatch(/quokka/i);
+    expect(output.words).toBeGreaterThan(5);
+
+    // Both stages narrated, and the round is numbered — which is what a page
+    // watching the run renders.
+    expect(run.reported[0]).toBe("Writing the first draft for engineers.");
+    expect(run.reported).toContain("Round 1: reading it back critically.");
+    // Nothing durable was asked for, so nothing was skipped: this body's only
+    // waits are its model calls.
+    expect(run.slept).toEqual([]);
+  });
+
+  test("stops on the ROUND BUDGET when the critic never ships", async ({ app }) => {
+    // Scripted in both modes: a live critic cannot be made to refuse three times
+    // running, and asking it and then accepting whatever it says is not evidence
+    // about the budget. What this pins is the loop's arithmetic — the half a
+    // live case cannot reach.
+    const fetched = scriptGateway([
+      DRAFT,
+      critique("revise", 4),
+      `${DRAFT} It starts on the first Monday of the month.`,
+      critique("revise", 5),
+      `${DRAFT} It starts on the first Monday, and the handover is a written note.`,
+      critique("revise", 6),
+    ]);
+
+    const run = await app.run(redline, {
+      brief: BRIEF,
+      audience: "executives",
+      rounds: MAX_ROUNDS,
+      mustCover: MUST_COVER,
+    });
+
+    expect(run.error).toBeUndefined();
+    const output = run.output;
+    if (output === undefined) expect.fail("a completed run must carry an output");
+
+    // The BUDGET stopped it, not the critic — which is the field a page reads to
+    // say "this is as good as it got" rather than "this is finished".
+    expect(output.shipped).toBe(false);
+    expect(output.roundsRun).toBe(MAX_ROUNDS);
+    // Every round revised, because none of them shipped.
+    expect(
+      output.rounds.map((round) => round.revisedWords).every((n) => typeof n === "number"),
+    ).toBe(true);
+    // One draft plus a critique-and-revise pair per round. A loop that critiqued
+    // twice, or revised the round it shipped, changes this number.
+    expect(fetched.calls).toHaveLength(1 + 2 * MAX_ROUNDS);
+
+    // `briefBlock` is what keeps the three stages from drifting apart, and this is
+    // the assertion behind that claim: the writer, the critic AND the reviser were
+    // all shown the same brief and the same must-cover point.
+    const prompts = promptsOf(fetched);
+    expect(prompts).toHaveLength(1 + 2 * MAX_ROUNDS);
+    for (const prompt of prompts) {
+      expect(prompt).toContain("quokka");
+      expect(prompt).toContain(MUST_COVER[0]);
+    }
+    // The critic and the reviser were also shown the DRAFT, which the writer
+    // could not have been.
+    expect(prompts[1]).toContain("The on-call rotation is moving");
+    expect(prompts[2]).toContain("The critique");
+  });
+
+  test("refuses a brief that is only whitespace, terminally", async ({ app }) => {
+    // No model is reached on this path in either mode, so it costs nothing live.
+    // The case exists because the schema's `.min(20)` counts CHARACTERS: twenty
+    // spaces validate at `start()` and arrive at the writer as nothing to write
+    // from, which is why `writeDraft` carries its own `FatalError`.
+    const run = await app.run(redline, {
+      brief: " ".repeat(40),
+      audience: "general readers",
+      rounds: 1,
+      mustCover: [],
+    });
+
+    expect(run.status).toBe("failed");
+    expect(run.error).toMatch(/too short to write from/i);
+    expect(run.output).toBeUndefined();
+    // It failed before narrating anything, which is the ordering the guard
+    // implies: the check is the first thing in the step.
+    expect(run.reported).toEqual([]);
+  });
+});

package/dist/templates/research-workflow/agent.eval.test.ts

@@ -0,0 +1,329 @@
+/// <reference types="vite/client" />
+
+// An EVAL: does this desk actually behave? Run it with `aai eval`.
+//
+// `agent.test.ts` drives the four tools against a STUBBED `ctx.workflows` and
+// the five steps against a stubbed `fetch`. Neither can say whether the AGENT —
+// a model, reading this system prompt, holding these four tools — hands the
+// work off at all, or whether the run it starts is findable afterwards. That is
+// what this file is for, and it is only possible because `describeEval` opens a
+// real workflow engine per case and hands its client to the session: before
+// that, a tool calling `ctx.workflows.start` was a tool an eval could not
+// execute.
+//
+// Two boundaries this file is careful about, because a case that implied either
+// would be the worse failure:
+//
+//   * **The engine is not durable.** No journal, no replay, no retry, and a
+//     `sleep()` is RECORDED rather than taken (which is why the review wait
+//     below is an assertion about what the body ASKED for). Nothing here says
+//     anything about resume, and `aai-cli`'s `dev-workflow.scenario.test.ts` is
+//     the tier that does.
+//   * **A step's HTTP is scripted, in BOTH modes.** The live half of an eval is
+//     the SESSION's model — which tool the desk reaches for, and when. The
+//     run's own five-to-twelve model calls and its web searches are answered
+//     from `MODEL_SCRIPT` through the published `stepFetch` slot, so a case is
+//     deterministic, free, and cannot fail on a DuckDuckGo 403 or a rate limit
+//     the engine's inert `maxRetries` could not ride out. What the researcher's
+//     search loop does with what it finds is `agent.test.ts`'s subject.
+//
+// And what no eval here can see at all: anything below the audio boundary —
+// endpointing, barge-in, whether two sentences merged into one turn.
+import { withDiscoveredTools } from "@alexkroman1/aai/testing";
+import { installStubStepFetch } from "@alexkroman1/aai/testing/vitest";
+import type { EvalToolCall, EvalWorkflows } from "@alexkroman1/aai-runtime/eval";
+import { describeEval } from "@alexkroman1/aai-runtime/eval/vitest";
+import { expect } from "vitest";
+import { z } from "zod";
+import authoredAgent from "./agent.ts";
+import { research } from "./shared.ts";
+
+/**
+ * The def a DEPLOYED agent runs: authored, plus what `tools/` declares.
+ *
+ * Load-bearing, and not applied by `agent()` — the BUILD is what enumerates
+ * `tools/`, so an eval driving the raw default export would measure a desk with
+ * no tools at all and every assertion below would mean nothing. This template
+ * declares its prompt inline in `agent.ts`, so there is no `system-prompt.md`
+ * to layer on with `withSystemPrompt`.
+ *
+ * The glob is written here rather than reached for from a shared helper because
+ * this file SHIPS — see `agent.test.ts`.
+ */
+const agentDef = withDiscoveredTools(
+  authoredAgent,
+  import.meta.glob("./tools/*.ts", { eager: true }),
+);
+
+/**
+ * The key the run's steps read with `requireStepEnv`.
+ *
+ * Passed as the agent env so the eval's workflow engine publishes it: the
+ * gateway call below is answered by a fake, but `stepGenerate` asks for the key
+ * BEFORE it makes the request, so a run with no key fails on the missing
+ * credential rather than reaching the script. The ENVIRONMENT and nothing else —
+ * a template may not read a developer's CLI config.
+ */
+const EVAL_ENV = { ASSEMBLYAI_API_KEY: process.env.ASSEMBLYAI_API_KEY ?? "eval-scripted-key" };
+
+/** The one angle the scripted planner comes back with. */
+const ANGLE = "What second-hand cargo bikes actually sell for";
+
+/** The written report the scripted `writeReport` produces. */
+const REPORT_BODY =
+  "## Second-hand cargo bikes in Amsterdam\n\nAsking prices cluster between 1,200 and 2,400 EUR.";
+
+/** The two sentences the desk reads down the phone. */
+const SPOKEN_SUMMARY =
+  "Second-hand cargo bikes in Amsterdam mostly go for between one and two and a half thousand euros.";
+
+/**
+ * What the run's model calls are answered with, in the order the body asks.
+ *
+ * Six calls, and the ORDER is the assertion: brief, angles, the researcher's
+ * one action, the gap pass, the report, the spoken summary. A stage that
+ * disappeared or moved would hand a later stage an earlier reply, which is
+ * exactly what the two content assertions in "writes the report" catch.
+ *
+ * The researcher's action is `stop` on purpose: `search` and `read` go through
+ * `webSearch`/`visitWebpage`, whose fetch is the global one and not the step
+ * slot, so scripting them is not available here — a case that let them run
+ * would really search the web.
+ */
+const MODEL_SCRIPT: readonly string[] = [
+  JSON.stringify({
+    brief: "What a used cargo bike costs in Amsterdam, and where they are sold.",
+    criteria: ["typical asking prices", "where people buy them"],
+  }),
+  JSON.stringify({ angles: [ANGLE] }),
+  JSON.stringify({ action: "stop", why: "the budget is better spent elsewhere" }),
+  JSON.stringify({ angles: [] }),
+  REPORT_BODY,
+  SPOKEN_SUMMARY,
+];
+
+/** A scripted step HTTP surface, and the gate that holds its first answer. */
+type ScriptedSteps = {
+  /** Every step request, in order — the gateway calls the run really made. */
+  readonly calls: readonly { url: string; method: string }[];
+  /** Let a held first answer through. Idempotent. */
+  readonly release: () => void;
+};
+
+/**
+ * Answer the run's model calls from {@link MODEL_SCRIPT}.
+ *
+ * Through `stepFetch`'s published slot rather than `vi.stubGlobal("fetch")`,
+ * which is what a step really dials — and which leaves the SESSION's own model
+ * on the live path, so a live case still measures the agent. Anything that is
+ * not the gateway THROWS rather than answering 200: an unexpected request from
+ * a step is a finding, and a silent empty body would be read as a model that
+ * said nothing.
+ *
+ * `hold` keeps the FIRST answer pending, which is the only way to observe a run
+ * that is still going: a durable `sleep` is skipped here, so an unheld run
+ * finishes in milliseconds.
+ */
+function scriptSteps(options: { hold?: boolean } = {}): ScriptedSteps {
+  const gate = Promise.withResolvers<void>();
+  let served = 0;
+  const stub = installStubStepFetch(async (request) => {
+    if (!request.url.includes("/chat/completions")) {
+      throw new Error(`unexpected step request in an eval: ${request.method} ${request.url}`);
+    }
+    const at = served++;
+    if (options.hold === true && at === 0) await gate.promise;
+    const content = MODEL_SCRIPT[Math.min(at, MODEL_SCRIPT.length - 1)];
+    return { body: { choices: [{ message: { content } }] } };
+  });
+  return { calls: stub.calls, release: () => gate.resolve() };
+}
+
+/** `request_research`'s answer when it really started something. */
+const Started = z.object({
+  started: z.literal(true),
+  runId: z.string().min(1),
+  topic: z.string().min(1),
+});
+
+/**
+ * The run id a `request_research` call reported.
+ *
+ * Parsed rather than regexed: a tool result reaches the event stream as a
+ * serialized string, and a shape that stopped matching should fail HERE naming
+ * the field instead of handing the next assertion `undefined`.
+ */
+function startedRunId(calls: readonly EvalToolCall[]): string {
+  const call = calls.find((one) => one.name === "request_research");
+  if (call?.result === undefined) {
+    throw new Error(
+      `the desk called no request_research: ${calls.map((one) => one.name).join(", ") || "(no tools)"}`,
+    );
+  }
+  return Started.parse(JSON.parse(call.result)).runId;
+}
+
+/** Every tool call in this turn that READS a run, whichever the model picked. */
+function readbacks(calls: readonly EvalToolCall[]): readonly EvalToolCall[] {
+  return calls.filter((one) => one.name === "research_status" || one.name === "research_progress");
+}
+
+/** The one utterance every case that starts work opens with. */
+const ASK = "Please research the second-hand cargo bike market in Amsterdam for me.";
+
+/** The scripted session turn that answers {@link ASK}. */
+const START_TURN = [
+  { tool: "request_research", args: { topic: "the second-hand cargo bike market in Amsterdam" } },
+  "I've started looking into that — I'll let you know when it lands.",
+] as const;
+
+/**
+ * Let the run finish before the case ends.
+ *
+ * Not tidiness: the scripted `stepFetch` is unpublished when the test that
+ * installed it finishes, so a body still mid-flight would make its next model
+ * call against whatever the next case publishes — or against the real gateway.
+ */
+async function drain(workflows: EvalWorkflows | undefined, steps: ScriptedSteps): Promise<void> {
+  steps.release();
+  for (const run of await (workflows?.runs() ?? [])) {
+    await workflows?.settle(run.runId, research);
+  }
+}
+
+describeEval(
+  agentDef,
+  (test) => {
+    test(
+      "hands the topic to a run and answers the turn without waiting for it",
+      async ({ session, workflows }) => {
+        // Held, so the run cannot possibly have finished by the time the desk
+        // replies — which is the whole claim of the handoff shape.
+        const steps = scriptSteps({ hold: true });
+
+        const turn = await session.say(ASK);
+
+        const runId = startedRunId(turn.toolCalls);
+        expect(turn.completed).toBe(true);
+        // The topic it passed is the caller's, not a paraphrase of the prompt.
+        const asked = turn.toolCalls.find((one) => one.name === "request_research");
+        expect(String(asked?.args.topic)).toMatch(/cargo bike/i);
+
+        // The run is REAL: the engine started it, under the name the agent
+        // declares, and it is still going now that the turn has ended.
+        const runs = await (workflows?.runs() ?? []);
+        const started = runs.find((one) => one.runId === runId);
+        expect(started?.workflow).toBe("research");
+        expect(started?.status).toBe("running");
+        // And it really began work — the brief stage narrated before its model
+        // call, which is the request this case is holding.
+        expect(started?.reported.join("\n")).toMatch(/really asking/);
+
+        await drain(workflows, steps);
+      },
+      { stubReply: [...START_TURN] },
+    );
+
+    test(
+      "the run really writes the report, and asks for the review wait",
+      async ({ session, workflows }) => {
+        const steps = scriptSteps();
+
+        const turn = await session.say(ASK);
+        const runId = startedRunId(turn.toolCalls);
+        const run = await workflows?.settle(runId, research);
+
+        // What a completed run reports as `output` is what the agent reads back
+        // and what the announcement is built from, so every field is asserted.
+        expect(run?.status).toBe("completed");
+        expect(run?.output?.report).toBe(REPORT_BODY);
+        expect(run?.output?.summary).toBe(SPOKEN_SUMMARY);
+        expect(run?.output?.angles).toEqual([ANGLE]);
+        expect(run?.output?.filedAt).toBe("filed");
+
+        // The five stages, in order, off the run's own narration — which is
+        // also what `research_progress` reads back down the phone. A stage that
+        // stopped reporting is a caller who is told nothing for minutes.
+        const narration = run?.reported.join("\n") ?? "";
+        expect(narration).toMatch(/really asking/);
+        expect(narration).toMatch(/Researching 1 angle/);
+        expect(narration).toMatch(new RegExp(`Looking into: ${ANGLE}`));
+        expect(narration).toMatch(/writing it up/);
+        expect(narration).toMatch(/Writing up 1 angle/);
+        expect(run?.reported.at(-1)).toBe("Filing the findings.");
+
+        // The review wait, ASKED FOR and not taken: this engine records a
+        // durable `sleep` rather than suspending, so what a case can honestly
+        // claim is that the body asked — and that is the assertion that fails
+        // if the suspension is ever deleted.
+        expect(run?.slept).toEqual([{ duration: "30 seconds" }]);
+
+        // Six model calls, all through the step slot: the fan-out's width came
+        // from a journaled stage rather than from anything the body recomputed.
+        expect(steps.calls).toHaveLength(MODEL_SCRIPT.length);
+      },
+      { stubReply: [...START_TURN] },
+    );
+
+    test(
+      "reads the live run back rather than guessing at it",
+      async ({ session, workflows }) => {
+        const steps = scriptSteps({ hold: true });
+
+        const started = await session.say(ASK);
+        const runId = startedRunId(started.toolCalls);
+        const turn = await session.say("What's it doing right now?");
+
+        // WHICH of the two readback tools the model picks is its business —
+        // the prompt offers both — so the claim is about what it was told:
+        // either the run's own latest progress line or its status, and never
+        // an answer the desk invented.
+        const read = readbacks(turn.toolCalls);
+        expect(read.length).toBeGreaterThan(0);
+        const answered = read.map((one) => one.result ?? "").join("\n");
+        expect(answered).toMatch(/really asking|Still working on it/);
+        expect(answered).not.toMatch(/Nothing started yet/);
+
+        // The load-bearing half: that readback happened while the run was
+        // genuinely in flight, which is the only state these two tools exist
+        // for.
+        const runs = await (workflows?.runs() ?? []);
+        expect(runs.find((one) => one.runId === runId)?.status).toBe("running");
+
+        await drain(workflows, steps);
+      },
+      {
+        stubReply: [
+          ...START_TURN,
+          { tool: "research_progress", args: {} },
+          "It's still working out what the question really is.",
+        ],
+      },
+    );
+
+    test(
+      "says nothing is running when nothing is, and starts nothing to find out",
+      async ({ session, workflows }) => {
+        const steps = scriptSteps();
+
+        const turn = await session.say("Any news on that research I asked for?");
+
+        const read = readbacks(turn.toolCalls);
+        expect(read.length).toBeGreaterThan(0);
+        expect(read.map((one) => one.result ?? "").join("\n")).toMatch(/Nothing started yet/);
+        // A question is not a request: asking after work nobody asked for must
+        // not put a run — and a research pass's worth of model calls — on the
+        // account.
+        expect(await (workflows?.runs() ?? [])).toEqual([]);
+        expect(steps.calls).toEqual([]);
+      },
+      {
+        stubReply: [
+          { tool: "research_status", args: {} },
+          "Nothing has been started yet — want me to look into something?",
+        ],
+      },
+    );
+  },
+  { env: EVAL_ENV },
+);

package/dist/templates/retail/address.ts

@@ -1,5 +1,14 @@
+/**
+ * Addresses: the shared schema fields, and the two address changes as
+ * plan/apply pairs (see `cancel.ts` for why every mutating action is split
+ * that way).
+ */
+
+import { isToolFailure, type ToolFailure } from "@alexkroman1/aai";
 import { z } from "zod";
-import type { Address } from "./shared.ts";
+import { resolveOrder } from "./resolve.ts";
+import type { Address, RetailState } from "./shared.ts";
+import { requireOwnUser } from "./store.ts";
 
 /** Spread into both address tools' schemas. Two hand-copied zod shapes is how
  *  the order address and the profile address drift apart. */
@@ -27,3 +36,80 @@ export function formatAddress(address: Address): string {
   const lines = [address.address1, address.address2].filter(Boolean).join(", ");
   return `${lines}, ${address.city} ${address.state} ${address.zip}, ${address.country}`;
 }
+
+// ─── One order's shipping address ────────────────────────────────────────────
+
+export interface OrderAddressPlan {
+  readBack: string;
+  orderId: string;
+  address: Address;
+}
+
+export function planOrderAddress(
+  state: RetailState,
+  spokenOrderId: string,
+  address: Address,
+): OrderAddressPlan | ToolFailure {
+  const order = resolveOrder(state, spokenOrderId);
+  if (isToolFailure(order)) return order;
+
+  // 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.`,
+    };
+  }
+
+  return {
+    readBack: `ship order ${order.order_id} to ${formatAddress(address)} instead`,
+    orderId: order.order_id,
+    address: toAddress(address),
+  };
+}
+
+export function applyOrderAddress(state: RetailState, plan: OrderAddressPlan) {
+  const order = state.store.orders[plan.orderId];
+  if (order) order.address = plan.address;
+  return {
+    order_id: plan.orderId,
+    status: order?.status ?? "pending",
+    address: plan.address,
+    message: `Order ${plan.orderId} now ships to ${formatAddress(plan.address)}.`,
+  };
+}
+
+// ─── The customer's default address ──────────────────────────────────────────
+
+export interface UserAddressPlan {
+  readBack: string;
+  userId: string;
+  address: Address;
+}
+
+export function planUserAddress(
+  state: RetailState,
+  userId: string,
+  address: Address,
+): UserAddressPlan | ToolFailure {
+  const user = requireOwnUser(state, userId);
+  if (isToolFailure(user)) return user;
+
+  return {
+    readBack:
+      `change your default address for future orders to ${formatAddress(address)} ` +
+      "(existing orders keep their own)",
+    userId: user.user_id,
+    address: toAddress(address),
+  };
+}
+
+export function applyUserAddress(state: RetailState, plan: UserAddressPlan) {
+  const user = state.store.users[plan.userId];
+  if (user) user.address = plan.address;
+  return {
+    user_id: plan.userId,
+    address: plan.address,
+    message: `Default address updated to ${formatAddress(plan.address)}. Existing orders keep their own shipping addresses.`,
+  };
+}