@alexkroman1/aai-cli 6.11.0 → 8.0.0

package/dist/templates/travel-concierge/agent.test.ts

@@ -1,7 +1,13 @@
 /// <reference types="vite/client" />
 
 import type { ToolContext } from "@alexkroman1/aai";
-import { createToolContext, runTool, withDiscoveredTools } from "@alexkroman1/aai/testing";
+import {
+  createToolContext,
+  ok,
+  okPosition,
+  toolRunner,
+  withDiscoveredTools,
+} from "@alexkroman1/aai/testing";
 import { describe, expect, test } from "vitest";
 import authoredAgent from "./agent.ts";
 
@@ -18,7 +24,15 @@ const agentDef = withDiscoveredTools(
   import.meta.glob("./tools/*.ts", { eager: true }),
 );
 
-import { activeAssistant, FLIGHTS, tripProjection, tripSlot, tripView } from "./shared.ts";
+import {
+  activeAssistant,
+  FLIGHTS,
+  gateFlow,
+  type SpecialistId,
+  tripProjection,
+  tripSlot,
+  tripView,
+} from "./shared.ts";
 
 // ─── Harness ─────────────────────────────────────────────────────────────────
 
@@ -26,17 +40,31 @@ import { activeAssistant, FLIGHTS, tripProjection, tripSlot, tripView } from "./
  *  below rests on. */
 const makeCtx = (): ToolContext => createToolContext();
 
-/** A tool by the name the model calls it by, bound to this agent. The lookup
- *  and its "no such tool" message are `runTool`'s (`@alexkroman1/aai/testing`);
- *  what is local is only which agent they run against. */
-const run = (name: string, args: Record<string, unknown>, ctx: ToolContext) =>
-  runTool(agentDef, name, args, ctx);
+/** A tool by the name the model calls it by, bound to this agent. The lookup,
+ *  its "no such tool" message and the args-or-context shape are all
+ *  `toolRunner`'s (`@alexkroman1/aai/testing`); what is local is only which
+ *  agent it runs against. */
+const run = toolRunner(agentDef);
 
 /** The state a tool just mutated, read back the way `syncState` reads it. */
 function stateOf(ctx: ToolContext) {
   return tripSlot.get(ctx);
 }
 
+/**
+ * Put the call at a desk the way the model has to: through that desk's own
+ * delegation tool.
+ *
+ * Every desk tool checks the stack first (`requireDesk`) and refuses from
+ * anywhere else, so a spec driving one has to stand where the model would. It is
+ * one line per test rather than a shared `beforeEach` deliberately — which desk
+ * a tool belongs to is what the block below is about, so it stays visible at the
+ * call site.
+ */
+const atDesk = async (id: SpecialistId, ctx: ToolContext): Promise<void> => {
+  await run(`to_${id}_assistant`, { request: "what the caller asked for" }, ctx);
+};
+
 // ─── 1. The dialog stack ─────────────────────────────────────────────────────
 
 describe("dialog stack (routing.ts)", () => {
@@ -85,6 +113,72 @@ describe("dialog stack (routing.ts)", () => {
   });
 });
 
