@alexkroman1/aai-cli 5.14.0 → 6.1.0

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

@@ -0,0 +1,314 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * The pure half of the transcription desk: reading a WAV header, deciding where
+ * to cut, and writing a header back over each cut.
+ *
+ * No directive in this file, and that is legal — the Workflow DevKit's builder
+ * scans `workflows/` and transforms only what carries a `"use workflow"` /
+ * `"use step"` body, so an ordinary module can sit beside them. It is a separate
+ * file because everything here is a pure function of a journaled value, which is
+ * what makes it testable without a run at all: `transcribe.ts`'s spec drives
+ * these directly.
+ *
+ * ## Why the chunking is here rather than at the provider
+ *
+ * AssemblyAI's SYNC endpoint answers in the request — no job id, no polling, no
+ * callback — and pays for that with a hard **120-second, 40 MB** limit per
+ * request. A two-hour recording is therefore not one call, it is sixty; and the
+ * splitting has to happen somewhere that can address the audio by BYTE RANGE,
+ * because re-downloading a 700 MB recording once per chunk is the obvious
+ * implementation and the wrong one.
+ *
+ * A linear-PCM WAV is the format that makes that possible without a decoder:
+ * every sample is the same size, so a byte offset IS a timestamp
+ * (`offset / (sampleRate * blockAlign)`) and a cut at any frame boundary is a
+ * clean cut. That is the whole reason this template asks for WAV and refuses
+ * 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.
+ */
+
+/** What the sync endpoint will accept in one request. */
+export const MAX_SEGMENT_SECONDS = 120;
+
+/**
+ * Seconds of audio per request, with headroom under the cap.
+ *
+ * Not `MAX_SEGMENT_SECONDS`: the overlap below is added on top of this, and a
+ * segment that lands one frame over the limit is a 413 rather than a shorter
+ * transcript.
+ */
+export const SEGMENT_SECONDS = 90;
+
+/**
+ * Seconds each segment repeats from the one before it.
+ *
+ * A cut lands wherever the arithmetic puts it, which is usually mid-word: the
+ * decoder on either side then hears half a word and reports something plausible
+ * and wrong. Overlapping the cut means both sides hear the whole word, and
+ * `stitchTranscript` drops the duplicate. The cost is 2 seconds of audio
+ * transcribed twice per segment — ~2% at `SEGMENT_SECONDS`.
+ */
+export const SEGMENT_OVERLAP_SECONDS = 2;
+
+/** The sync endpoint's payload cap, which a very high sample rate can reach first. */
+export const MAX_SEGMENT_BYTES = 40 * 1024 * 1024;
+
+/** The sync endpoint refuses audio shorter than this. */
+export const MIN_SEGMENT_MS = 80;
+
+/**
+ * The largest `bytesPerSecond` this desk will cut, and the reason it is checked
+ * at PARSE time rather than at cut time.
+ *
+ * `planSegments` divides by a format's bytes-per-second and then subtracts the
+ * overlap from the byte cap, so two declared formats make its loop never
+ * advance — and this is the one workflow app that takes an arbitrary uploaded
+ * file over a public form, so both are reachable by anyone with the URL:
+ *
+ * - a **zero** sample rate (or zero channels/bits, which
+ *   {@link blockAlign} already catches) makes `stride` zero, so `start +=
+ *   stride` is a no-op and the loop pushes a `Segment` per iteration until the
+ *   process dies of memory;
+ * - a **huge** one — `sampleRate` is a `uint32` and `channels`/`bitsPerSample`
+ *   are `uint16`, so a header can declare gigabytes a second — makes the
+ *   overlap alone exceed {@link MAX_SEGMENT_BYTES}, leaving `stride` NEGATIVE
+ *   and the loop walking backwards forever.
+ *
+ * Both are pure CPU with no `await` in them, so no `AbortSignal.timeout` and no
+ * step retry budget can interrupt one: the guard has to come before the loop.
+ * Requiring a whole second of audio to fit alongside the overlap is the bound
+ * that keeps the stride positive with room to spare; 48 kHz 24-bit stereo is
+ * 288 kB/s, four orders of magnitude under it.
+ */
+export const MAX_BYTES_PER_SECOND = MAX_SEGMENT_BYTES / (SEGMENT_OVERLAP_SECONDS + 1);
+
+/** A parsed linear-PCM WAV header, plus where its samples live. */
+export type WavFormat = {
+  sampleRate: number;
+  channels: number;
+  bitsPerSample: number;
+  /** Byte offset of the first sample. */
+  dataStart: number;
+  /** Byte offset one past the last sample. */
+  dataEnd: number;
+};
+
+/** One request's worth of audio, addressed as a byte range of the source. */
+export type Segment = {
+  /** Position in the recording — the fan-out's order, and the merge's. */
+  index: number;
+  /** First byte, frame-aligned and inclusive. */
+  start: number;
+  /** One past the last byte, frame-aligned. */
+  end: number;
+  /** Where this segment starts in the recording, for the progress log. */
+  startMs: number;
+  /** Where it ends. Overlaps the next segment's `startMs` — see the module doc. */
+  endMs: number;
+};
+
+/** Raised for a recording this template cannot cut. Always terminal. */
+export class UnsupportedRecordingError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "UnsupportedRecordingError";
+  }
+}
+
+/** Bytes one sample frame occupies — all channels of one instant. */
+export function blockAlign(format: Pick<WavFormat, "channels" | "bitsPerSample">): number {
+  return (format.channels * format.bitsPerSample) / 8;
+}
+
+/** Bytes of audio per second of wall clock. */
+export function bytesPerSecond(
+  format: Pick<WavFormat, "channels" | "bitsPerSample" | "sampleRate">,
+): number {
+  return blockAlign(format) * format.sampleRate;
+}
+
+/** Where a byte offset falls in the recording. */
+export function offsetToMs(format: WavFormat, offset: number): number {
+  return Math.round(((offset - format.dataStart) / bytesPerSecond(format)) * 1000);
+}
+
+/** Four bytes read as ASCII — a RIFF chunk id. */
+function chunkId(bytes: Uint8Array, at: number): string {
+  return String.fromCharCode(...bytes.subarray(at, at + 4));
+}
+
+/**
+ * Read a WAV header out of the first bytes of a recording.
+ *
+ * `totalBytes` is the size of the whole file, which the header cannot be trusted
+ * for: a WAV written by a streaming encoder declares `0` or `0xFFFFFFFF` for its
+ * data length because the length was not known when the header went out, and a
+ * truncated download declares more than it holds. So the sample range is the
+ * intersection of what the header claims and what the file actually has.
+ *
+ * @param head - The start of the file. Must reach past the `data` chunk's
+ *   header — {@link parseWav} walks the chunk list, and a file with a large
+ *   `LIST` or `bext` chunk in front of its samples pushes that further than the
+ *   canonical 44 bytes.
+ * @param totalBytes - The size of the whole file, from `Content-Range` or
+ *   `Content-Length`.
+ */
+export function parseWav(head: Uint8Array, totalBytes: number): WavFormat {
+  if (head.length < 12 || chunkId(head, 0) !== "RIFF" || chunkId(head, 8) !== "WAVE") {
+    throw new UnsupportedRecordingError(
+      "That is not a WAV file. This desk cuts linear-PCM WAV by byte offset, so a compressed " +
+        "recording has to be converted first (`ffmpeg -i in.m4a -c:a pcm_s16le out.wav`).",
+    );
+  }
+  const view = new DataView(head.buffer, head.byteOffset, head.byteLength);
+  let fmt: Pick<WavFormat, "sampleRate" | "channels" | "bitsPerSample"> | undefined;
+
+  // The chunk list. Each entry is a 4-byte id, a 4-byte little-endian length,
+  // and a payload padded to an even length — the padding byte is not counted by
+  // the length, which is the off-by-one this loop exists to get right once.
+  for (let at = 12; at + 8 <= head.length; ) {
+    const id = chunkId(head, at);
+    const size = view.getUint32(at + 4, true);
+    const payload = at + 8;
+
+    if (id === "fmt " && payload + 16 <= head.length) {
+      const encoding = view.getUint16(payload, true);
+      // 1 is WAVE_FORMAT_PCM. 0xFFFE is WAVE_FORMAT_EXTENSIBLE, whose real
+      // encoding lives in a GUID further in; refused rather than guessed,
+      // because guessing wrong produces noise that transcribes as words.
+      if (encoding !== 1) {
+        throw new UnsupportedRecordingError(
+          `That WAV holds encoding ${encoding}, not linear PCM — re-encode it with \`-c:a pcm_s16le\`.`,
+        );
+      }
+      fmt = {
+        channels: view.getUint16(payload + 2, true),
+        sampleRate: view.getUint32(payload + 4, true),
+        bitsPerSample: view.getUint16(payload + 14, true),
+      };
+    } else if (id === "data") {
+      if (!fmt)
+        throw new UnsupportedRecordingError("That WAV has no `fmt ` chunk before its data.");
+      if (blockAlign(fmt) <= 0) {
+        throw new UnsupportedRecordingError(
+          `That WAV declares ${fmt.channels} channels at ${fmt.bitsPerSample} bits — nothing to cut.`,
+        );
+      }
+      // The rate is validated HERE, beside the encoding and the block align,
+      // because everything downstream divides by it — see
+      // {@link MAX_BYTES_PER_SECOND} for the two loops a bad one hangs.
+      if (fmt.sampleRate <= 0) {
+        throw new UnsupportedRecordingError(
+          "That WAV declares a sample rate of 0, so nothing in it can be given a timestamp.",
+        );
+      }
+      const perSecond = bytesPerSecond(fmt);
+      if (perSecond > MAX_BYTES_PER_SECOND) {
+        throw new UnsupportedRecordingError(
+          `That WAV declares ${fmt.sampleRate} Hz across ${fmt.channels} channels at ${fmt.bitsPerSample} bits — ${perSecond} bytes a second, past the ${MAX_BYTES_PER_SECOND} this desk can cut into ${MAX_SEGMENT_BYTES}-byte requests.`,
+        );
+      }
+      // See the doc above: `0` and `0xFFFFFFFF` both mean "unknown", and any
+      // declared length is capped by what was actually served.
+      const declared = size === 0 || size === 0xff_ff_ff_ff ? Number.POSITIVE_INFINITY : size;
+      return { ...fmt, dataStart: payload, dataEnd: Math.min(payload + declared, totalBytes) };
+    }
+
+    at = payload + size + (size % 2);
+  }
+
+  throw new UnsupportedRecordingError(
+    `No \`data\` chunk in the first ${head.length} bytes of that WAV — its header is longer than this desk probes.`,
+  );
+}
+
+/** Round an offset down to a frame boundary, so a cut never lands mid-sample. */
+function alignDown(offset: number, frame: number): number {
+  return Math.floor(offset / frame) * frame;
+}
+
+/**
+ * Cut a recording into segments the sync endpoint will accept.
+ *
+ * The fan-out's width comes from this, and it is a pure function of a journaled
+ * value (the format, which a step returned) — the ordinary determinism rule: a
+ * replay has to re-derive the same list, in the same order, or the DevKit hands
+ * the Nth journal entry to a different call.
+ */
+export function planSegments(format: WavFormat): Segment[] {
+  const frame = blockAlign(format);
+  const perSecond = bytesPerSecond(format);
+  const audioBytes = format.dataEnd - format.dataStart;
+  if (audioBytes < (perSecond * MIN_SEGMENT_MS) / 1000) {
+    throw new UnsupportedRecordingError(
+      `That recording is ${Math.round((audioBytes / perSecond) * 1000)}ms long — the sync endpoint needs at least ${MIN_SEGMENT_MS}ms.`,
+    );
+  }
+
+  // The overlap is decided FIRST, because both of the stride's caps have to
+  // leave room for it: a segment is `stride + overlap` long, so subtracting it
+  // here is what keeps that sum inside the endpoint's two limits. Getting this
+  // backwards is a 413 on exactly the inputs that reach a cap.
+  const overlap = alignDown(
+    Math.min(
+      SEGMENT_OVERLAP_SECONDS * perSecond,
+      (MAX_SEGMENT_SECONDS - SEGMENT_SECONDS) * perSecond,
+    ),
+    frame,
+  );
+  // Whichever cap binds first. A 96 kHz stereo 24-bit recording reaches 40 MB
+  // at ~73 seconds, so on that input the byte cap is the one that decides;
+  // ordinary speech audio is nowhere near it and the duration cap decides.
+  const stride = alignDown(
+    Math.min(SEGMENT_SECONDS * perSecond, MAX_SEGMENT_BYTES - overlap),
+    frame,
+  );
+
+  const segments: Segment[] = [];
+  for (let start = format.dataStart; start < format.dataEnd; start += stride) {
+    const end = Math.min(start + stride + overlap, format.dataEnd);
+    segments.push({
+      index: segments.length,
+      start,
+      end,
+      startMs: offsetToMs(format, start),
+      endMs: offsetToMs(format, end),
+    });
+    // The overlap means the last segment reaches the end one stride early, and
+    // without this the loop would emit a final empty one.
+    if (end >= format.dataEnd) break;
+  }
+  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

@@ -0,0 +1,338 @@
+/// <reference types="vite/client" />
+
+import type { ToolContext } from "@alexkroman1/aai";
+import { createToolContext, runTool, withDiscoveredTools } from "@alexkroman1/aai/testing";
+import { describe, expect, test } from "vitest";
+import authoredAgent from "./agent.ts";
+
+/**
+ * The def a DEPLOYED agent runs: authored, plus what `tools/` declares.
+ *
+ * The glob is written HERE rather than reached for from a shared helper because
+ * this file SHIPS: it is what a scaffolded project runs, so it may not import
+ * anything outside its own template, and `import.meta.glob` is expanded against
+ * the file containing it either way. This is the pattern a user writes.
+ */
+const agentDef = withDiscoveredTools(
+  authoredAgent,
+  import.meta.glob("./tools/*.ts", { eager: true }),
+);
+
+import { activeAssistant, FLIGHTS, tripSlot, tripView } from "./shared.ts";
+
+// ─── Harness ─────────────────────────────────────────────────────────────────
+
+/** Each context owns its OWN slot store, which is what the isolation test
+ *  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);
+
+/** The state a tool just mutated, read back the way `syncState` reads it. */
+function stateOf(ctx: ToolContext) {
+  return tripSlot.get(ctx);
+}
+
+// ─── 1. The dialog stack ─────────────────────────────────────────────────────
+
+describe("dialog stack (routing.ts)", () => {
+  test("delegating pushes a desk and hands back its brief", async () => {
+    const ctx = makeCtx();
+    expect(activeAssistant(stateOf(ctx))).toBe("primary");
+
+    const handoff = (await run(
+      "to_hotel_assistant",
+      { request: "somewhere near the water" },
+      ctx,
+    )) as {
+      desk: string;
+      instructions: string;
+    };
+    expect(handoff.desk).toBe("hotel desk");
+    // The brief IS the tool result — that is the whole port of their
+    // per-assistant prompt onto a session whose prompt is fixed at connect.
+    expect(handoff.instructions).toContain("hotel desk");
+    expect(activeAssistant(stateOf(ctx))).toBe("hotel");
+  });
+
+  test("re-delegating to the desk already holding the call does not grow the stack", async () => {
+    const ctx = makeCtx();
+    await run("to_flight_assistant", { request: "move my flight" }, ctx);
+    await run("to_flight_assistant", { request: "actually a later one" }, ctx);
+    expect(stateOf(ctx).dialogState).toEqual(["primary", "flight"]);
+  });
+
+  test("complete_or_escalate pops, and never past the concierge", async () => {
+    const ctx = makeCtx();
+    await run("to_excursion_assistant", { request: "something to do" }, ctx);
+
+    const back = (await run("complete_or_escalate", { reason: "booked it" }, ctx)) as {
+      returnedFrom: string;
+      nowHandling: string;
+    };
+    expect(back.returnedFrom).toBe("excursions desk");
+    expect(back.nowHandling).toBe("concierge");
+    expect(activeAssistant(stateOf(ctx))).toBe("primary");
+
+    // Popping again at the bottom is a no-op rather than an empty stack: the
+    // slot's `after` hook is what guarantees there is always an assistant.
+    await run("complete_or_escalate", { reason: "nothing else" }, ctx);
+    expect(stateOf(ctx).dialogState).toEqual(["primary"]);
+  });
+});
+
+// ─── 2. The confirmation gate ────────────────────────────────────────────────
+//
+// Their graph halts before a sensitive tool (`interrupt_before`) and resumes on
+// approval. Here every sensitive tool stages and applies nothing, so the
+// approval has somewhere to arrive. These are the tests that matter: a
+// regression makes the agent able to rebook a flight BY MISTAKE.
+
+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) => {
+    const ctx = makeCtx();
+    const before = structuredClone(stateOf(ctx));
+
+    const staged = (await run(name, args, ctx)) as { awaitingConfirmation: boolean };
+    expect(staged.awaitingConfirmation).toBe(true);
+
+    const after = stateOf(ctx);
+    expect(after.ticket).toEqual(before.ticket);
+    expect(after.bookings).toEqual([]);
+    expect(after.pending).not.toBeNull();
+  });
+
+  test("confirm_action applies the staged change, and only then", async () => {
+    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");
+    // 3 nights at $265.
+    expect(applied.applied).toContain("$795");
+
+    const state = stateOf(ctx);
+    expect(state.pending).toBeNull();
+    expect(state.bookings).toHaveLength(1);
+    expect(state.bookings[0]?.reference).toBe(applied.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.",
+    });
+  });
+
+  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 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.",
+    });
+  });
+
+  test("a staged action naming something that does not exist is refused at staging time", async () => {
+    // Refused where the model can still recover — before the caller is asked to
+    // confirm a flight the airline does not fly.
+    const ctx = makeCtx();
+    expect(await run("update_ticket", { flightId: "ZZ99" }, ctx)).toEqual({
+      error: "No flight ZZ99 in the schedule.",
+    });
+    expect(stateOf(ctx).pending).toBeNull();
+  });
+
+  test("cancelling the ticket makes a later ticket change impossible", async () => {
+    const ctx = makeCtx();
+    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." });
+  });
+
+  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
+    // second win — both answered `awaitingConfirmation`, the caller said yes
+    // once, and one of the two changes was silently dropped forever.
+    const ctx = makeCtx();
+    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 {
+      error: string;
+    };
+    // The refusal NAMES what is already waiting, which is what lets the model
+    // settle that one and come back rather than guess.
+    expect(second.error).toContain("LX52");
+    expect(second.error).toMatch(/confirm_action or cancel_action/);
+
+    // 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 };
+    expect(applied.applied).toContain("LX52");
+    expect(stateOf(ctx).bookings).toEqual([]);
+
+    // Once the queue is clear, the hotel can be staged after all.
+    const retried = (await run("book_hotel", { hotelId: "H1", nights: 2 }, ctx)) as {
+      awaitingConfirmation: boolean;
+    };
+    expect(retried.awaitingConfirmation).toBe(true);
+  });
+
+  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);
+    const staged = (await run("book_excursion", { excursionId: "E2" }, ctx)) as {
+      awaitingConfirmation: boolean;
+    };
+    expect(staged.awaitingConfirmation).toBe(true);
+  });
+
+  test("two independent contexts never share a stack, a ticket or an itinerary", async () => {
+    // What this really checks: the state lives in the SLOT and not in a
+    // module-level variable. `createToolContext()` hands each call its own
+    // detached slot store, so the isolation is per CONTEXT — two distinct
+    // session ids would prove nothing extra, and `sessionSlot` could stop
+    // keying by session with this still passing.
+    const first = makeCtx();
+    const second = makeCtx();
+
+    await run("to_hotel_assistant", { request: "a room" }, first);
+    await run("book_hotel", { hotelId: "H3", nights: 1 }, 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.",
+    });
+    expect(stateOf(first).bookings).toHaveLength(1);
+  });
+});
+
+// ─── 3. Search ───────────────────────────────────────────────────────────────
+
+describe("search tools", () => {
+  test("an unmatched route widens to the whole schedule rather than answering nothing", async () => {
+    const ctx = makeCtx();
+    const hit = (await run("search_flights", { route: "Zurich to Boston" }, ctx)) as {
+      widened: boolean;
+      flights: unknown[];
+    };
+    expect(hit.widened).toBe(false);
+    expect(hit.flights).toHaveLength(3);
+
+    const miss = (await run("search_flights", { route: "Osaka" }, ctx)) as {
+      widened: boolean;
+      flights: unknown[];
+    };
+    expect(miss.widened).toBe(true);
+    expect(miss.flights).toHaveLength(FLIGHTS.length);
+  });
+
+  test("hotels come back cheapest first, and a ceiling filters them", async () => {
+    const ctx = makeCtx();
+    const all = (await run("search_hotels", { city: "Boston" }, ctx)) as {
+      hotels: { perNight: string }[];
+    };
+    expect(all.hotels.map((h) => h.perNight)).toEqual(["$180", "$265", "$340"]);
+
+    const cheap = (await run("search_hotels", { city: "Boston", maxPerNight: 200 }, ctx)) as {
+      hotels: { name: string }[];
+    };
+    expect(cheap.hotels).toHaveLength(1);
+    expect(cheap.hotels[0]?.name).toBe("Cambridge Rooms");
+  });
+
+  test("an excursion keyword that matches nothing falls back to the city", async () => {
+    const ctx = makeCtx();
+    const result = (await run("search_excursions", { city: "Boston", keyword: "skiing" }, ctx)) as {
+      widened: boolean;
+      excursions: unknown[];
+    };
+    expect(result.widened).toBe(true);
+    expect(result.excursions).toHaveLength(3);
+  });
+
+  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 {
+      passenger: string;
+      ticket: { flight: string; departs: string } | null;
+    };
+    expect(booking.passenger).toBe("Nadia Rossi");
+    expect(booking.ticket?.flight).toBe("LX52");
+    expect(booking.ticket?.departs).toBe("Wed 09:20");
+  });
+});
+
+// ─── 4. The projection contract with client.tsx ─────────────────────────────
+
+describe("tripView projection", () => {
+  test("an untouched call projects the seeded booking at the concierge desk", () => {
+    // Exactly the value client.tsx hoists as its fallback.
+    const view = tripSlot.projection(tripView)(undefined);
+    expect(view).toMatchObject({
+      assistant: "primary",
+      assistantTitle: "concierge",
+      bookings: [],
+      total: 0,
+      pending: null,
+    });
+    expect(view.ticket?.flightId).toBe("LX40");
+  });
+
+  test("renders the staged action as the prose the concierge just spoke", async () => {
+    const ctx = makeCtx();
+    await run("to_car_rental_assistant", { request: "a car for the week" }, ctx);
+    await run("book_car_rental", { carId: "C3", days: 4 }, ctx);
+
+    const view = tripView(stateOf(ctx));
+    expect(view.assistant).toBe("car_rental");
+    expect(view.assistantTitle).toBe("car rental desk");
+    // $95/day × 4 — the sidebar and the spoken read-back derive from one string.
+    expect(view.pending).toContain("$380");
+    expect(view.log.at(-1)).toContain("Awaiting confirmation");
+  });
+
+  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("book_excursion", { excursionId: "E1" }, ctx); // 35
+    await run("confirm_action", {}, ctx);
+
+    const view = tripView(stateOf(ctx));
+    expect(view.total).toBe(395);
+    expect(view.bookings.map((b) => b.kind)).toEqual(["hotel", "excursion"]);
+    expect(view.pending).toBeNull();
+  });
+});

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

@@ -0,0 +1,29 @@
+import { agent } from "@alexkroman1/aai";
+import { tripSlot, tripView } from "./shared.ts";
+
+/**
+ * A phone travel concierge, adapted from LangGraph's customer-support tutorial.
+ * `shared.ts` carries the attribution and what changed on the way to voice; the
+ * 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.
+ */
+export default agent({
+  name: "Swiss Air Concierge",
+  // The stack, the ticket and the itinerary exist before the first tool call,
+  // so a resumed connection has something to project.
+  // One projection replaces a `ctx.send` in each of eleven tools — and is the
+  // single place that decides the caller's record leaves the server trimmed.
+  syncState: tripSlot.projection(tripView),
+  greeting:
+    "Swiss Air Travel, this is the concierge desk. I can see your booking — what can I do for you today?",
+});