@alexkroman1/aai-cli 13.3.0 → 14.0.0

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

@@ -53,12 +53,12 @@
  * request rather than two and the value journaled by the last poll IS the result.
  */
 
-import type { WorkflowCtx } from "@alexkroman1/aai";
-import { report, TRANSCRIBE_API, uploadInfo } from "@alexkroman1/aai/step";
+import type { WorkflowContext } from "@alexkroman1/aai";
+import { stepReport, stepUploadInfo, TRANSCRIBE_API } from "@alexkroman1/aai/step";
 import {
-  stepTranscribePollClassified,
-  stepTranscribeSubmitClassified,
-  stepTranscribeUploadClassified,
+  stepTranscribePollOrFail,
+  stepTranscribeSubmitOrFail,
+  stepTranscribeUploadOrFail,
 } from "@alexkroman1/aai/step-errors";
 import { countWords, formatBytes } from "@alexkroman1/aai/utils";
 import type { Transcript } from "./transcribe.ts";
@@ -78,7 +78,7 @@ const MAX_POLLS = 360;
 /** Transcribe a recording through the async API. */
 export async function transcribeBatchFlow(
   input: { recording: string },
-  ctx: WorkflowCtx,
+  ctx: WorkflowContext,
 ): Promise<Transcript> {
   // Both at once: the clock does not depend on the upload, and issuing them
   // together costs one round trip instead of two before a byte moves. Their issue
@@ -122,24 +122,24 @@ export async function transcribeBatchFlow(
  * far smaller: if it expires before the next step runs, the run fails and a fresh one
  * re-uploads — which is what would have happened anyway, once, instead of five times.
  *
- * The `Classified` callers on `@alexkroman1/aai/step-errors` are the SDK's own
+ * The `OrFail` callers on `@alexkroman1/aai/step-errors` are the SDK's own
  * `stepTranscribe*` plus `throwStepError` and nothing else, which is what turns the
  * SDK's `TranscribeError` into the DevKit's verdict: a missing key and a 400 stop, a
  * 429 waits as long as the service asked. Every step here ends the same way for the
  * same reason.
  */
 export async function uploadToProvider(uploadId: string): Promise<{ audioUrl: string }> {
-  const stored = await uploadInfo(uploadId);
-  await report(
+  const stored = await stepUploadInfo(uploadId);
+  await stepReport(
     `Uploading ${stored.name || uploadId} (${formatBytes(stored.size)}) to the async API.`,
   );
-  return await stepTranscribeUploadClassified(uploadId);
+  return await stepTranscribeUploadOrFail(uploadId);
 }
 
 /** Create the transcription job, and answer with the id that outlives this run. */
 export async function createJob(audioUrl: string): Promise<{ id: string }> {
-  const job = await stepTranscribeSubmitClassified(audioUrl);
-  await report(`Submitted — job ${job.id}.`);
+  const job = await stepTranscribeSubmitOrFail(audioUrl);
+  await stepReport(`Submitted — job ${job.id}.`);
   return job;
 }
 
@@ -156,13 +156,13 @@ export async function pollTranscript(
   id: string,
   startedAt: number,
 ): Promise<{ done: false } | { done: true; transcript: Transcript }> {
-  const progress = await stepTranscribePollClassified(id);
+  const progress = await stepTranscribePollOrFail(id);
   if (!progress.done) {
-    await report(`Transcript ${id} is ${progress.status}.`);
+    await stepReport(`Transcript ${id} is ${progress.status}.`);
     return { done: false };
   }
 
-  const stored = await uploadInfo(uploadId);
+  const stored = await stepUploadInfo(uploadId);
   const transcript = progress.transcript.text;
   return {
     done: true,

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

@@ -152,7 +152,7 @@ export function downsampleSegment(
   const bind = sampleReaderFor(from);
   const frame = blockAlign(from);
   const inFrames = Math.floor(bytes.length / frame);
-  // A CALLER ERROR, and stated as one. `readUpload` clamps a window to what is
+  // A CALLER ERROR, and stated as one. `stepReadUpload` clamps a window to what is
   // stored, so the streaming flow can hand a short read down here; with no whole
   // frame the averaging window below is zero wide, `total / 0` is `NaN`, and
   // `setInt16` writes that as a 0 — a two-byte WAV of silence, transcribed and

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

@@ -70,8 +70,8 @@
  */
 
 import { basename, extname, join } from "node:path";
-import { probeMedia, runFfmpeg, wavEncodeArgs } from "@alexkroman1/aai/ffmpeg";
-import { readUpload, report, requireCompleteUpload } from "@alexkroman1/aai/step";
+import { ffmpegBaseArgs, probeMedia, runFfmpeg, wavEncodeArgs } from "@alexkroman1/aai/ffmpeg";
+import { stepReadUpload, stepReport, stepRequireCompleteUpload } from "@alexkroman1/aai/step";
 import { throwFfmpegStepError } from "@alexkroman1/aai/step-errors";
 import { readUploadToFile, withTempDir, writeUploadFromFile } from "@alexkroman1/aai/step-files";
 import { formatBytes, formatDuration } from "@alexkroman1/aai/utils";
@@ -122,16 +122,16 @@ export type NormalizedRecording = {
  * file that already exists instead of paying for a second one.
  */
 export async function normalizeRecording(uploadId: string): Promise<NormalizedRecording> {
-  // `requireCompleteUpload`, not `uploadInfo`: `size` is the readable PREFIX, and
+  // `stepRequireCompleteUpload`, not `stepUploadInfo`: `size` is the readable PREFIX, and
   // every judgement below — cuttable, heavier-per-second, the byte count copied to
   // disk — is about the WHOLE file.
-  const stored = await requireCompleteUpload(uploadId);
-  const head = await readUpload(uploadId, { end: HEADER_PROBE_BYTES });
+  const stored = await stepRequireCompleteUpload(uploadId);
+  const head = await stepReadUpload(uploadId, { end: HEADER_PROBE_BYTES });
 
   if (cuttable(head.bytes, stored.size) && !heavierThanNormalized(head.bytes, stored.size)) {
     // No subprocess, no copy, no second upload. The overwhelmingly common case
     // for a desk whose form says WAV, and the reason the check is a 64 KB read.
-    await report(`${stored.name || uploadId} is already linear-PCM WAV — cutting it as it is.`);
+    await stepReport(`${stored.name || uploadId} is already linear-PCM WAV — cutting it as it is.`);
     return { recording: uploadId, converted: false };
   }
 
@@ -144,7 +144,7 @@ export async function normalizeRecording(uploadId: string): Promise<NormalizedRe
   // WAV that is fine but too heavy to cut at this rate. Reporting "not a WAV we
   // can cut" for the second one is a line that contradicts the file they
   // uploaded.
-  await report(
+  await stepReport(
     `Converting ${stored.name || uploadId} (${formatBytes(stored.size)}) — ` +
       (cuttable(head.bytes, stored.size)
         ? `heavier per second than ${NORMALIZED_SAMPLE_RATE / 1000} kHz mono.`
@@ -164,7 +164,7 @@ export async function normalizeRecording(uploadId: string): Promise<NormalizedRe
       // `STEP_FILE_READ_CONCURRENCY` of them. Passing `size` means "I am judging
       // completeness myself", which is what a body polling a still-arriving
       // upload needs and is the opposite of what happened above: this step has
-      // already called `requireCompleteUpload`, so the file IS whole and the
+      // already called `stepRequireCompleteUpload`, so the file IS whole and the
       // windows may land in any order. Omitting it lets `readUploadToFile`
       // establish that for itself and fan out. The cost is one metadata round
       // trip, against the dozens of window reads it overlaps.
@@ -177,22 +177,18 @@ export async function normalizeRecording(uploadId: string): Promise<NormalizedRe
       const info = await probeMedia(source, { timeoutMs: CONVERT_TIMEOUT_MS }).catch(
         throwFfmpegStepError,
       );
-      await report(
+      await stepReport(
         `It is ${describeSource(info.audio?.codec, info.durationSec)} — re-encoding to ` +
           `${NORMALIZED_SAMPLE_RATE / 1000} kHz mono WAV.`,
       );
 
       await runFfmpeg(
         [
-          // The argv is the caller's, verbatim — `runFfmpeg` adds nothing. So the
-          // standing flags are here: quiet, non-interactive, overwrite. `-nostdin`
-          // matters most in a guest, where there is no terminal and an ffmpeg that
-          // decides to read stdin is a process that never exits.
-          "-hide_banner",
-          "-loglevel",
-          "error",
-          "-nostdin",
-          "-y",
+          // The argv is the caller's, verbatim — `runFfmpeg` adds nothing — so
+          // the standing flags are the caller's too. This copy used to omit
+          // `-nostats`, which is the one that keeps ffmpeg's progress spam from
+          // evicting the error out of the captured stderr tail.
+          ...ffmpegBaseArgs(),
           "-i",
           source,
           ...wavEncodeArgs({
@@ -212,7 +208,7 @@ export async function normalizeRecording(uploadId: string): Promise<NormalizedRe
         type: "audio/wav",
       });
 
-      await report(
+      await stepReport(
         `Converted to ${formatBytes(written.size)} of WAV (from ${formatBytes(stored.size)}).`,
       );
       return { recording: written.id, converted: true };

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

@@ -22,7 +22,7 @@
  * first byte with `complete: false` and its `size` grows as bytes land.
  *
  * The reader needed almost nothing for this, which is why this flow is so close to
- * the other one: `readUpload` already clamped its window to what is stored (so a
+ * the other one: `stepReadUpload` already clamped its window to what is stored (so a
  * plan computed from a header could end one byte past the file), and that clamp is
  * exactly "read what has arrived". So `transcribeSegment` below is `transcribe.ts`'s
  * OWN step, unchanged, called on windows this body has checked are present.
@@ -50,7 +50,7 @@
  *   0.9 MB/s: `size` was 0 at every poll for 45 seconds and then the whole file, so
  *   the run planned nothing, transcribed nothing, and did its entire fan-out after
  *   the upload — the classic flow, with extra steps. `segmentStored` reads `ranges`
- *   instead, and `readUpload` clamps to the run a read starts in rather than to the
+ *   instead, and `stepReadUpload` clamps to the run a read starts in rather than to the
  *   prefix, so a window that has landed is a window this flow can work on.
  * - **The stall test on the prefix would then FAIL a healthy upload.** A parts
  *   upload moving at full speed reports the same prefix at every poll, which is
@@ -167,13 +167,13 @@
  * what keeps that order a pure function of journaled values.
  */
 
-import type { WorkflowCtx } from "@alexkroman1/aai";
+import type { WorkflowContext } from "@alexkroman1/aai";
 import {
   mapConcurrent,
-  readUpload,
-  report,
+  stepReadUpload,
+  stepReport,
+  stepUploadInfo,
   type UploadRange,
-  uploadInfo,
 } from "@alexkroman1/aai/step";
 import { throwFatalStepError } from "@alexkroman1/aai/step-errors";
 import { formatDuration, omitUndefined, plural } from "@alexkroman1/aai/utils";
@@ -308,7 +308,7 @@ export type StreamPlan = {
  * an upload id exactly as in the classic flow; what differs is that the client chose
  * it and the bytes are still on their way.
  */
-export async function transcribeStreamFlow(input: { recording: string }, ctx: WorkflowCtx) {
+export async function transcribeStreamFlow(input: { recording: string }, ctx: WorkflowContext) {
   // `ctx.now()`, not a step: the engine journals the read under its own key, so
   // every walk of this line sees the instant the first one did.
   const startedAt = await ctx.now();
@@ -364,7 +364,7 @@ export async function transcribeStreamFlow(input: { recording: string }, ctx: Wo
       // A segment is READY when its whole window is stored — except once the upload
       // is complete, where `at.size` is the true total and the plan came from the
       // header's DECLARED length: a recording that came up short leaves a final
-      // segment ending past the file, and `readUpload` clamping is what makes that
+      // segment ending past the file, and `stepReadUpload` clamping is what makes that
       // the right answer rather than an error.
       const ready = plan.segments.filter(
         (segment) =>
@@ -443,7 +443,7 @@ export async function transcribeStreamFlow(input: { recording: string }, ctx: Wo
  * from.
  */
 export async function probeUpload(id: string): Promise<UploadProgressView> {
-  const info = await uploadInfo(id);
+  const info = await stepUploadInfo(id);
   return {
     size: info.size,
     complete: info.complete,
@@ -609,7 +609,7 @@ export function storedBytes(size: number, ranges: readonly UploadRange[] | undef
  * only the prefix and the run has nothing to do until the upload is over, which
  * is the entire wait this flow exists to remove.
  *
- * A window has to be covered WHOLE by one run: `readUpload` clamps to the run a
+ * A window has to be covered WHOLE by one run: `stepReadUpload` clamps to the run a
  * read starts in, so a segment straddling a hole would come back short and be
  * transcribed as a fragment. `rangesOf` merges adjacent windows, so a run really
  * is a contiguous stretch and one containment test is the whole check.
@@ -636,7 +636,7 @@ export function segmentStored(segment: Segment, at: UploadProgressView): boolean
  * which is what the classic flow is for.
  */
 export async function planStreamed(id: string): Promise<StreamPlan> {
-  const head = await readUpload(id, { end: HEADER_PROBE_BYTES });
+  const head = await stepReadUpload(id, { end: HEADER_PROBE_BYTES });
   const format = fatalOnUnsupported(() => parseWav(head.bytes, Number.POSITIVE_INFINITY));
   if (!Number.isFinite(format.dataEnd)) {
     return throwFatalStepError(
@@ -647,7 +647,7 @@ export async function planStreamed(id: string): Promise<StreamPlan> {
     );
   }
   const segments = fatalOnUnsupported(() => planSegments(format));
-  await report(
+  await stepReport(
     `Planned ${formatDuration(segments.at(-1)?.endMs ?? 0)} of audio as ` +
       `${segments.length} ${plural(segments.length, "segment")} while it uploads.`,
   );

package/dist/templates/transcription-workflow/workflows/sync-api.ts

@@ -18,7 +18,7 @@
  * the same shape). It is called FROM steps, so it inherits their environment.
  */
 
-import { stepTranscribeSyncClassified } from "@alexkroman1/aai/step-errors";
+import { stepTranscribeSyncOrFail } from "@alexkroman1/aai/step-errors";
 
 /**
  * Time one transcription, so the progress log carries LATENCY.
@@ -57,7 +57,7 @@ export function elapsed(ms: number): string {
  * concatenated straight into the request body rather than into an intermediate
  * buffer that doubles the segment's footprint.
  *
- * `stepTranscribeSyncClassified` — the SDK's own `stepTranscribeSync` plus
+ * `stepTranscribeSyncOrFail` — the SDK's own `stepTranscribeSync` plus
  * `throwStepError`, and nothing else — is the whole of what this adds to the SDK
  * call, and it is where the three-way call is made: a `FatalError` stops the DevKit retrying
  * something that will answer the same way, a bare `RetryableError` retries in ONE
@@ -75,6 +75,6 @@ export async function transcribeWav(
   filename: string,
   label: string,
 ): Promise<string> {
-  const { text } = await stepTranscribeSyncClassified(bytes, { filename, label });
+  const { text } = await stepTranscribeSyncOrFail(bytes, { filename, label });
   return text;
 }

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

@@ -48,7 +48,7 @@
  * - **The audio is addressed by BYTE RANGE, never carried.** A workflow's input
  *   is journaled and replayed on every resume, so the recording lives in the
  *   app's own upload store and the run carries only its id; each step reads
- *   exactly its own window with `readUpload`. Sixty steps therefore move the
+ *   exactly its own window with `stepReadUpload`. Sixty steps therefore move the
  *   recording once between them, not sixty times.
  * - **The fan-out is bounded by `mapConcurrent`, and the bound is not a detail.**
  *   The DevKit correlates a journal entry to a step call by the ORDER the call
@@ -57,20 +57,20 @@
  *   calls settle. Its module doc carries the argument; what matters here is that
  *   there is no barrier, so a slow segment costs only itself.
  * - **The transcript STREAMS as it is produced.** Each segment is emitted the
- *   moment it lands (`emit(TRANSCRIPT_STREAM, …)`), so the page renders the
+ *   moment it lands (`stepEmit(TRANSCRIPT_STREAM, …)`), so the page renders the
  *   answer growing rather than a status line and then everything at once. That is
  *   the difference a fan-out can make to a reader and a run output cannot: an
  *   `output` exists only when the last segment does.
  */
 
-import type { WorkflowCtx } from "@alexkroman1/aai";
+import type { WorkflowContext } from "@alexkroman1/aai";
 import {
-  emit,
   mapConcurrent,
-  readUpload,
-  report,
-  requireCompleteUpload,
-  uploadInfo,
+  stepEmit,
+  stepReadUpload,
+  stepReport,
+  stepRequireCompleteUpload,
+  stepUploadInfo,
   wavHeader,
 } from "@alexkroman1/aai/step";
 import { throwFatalStepError } from "@alexkroman1/aai/step-errors";
@@ -248,7 +248,7 @@ export type SegmentTranscript = {
  * The input is what `POST /workflows/runs` carries — see `agent.ts` for the
  * schema it is validated against before a run exists.
  */
-export async function transcribeFlow(input: { recording: string }, ctx: WorkflowCtx) {
+export async function transcribeFlow(input: { recording: string }, ctx: WorkflowContext) {
   // Both at once: neither needs the other, and issued together they are one
   // 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
@@ -313,13 +313,13 @@ export async function splitRecording(uploadId: string): Promise<{
   // half-arrived recording this planned a fan-out over the first half and the run
   // returned a transcript of it, reporting success. `stream.ts` is the flow for a
   // recording that is still landing; this one wants all of it.
-  const stored = await requireCompleteUpload(uploadId);
-  const head = await readUpload(uploadId, { end: HEADER_PROBE_BYTES });
+  const stored = await stepRequireCompleteUpload(uploadId);
+  const head = await stepReadUpload(uploadId, { end: HEADER_PROBE_BYTES });
   const format = fatalOnUnsupported(() => parseWav(head.bytes, stored.size));
   const segments = fatalOnUnsupported(() => planSegments(format));
   const durationMs = segments.at(-1)?.endMs ?? 0;
 
-  await report(
+  await stepReport(
     `Split ${formatDuration(durationMs)} of audio into ${segments.length} ${plural(segments.length, "segment")}.`,
   );
   return { format, segments, durationMs };
@@ -345,12 +345,14 @@ 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 ${formatDuration(segment.startMs)}–${formatDuration(segment.endMs)}.`);
+  await stepReport(
+    `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
   // get wrong.
-  const audio = await readUpload(uploadId, { start: segment.start, end: segment.end });
+  const audio = await stepReadUpload(uploadId, { start: segment.start, end: segment.end });
 
   // The audio and nothing else. A `config` part carrying `language_code` used
   // to ride along, and it is gone with the picker that fed it: the model detects
@@ -401,15 +403,15 @@ export async function transcribeSegment(
   );
   // 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(
+  await stepReport(
     `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.
-  // Its own namespace because `report`'s stream carries sentences a page prints
-  // verbatim — see `emit`'s doc.
-  await emit(TRANSCRIPT_STREAM, {
+  // Its own namespace because `stepReport`'s stream carries sentences a page prints
+  // verbatim — see `stepEmit`'s doc.
+  await stepEmit(TRANSCRIPT_STREAM, {
     index: segment.index,
     startMs: segment.startMs,
     endMs: segment.endMs,
@@ -422,7 +424,7 @@ export async function transcribeSegment(
  * Stitch the segments into one transcript.
  *
  * A step rather than a pure call in the body, and the reason is the narration:
- * the body replays from the top on every resume, so a `report()` written there
+ * the body replays from the top on every resume, so a `stepReport()` written there
  * is re-emitted on each one. Journaling the finished transcript also means a
  * caller re-reading a completed run gets the same bytes rather than a value
  * recomputed from parts.
@@ -433,7 +435,7 @@ export async function mergeTranscript(
   parts: readonly SegmentTranscript[],
   startedAt: number,
 ): Promise<Transcript> {
-  await report(`Stitching ${parts.length} ${plural(parts.length, "segment")} together.`);
+  await stepReport(`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
@@ -443,7 +445,7 @@ export async function mergeTranscript(
 
   // The FILENAME, not the id: the page prints this, and `upl_9f3…` tells a
   // reader nothing about which recording they are looking at.
-  const source = (await uploadInfo(uploadId)).name || uploadId;
+  const source = (await stepUploadInfo(uploadId)).name || uploadId;
   return {
     source,
     segments: parts.length,
@@ -457,19 +459,6 @@ export async function mergeTranscript(
   };
 }
 
-// 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 {
-  stitchChunks,
-  stitchTranscript,
-  TRANSCRIPT_STREAM,
-  type TranscriptChunk,
-} from "./stitch.ts";
-
 // ---- I/O helpers ------------------------------------------------------------
 
 /**

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

@@ -30,11 +30,11 @@
  */
 import agentDef from "virtual:aai/agent";
 import {
-  callsIn,
   describeTurn,
   type EvalSession,
   type EvalToolCall,
   lastStateIn,
+  toolCallsInTurns,
   toolNames,
   turnCalling,
 } from "@alexkroman1/aai-runtime/eval";
@@ -116,7 +116,7 @@ describeEval(agentDef, (test) => {
       // every turn's tool list AND tells the two findings apart: no
       // `update_ticket` at all, or calls that were all refused by the desk gate.
       const staging = turnCalling(turns, "update_ticket", stagedSomething);
-      const attempts = callsIn(turns).filter((call) => call.name === "update_ticket");
+      const attempts = toolCallsInTurns(turns).filter((call) => call.name === "update_ticket");
       // The staging call itself, by INDEX, because what follows it in the same
       // turn is the subject of the assertion below.
       const stagedAt = staging.toolCalls.findIndex(

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

@@ -1,7 +1,12 @@
 /** The def a DEPLOYED agent runs: authored, plus what `tools/` declares. */
 import agentDef from "virtual:aai/agent";
 import type { ToolContext } from "@alexkroman1/aai";
-import { createToolContext, ok, okPosition, toolRunner } from "@alexkroman1/aai/testing";
+import {
+  createToolContext,
+  expectDialogOk,
+  expectToolOk,
+  toolRunner,
+} from "@alexkroman1/aai/testing";
 import { describe, expect, test } from "vitest";
 
 import {
@@ -196,11 +201,11 @@ describe("sensitive tools stage rather than act", () => {
     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`
+    // return value, so the applied sentence is under `result`. `expectDialogOk`
     // 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 }>(
+    const confirmed = expectDialogOk<{ applied: string; reference: string }>(
       await run("confirm_action", ctx),
     );
     expect(confirmed.result.applied).toContain("Harborview Suites");
@@ -225,7 +230,7 @@ describe("sensitive tools stage rather than act", () => {
     const ctx = makeCtx();
     await atDesk("flight", ctx);
     await run("update_ticket", { flightId: "LX54" }, ctx);
-    const dropped = okPosition<{ discarded: string }>(await run("cancel_action", ctx));
+    const dropped = expectDialogOk<{ discarded: string }>(await run("cancel_action", ctx));
     expect(dropped.result.discarded).toContain("LX54");
     expect(dropped.state).toBe("browsing");
 
@@ -291,9 +296,9 @@ describe("sensitive tools stage rather than act", () => {
     // 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
+    // `expectToolOk` is `expectDialogOk` 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));
+    const applied = expectToolOk<{ applied: string }>(await run("confirm_action", ctx));
     expect(applied.applied).toContain("LX52");
     expect(stateOf(ctx).bookings).toEqual([]);
 
@@ -368,7 +373,10 @@ describe("search tools", () => {
     const all = (await run("search_hotels", { city: "Boston" }, ctx)) as {
       hotels: { perNight: string }[];
     };
-    expect(all.hotels.map((h) => h.perNight)).toEqual(["$180", "$265", "$340"]);
+    // Always to the cent: `formatMoney` is one shape at every desk, where
+    // this template's own `toLocaleString` copy dropped `.00` on a round
+    // number and kept it on a price with change.
+    expect(all.hotels.map((h) => h.perNight)).toEqual(["$180.00", "$265.00", "$340.00"]);
 
     const cheap = (await run("search_hotels", { city: "Boston", maxPerNight: 200 }, ctx)) as {
       hotels: { name: string }[];

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

@@ -1,5 +1,5 @@
 import "@alexkroman1/aai-ui/styles.css";
-import { AutoScroll, client, useAgentState } from "@alexkroman1/aai-ui";
+import { AutoScroll, mountClient, useAgentState } from "@alexkroman1/aai-ui";
 import type { TripView } from "./shared.ts";
 import { SPECIALIST_IDS, SPECIALISTS, tripProjection } from "./shared.ts";
 
@@ -118,7 +118,7 @@ function ItinerarySidebar() {
   );
 }
 
-client({
+mountClient({
   name: "Swiss Air Concierge",
   sidebar: ItinerarySidebar,
   theme: {

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

@@ -47,6 +47,7 @@ import {
   type ToolContext,
   type ToolFailure,
 } from "@alexkroman1/aai";
+import { formatMoney, plural } from "@alexkroman1/aai/utils";
 
 // ─── The booking world ───────────────────────────────────────────────────────
 // Their notebook downloads a sqlite database of a real airline's schedule and
@@ -180,11 +181,6 @@ export const EXCURSIONS: Excursion[] = [
   { id: "E4", name: "Lake Zurich cruise", city: "Zurich", kind: "boat", price: 52 },
 ];
 
-/** `$1,234` — one money format, so a spoken price and a rendered one agree. */
-export function formatPrice(amount: number): string {
-  return `$${amount.toLocaleString("en-US")}`;
-}
-
 // ─── The dialog stack ────────────────────────────────────────────────────────
 
 export const SPECIALIST_IDS = ["flight", "hotel", "car_rental", "excursion"] as const;
@@ -504,24 +500,24 @@ export function describeAction(action: DeepReadonly<PendingAction>): string | To
     case "update_ticket": {
       const flight = FLIGHTS.find((f) => f.id === action.flightId);
       if (!flight) return { error: `No flight ${action.flightId} in the schedule.` };
-      return `move your ticket to ${flight.id}, ${flight.route}, departing ${flight.departs}, at ${formatPrice(flight.fare)}`;
+      return `move your ticket to ${flight.id}, ${flight.route}, departing ${flight.departs}, at ${formatMoney(flight.fare)}`;
     }
     case "cancel_ticket":
       return "cancel your ticket entirely";
     case "book_hotel": {
       const hotel = HOTELS.find((h) => h.id === action.hotelId);
       if (!hotel) return { error: `No hotel ${action.hotelId}.` };
-      return `book ${hotel.name} in ${hotel.area} for ${action.nights} night${action.nights === 1 ? "" : "s"}, ${formatPrice(hotel.pricePerNight * action.nights)} total`;
+      return `book ${hotel.name} in ${hotel.area} for ${action.nights} ${plural(action.nights, "night")}, ${formatMoney(hotel.pricePerNight * action.nights)} total`;
     }
     case "book_car": {
       const car = CAR_RENTALS.find((c) => c.id === action.carId);
       if (!car) return { error: `No car ${action.carId}.` };
-      return `reserve the ${car.tier} from ${car.vendor} for ${action.days} day${action.days === 1 ? "" : "s"}, ${formatPrice(car.pricePerDay * action.days)} total`;
+      return `reserve the ${car.tier} from ${car.vendor} for ${action.days} ${plural(action.days, "day")}, ${formatMoney(car.pricePerDay * action.days)} total`;
     }
     case "book_excursion": {
       const excursion = EXCURSIONS.find((e) => e.id === action.excursionId);
       if (!excursion) return { error: `No excursion ${action.excursionId}.` };
-      return `book ${excursion.name} at ${formatPrice(excursion.price)}`;
+      return `book ${excursion.name} at ${formatMoney(excursion.price)}`;
     }
     // Unreachable while `PendingAction` is exhausted above — and the arm a new
     // member of the union lands in until it has one of its own, which is a
@@ -627,11 +623,11 @@ export function applyPending(
       state.bookings.push({
         kind: "hotel",
         reference,
-        summary: `${hotel.name} (${hotel.area}), ${action.nights} night${action.nights === 1 ? "" : "s"}`,
+        summary: `${hotel.name} (${hotel.area}), ${action.nights} ${plural(action.nights, "night")}`,
         price,
       });
       note(state, `Hotel booked: ${hotel.name} — ${reference}`);
-      return { applied: `${hotel.name} booked, ${formatPrice(price)}.`, reference };
+      return { applied: `${hotel.name} booked, ${formatMoney(price)}.`, reference };
     }
     case "book_car": {
       const car = CAR_RENTALS.find((c) => c.id === action.carId);
@@ -640,12 +636,12 @@ export function applyPending(
       state.bookings.push({
         kind: "car",
         reference,
-        summary: `${car.vendor} ${car.tier}, ${action.days} day${action.days === 1 ? "" : "s"}`,
+        summary: `${car.vendor} ${car.tier}, ${action.days} ${plural(action.days, "day")}`,
         price,
       });
       note(state, `Car reserved: ${car.vendor} ${car.tier} — ${reference}`);
       return {
-        applied: `${car.tier} from ${car.vendor} reserved, ${formatPrice(price)}.`,
+        applied: `${car.tier} from ${car.vendor} reserved, ${formatMoney(price)}.`,
         reference,
       };
     }
@@ -659,7 +655,7 @@ export function applyPending(
         price: excursion.price,
       });
       note(state, `Excursion booked: ${excursion.name} — ${reference}`);
-      return { applied: `${excursion.name} booked, ${formatPrice(excursion.price)}.`, reference };
+      return { applied: `${excursion.name} booked, ${formatMoney(excursion.price)}.`, reference };
     }
     // Same as `describeAction`: unreachable today, and a refusal rather than a
     // silent no-op for whatever the union grows next.

package/dist/templates/travel-concierge/tools/lookup_booking.ts

@@ -1,4 +1,5 @@
-import { FLIGHTS, formatPrice, tripSlot } from "../shared.ts";
+import { formatMoney } from "@alexkroman1/aai/utils";
+import { FLIGHTS, tripSlot } from "../shared.ts";
 
 /**
  * Their `fetch_user_flight_information`, which the notebook runs ONCE and
@@ -22,13 +23,13 @@ export default tripSlot.tool({
               route: flight.route,
               departs: flight.departs,
               arrives: flight.arrives,
-              fare: formatPrice(flight.fare),
+              fare: formatMoney(flight.fare),
             }
           : null,
       bookings: trip.bookings.map((b) => ({
         reference: b.reference,
         what: b.summary,
-        price: formatPrice(b.price),
+        price: formatMoney(b.price),
       })),
     };
   },