+// ─── 1b. The desk gate ───────────────────────────────────────────────────────
+//
+// What their graph gets from binding a tool set per node, and what this port
+// used to only ask the prompt for. The eval (`agent.eval.test.ts`) is what
+// measured the asking losing — 0 of 5 live runs, the model searching hotels
+// while the stack said `primary` — so these are the tests that make the stack
+// binding rather than descriptive.
+
+describe("the desk gate (requireDesk)", () => {
+  const DESK_TOOLS = [
+    ["search_flights", { route: "Boston" }, "flight"],
+    ["update_ticket", { flightId: "LX52" }, "flight"],
+    ["cancel_ticket", {}, "flight"],
+    ["search_hotels", { city: "Boston" }, "hotel"],
+    ["book_hotel", { hotelId: "H1", nights: 2 }, "hotel"],
+    ["search_car_rentals", { city: "Boston" }, "car_rental"],
+    ["book_car_rental", { carId: "C2", days: 3 }, "car_rental"],
+    ["search_excursions", { city: "Boston" }, "excursion"],
+    ["book_excursion", { excursionId: "E2" }, "excursion"],
+  ] as const;
+
+  test.each(DESK_TOOLS)("%s refuses at the concierge desk", async (name, args, desk) => {
+    const ctx = makeCtx();
+    const refused = (await run(name, args, ctx)) as { error?: string };
+    // The refusal NAMES the way in, which is what the model recovers from
+    // inside the same turn — a bare "not allowed" would leave it guessing.
+    expect(refused.error).toContain(`to_${desk}_assistant`);
+    // And nothing happened: no search result, no staging, no stack movement.
+    expect(stateOf(ctx).pending).toBeNull();
+    expect(activeAssistant(stateOf(ctx))).toBe("primary");
+    expect(gateFlow.position(ctx).state).toBe("browsing");
+  });
+
+  test.each(DESK_TOOLS)("%s refuses from ANOTHER desk", async (name, args, desk) => {
+    const ctx = makeCtx();
+    // The excursions desk for anything that is not its own, and the flight desk
+    // for the excursion tools — so every case really is a wrong desk rather
+    // than a coincidence of ordering.
+    const wrong = desk === "excursion" ? "flight" : "excursion";
+    await atDesk(wrong, ctx);
+    const refused = (await run(name, args, ctx)) as { error?: string };
+    expect(refused.error).toContain(`to_${desk}_assistant`);
+    expect(refused.error).toContain(desk === "excursion" ? "flight desk" : "excursions desk");
+    expect(stateOf(ctx).pending).toBeNull();
+  });
+
+  test.each(DESK_TOOLS)("%s works once its own desk holds the call", async (name, args, desk) => {
+    // The other half, and the one that makes the block above non-vacuous: a
+    // gate that refused everywhere would pass every assertion up to here.
+    const ctx = makeCtx();
+    await atDesk(desk, ctx);
+    expect(await run(name, args, ctx)).not.toMatchObject({
+      error: expect.stringContaining("belongs to the"),
+    });
+  });
+
+  test("the concierge's own tools are NOT gated", async () => {
+    // `lookup_booking` is the concierge's, and the gate must not make the desk
+    // unable to answer "what am I holding?" from wherever the call is.
+    const ctx = makeCtx();
+    await atDesk("hotel", ctx);
+    const booking = (await run("lookup_booking", ctx)) as { passenger: string };
+    expect(booking.passenger).toBe("Nadia Rossi");
+  });
+});
+
 // ─── 2. The confirmation gate ────────────────────────────────────────────────
 //
 // Their graph halts before a sensitive tool (`interrupt_before`) and resumes on
