@alexkroman1/aai-cli 6.10.1 → 7.0.0

package/dist/templates/transcription-workflow/workflows/transcribe.ts

@@ -7,15 +7,21 @@
  * every directive body obeys — replayed from the top, so no live handles and no
  * undurable decisions; step arguments and return values are serialized, so pass
  * an id and not a payload — and both hold here unchanged. What this template
- * adds is the shape a real provider limit forces on a workflow, and it is three
+ * adds is the shape a real provider limit forces on a workflow, and it is four
  * steps in a straight line:
  *
  * ```text
+ *   normalizeRecording  one step   →  an upload id in a format that can be cut
  *   splitRecording      one step   →  the format + a byte range per segment
  *   transcribeSegment   N steps    →  one sync API request each, bounded
  *   mergeTranscript     one step   →  the stitched transcript
  * ```
  *
+ * The first is the newest and the one a reader is least likely to expect, since
+ * everything below it is arithmetic over a WAV and real recordings are not WAVs.
+ * `normalize.ts` is where ffmpeg enters, and its module doc carries why the
+ * conversion is file-to-file and why a temp file may not outlive its step.
+ *
  * ## Why the SYNC endpoint, and why that forces a fan-out
  *
  * AssemblyAI has two pre-recorded APIs. The BATCH one takes a job and a webhook
@@ -35,7 +41,7 @@
  * ## Three properties this leans on
  *
  * - **A step can read the agent's env now.** `stepEnv`/`requireStepEnv`
- *   (`@alexkroman1/aai/utils`) is what makes any of this real: a step is
+ *   (`@alexkroman1/aai/step`) is what makes any of this real: a step is
  *   dispatched separately from the agent bundle and is handed no `ToolContext`,
  *   so before that seam existed no step anywhere could authenticate an outbound
  *   call, and every workflow template's I/O was a fixture saying so.
@@ -57,18 +63,22 @@
  *   `output` exists only when the last segment does.
  */
 
