@alexkroman1/aai-cli 6.11.0 → 8.0.0

package/dist/templates/research-workflow/workflows/research.ts

@@ -35,7 +35,7 @@
  *
  * ## Every stage REPORTS, and the report goes two places
  *
- * `report()` (`@alexkroman1/aai/utils`) writes to the run's own stream — which
+ * `report()` (`@alexkroman1/aai/step`) writes to the run's own stream — which
  * `research_progress` reads back down the phone and a page renders — and to the
  * server log, with the attempt number appended past the first. A pass that is
  * retrying and one that is working print the same sentences otherwise.
@@ -49,16 +49,10 @@
  * researcher CONCLUDED, which is exactly what the step returns.
  */
 
-import { throwStepError } from "@alexkroman1/aai/step-errors";
+import { mapConcurrent, report } from "@alexkroman1/aai/step";
+import { stepGenerateClassified, stepGenerateJsonClassified } from "@alexkroman1/aai/step-errors";
 import { visitWebpage, webSearch } from "@alexkroman1/aai/tools";
-import {
-  errorMessage,
-  isToolFailure,
-  mapInBatches,
-  report,
-  stepGenerate,
-  stepGenerateJson,
-} from "@alexkroman1/aai/utils";
+import { errorMessage, isToolFailure, plural } from "@alexkroman1/aai/utils";
 import { sleep } from "workflow";
 import { z } from "zod";
 import {
@@ -108,9 +102,9 @@ export type Source = { title: string; url: string };
 
 // ---- What each stage's model call has to come back as ------------------------
 //
-// `stepGenerateJson` validates against these, so a reply that missed is a plain
-// throw and therefore a retry — where the hand-rolled `askJson<T>()` this
-// replaces returned a value the compiler believed and nothing checked. They are
+// `stepGenerateJsonClassified` validates against these, so a reply that missed
+// is a plain throw and therefore a retry — where the hand-rolled `askJson<T>()`
+// this replaces returned a value the compiler believed and nothing checked. They are
 // deliberately LENIENT wherever the old hand-written coercion was: a model that
 // put one number in an array of strings should cost that element, not the whole
 // pass.
@@ -221,12 +215,14 @@ export async function researchFlow(input: { topic: string; requestedBy: string }
   // failed angle fails the RUN: its finished siblings are already journaled, so
   // the resume replays them for free and re-issues only what is missing, where
   // catching here would file a report with a silent hole in it.
-  const first = await mapInBatches(angles, ANGLE_CONCURRENCY, (angle) => investigate(brief, angle));
+  const first = await mapConcurrent(angles, ANGLE_CONCURRENCY, (angle) =>
+    investigate(brief, angle),
+  );
 
   // The supervisor's second look. Usually empty — a second wave costs the caller
   // minutes, and the prompt says so.
   const gaps = await findGaps(brief, first);
-  const second = await mapInBatches(gaps, ANGLE_CONCURRENCY, (angle) => investigate(brief, angle));
+  const second = await mapConcurrent(gaps, ANGLE_CONCURRENCY, (angle) => investigate(brief, angle));
 
   const notes = [...first, ...second];
   const written = await writeReport(input.topic, brief, notes);
@@ -261,10 +257,9 @@ export async function writeBrief(topic: string): Promise<Brief> {
   "use step";
 
   await report(`Working out what "${topic}" is really asking.`);
-  const parsed = await askJson(
+  const parsed = await stepGenerateJsonClassified(
     `Research request, as the caller said it: ${topic}`,
-    BRIEF_SYSTEM,
-    BriefReply,
+    { system: BRIEF_SYSTEM, schema: BriefReply },
   );
   return { brief: parsed.brief || topic, criteria: parsed.criteria.slice(0, MAX_ANGLES) };
 }
@@ -279,7 +274,10 @@ export async function writeBrief(topic: string): Promise<Brief> {
 export async function planAngles(brief: Brief): Promise<string[]> {
   "use step";
 
-  const parsed = await askJson(briefText(brief), PLAN_SYSTEM, AnglesReply);
+  const parsed = await stepGenerateJsonClassified(briefText(brief), {
+    system: PLAN_SYSTEM,
+    schema: AnglesReply,
+  });
   const angles = parsed.angles.slice(0, MAX_ANGLES);
   if (angles.length === 0) {
     // Nothing to fan out over is a plan failure, not an empty result: the brief
@@ -287,7 +285,7 @@ export async function planAngles(brief: Brief): Promise<string[]> {
     await report("No angles came back; researching the brief itself.");
     return [brief.brief];
   }
-  await report(`Researching ${angles.length} angle${angles.length === 1 ? "" : "s"}.`);
+  await report(`Researching ${angles.length} ${plural(angles.length, "angle")}.`);
   return angles;
 }
 
@@ -341,16 +339,15 @@ export async function findGaps(brief: Brief, notes: readonly Note[]): Promise<st
   "use step";
 
   if (notes.length === 0) return [];
-  const parsed = await askJson(
+  const parsed = await stepGenerateJsonClassified(
     `${briefText(brief)}\n\nWhat came back:\n${notes.map(noteText).join("\n\n")}`,
-    GAPS_SYSTEM,
-    AnglesReply,
+    { system: GAPS_SYSTEM, schema: AnglesReply },
   );
   const gaps = parsed.angles.slice(0, MAX_ANGLES - 1);
   await report(
     gaps.length === 0
       ? "The brief is covered; writing it up."
-      : `Following up ${gaps.length} gap${gaps.length === 1 ? "" : "s"}.`,
+      : `Following up ${gaps.length} ${plural(gaps.length, "gap")}.`,
   );
   return gaps;
 }
@@ -369,12 +366,14 @@ export async function writeReport(
 ): Promise<{ report: string; summary: string }> {
   "use step";
 
-  await report(`Writing up ${notes.length} angle${notes.length === 1 ? "" : "s"}.`);
-  const written = await ask(
+  await report(`Writing up ${notes.length} ${plural(notes.length, "angle")}.`);
+  const written = await stepGenerateClassified(
     `${briefText(brief)}\n\nFindings:\n${notes.map(noteText).join("\n\n")}`,
-    REPORT_SYSTEM,
+    { system: REPORT_SYSTEM },
   );
-  const summary = await ask(`Topic: ${topic}\n\nReport:\n${written}`, BRIEF_SUMMARY_SYSTEM);
+  const summary = await stepGenerateClassified(`Topic: ${topic}\n\nReport:\n${written}`, {
+    system: BRIEF_SUMMARY_SYSTEM,
+  });
   return { report: written, summary };
 }
 
@@ -404,12 +403,11 @@ async function nextAction(
   seen: readonly string[],
   left: number,
 ): Promise<Action> {
-  return await askJson(
+  return await stepGenerateJsonClassified(
     `${briefText(brief)}\n\nYour angle: ${angle}\n` +
       `Actions left: ${left}\n\n` +
       (seen.length === 0 ? "You have not looked at anything yet." : seen.join("\n\n")),
-    RESEARCH_SYSTEM,
-    ActionReply,
+    { system: RESEARCH_SYSTEM, schema: ActionReply },
   );
 }
 
@@ -474,11 +472,10 @@ async function compress(angle: string, seen: readonly string[], sources: Source[
   if (seen.length === 0) {
     return { angle, findings: "Nothing was found on this angle.", sources: [] };
   }
-  const parsed = await askJson(
-    `Angle: ${angle}\n\n${seen.join("\n\n")}`,
-    COMPRESS_SYSTEM,
-    CompressReply,
-  );
+  const parsed = await stepGenerateJsonClassified(`Angle: ${angle}\n\n${seen.join("\n\n")}`, {
+    system: COMPRESS_SYSTEM,
+    schema: CompressReply,
+  });
   return {
     angle,
     findings: parsed.findings ?? seen.join("\n\n"),
@@ -489,31 +486,17 @@ async function compress(angle: string, seen: readonly string[], sources: Source[
 }
 
 // ---- Model plumbing ---------------------------------------------------------
-
-/**
- * `stepGenerate`, with this desk's retry POLICY on top.
- *
- * The SDK classifies the gateway's failure (`StepGenerateError.retryable`) and
- * stops there, deliberately: whether a terminal failure should burn the step's
- * remaining attempts is the caller's call. `throwStepError` is that call made
- * one way — terminal stays terminal, and a rate limit becomes a `RetryableError`
- * carrying the delay the gateway itself named.
- */
-async function ask(prompt: string, system: string): Promise<string> {
-  return await stepGenerate(prompt, { system }).catch(throwStepError);
-}
-
-/**
- * The same call, for a stage whose reply is JSON of a known shape.
- *
- * `stepGenerateJson` owns the four things every such stage used to re-derive —
- * unwrap the fence, parse, reject a non-object, check the shape — and throws
- * PLAINLY when any of them misses, which is what makes a malformed reply a
- * retry rather than a failure.
- */
-async function askJson<S extends z.ZodType>(prompt: string, system: string, schema: S) {
-  return await stepGenerateJson(prompt, { system, schema }).catch(throwStepError);
-}
+//
+// There is none left, and its absence is the point. This desk carried an `ask()`
+// and an `askJson()` whose whole body was `.catch(throwStepError)`; the SDK's
+// `stepGenerateClassified` and `stepGenerateJsonClassified`
+// (`@alexkroman1/aai/step-errors`) ARE that call — the `/step` one with the
+// gateway's verdict classified, so a terminal failure stays terminal and a rate
+// limit becomes a `RetryableError` carrying the delay the gateway itself named.
+// `stepGenerateJsonClassified` also owns the four things every JSON stage used
+// to re-derive — unwrap the fence, parse, reject a non-object, check the shape —
+// and throws PLAINLY when any of them misses, which is what makes a malformed
+// reply a retry rather than a failure.
 
 // ---- Pure helpers -----------------------------------------------------------
 

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.`,
+  };
+}

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

@@ -0,0 +1,314 @@
+/// <reference types="vite/client" />
+
+import { withSystemPrompt } from "@alexkroman1/aai/manifest";
+import type { SessionEvent } from "@alexkroman1/aai/protocol";
+import { withDiscoveredTools } from "@alexkroman1/aai/testing";
+// An EVAL: does this desk actually behave? Run it with `aai eval`.
+//
+// `agent.test.ts` drives each tool directly and asserts about its result;
+// `registry.test.ts` asserts every tool's gate one at a time. Neither can say
+// whether the AGENT — a model, reading this system prompt, holding these
+// seventeen tools — puts them in the right ORDER. That is what this file is
+// for, and the four things it asserts are the four this template's whole shape
+// exists to guarantee:
+//
+//   1. nothing about an order is reachable before the caller is identified,
+//   2. a change is STAGED and the store is untouched,
+//   3. an explicit yes applies it, exactly once,
+//   4. after a handoff the call is over and every tool refuses.
+//
+// Each one is a MECHANISM (a dialog gate, a plan/apply split, a terminal
+// state), so each assertion reads the mechanism's own output — the SDK's
+// refusal sentence, the tool result, and the projection the browser is sent —
+// rather than judging the sentence the model chose to say.
+//
+// What no eval here can see: anything below the audio boundary. Whether a
+// caller reading an order number in bursts lands as one turn is a property of
+// endpointing, and these fake speech stages remove it.
+import { type EvalSession, type EvalTurn, lastStateIn } 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 systemPrompt from "./system-prompt.md?raw";
+
+/**
+ * The def a DEPLOYED agent runs: authored, plus what `tools/` declares, plus
+ * what `system-prompt.md` says.
+ *
+ * BOTH wrappers are load-bearing and neither is applied by `agent()` — they are
+ * applied by the BUILD (`aai build` enumerates `tools/` and resolves the prompt
+ * file), so an eval driving the raw default export would measure a
+ * seventeen-tool desk with no tools and the FRAMEWORK DEFAULT prompt. For this
+ * template that is the whole subject: the authenticate-first discipline, the
+ * three-step readback and the one-customer-per-call rule are all in that file.
+ *
+ * The glob is written here rather than reached for from a shared helper because
+ * this file SHIPS — see `registry.test.ts`.
+ */
+const retailAgent = withSystemPrompt(
+  withDiscoveredTools(authoredAgent, import.meta.glob("./tools/*.ts", { eager: true })),
+  systemPrompt,
+);
+
+/** Harper Brown: exactly ONE pending order, which is what makes "cancel my
+ *  pending order" unambiguous — `resolveOrder` refuses a reference that matches
+ *  two, so a persona with two pending orders would put this eval's subject
+ *  (the confirmation gate) behind a disambiguation turn. */
+const CALLER_EMAIL = "harper.brown3965@example.com";
+const PENDING_ORDER = "#W2273069";
+
+/** The six tools that legitimately run before the caller is identified — the
+ *  ones declaring `when: BEFORE_TRANSFER`. Anything else must refuse. */
+const PUBLIC_TOOLS = new Set([
+  "find_user_id_by_email",
+  "find_user_id_by_name_zip",
+  "get_product_details",
+  "get_item_details",
+  "list_all_product_types",
+  "transfer_to_human_agents",
+]);
+
+/**
+ * What the BROWSER is sent, as this eval reads it.
+ *
+ * Parsed rather than cast: `state.updated` carries `unknown`, and a schema that
+ * stops matching is a loud failure naming the field, where a cast would hand
+ * the assertions `undefined` and fail three lines later. It names only the
+ * fields asserted below, so `storeView` may grow without touching this.
+ */
+const ProjectedStore = z.object({
+  customer: z.object({ userId: z.string() }).nullable(),
+  orders: z.array(z.object({ orderId: z.string(), status: z.string() })),
+  pending: z.object({ kind: z.string(), readBack: z.string() }).nullable(),
+});
+
+/**
+ * The latest projection the session pushed, or undefined if it pushed none.
+ *
+ * `lastStateIn` is the SDK's reader; the schema is what is worth passing to it,
+ * for the reason above — a frame that stopped matching fails naming the field.
+ */
+const projection = (events: readonly SessionEvent[]) => lastStateIn(events, ProjectedStore);
+
+/** The status the projection carries for `orderId` — the one fact "did anything
+ *  change?" turns on. `undefined` covers both "no projection yet" and "not this
+ *  customer's order", which are the same claim here: it was not touched. */
+function statusOf(events: readonly SessionEvent[], orderId: string): string | undefined {
+  return projection(events)?.orders.find((o) => o.orderId === orderId)?.status;
+}
+
+/**
+ * The dialog gate's own refusal sentence, for the state it names.
+ *
+ * The character class absorbs the JSON escaping: a tool result reaches the
+ * event stream as a serialized string, so the state name arrives inside
+ * `\\"identifying\\"` rather than plain quotes.
+ */
+const refusalAt = (state: string) =>
+  new RegExp(`Not available yet: this conversation is at [\\\\"]*${state}`);
+
+/**
+ * Drive a whole call, one caller line at a time, and hand back every turn.
+ *
+ * The cases below assert about the turn a MECHANISM fired in rather than about
+ * turn number two, because how many turns a desk takes to get there is the
+ * model's business and it really does vary: measured live, this agent reads the
+ * order back out of `get_order_details` and asks before it stages, so the
+ * staging call has landed in turn two, three and four across runs. A case
+ * pinned to a turn index is a flake with a misleading name.
+ */
+async function sayAll(session: EvalSession, lines: readonly string[]): Promise<EvalTurn[]> {
+  const turns: EvalTurn[] = [];
+  for (const line of lines) turns.push(await session.say(line));
+  return turns;
+}
+
+/** The turn a named tool was called in, if any. */
+const turnCalling = (turns: readonly EvalTurn[], tool: string) =>
+  turns.find((t) => t.toolCalls.some((c) => c.name === tool));
+
+/** One line the caller says to identify themselves, and the scripted tool call
+ *  that answers it — the first turn of three of these four cases. */
+const AUTH_TURN = [
+  { tool: "find_user_id_by_email", args: { email: CALLER_EMAIL } },
+  "Thanks — I have your account here. What can I do for you?",
+] as const;
+
+/** The staged cancellation, as a scripted turn. */
+const STAGE_TURN = [
+  {
+    tool: "cancel_pending_order",
+    args: { order_id: PENDING_ORDER, reason: "ordered by mistake" },
+  },
+  "So that would cancel your pending order and refund one thousand two hundred dollars " +
+    "and fifty-seven cents to your Visa. Is that right?",
+] as const;
+
+describeEval(retailAgent, (test) => {
+  test(
+    "will not touch an order before the caller is identified",
+    async ({ session }) => {
+      const turn = await session.say(
+        "Hi — cancel my pending order please, number W two two seven three zero six nine. " +
+          "I don't need it any more.",
+      );
+
+      // The claim is about the GATE, so it is made of every gated call the
+      // model chose to make: each one has to have been refused, and the
+      // refusal has to say where the call actually is. A model that asks for
+      // the email instead makes no gated call at all, which satisfies this
+      // vacuously and is the same right answer — the two remaining assertions
+      // are what stop the case being vacuous overall.
+      for (const call of turn.toolCalls) {
+        if (PUBLIC_TOOLS.has(call.name)) continue;
+        expect(call.result).toMatch(refusalAt("identifying"));
+      }
+      // Nothing was authenticated, so the browser has been sent no customer —
+      // which is also the projection's security claim.
+      expect(projection(session.events())?.customer ?? null).toBeNull();
+      // And it asked for the one thing it needs.
+      expect(turn.text).toMatch(/email|account|name|zip/i);
+    },
+    {
+      stubReply: [
+        {
+          tool: "cancel_pending_order",
+          args: { order_id: PENDING_ORDER, reason: "no longer needed" },
+        },
+        "Before I can look anything up I'll need to find your account — what's the email on it?",
+      ],
+    },
+  );
+
+  test(
+    "stages a cancellation and changes nothing until the caller says yes",
+    async ({ session }) => {
+      // FIVE lines, because how many turns this desk takes to STAGE is its own
+      // business and measured live it varies by two: reading the order back out
+      // of `get_order_details` and asking "does that sound right?" is a whole
+      // turn, and whether it spends one is not something an eval should pin.
+      // Every assertion below is about the turn the staging landed in, so a
+      // later apply cannot affect any of them.
+      const turns = await sayAll(session, [
+        `My email is ${CALLER_EMAIL}.`,
+        "I'd like to cancel my pending order — I ordered it by mistake.",
+        "Yes, please go ahead and cancel it.",
+        "Yes — I'm sure. Cancel it.",
+        "Yes. Cancel it, please.",
+      ]);
+
+      const staging = turnCalling(turns, "cancel_pending_order");
+      const staged = staging?.toolCalls.find((c) => c.name === "cancel_pending_order");
+      expect(staged?.result).toMatch(/NOTHING HAS CHANGED YET/);
+      // The gate is a POSITION, and this is it moving: the tool reported the
+      // state it landed in, which is the only state `confirm_change` is legal
+      // in and is reachable only by staging.
+      expect(staged?.result).toMatch(/serving\.awaitingConfirmation/);
+      // A change cannot be described and applied in the same turn. This is the
+      // property the prose in the system prompt could never have.
+      expect(staging?.toolCalls.map((c) => c.name)).not.toContain("confirm_change");
+      // And after the turn that staged it, the store really is untouched — read
+      // off the projection the BROWSER was sent in that same turn.
+      expect(statusOf(staging?.events ?? [], PENDING_ORDER)).toBe("pending");
+      expect(projection(staging?.events ?? [])?.pending?.kind).toBe("cancel_pending_order");
+      // Step 2 of the policy: read it back and ask.
+      expect(staging?.text).toMatch(/\?/);
+    },
+    { stubReply: [...AUTH_TURN, ...STAGE_TURN, "Cancelling it now — one moment."] },
+  );
+
+  test(
+    "applies the staged change on an explicit yes, exactly once",
+    async ({ session }) => {
+      // Five lines, three of them a yes: which turn the desk applies the change
+      // in is its own business, and saying yes repeatedly is what makes
+      // "exactly once" below a claim about the MECHANISM rather than about the
+      // model's pacing.
+      await sayAll(session, [
+        `My email is ${CALLER_EMAIL}.`,
+        "Please cancel my pending order — I ordered it by mistake.",
+        "Yes, that's right, go ahead.",
+        "Yes — confirm it now, please.",
+        "Yes. Confirm it.",
+      ]);
+
+      const confirms = session.toolCalls().filter((c) => c.name === "confirm_change");
+      const applied = confirms.filter((c) => c.result?.includes('"status":"cancelled"'));
+      // ONE apply for the whole call, however many times the caller said yes.
+      // Measured live, a second yes really does produce a second
+      // `confirm_change` — and it is REFUSED, because applying cleared
+      // `pending` and sent `SETTLED`, and `awaitingConfirmation` is reachable
+      // only by staging something new. That is the gate doing the one job a
+      // prompt could not: a repeated yes cannot cancel an order twice.
+      expect(applied).toHaveLength(1);
+      for (const extra of confirms.filter((c) => c !== applied[0])) {
+        expect(extra.result).toMatch(/Not available yet/);
+      }
+      // And it came after the stage, never instead of it.
+      const names = session.toolCalls().map((c) => c.name);
+      expect(names.indexOf("cancel_pending_order")).toBeGreaterThanOrEqual(0);
+      expect(names.indexOf("confirm_change")).toBeGreaterThan(
+        names.indexOf("cancel_pending_order"),
+      );
+      // The store moved, and the staged change is gone with it.
+      expect(statusOf(session.events(), PENDING_ORDER)).toBe("cancelled");
+      expect(projection(session.events())?.pending).toBeNull();
+    },
+    {
+      stubReply: [
+        ...AUTH_TURN,
+        ...STAGE_TURN,
+        { tool: "confirm_change", args: {} },
+        "That's cancelled, and the refund is on its way to your Visa.",
+      ],
+    },
+  );
+
+  test(
+    "hands the call to a human and then refuses everything, including the order",
+    async ({ session }) => {
+      await session.say(`My email is ${CALLER_EMAIL}.`);
+      const handoff = await session.say(
+        "This isn't working for me — I want to speak to a real person.",
+      );
+
+      const transfer = handoff.toolCalls.find((c) => c.name === "transfer_to_human_agents");
+      // Named first, and with a message: a live model that answers the request
+      // with a question instead of the tool leaves `transfer` undefined, and
+      // `.toMatch()` on it reports only "expected a string, got undefined" —
+      // which says nothing about what the desk actually did.
+      expect(
+        transfer,
+        `tools called: [${handoff.toolCalls.map((c) => c.name).join(", ")}]; said: ${handoff.text}`,
+      ).toBeDefined();
+      // The terminal state is what makes "say nothing else after this" a
+      // property of the agent rather than a line in its prompt: `done` is the
+      // flow saying there is nowhere left to go.
+      expect(transfer?.result).toMatch(/"state":"transferred"/);
+      expect(transfer?.result).toMatch(/"done":true/);
+
+      const after = await session.say("Actually, before you go — just cancel my pending order.");
+      for (const call of after.toolCalls) {
+        expect(call.result).toMatch(refusalAt("transferred"));
+      }
+      // Which is the point: the order the caller asked about is untouched.
+      expect(statusOf(session.events(), PENDING_ORDER)).toBe("pending");
+    },
+    {
+      stubReply: [
+        ...AUTH_TURN,
+        {
+          tool: "transfer_to_human_agents",
+          args: { summary: "Caller asked for a human agent." },
+        },
+        "You are being transferred to a human agent. Please hold on.",
+        {
+          tool: "cancel_pending_order",
+          args: { order_id: PENDING_ORDER, reason: "no longer needed" },
+        },
+        "You are being transferred to a human agent. Please hold on.",
+      ],
+    },
+  );
+});