@@ -94,13 +188,14 @@ describe("dialog stack (routing.ts)", () => {
 
 describe("sensitive tools stage rather than act", () => {
   test.each([
-    ["update_ticket", { flightId: "LX52" }],
-    ["cancel_ticket", {}],
-    ["book_hotel", { hotelId: "H1", nights: 2 }],
-    ["book_car_rental", { carId: "C2", days: 3 }],
-    ["book_excursion", { excursionId: "E2" }],
-  ])("%s changes nothing on its own", async (name, args) => {
+    ["update_ticket", { flightId: "LX52" }, "flight"],
+    ["cancel_ticket", {}, "flight"],
+    ["book_hotel", { hotelId: "H1", nights: 2 }, "hotel"],
+    ["book_car_rental", { carId: "C2", days: 3 }, "car_rental"],
+    ["book_excursion", { excursionId: "E2" }, "excursion"],
+  ] as const)("%s changes nothing on its own", async (name, args, desk) => {
     const ctx = makeCtx();
+    await atDesk(desk, ctx);
     const before = structuredClone(stateOf(ctx));
 
     const staged = (await run(name, args, ctx)) as { awaitingConfirmation: boolean };
@@ -114,38 +209,51 @@ describe("sensitive tools stage rather than act", () => {
 
   test("confirm_action applies the staged change, and only then", async () => {
     const ctx = makeCtx();
+    await atDesk("hotel", ctx);
     await run("book_hotel", { hotelId: "H1", nights: 3 }, ctx);
 
-    const applied = (await run("confirm_action", {}, ctx)) as {
-      applied: string;
-      reference: string;
-    };
-    expect(applied.applied).toContain("Harborview Suites");
+    // Staging moved the gate, in the same window it wrote `pending`.
+    expect(gateFlow.position(ctx).state).toBe("awaitingConfirmation");
+
+    // A gated tool answers the flow's POSITION wrapped around the body's own
+    // return value, so the applied sentence is under `result`. `okPosition`
+    // keeps the position and THROWS on a refusal, quoting it — where the cast
+    // it replaces read `undefined` off the failure and died three assertions
+    // later on a property of undefined.
+    const confirmed = okPosition<{ applied: string; reference: string }>(
+      await run("confirm_action", ctx),
+    );
+    expect(confirmed.result.applied).toContain("Harborview Suites");
     // 3 nights at $265.
-    expect(applied.applied).toContain("$795");
+    expect(confirmed.result.applied).toContain("$795");
+    // SETTLED: the gate re-armed as part of the same call.
+    expect(confirmed.state).toBe("browsing");
 
     const state = stateOf(ctx);
     expect(state.pending).toBeNull();
     expect(state.bookings).toHaveLength(1);
-    expect(state.bookings[0]?.reference).toBe(applied.reference);
+    expect(state.bookings[0]?.reference).toBe(confirmed.result.reference);
 
-    // The gate re-arms: a second confirm has nothing to apply.
-    expect(await run("confirm_action", {}, ctx)).toEqual({
-      error: "Nothing is waiting for confirmation. Use the booking tool first.",
+    // The gate re-arms, and now REFUSES rather than reporting an empty apply —
+    // `when: "awaitingConfirmation"` is what a second confirm meets.
+    expect(await run("confirm_action", ctx)).toMatchObject({
+      error: expect.stringContaining('this conversation is at "browsing"'),
     });
   });
 
   test("cancel_action drops the staged change and leaves the booking alone", async () => {
     const ctx = makeCtx();
+    await atDesk("flight", ctx);
     await run("update_ticket", { flightId: "LX54" }, ctx);
-    const dropped = (await run("cancel_action", {}, ctx)) as { discarded: string };
-    expect(dropped.discarded).toContain("LX54");
+    const dropped = okPosition<{ discarded: string }>(await run("cancel_action", ctx));
+    expect(dropped.result.discarded).toContain("LX54");
+    expect(dropped.state).toBe("browsing");
 
     const state = stateOf(ctx);
     expect(state.pending).toBeNull();
     expect(state.ticket?.flightId).toBe("LX40");
-    expect(await run("cancel_action", {}, ctx)).toEqual({
-      message: "Nothing was waiting for confirmation.",
+    expect(await run("cancel_action", ctx)).toMatchObject({
+      error: expect.stringContaining('this conversation is at "browsing"'),
     });
   });
 
@@ -153,6 +261,7 @@ describe("sensitive tools stage rather than act", () => {
     // Refused where the model can still recover — before the caller is asked to
     // confirm a flight the airline does not fly.
     const ctx = makeCtx();
+    await atDesk("flight", ctx);
     expect(await run("update_ticket", { flightId: "ZZ99" }, ctx)).toEqual({
       error: "No flight ZZ99 in the schedule.",
     });
@@ -161,29 +270,35 @@ describe("sensitive tools stage rather than act", () => {
 
   test("cancelling the ticket makes a later ticket change impossible", async () => {
     const ctx = makeCtx();
-    await run("cancel_ticket", {}, ctx);
-    await run("confirm_action", {}, ctx);
+    await atDesk("flight", ctx);
+    await run("cancel_ticket", ctx);
+    await run("confirm_action", ctx);
     expect(stateOf(ctx).ticket).toBeNull();
 
     expect(await run("update_ticket", { flightId: "LX52" }, ctx)).toEqual({
       error: "This caller has no ticket to move — it was cancelled on this call.",
     });
-    expect(await run("cancel_ticket", {}, ctx)).toEqual({ error: "There is no ticket to cancel." });
+    expect(await run("cancel_ticket", ctx)).toEqual({ error: "There is no ticket to cancel." });
   });
 
   test("a second staging is REFUSED rather than overwriting the first", async () => {
     // The LLM loop runs a step's tool calls concurrently, so two sensitive
-    // tools in one step is ordinary: the model hears "move my flight and book
-    // the hotel" and emits both. Assigning `pending` unconditionally made the
+    // tools in one step is ordinary: the model hears "move my flight and cancel
+    // the old one" and emits both. Assigning `pending` unconditionally made the
     // second win — both answered `awaitingConfirmation`, the caller said yes
     // once, and one of the two changes was silently dropped forever.
     const ctx = makeCtx();
+    await atDesk("flight", ctx);
     const first = (await run("update_ticket", { flightId: "LX52" }, ctx)) as {
       awaitingConfirmation: boolean;
     };
     expect(first.awaitingConfirmation).toBe(true);
 
-    const second = (await run("book_hotel", { hotelId: "H1", nights: 2 }, ctx)) as {
+    // Both from ONE desk, which is what a concurrent pair looks like now that
+    // `requireDesk` is enforced. Another desk's tool would be refused by the
+    // DESK gate first, which is a different refusal and would leave this one
+    // unexercised.
+    const second = (await run("cancel_ticket", ctx)) as {
       error: string;
     };
     // The refusal NAMES what is already waiting, which is what lets the model
@@ -193,11 +308,17 @@ describe("sensitive tools stage rather than act", () => {
 
     // The first staging is untouched, and it is what a yes applies.
     expect(stateOf(ctx).pending).toEqual({ kind: "update_ticket", flightId: "LX52" });
-    const applied = (await run("confirm_action", {}, ctx)) as { applied: string };
+    // A refused SECOND staging must not have moved the gate either — it was
+    // already `awaitingConfirmation` and the refusal changed nothing.
+    expect(gateFlow.position(ctx).state).toBe("awaitingConfirmation");
+    // `ok` is `okPosition` with `.result` taken off: this assertion is about
+    // what the apply DID, not about where the gate landed.
+    const applied = ok<{ applied: string }>(await run("confirm_action", ctx));
     expect(applied.applied).toContain("LX52");
     expect(stateOf(ctx).bookings).toEqual([]);
 
-    // Once the queue is clear, the hotel can be staged after all.
+    // Once the queue is clear, the next desk's booking can be staged after all.
+    await atDesk("hotel", ctx);
     const retried = (await run("book_hotel", { hotelId: "H1", nights: 2 }, ctx)) as {
       awaitingConfirmation: boolean;
     };
@@ -206,8 +327,10 @@ describe("sensitive tools stage rather than act", () => {
 
   test("cancel_action clears the block, so a declined change does not wedge the desk", async () => {
     const ctx = makeCtx();
+    await atDesk("car_rental", ctx);
     await run("book_car_rental", { carId: "C2", days: 3 }, ctx);
-    await run("cancel_action", {}, ctx);
+    await run("cancel_action", ctx);
+    await atDesk("excursion", ctx);
     const staged = (await run("book_excursion", { excursionId: "E2" }, ctx)) as {
       awaitingConfirmation: boolean;
     };
@@ -225,12 +348,14 @@ describe("sensitive tools stage rather than act", () => {
 
     await run("to_hotel_assistant", { request: "a room" }, first);
     await run("book_hotel", { hotelId: "H3", nights: 1 }, first);
-    await run("confirm_action", {}, first);
+    await run("confirm_action", first);
 
     expect(activeAssistant(stateOf(second))).toBe("primary");
     expect(stateOf(second).bookings).toEqual([]);
-    expect(await run("confirm_action", {}, second)).toEqual({
-      error: "Nothing is waiting for confirmation. Use the booking tool first.",
+    // The GATE is per-session too, not just the trip.
+    expect(gateFlow.position(second).state).toBe("browsing");
+    expect(await run("confirm_action", second)).toMatchObject({
+      error: expect.stringContaining('this conversation is at "browsing"'),
     });
     expect(stateOf(first).bookings).toHaveLength(1);
   });
@@ -241,6 +366,7 @@ describe("sensitive tools stage rather than act", () => {
 describe("search tools", () => {
   test("an unmatched route widens to the whole schedule rather than answering nothing", async () => {
     const ctx = makeCtx();
+    await atDesk("flight", ctx);
     const hit = (await run("search_flights", { route: "Zurich to Boston" }, ctx)) as {
       widened: boolean;
       flights: unknown[];
@@ -258,6 +384,7 @@ describe("search tools", () => {
 
   test("hotels come back cheapest first, and a ceiling filters them", async () => {
     const ctx = makeCtx();
+    await atDesk("hotel", ctx);
     const all = (await run("search_hotels", { city: "Boston" }, ctx)) as {
       hotels: { perNight: string }[];
     };
@@ -272,6 +399,7 @@ describe("search tools", () => {
 
   test("an excursion keyword that matches nothing falls back to the city", async () => {
     const ctx = makeCtx();
+    await atDesk("excursion", ctx);
     const result = (await run("search_excursions", { city: "Boston", keyword: "skiing" }, ctx)) as {
       widened: boolean;
       excursions: unknown[];
@@ -282,9 +410,10 @@ describe("search tools", () => {
 
   test("lookup_booking reports the ticket the caller is actually holding", async () => {
     const ctx = makeCtx();
+    await atDesk("flight", ctx);
     await run("update_ticket", { flightId: "LX52" }, ctx);
-    await run("confirm_action", {}, ctx);
-    const booking = (await run("lookup_booking", {}, ctx)) as {
+    await run("confirm_action", ctx);
+    const booking = (await run("lookup_booking", ctx)) as {
       passenger: string;
       ticket: { flight: string; departs: string } | null;
     };
@@ -326,10 +455,12 @@ describe("tripView projection", () => {
 
   test("totals every confirmed booking", async () => {
     const ctx = makeCtx();
+    await atDesk("hotel", ctx);
     await run("book_hotel", { hotelId: "H3", nights: 2 }, ctx); // 2 × 180
-    await run("confirm_action", {}, ctx);
+    await run("confirm_action", ctx);
+    await atDesk("excursion", ctx);
     await run("book_excursion", { excursionId: "E1" }, ctx); // 35
-    await run("confirm_action", {}, ctx);
+    await run("confirm_action", ctx);
 
     const view = tripView(stateOf(ctx));
     expect(view.total).toBe(395);

package/dist/templates/travel-concierge/agent.ts

@@ -7,15 +7,24 @@ import { tripProjection } from "./shared.ts";
  * two mechanisms worth reading for are the dialog stack (`routing.ts`) and the
  * confirmation gate (`stageAction` / `confirm_action`).
  *
- * **Every tool in `tools/` belongs to this one agent — the delegation is in the
- * PROMPT, not in the tool list.** Their graph gives each specialist node its
- * own bound tool set, so a specialist physically cannot call another desk's
- * tools. A voice session has one model with one tool list for its whole life,
- * so the specialist's brief arrives as a tool result and the narrowing is
- * something the model is asked to honour rather than something the runtime
- * enforces. That is the honest limit of the port, and it is why
- * `complete_or_escalate` is described the way it is: the stack is what the
- * caller and the sidebar can both see, even when the model reaches past it.
+ * **Every tool in `tools/` belongs to this one agent, and the delegation is
+ * ENFORCED anyway.** Their graph gives each specialist node its own bound tool
+ * set, so a specialist physically cannot call another desk's tools. A voice
+ * session has one model with one tool list for its whole life, so a list cannot
+ * be narrowed here — but a TOOL can refuse, which is the same guarantee by a
+ * route that works mid-call: every desk tool checks the stack first
+ * (`requireDesk` in `shared.ts`) and answers a `ToolFailure` naming the
+ * `to_…_assistant` to call. So the position the sidebar renders is always the
+ * position the work is being done at, and the specialist's brief has always
+ * been read before that desk's first search.
+ *
+ * This used to be asked for in the prompt instead, described here as the honest
+ * limit of the port. It was measured and the prompt lost — 0 of 5 live runs, the
+ * model searching hotels from the concierge desk every time — so the eval case
+ * that predicted it (`agent.eval.test.ts`, "a hotel request goes to the hotel
+ * desk") is what turned the narrowing into a mechanism. `complete_or_escalate`
+ * is still described the way it is for the other half of the reason: the stack
+ * is what the caller and the sidebar can both see.
  */
 export default agent({
   name: "Swiss Air Concierge",

package/dist/templates/travel-concierge/client.tsx

@@ -1,5 +1,5 @@
 import "@alexkroman1/aai-ui/styles.css";
-import { AutoScroll, client, useAgentState, useTheme } from "@alexkroman1/aai-ui";
+import { AutoScroll, client, useAgentState } from "@alexkroman1/aai-ui";
 import type { TripView } from "./shared.ts";
 import { SPECIALIST_IDS, SPECIALISTS, tripProjection } from "./shared.ts";
 
@@ -15,7 +15,6 @@ function deskLabel(id: (typeof DESKS)[number]): string {
  * the transcript — the whole delegation mechanism is otherwise invisible.
  */
 function DeskStrip({ active }: { active: TripView["assistant"] }) {
-  const theme = useTheme();
   return (
     <div className="flex flex-wrap gap-1.5">
       {DESKS.map((id) => {
@@ -23,12 +22,9 @@ function DeskStrip({ active }: { active: TripView["assistant"] }) {
         return (
           <span
             key={id}
-            className="rounded-full px-2.5 py-1 text-[11px] font-medium capitalize"
-            style={{
-              background: on ? theme.primary : theme.surface,
-              color: on ? theme.bg : theme.text,
-              opacity: on ? 1 : 0.55,
-            }}
+            className={`rounded-full px-2.5 py-1 text-[11px] font-medium capitalize ${
+              on ? "bg-aai-primary text-aai-bg" : "bg-aai-surface text-aai-text opacity-55"
+            }`}
           >
             {deskLabel(id)}
           </span>
@@ -39,11 +35,10 @@ function DeskStrip({ active }: { active: TripView["assistant"] }) {
 }
 
 function ItinerarySidebar() {
-  const theme = useTheme();
   const trip = useAgentState(tripProjection);
 
   return (
-    <div className="flex flex-col gap-4 p-4 h-full min-h-0" style={{ color: theme.text }}>
+    <div className="flex flex-col gap-4 p-4 h-full min-h-0 text-aai-text">
       <div className="flex flex-col gap-2">
         <h3 className="text-sm font-bold opacity-60 uppercase tracking-wide">{trip.passenger}</h3>
         <DeskStrip active={trip.assistant} />
@@ -52,10 +47,7 @@ function ItinerarySidebar() {
       {/* The staged action — the browser half of the confirmation gate. What is
           on screen is exactly what the concierge just asked out loud. */}
       {trip.pending && (
-        <div
-          className="rounded-lg p-3 text-sm"
-          style={{ background: theme.surface, border: `1px solid ${theme.primary}` }}
-        >
+        <div className="rounded-lg p-3 text-sm bg-aai-surface border border-aai-primary">
           <p className="text-[11px] font-bold uppercase tracking-wide opacity-60">
             Waiting on your yes
           </p>
@@ -66,7 +58,7 @@ function ItinerarySidebar() {
       <div className="flex flex-col gap-2">
         <p className="text-[11px] font-bold uppercase tracking-wide opacity-60">Ticket</p>
         {trip.ticket ? (
-          <div className="rounded-lg p-3" style={{ background: theme.surface }}>
+          <div className="rounded-lg p-3 bg-aai-surface">
             <p className="text-sm font-medium">
               {trip.ticket.flightId} · {trip.ticket.route}
             </p>
@@ -85,24 +77,20 @@ function ItinerarySidebar() {
           {trip.bookings.map((booking) => (
             <div
               key={booking.reference}
-              className="flex items-center justify-between gap-3 rounded-lg p-3"
-              style={{ background: theme.surface }}
+              className="flex items-center justify-between gap-3 rounded-lg p-3 bg-aai-surface"
             >
               <div className="min-w-0">
                 <p className="truncate text-sm">{booking.summary}</p>
                 <p className="text-xs opacity-60">{booking.reference}</p>
               </div>
-              <span className="text-sm font-bold" style={{ color: theme.primary }}>
+              <span className="text-sm font-bold text-aai-primary">
                 ${booking.price.toLocaleString("en-US")}
               </span>
             </div>
           ))}
-          <div
-            className="flex justify-between border-t pt-2 text-sm font-bold"
-            style={{ borderColor: theme.border }}
-          >
+          <div className="flex justify-between border-t border-aai-border pt-2 text-sm font-bold">
             <span>Total</span>
-            <span style={{ color: theme.primary }}>${trip.total.toLocaleString("en-US")}</span>
+            <span className="text-aai-primary">${trip.total.toLocaleString("en-US")}</span>
           </div>
         </div>
       )}

package/dist/templates/travel-concierge/routing.ts

@@ -24,6 +24,7 @@ import {
   activeAssistant,
   applyPending,
   describeAction,
+  gateFlow,
   note,
   SPECIALISTS,
   type SpecialistId,
@@ -111,28 +112,46 @@ export const completeOrEscalate = tripSlot.updateTool({
  * halts before a sensitive tool and resumes on approval; the halt here is that
  * every sensitive tool stages instead of acting, so the approval has somewhere
  * to arrive.
+ *
+ * **`when: "awaitingConfirmation"` is the other side of that halt.** It used to
+ * be a null check inside {@link applyPending} — "Nothing is waiting for
+ * confirmation. Use the booking tool first." — which is the question "where is
+ * this conversation", asked of the payload. The gate asks the machine instead,
+ * and its refusal carries the state's own instruction. `SETTLED` fires only when
+ * the body did NOT answer with a {@link ToolFailure}, so an application that
+ * failed leaves the change staged and the caller still being asked.
  */
-export const confirmAction = tripSlot.updateTool({
+export const confirmAction = gateFlow.tool({
   description:
     "Apply the change the caller has just confirmed out loud. Only call this " +
     "after you have read the change back and heard a clear yes.",
-  execute(_args, trip) {
-    return applyPending(trip);
-  },
+  when: "awaitingConfirmation",
+  send: { type: "SETTLED" },
+  execute: (_args, ctx) => tripSlot.update(ctx, (trip) => applyPending(trip)),
 });
 
-/** `cancel_action` — the caller said no. Drops the staged action, changes nothing. */
-export const cancelAction = tripSlot.updateTool({
+/**
+ * `cancel_action` — the caller said no. Drops the staged action, changes nothing.
+ *
+ * Gated for the same reason as `confirm_action`, and its own "nothing was
+ * waiting" arm is gone with the same argument.
+ */
+export const cancelAction = gateFlow.tool({
   description:
     "Discard the change the caller just declined. Call this when they say no, " +
     "or when they want to change the details before confirming.",
-  execute(_args, trip) {
-    const action = trip.pending;
-    if (!action) return { message: "Nothing was waiting for confirmation." };
-    trip.pending = null;
-    const described = describeAction(action);
-    const summary = typeof described === "string" ? described : action.kind;
-    note(trip, `Declined: ${summary}`);
-    return { discarded: summary, message: "Nothing was changed." };
-  },
+  when: "awaitingConfirmation",
+  send: { type: "SETTLED" },
+  execute: (_args, ctx) =>
+    tripSlot.update(ctx, (trip) => {
+      const action = trip.pending;
+      // Reachable only if the position and the payload disagree; see
+      // `applyPending`. Reported rather than thrown, mid-call.
+      if (!action) return { discarded: null, message: "Nothing was staged after all." };
+      trip.pending = null;
+      const described = describeAction(action);
+      const summary = typeof described === "string" ? described : action.kind;
+      note(trip, `Declined: ${summary}`);
+      return { discarded: summary, message: "Nothing was changed." };
+    }),
 });