@alexkroman1/aai-cli 13.3.0 → 14.0.0

package/dist/templates/retail/payment.ts

@@ -4,6 +4,7 @@
  */
 
 import { isToolFailure, type ToolFailure } from "@alexkroman1/aai";
+import { formatMoney } from "@alexkroman1/aai/utils";
 import { resolveOrder } from "./resolve.ts";
 import type { RetailState } from "./shared.ts";
 import { authenticatedUser, findPaymentMethod, isGiftCard, money } from "./store.ts";
@@ -53,13 +54,13 @@ export function planPayment(
   const amount = original.amount;
   if (isGiftCard(newMethod) && newMethod.balance < amount) {
     return {
-      error: `Gift card ${newMethodId}'s balance ($${newMethod.balance.toFixed(2)}) does not cover the $${amount.toFixed(2)} order total.`,
+      error: `Gift card ${newMethodId}'s balance (${formatMoney(newMethod.balance)}) does not cover the ${formatMoney(amount)} order total.`,
     };
   }
 
   return {
     readBack:
-      `charge order ${order.order_id} — $${amount.toFixed(2)} — to ${newMethodId} instead, ` +
+      `charge order ${order.order_id} — ${formatMoney(amount)} — to ${newMethodId} instead, ` +
       `refunding ${original.payment_method_id}`,
     orderId: order.order_id,
     newMethodId,
@@ -102,6 +103,6 @@ export function applyPayment(state: RetailState, plan: PaymentPlan) {
     amount: plan.amount,
     paid_with: plan.newMethodId,
     refunded_to: plan.oldMethodId,
-    message: `Order ${plan.orderId} is now charged to ${plan.newMethodId}, and $${plan.amount.toFixed(2)} is going back to ${plan.oldMethodId}.`,
+    message: `Order ${plan.orderId} is now charged to ${plan.newMethodId}, and ${formatMoney(plan.amount)} is going back to ${plan.oldMethodId}.`,
   };
 }

package/dist/templates/retail/pending.test.ts

@@ -1,6 +1,6 @@
 import type { ToolContext } from "@alexkroman1/aai";
 import { isToolFailure } from "@alexkroman1/aai";
-import { createToolContext, ok, okPosition } from "@alexkroman1/aai/testing";
+import { createToolContext, expectDialogOk, expectToolOk } from "@alexkroman1/aai/testing";
 import { describe, expect, test } from "vitest";
 import type { StagedResult } from "./pending.ts";
 import { retailSlot } from "./store.ts";
@@ -17,7 +17,7 @@ import transferToHumanAgents from "./tools/transfer_to_human_agents.ts";
  *  one delivered order (#W4316152), which is every shape these cases need. */
 async function aaravCtx(): Promise<ToolContext> {
   const ctx = createToolContext();
-  ok(await findUserIdByEmail.execute({ email: "aarav.anderson9752@example.com" }, ctx));
+  expectToolOk(await findUserIdByEmail.execute({ email: "aarav.anderson9752@example.com" }, ctx));
   return ctx;
 }
 
@@ -29,7 +29,7 @@ describe("staging", () => {
     const ctx = await aaravCtx();
     const before = structuredClone(retailSlot.get(ctx).store.orders["#W9300146"]);
 
-    const staged = okPosition<StagedResult>(await stageCancel(ctx));
+    const staged = expectDialogOk<StagedResult>(await stageCancel(ctx));
 
     expect(staged.state).toBe("serving.awaitingConfirmation");
     expect(staged.result.staged).toBe("cancel_pending_order");
@@ -43,7 +43,7 @@ describe("staging", () => {
 
   test("the readback names the order, the items, the amount and where the money goes", async () => {
     const ctx = await aaravCtx();
-    const staged = ok<StagedResult>(await stageCancel(ctx));
+    const staged = expectToolOk<StagedResult>(await stageCancel(ctx));
     expect(staged.read_back).toContain("#W9300146");
     expect(staged.read_back).toContain("153.23");
     expect(staged.read_back).toContain("gift_card_7245904");
@@ -52,14 +52,14 @@ describe("staging", () => {
 
   test("the result says out loud that nothing has happened", async () => {
     const ctx = await aaravCtx();
-    const staged = ok<StagedResult>(await stageCancel(ctx));
+    const staged = expectToolOk<StagedResult>(await stageCancel(ctx));
     expect(staged.message).toContain("NOTHING HAS CHANGED YET");
     expect(staged.message).toContain("confirm_change");
   });
 
   test("a second stage is refused, and the refusal names the one already waiting", async () => {
     const ctx = await aaravCtx();
-    ok(await stageCancel(ctx));
+    expectToolOk(await stageCancel(ctx));
 
     // A DIFFERENT change, so this is not a repeat of the first call.
     const second = await modifyUserAddress.execute(
@@ -89,9 +89,9 @@ describe("staging", () => {
 describe("confirming", () => {
   test("confirm_change applies the staged change and returns to helping", async () => {
     const ctx = await aaravCtx();
-    ok(await stageCancel(ctx));
+    expectToolOk(await stageCancel(ctx));
 
-    const done = okPosition<{ confirmed: string; status: string }>(
+    const done = expectDialogOk<{ confirmed: string; status: string }>(
       await confirmChange.execute({}, ctx),
     );
     expect(done.state).toBe("serving.helping");
@@ -114,8 +114,8 @@ describe("confirming", () => {
 
   test("confirming twice is refused — the second call has nothing staged", async () => {
     const ctx = await aaravCtx();
-    ok(await stageCancel(ctx));
-    ok(await confirmChange.execute({}, ctx));
+    expectToolOk(await stageCancel(ctx));
+    expectToolOk(await confirmChange.execute({}, ctx));
 
     const again = await confirmChange.execute({}, ctx);
     expect(isToolFailure(again)).toBe(true);
@@ -130,9 +130,9 @@ describe("confirming", () => {
 describe("cancelling a staged change", () => {
   test("cancel_change drops it, changes nothing, and frees the call", async () => {
     const ctx = await aaravCtx();
-    ok(await stageCancel(ctx));
+    expectToolOk(await stageCancel(ctx));
 
-    const dropped = okPosition<{ dropped: string | null; message: string }>(
+    const dropped = expectDialogOk<{ dropped: string | null; message: string }>(
       await cancelChange.execute({}, ctx),
     );
     expect(dropped.state).toBe("serving.helping");
@@ -144,12 +144,12 @@ describe("cancelling a staged change", () => {
 
   test("a corrected change can be staged straight after", async () => {
     const ctx = await aaravCtx();
-    ok(await stageCancel(ctx));
-    ok(await cancelChange.execute({}, ctx));
+    expectToolOk(await stageCancel(ctx));
+    expectToolOk(await cancelChange.execute({}, ctx));
 
     // The caller changed their mind about which order — the very thing
     // `cancel_change` exists for.
-    const restaged = ok<StagedResult>(
+    const restaged = expectToolOk<StagedResult>(
       await returnDeliveredOrderItems.execute(
         {
           order_id: "#W4316152",
@@ -166,9 +166,9 @@ describe("cancelling a staged change", () => {
 describe("what stays legal while a change waits", () => {
   test("a read is still answerable — 'what was the total again?'", async () => {
     const ctx = await aaravCtx();
-    ok(await stageCancel(ctx));
+    expectToolOk(await stageCancel(ctx));
     // `when: "serving"` matches both children, which is what makes this work.
-    const read = okPosition<{ order_id: string }>(
+    const read = expectDialogOk<{ order_id: string }>(
       await getOrderDetails.execute({ order_id: "#W9300146" }, ctx),
     );
     expect(read.result.order_id).toBe("#W9300146");
@@ -178,9 +178,9 @@ describe("what stays legal while a change waits", () => {
 
   test("a caller can still ask for a human, and everything refuses afterwards", async () => {
     const ctx = await aaravCtx();
-    ok(await stageCancel(ctx));
+    expectToolOk(await stageCancel(ctx));
 
-    const transferred = okPosition(
+    const transferred = expectDialogOk(
       await transferToHumanAgents.execute({ summary: "wants a human" }, ctx),
     );
     // `TRANSFERRED` is declared on the `serving` PARENT, which is what lets it

package/dist/templates/retail/store.test.ts

@@ -1,5 +1,5 @@
 import { isToolFailure, type ToolContext } from "@alexkroman1/aai";
-import { createToolContext, ok, okPosition } from "@alexkroman1/aai/testing";
+import { createToolContext, expectDialogOk, expectToolOk } from "@alexkroman1/aai/testing";
 import { describe, expect, test } from "vitest";
 import { z } from "zod";
 import {
@@ -237,16 +237,16 @@ describe("retailTool", () => {
   test("runs once the flow says serving", async () => {
     const ctx = makeCtx();
     serve(ctx);
-    expect(ok(await gated.execute({}, ctx))).toEqual({ ok: true });
+    expect(expectToolOk(await gated.execute({}, ctx))).toEqual({ ok: true });
   });
 
   test("the result carries the position the call landed in", async () => {
     const ctx = makeCtx();
     serve(ctx);
-    // `okPosition` rather than a cast to `{ instruction?: string }`: it keeps
+    // `expectDialogOk` rather than a cast to `{ instruction?: string }`: it keeps
     // the envelope this test is about, and a refusal fails here naming what the
     // flow said instead of reading `undefined` off a field nobody assigned.
-    const answered = okPosition<{ ok: boolean }>(await gated.execute({}, ctx));
+    const answered = expectDialogOk<{ ok: boolean }>(await gated.execute({}, ctx));
     expect(answered).toMatchObject({ state: "serving.helping", done: false });
     expect(answered.instruction).toMatch(/one identified customer/);
   });
@@ -307,7 +307,7 @@ describe("the call flow", () => {
       summary: () => "ran",
       execute: () => ({ ok: true }),
     });
-    expect(ok(await anywhere.execute({}, ctx))).toEqual({ ok: true });
+    expect(expectToolOk(await anywhere.execute({}, ctx))).toEqual({ ok: true });
 
     const at = callFlow.send(ctx, { type: "TRANSFERRED" });
     expect(at.state).toBe("transferred");

package/dist/templates/retail/swap.ts

@@ -7,6 +7,7 @@
  */
 
 import { isToolFailure, type ToolFailure } from "@alexkroman1/aai";
+import { formatMoney } from "@alexkroman1/aai/utils";
 import { resolveOrder } from "./resolve.ts";
 import type { Order, OrderItem, RetailState, User, Variant } from "./shared.ts";
 import {
@@ -48,7 +49,6 @@ export interface SwapLine {
   fromOptions: Record<string, string>;
   fromPrice: number;
   toItemId: string;
-  toName: string;
   toOptions: Record<string, string>;
   toPrice: number;
 }
@@ -146,9 +146,6 @@ export function toSwapLines(plan: SwapPlan): SwapLine[] {
     fromOptions: { ...pair.item.options },
     fromPrice: pair.item.price,
     toItemId: pair.newVariant.item_id,
-    // Same product by construction — a swap can only reach another option of
-    // it — so the name is the item's own and the OPTIONS are what differ.
-    toName: pair.item.name,
     toOptions: { ...pair.newVariant.options },
     toPrice: pair.newVariant.price,
   }));
@@ -163,7 +160,7 @@ export function assertCanCoverDiff(user: User, methodId: string, diff: number):
   if (isToolFailure(method)) return method;
   if (isGiftCard(method) && method.balance < diff) {
     return {
-      error: `Gift card ${methodId}'s balance ($${method.balance.toFixed(2)}) does not cover the $${diff.toFixed(2)} difference. Ask for another payment method.`,
+      error: `Gift card ${methodId}'s balance (${formatMoney(method.balance)}) does not cover the ${formatMoney(diff)} difference. Ask for another payment method.`,
     };
   }
   return null;
@@ -190,8 +187,8 @@ function describeLine(line: SwapLine): string {
 }
 
 function describeDiff(diff: number, methodId: string): string {
-  if (diff > 0) return `$${diff.toFixed(2)} charged to ${methodId}`;
-  if (diff < 0) return `$${Math.abs(diff).toFixed(2)} refunded to ${methodId}`;
+  if (diff > 0) return `${formatMoney(diff)} charged to ${methodId}`;
+  if (diff < 0) return `${formatMoney(Math.abs(diff))} refunded to ${methodId}`;
   return "no price difference";
 }
 
@@ -275,8 +272,8 @@ export function applyModifyItems(state: RetailState, plan: ModifyItemsPlan) {
     })),
     message:
       plan.diff > 0
-        ? `Done. $${plan.diff.toFixed(2)} was charged to ${plan.paymentMethodId}. This order can no longer be modified or cancelled.`
-        : `Done. $${Math.abs(plan.diff).toFixed(2)} is being refunded to ${plan.paymentMethodId}. This order can no longer be modified or cancelled.`,
+        ? `Done. ${formatMoney(plan.diff)} was charged to ${plan.paymentMethodId}. This order can no longer be modified or cancelled.`
+        : `Done. ${formatMoney(Math.abs(plan.diff))} is being refunded to ${plan.paymentMethodId}. This order can no longer be modified or cancelled.`,
   };
 }
 
@@ -358,7 +355,7 @@ export function applyExchange(state: RetailState, plan: ExchangePlan) {
     })),
     message:
       plan.diff > 0
-        ? `Exchange requested on ${plan.orderId}. $${plan.diff.toFixed(2)} will be charged to ${plan.paymentMethodId}. An email with return instructions is on its way.`
-        : `Exchange requested on ${plan.orderId}. $${Math.abs(plan.diff).toFixed(2)} will be refunded to ${plan.paymentMethodId}. An email with return instructions is on its way.`,
+        ? `Exchange requested on ${plan.orderId}. ${formatMoney(plan.diff)} will be charged to ${plan.paymentMethodId}. An email with return instructions is on its way.`
+        : `Exchange requested on ${plan.orderId}. ${formatMoney(Math.abs(plan.diff))} will be refunded to ${plan.paymentMethodId}. An email with return instructions is on its way.`,
   };
 }

package/dist/templates/solo-rpg/agent.eval.test.ts

@@ -33,7 +33,7 @@
  * deployed.
  */
 import agentDef from "virtual:aai/agent";
-import { type EvalTurn, toolResultIn } from "@alexkroman1/aai-runtime/eval";
+import { type EvalTurn, toolResultIn, toolResultsIn } from "@alexkroman1/aai-runtime/eval";
 import { describeEval } from "@alexkroman1/aai-runtime/eval/vitest";
 import { expect } from "vitest";
 import { z } from "zod";
@@ -82,20 +82,6 @@ const Refusal = z.object({ error: z.string() });
 const answerOf = <T>(turn: EvalTurn, name: string, schema: z.ZodType<T>): T =>
   toolResultIn(turn.toolCalls, name, schema);
 
-/**
- * What EVERY call to `name` answered on this turn, in call order.
- *
- * The plural form is for a claim about calls that may legitimately not have
- * happened — a refusal the narrator may have pre-empted by not calling at all.
- * `toolResultIn` over a ONE-CALL list per call: the name is that call's own, so
- * the reader's "no such call" and "two calls" throws are unreachable and what
- * is left is the parse, the schema, and the "never completed" failure.
- */
-const answersOf = <T>(turn: EvalTurn, name: string, schema: z.ZodType<T>): T[] =>
-  turn.toolCalls
-    .filter((c) => c.name === name)
-    .map((call) => toolResultIn([call], call.name, schema));
-
 /**
  * Every field `setup_character` requires, for the SCRIPTED runs.
  *
@@ -267,7 +253,7 @@ describeEval(agentDef, (test) => {
       expect(answerOf(down, "update_state", Settled).state).toBe("gameOver");
 
       const after = await session.say("I refuse to die. Roll to fight on.");
-      const attempts = answersOf(after, "action_roll", Refusal);
+      const attempts = toolResultsIn(after.toolCalls, "action_roll", Refusal);
       // The gate is only OBSERVABLE if something calls the gated tool, and the
       // script is what guarantees that — hence the exact count. `gameOver` was
       // once a flag nothing acted on, so a player with both tracks empty could

package/dist/templates/solo-rpg/agent.test.ts

@@ -1,6 +1,6 @@
 import type { ToolContext, ToolDef, ToolInputSchema } from "@alexkroman1/aai";
 import { isToolFailure } from "@alexkroman1/aai";
-import { createToolContext, ok } from "@alexkroman1/aai/testing";
+import { createToolContext, expectToolOk } from "@alexkroman1/aai/testing";
 import { describe, expect, test, vi } from "vitest";
 import {
   applyConsequences,
@@ -24,11 +24,11 @@ import updateState from "./tools/update_state.ts";
 
 // ── Test doubles ─────────────────────────────────────────────────────────────
 
-/** `send` is a spy rather than the recorder `createToolContext` installs,
- *  because this suite asserts call counts on it. Each call gets its own slot
- *  store, which is what makes two contexts two games. */
+/** Each call gets its own slot store, which is what makes two contexts two
+ *  games. `send` is the recorder `createToolContext` installs — no test here
+ *  asserts on it, and overriding it would only throw the recording away. */
 function makeCtx(): ToolContext {
-  return createToolContext({ send: vi.fn() });
+  return createToolContext();
 }
 
 const SETUP_ARGS = {
@@ -288,7 +288,7 @@ describe("burn_momentum", () => {
     const ctx = makeCtx();
     seedRolledState(8, ctx); // 8 beats both dice (3, 5)
 
-    const result = ok<Record<string, unknown>>(await callNoArgs(burnMomentum, ctx));
+    const result = expectToolOk<Record<string, unknown>>(await callNoArgs(burnMomentum, ctx));
     expect(result.burned).toBe(true);
     expect(result.newResultCode).toBe("STRONG_HIT");
 
@@ -302,7 +302,7 @@ describe("burn_momentum", () => {
   test("momentum beating only one die upgrades a MISS to WEAK_HIT", async () => {
     const ctx = makeCtx();
     seedRolledState(4, ctx); // beats 3, not 5
-    const result = ok<{ newResultCode: string }>(await callNoArgs(burnMomentum, ctx));
+    const result = expectToolOk<{ newResultCode: string }>(await callNoArgs(burnMomentum, ctx));
     expect(result.newResultCode).toBe("WEAK_HIT");
   });
 
@@ -528,7 +528,7 @@ describe("update_state", () => {
     state.clocks[0]!.filled = 3; // 3 of 4
     seedPlaying(ctx, state);
 
-    const result = ok<{ clockEvents: { clock: string; trigger: string }[] }>(
+    const result = expectToolOk<{ clockEvents: { clock: string; trigger: string }[] }>(
       await updateState.execute({ advanceClockName: "Doom" }, ctx),
     );
     expect(result.clockEvents).toEqual([{ clock: "Doom", trigger: "The doom arrives" }]);
@@ -542,7 +542,7 @@ describe("update_state", () => {
     }
     seedPlaying(ctx, state);
 
-    const result = ok<{ warnings?: string[] }>(
+    const result = expectToolOk<{ warnings?: string[] }>(
       await updateState.execute({ addNpcName: "One Too Many" }, ctx),
     );
     expect(result.warnings?.[0]).toMatch(/NPC limit/);
@@ -609,7 +609,7 @@ describe("the story flow", () => {
     expect(created.state).toBe("playing.awaitingRoll");
     expect(created.instruction).toMatch(/action_roll/);
 
-    ok(
+    expectToolOk(
       await actionRoll.execute(
         { move: "clash", stat: "iron", position: "risky", effect: "standard", purpose: "swing" },
         ctx,
@@ -618,7 +618,7 @@ describe("the story flow", () => {
     expect(storyFlow.position(ctx).state).toBe("playing.rollResolved");
 
     // Moving the scene on SPENDS the roll: the burn window is closed.
-    ok(await updateState.execute({ location: "The Bridge" }, ctx));
+    expectToolOk(await updateState.execute({ location: "The Bridge" }, ctx));
     expect(storyFlow.position(ctx).state).toBe("playing.awaitingRoll");
     expect(isToolFailure(await callNoArgs(burnMomentum, ctx))).toBe(true);
   });
@@ -644,7 +644,7 @@ describe("the story flow", () => {
     // act on it, so a player could keep rolling after both tracks emptied. The
     // WRITE is `gameSlot`'s `after` hook; this tool no longer calls it, which
     // is the point of moving it there.
-    ok(await updateState.execute({ health: 0, spirit: 0 }, ctx));
+    expectToolOk(await updateState.execute({ health: 0, spirit: 0 }, ctx));
     const at = storyFlow.position(ctx);
     expect(at.state).toBe("gameOver");
     expect(at.done).toBe(true);

package/dist/templates/solo-rpg/client.tsx

@@ -1,6 +1,6 @@
 import "@alexkroman1/aai-ui/styles.css";
 import type { DeepReadonly } from "@alexkroman1/aai";
-import { client, useAgentState } from "@alexkroman1/aai-ui";
+import { mountClient, useAgentState } from "@alexkroman1/aai-ui";
 import type { ReactNode } from "react";
 import {
   type Clock,
@@ -782,7 +782,7 @@ function Sidebar() {
 
 // ── App ──────────────────────────────────────────────────────────────────────
 
-client({
+mountClient({
   name: "Solo RPG",
   icon: (
     <span style={{ fontSize: "28px", color: C.accent }}>
@@ -805,7 +805,7 @@ client({
 });
 
 // No `onSessionId`/`resumeSessionId` here any more, and their removal is a FIX
-// rather than a simplification. `createSessionCore` remembers the id in
+// rather than a simplification. `createBrowserSession` remembers the id in
 // `sessionStorage` by default now — see `session-resume-store.ts`, whose doc
 // names this template as the one client of fourteen that had wired it by hand.
 // What it had wired was `localStorage`, which is the wrong store for a pointer

package/dist/templates/spoken-summary/agent.test.ts

@@ -17,9 +17,9 @@
  * its return value, and audio in one is megabytes replayed on every resume.
  */
 
-import { readUpload, uploadInfo } from "@alexkroman1/aai/step";
+import { stepReadUpload, stepUploadInfo } from "@alexkroman1/aai/step";
 import { FatalError, RetryableError } from "@alexkroman1/aai/step-errors";
-import { createWorkflowCtx, stubGatewayRoute } from "@alexkroman1/aai/testing";
+import { createWorkflowContext, stubGatewayRoute } from "@alexkroman1/aai/testing";
 import {
   installStubGateway,
   installStubReporter,
@@ -215,14 +215,14 @@ describe("speaking", () => {
 
     const { audio } = await speak("Hello.");
 
-    await expect(uploadInfo(audio)).resolves.toMatchObject({
+    await expect(stepUploadInfo(audio)).resolves.toMatchObject({
       name: "summary.wav",
       // The byte route serves this as `Content-Type`, and a browser will not
       // play inline a file it was handed as octet-stream.
       type: "audio/wav",
       size: 44 + 4000,
     });
-    const { bytes } = await readUpload(audio, { end: 12 });
+    const { bytes } = await stepReadUpload(audio, { end: 12 });
     expect(String.fromCharCode(...bytes.subarray(0, 4))).toBe("RIFF");
     expect(String.fromCharCode(...bytes.subarray(8, 12))).toBe("WAVE");
   });
@@ -292,7 +292,7 @@ describe("the whole run", () => {
     installStubReporter();
     installStubSpeech();
 
-    const summary = await spokenSummaryFlow({ recording: UPLOAD_ID }, createWorkflowCtx());
+    const summary = await spokenSummaryFlow({ recording: UPLOAD_ID }, createWorkflowContext());
 
     expect(summary).toEqual({
       source: "standup.wav",
@@ -314,7 +314,7 @@ describe("the whole run", () => {
     installStubReporter();
     const speech = installStubSpeech();
 
-    await spokenSummaryFlow({ recording: UPLOAD_ID, voice: "michael" }, createWorkflowCtx());
+    await spokenSummaryFlow({ recording: UPLOAD_ID, voice: "michael" }, createWorkflowContext());
 
     expect(speech.calls[0]).toMatchObject({ text: "Spoken.", voice: "michael" });
   });
@@ -324,9 +324,9 @@ describe("the whole run", () => {
     installStubReporter();
     installStubSpeech();
 
-    await expect(spokenSummaryFlow({ recording: UPLOAD_ID }, createWorkflowCtx())).rejects.toThrow(
-      "corrupt audio",
-    );
+    await expect(
+      spokenSummaryFlow({ recording: UPLOAD_ID }, createWorkflowContext()),
+    ).rejects.toThrow("corrupt audio");
   });
 });
 

package/dist/templates/spoken-summary/agent.ts

@@ -24,7 +24,7 @@
  *   event stream wired into a live pipeline's playback, with a turn tracker and
  *   barge-in behind it, and a step has no turn to be part of and has to return
  *   a VALUE.
- * - **`writeUpload`** (same subpath) puts that value where a browser can reach
+ * - **`stepWriteUpload`** (same subpath) puts that value where a browser can reach
  *   it. A run's OUTPUT is read back as JSON, so audio cannot travel in one —
  *   the same rule that keeps a recording's bytes out of a run's INPUT, arriving
  *   at the other end of the run.
@@ -54,7 +54,7 @@
  * `POST /workflows/uploads` (the browser does this for you: `uploads` below is
  * what makes `<WorkflowFields>` render a file picker, and `useWorkflowSubmit`
  * stores the file before starting the run), the input carries the returned id,
- * and the step that needs the bytes streams them out with `readUpload`.
+ * and the step that needs the bytes streams them out with `stepReadUpload`.
  *
  * ## It is scriptable, which is the other half of having an API
  *
@@ -140,7 +140,7 @@ export const spokenSummary: WorkflowDef<typeof spokenSummaryInput, SpokenSummary
   input: spokenSummaryInput,
   // The one line that makes the form take a file: `<WorkflowFields>` renders a
   // picker for this property, `useWorkflowSubmit` stores the chosen file, and
-  // the step that transcribes it reads it back with `readUpload`.
+  // the step that transcribes it reads it back with `stepReadUpload`.
   uploads: ["recording"],
   run: spokenSummaryFlow,
 });

package/dist/templates/spoken-summary/client.tsx

@@ -69,9 +69,11 @@ import "@alexkroman1/aai-ui/styles.css";
 // `workflows/summarize.ts` already declares.
 import { formatDuration } from "@alexkroman1/aai/utils";
 import {
+  BulletList,
   createWorkflowApi,
+  Facts,
   Form,
-  page,
+  mountPage,
   SubmitButton,
   UploadProgressBar,
   useDownloadUrl,
@@ -79,7 +81,6 @@ import {
   WorkflowFields,
   WorkflowProgress,
 } from "@alexkroman1/aai-ui";
-import { useState } from "react";
 import type { spokenSummary } from "./agent.ts";
 
 /**
@@ -128,16 +129,11 @@ function captionsUrl(text: string, durationMs: number): string {
 }
 
 export function App() {
-  // Did THIS load start the run? A reload cannot have, and that is the only way
-  // the page can tell "working on what you just sent" from "picking up where
-  // you left off" — the hook reports the run, not who asked for it.
-  const [startedHere, setStartedHere] = useState(false);
   // The generic is what makes `run.status === "completed"` narrow to a TYPED
   // `run.output` instead of `unknown`. The reload is the hook's own doing — see
   // the module doc for why the key it mints is the right one for this page.
-  const { submitForm, run, pending, upload, pauseUpload, resumeUpload, error } = useWorkflowSubmit<
-    typeof spokenSummary
-  >(WORKFLOW, { api });
+  const { submitForm, run, pending, upload, pauseUpload, resumeUpload, error, startedHere } =
+    useWorkflowSubmit<typeof spokenSummary>(WORKFLOW, { api });
   const output = run?.status === "completed" ? run.output : undefined;
   // `useDownloadUrl` is the SDK's: the byte route takes the agent's bearer, so the
   // bytes have to be FETCHED and handed to the element as an object URL — and the
@@ -153,14 +149,7 @@ export function App() {
         </p>
       </header>
 
-      <Form
-        onSubmit={(values) => {
-          setStartedHere(true);
-          return submitForm(values);
-        }}
-        error={error}
-        className="flex flex-col gap-4"
-      >
+      <Form onSubmit={(values) => submitForm(values)} error={error} className="flex flex-col gap-4">
         {/* Every control, from the workflow's own input schema. See the module doc. */}
         <WorkflowFields workflow={WORKFLOW} />
         <SubmitButton pending={pending} pendingLabel="Working…">
@@ -180,25 +169,27 @@ export function App() {
           nothing for `<WorkflowProgress>` to read. */}
       <UploadProgressBar upload={upload} onPause={pauseUpload} onResume={resumeUpload} />
 
-      {/* What the run itself says, from `report()` in the workflow's steps. */}
+      {/* What the run itself says, from `stepReport()` in the workflow's steps. */}
       <WorkflowProgress runId={run?.runId} api={api} />
 
-      {run?.status === "failed" && <p className="text-red-600">That one failed: {run.error}</p>}
+      {/* `role="alert"`, the same contract `<Form>` gives the submit error: this
+          is the outcome the reader waited minutes for. */}
+      {run?.status === "failed" && (
+        <p role="alert" className="text-red-600">
+          That one failed: {run.error}
+        </p>
+      )}
 
       {output !== undefined && (
         <article className="flex flex-col gap-5">
           <div className="flex flex-col gap-1">
             <h2 className="text-xl">{output.headline}</h2>
-            <p className="text-sm opacity-70">
-              {output.source} · {formatDuration(output.durationMs)} · {output.words} words
-            </p>
+            <Facts
+              items={[output.source, formatDuration(output.durationMs), `${output.words} words`]}
+            />
           </div>
 
-          <ul className="flex list-disc flex-col gap-1 pl-5">
-            {output.points.map((point) => (
-              <li key={point}>{point}</li>
-            ))}
-          </ul>
+          <BulletList items={output.points} />
 
           <section className="flex flex-col gap-2">
             <h3 className="text-sm font-medium opacity-70">
@@ -206,11 +197,13 @@ export function App() {
             </h3>
             {audio.pending && <p className="text-sm opacity-70">Fetching the audio…</p>}
             {audio.error !== undefined && (
-              <p className="text-red-600">Could not load the audio: {audio.error}</p>
+              <p role="alert" className="text-red-600">
+                Could not load the audio: {audio.error}
+              </p>
             )}
             {audio.url !== undefined && (
               <>
-                <audio controls src={audio.url} className="w-full">
+                <audio aria-label="Summary read aloud" controls src={audio.url} className="w-full">
                   {/* A real caption track, not a suppression: the summary was
                       written before it was spoken, so the words are already
                       here and one cue spanning the clip is an honest
@@ -244,4 +237,4 @@ export function App() {
   );
 }
 
-page({ name: "Spoken Summary", component: App });
+mountPage({ name: "Spoken Summary", component: App });