-import { throwFatalStepError } from "@alexkroman1/aai/step-errors";
-import { emit, mapConcurrent, readUpload, report, uploadInfo } from "@alexkroman1/aai/utils";
 import {
-  clock,
-  countWords,
-  stitchTranscript,
-  TRANSCRIPT_STREAM,
-  type TranscriptChunk,
-} from "./stitch.ts";
+  emit,
+  encodeWav,
+  mapConcurrent,
+  readUpload,
+  report,
+  uploadInfo,
+} from "@alexkroman1/aai/step";
+import { throwFatalStepError } from "@alexkroman1/aai/step-errors";
+import { countWords, formatDuration, plural } from "@alexkroman1/aai/utils";
+import { normalizeRecording } from "./normalize.ts";
+import { stitchTranscript, TRANSCRIPT_STREAM, type TranscriptChunk } from "./stitch.ts";
 import { elapsed, timed, transcribeWav } from "./sync-api.ts";
 import {
   bytesPerSecond,
+  HEADER_PROBE_BYTES,
   parseWav,
   planSegments,
   SEGMENT_OVERLAP_SECONDS,
@@ -76,7 +86,6 @@ import {
   type Segment,
   UnsupportedRecordingError,
   type WavFormat,
-  wavWithHeader,
 } from "./wav.ts";
 
 /**
@@ -186,15 +195,6 @@ export function segmentConcurrency(format: WavFormat): number {
   return Math.max(1, Math.min(MAX_SEGMENT_CONCURRENCY, Math.floor(BYTES_IN_FLIGHT / perSegment)));
 }
 
-/**
- * Bytes probed for the WAV header.
- *
- * The canonical header is 44 bytes; a recorder that writes a `LIST` or `bext`
- * chunk in front of the samples pushes the `data` chunk further out, and 64 KB
- * covers every such file anyone has produced by accident.
- */
-const HEADER_PROBE_BYTES = 64 * 1024;
-
 /**
  * What a finished run reports, whichever flow produced it.
  *
@@ -234,7 +234,16 @@ export async function transcribeFlow(input: { recording: string }) {
   // round trip instead of two before any audio is read. The ORDER is still a
   // pure function of this line — the two calls go out synchronously, left to
   // right — which is what a replay reproduces.
-  const [startedAt, plan] = await Promise.all([startClock(), splitRecording(input.recording)]);
+  //
+  // The clock starts before the conversion rather than after it, because a
+  // reader comparing the three flows over one file is comparing what the desk
+  // COST them, and re-encoding an m4a is part of that.
+  const [startedAt, ready] = await Promise.all([startClock(), normalizeRecording(input.recording)]);
+
+  // `ready.recording` from here on, not `input.recording`: a converted file is a
+  // DIFFERENT upload, and cutting the original by offsets planned against the
+  // converted one is a fan-out of garbage that still reports success.
+  const plan = await splitRecording(ready.recording);
 
   // One step per segment, bounded, in an order a replay reproduces exactly.
   // A failed segment fails the RUN, deliberately: every sibling that finished is
@@ -242,11 +251,12 @@ export async function transcribeFlow(input: { recording: string }) {
   // what is missing, where catching here to salvage a partial transcript would
   // return a recording with a silent hole in it and report success.
   const parts = await mapConcurrent(plan.segments, segmentConcurrency(plan.format), (segment) =>
-    transcribeSegment(input.recording, plan.format, segment),
+    transcribeSegment(ready.recording, plan.format, segment),
   );
 
-  // Whatever this returns is what a caller reads as `output` on a completed run
-  // — so it is what the page renders, typed through `WorkflowOutputOf`.
+  // The ORIGINAL id, and only here: `mergeTranscript` uses it for the filename a
+  // reader sees, and `standup.m4a` is the recording they uploaded — where the
+  // converted copy is an artifact of how the desk works.
   return await mergeTranscript(input.recording, plan.durationMs, parts, startedAt);
 }
 
@@ -272,7 +282,7 @@ export async function splitRecording(uploadId: string): Promise<{
   const durationMs = segments.at(-1)?.endMs ?? 0;
 
   await report(
-    `Split ${clock(durationMs)} of audio into ${segments.length} segment${segments.length === 1 ? "" : "s"}.`,
+    `Split ${formatDuration(durationMs)} of audio into ${segments.length} ${plural(segments.length, "segment")}.`,
   );
   return { format, segments, durationMs };
 }
@@ -299,7 +309,7 @@ export async function transcribeSegment(
   // calls together, so their lines interleave by completion — the page renders a
   // log, not a sequence, and `segment.index` is what puts the TRANSCRIPT back in
   // order.
-  await report(`Transcribing ${clock(segment.startMs)}–${clock(segment.endMs)}.`);
+  await report(`Transcribing ${formatDuration(segment.startMs)}–${formatDuration(segment.endMs)}.`);
 
   // `[start, end)`, the same half-open pair `planSegments` produced — the store
   // owns the conversion to HTTP's inclusive range, so there is no `- 1` here to
@@ -312,20 +322,25 @@ export async function transcribeSegment(
   // answers better — and getting it wrong is a whole transcript in the wrong
   // language. Add one back only for a desk that really knows.
   //
-  // `wavWithHeader` is what makes a WINDOW decodable: the endpoint decodes each
+  // `encodeWav` is what makes a WINDOW decodable: the endpoint decodes each
   // request independently, so a slice of the middle of a recording is a headerless
   // tail until one is put back on it. The streaming flow needs no equivalent — its
-  // parts were cut with a header each.
+  // parts were cut with a header each. The header is the SDK's rather than this
+  // template's: a `WavFormat` is structurally a `PcmFormat`, and 22 lines of
+  // `DataView` writes with a comment about which of the two declared lengths a
+  // decoder trusts is not a thing worth a second copy of.
   const { value: text, ms } = await timed(() =>
     transcribeWav(
-      wavWithHeader(format, audio.bytes),
+      encodeWav(audio.bytes, format),
       `segment-${segment.index}.wav`,
-      `Segment ${segment.index} (${clock(segment.startMs)})`,
+      `Segment ${segment.index} (${formatDuration(segment.startMs)})`,
     ),
   );
   // The LATENCY, which is what says whether the concurrency bound or the endpoint
   // is the thing limiting the run — see `timed`'s doc.
-  await report(`Transcribed ${clock(segment.startMs)}–${clock(segment.endMs)} in ${elapsed(ms)}.`);
+  await report(
+    `Transcribed ${formatDuration(segment.startMs)}–${formatDuration(segment.endMs)} in ${elapsed(ms)}.`,
+  );
   // And the WORDS, into their own stream, which is what makes this run's answer
   // streamable rather than only its narration: the page stitches whatever has
   // arrived and renders the transcript growing, minutes before `output` exists.
@@ -363,7 +378,7 @@ export async function mergeTranscript(
 ): Promise<Transcript> {
   "use step";
 
-  await report(`Stitching ${parts.length} segment${parts.length === 1 ? "" : "s"} together.`);
+  await report(`Stitching ${parts.length} ${plural(parts.length, "segment")} together.`);
 
   // `mapConcurrent` resolves in ITEM order however the calls settled, so this is
   // already ordered — sorted anyway, because the merge is where an ordering
@@ -408,12 +423,13 @@ export async function startClock(): Promise<number> {
   return Date.now();
 }
 
-// `clock` and `countWords` are re-exported rather than re-declared: `stream.ts`
-// and `batch.ts` already import them from this module, and the split that let the
-// PAGE stitch a partial transcript should not ripple through every flow.
+// Re-exported rather than re-declared: `stream.ts` and `batch.ts` already import
+// these from this module, and the split that let the PAGE stitch a partial
+// transcript should not ripple through every flow. `clock` and `countWords` used
+// to be in this list and are `formatDuration`/`countWords` on
+// `@alexkroman1/aai/utils` now — a run narrates itself and the page renders the
+// same run, so those two were a private copy of a formatter the SDK ships.
 export {
-  clock,
-  countWords,
   stitchChunks,
   stitchTranscript,
   TRANSCRIPT_STREAM,
@@ -425,9 +441,8 @@ export {
 /**
  * Run a `wav.ts` helper, turning its "cannot cut this" into a terminal failure.
  *
- * Exported for the same reason `countWords` is: `stream.ts` plans with the same
- * `wav.ts` helpers and owes the same classification, and it had this byte for
- * byte.
+ * Exported because `stream.ts` plans with the same `wav.ts` helpers and owes the
+ * same classification, and it had this byte for byte.
  */
 export function fatalOnUnsupported<T>(read: () => T): T {
   try {

package/dist/templates/transcription-workflow/workflows/wav.ts

@@ -26,6 +26,21 @@
  * anything else by name rather than trying to be clever — an MP3 or an M4A frame
  * boundary cannot be found by arithmetic, and finding it means shipping a
  * decoder into a step.
+ *
+ * ## Who READS the refusals below
+ *
+ * {@link UnsupportedRecordingError} is raised from here and handled in two
+ * completely different ways, which is worth knowing before editing a message:
+ *
+ * - The plain `transcribe` flow CONVERTS rather than refusing. `normalize.ts`
+ *   calls {@link parseWav} as a QUESTION — a throw is its signal to hand the file
+ *   to ffmpeg — so on that path no message here reaches a person, and a file this
+ *   module rejects for a huge {@link MAX_BYTES_PER_SECOND} is one that
+ *   normalization fixes by downsampling.
+ * - `transcribeStream` still refuses, and has to: it cuts a recording while the
+ *   bytes are still arriving, and a partial file is not something ffmpeg can
+ *   transcode. There the sentences below are the whole of what a person is told,
+ *   so they keep naming the `ffmpeg` line that fixes the file.
  */
 
 /** What the sync endpoint will accept in one request. */
@@ -57,6 +72,22 @@ export const MAX_SEGMENT_BYTES = 40 * 1024 * 1024;
 /** The sync endpoint refuses audio shorter than this. */
 export const MIN_SEGMENT_MS = 80;
 
+/**
+ * Bytes probed for the WAV header.
+ *
+ * The canonical header is 44 bytes; a recorder that writes a `LIST` or `bext`
+ * chunk in front of the samples pushes the `data` chunk further out, and 64 KB
+ * covers every such file anyone has produced by accident.
+ *
+ * Declared HERE because three callers need the same window, and the third one is
+ * what made a shared constant the rule rather than a preference: `splitRecording`
+ * cuts on it, `planFromHead` in `stream.ts` cuts on it, and `normalize.ts` decides
+ * whether to CONVERT on it. Two of those probing a different amount than the third
+ * is a file the desk converts and then cannot cut, or refuses and then converts —
+ * both silent, and neither reproducible from any one module.
+ */
+export const HEADER_PROBE_BYTES = 64 * 1024;
+
 /**
  * The largest `bytesPerSecond` this desk will cut, and the reason it is checked
  * at PARSE time rather than at cut time.
@@ -281,34 +312,3 @@ export function planSegments(format: WavFormat): Segment[] {
   }
   return segments;
 }
-
-/**
- * Put a canonical 44-byte WAV header in front of a slice of samples.
- *
- * A byte range of a WAV is raw PCM with no header, and the sync endpoint reads
- * the rate and channel count out of one. Sending `audio/pcm` with a `config`
- * part instead would work equally well; a header keeps the two parts of the
- * request from being able to disagree.
- */
-export function wavWithHeader(format: WavFormat, samples: Uint8Array): Uint8Array<ArrayBuffer> {
-  const out = new Uint8Array(44 + samples.length);
-  const view = new DataView(out.buffer);
-  const write = (at: number, text: string) => {
-    for (let i = 0; i < text.length; i++) view.setUint8(at + i, text.charCodeAt(i));
-  };
-
-  write(0, "RIFF");
-  view.setUint32(4, 36 + samples.length, true);
-  write(8, "WAVEfmt ");
-  view.setUint32(16, 16, true); // `fmt ` payload length
-  view.setUint16(20, 1, true); // linear PCM
-  view.setUint16(22, format.channels, true);
-  view.setUint32(24, format.sampleRate, true);
-  view.setUint32(28, bytesPerSecond(format), true);
-  view.setUint16(32, blockAlign(format), true);
-  view.setUint16(34, format.bitsPerSample, true);
-  write(36, "data");
-  view.setUint32(40, samples.length, true);
-  out.set(samples, 44);
-  return out;
-}

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,14 @@ const agentDef = withDiscoveredTools(
   import.meta.glob("./tools/*.ts", { eager: true }),
 );
 
-import { activeAssistant, FLIGHTS, tripProjection, tripSlot, tripView } from "./shared.ts";
+import {
+  activeAssistant,
+  FLIGHTS,
+  gateFlow,
+  tripProjection,
+  tripSlot,
+  tripView,
+} from "./shared.ts";
 
 // ─── Harness ─────────────────────────────────────────────────────────────────
 
@@ -26,11 +39,11 @@ 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) {
@@ -116,36 +129,47 @@ describe("sensitive tools stage rather than act", () => {
     const ctx = makeCtx();
     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 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"'),
     });
   });
 
@@ -161,14 +185,14 @@ 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 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 () => {
@@ -193,7 +217,12 @@ 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([]);
 
@@ -207,7 +236,7 @@ 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 run("book_car_rental", { carId: "C2", days: 3 }, ctx);
-    await run("cancel_action", {}, ctx);
+    await run("cancel_action", ctx);
     const staged = (await run("book_excursion", { excursionId: "E2" }, ctx)) as {
       awaitingConfirmation: boolean;
     };
@@ -225,12 +254,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);
   });
@@ -283,8 +314,8 @@ describe("search tools", () => {
   test("lookup_booking reports the ticket the caller is actually holding", async () => {
     const ctx = makeCtx();
     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;
     };
@@ -327,9 +358,9 @@ describe("tripView projection", () => {
   test("totals every confirmed booking", async () => {
     const ctx = makeCtx();
     await run("book_hotel", { hotelId: "H3", nights: 2 }, ctx); // 2 × 180
-    await run("confirm_action", {}, ctx);
+    await run("confirm_action", 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/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." };
+    }),
 });