@alexkroman1/aai-cli 13.3.0 → 14.0.0

package/dist/templates/recap-workflow/agent.test.ts

@@ -33,7 +33,7 @@
  * **The branch this file used to name as its biggest gap no longer exists.** It
  * was `recapFlow`'s `if (isWorkflowSuspend(err)) throw err;` — the guard whose
  * absence had once deleted the transcript the run was waiting for — and it was
- * unpinnable here by construction, since `createWorkflowCtx`'s `sleep` is
+ * unpinnable here by construction, since `createWorkflowContext`'s `sleep` is
  * RECORDED and its `waitFor` answers out of `hooks`, so no wait it serves ever
  * suspended. A wait now hands the body a promise that never settles, so a
  * suspension cannot reach a `catch` at all and there is no branch left to test:
@@ -47,7 +47,7 @@ import type { WorkflowClient } from "@alexkroman1/aai";
 import {
   createRunSnapshot,
   createToolContext,
-  createWorkflowCtx,
+  createWorkflowContext,
   parseSchemaInput,
   schemaInputIssues,
   stubGatewayRoute,
@@ -55,7 +55,7 @@ import {
 } from "@alexkroman1/aai/testing";
 import {
   installStubStepFetch,
-  mockWorkflows,
+  installStubWorkflows,
   installStubGateway as stubGateway,
 } from "@alexkroman1/aai/testing/vitest";
 import type { WorkflowRunSnapshot } from "@alexkroman1/aai/workflow-api";
@@ -89,14 +89,14 @@ const run = toolRunner(agentDef);
 /**
  * A `ctx.workflows` that records `start` and answers the lookups from a fixture.
  *
- * `mockWorkflows` (`@alexkroman1/aai/testing/vitest`) is the whole thing — a
+ * `installStubWorkflows` (`@alexkroman1/aai/testing/vitest`) is the whole thing — a
  * `vi.fn` per method over one `runs` list, with `stream`/`streamTail` left
  * rejecting because `recap_progress` reads progress through `lastLine` and
  * composing those two by hand is the hazard `lastLine` exists to remove. What
  * is local is only which workflow this desk declares.
  */
 function stubWorkflows(runs: WorkflowRunSnapshot[] = []): WorkflowClient {
-  return mockWorkflows({ runs, names: ["recap"] });
+  return installStubWorkflows({ runs, names: ["recap"] });
 }
 
 /** A finished recap, as the workflow's output reaches the tools. */
@@ -399,7 +399,7 @@ describe("cancel_recap", () => {
  *
  * Published into `stepFetch`'s OWN slot, not over `globalThis.fetch`. Every
  * request in this file goes through `stepFetch` — `request()` and
- * `discardTranscript` reach it directly, `stepTranscribeSubmitClassified`
+ * `discardTranscript` reach it directly, `stepTranscribeSubmitOrFail`
  * through the SDK — and `step-fetch.ts` falls back to `globalThis.fetch` only
  * when nothing is published. A global stub therefore passed while exercising a
  * path production never takes; every sibling template already stubs the slot,
@@ -686,7 +686,7 @@ describe("summarize", () => {
     // The policy is an argument to `ctx.step` now, so it is observable only at
     // the call. `runSteps: false` and a skeleton of results: the subject is what
     // the body ASKED FOR.
-    const ctx = createWorkflowCtx({
+    const ctx = createWorkflowContext({
       runSteps: false,
       results: {
         submitRecording: { id: "t_1" },
@@ -724,7 +724,7 @@ describe("awaitTranscript — the polling port, and the callback over it", () =>
       { status: "processing" },
       { status: "completed", text: "Done.", audio_duration: 60 },
     ]);
-    const state = await awaitTranscript("t_1", createWorkflowCtx());
+    const state = await awaitTranscript("t_1", createWorkflowContext());
     expect(state).toMatchObject({ status: "completed", text: "Done." });
     expect(polls()).toBe(3);
   });
@@ -733,13 +733,15 @@ describe("awaitTranscript — the polling port, and the callback over it", () =>
     // `error` is terminal: polling a failed job to the bound would spend twenty
     // minutes learning what the first answer already said.
     const polls = stubStatuses([{ status: "error", error: "Transcoding failed" }]);
-    await expect(awaitTranscript("t_1", createWorkflowCtx())).rejects.toThrow(/Transcoding failed/);
+    await expect(awaitTranscript("t_1", createWorkflowContext())).rejects.toThrow(
+      /Transcoding failed/,
+    );
     expect(polls()).toBe(1);
   });
 
   test("gives up at the bound rather than polling a stuck job forever", async () => {
     stubStatuses([{ status: "processing" }]);
-    await expect(awaitTranscript("t_1", createWorkflowCtx())).rejects.toThrow(/Gave up/);
+    await expect(awaitTranscript("t_1", createWorkflowContext())).rejects.toThrow(/Gave up/);
   });
 
   /** A job still `processing` for `polls` turns, then completed. */
@@ -758,7 +760,7 @@ describe("awaitTranscript — the polling port, and the callback over it", () =>
     // the constant promises is eight sleeps, so the earliest honest turn to say
     // it is the ninth. Here the job finishes on that ninth poll, two minutes in
     // and not a second over, so the caller is told nothing.
-    const ctx = createWorkflowCtx();
+    const ctx = createWorkflowContext();
     stubSlowJob(8);
 
     await awaitTranscript("t_1", ctx);
@@ -773,7 +775,7 @@ describe("awaitTranscript — the polling port, and the callback over it", () =>
     // two minutes of waiting behind it — so the note goes out, and the eleven
     // polls after it say nothing more. A note per poll would be a caller told
     // the same sentence every fifteen seconds.
-    const ctx = createWorkflowCtx();
+    const ctx = createWorkflowContext();
     stubSlowJob(20);
 
     await awaitTranscript("t_1", ctx);
@@ -788,7 +790,7 @@ describe("awaitTranscript — the polling port, and the callback over it", () =>
   // cases are the REGRESSION guard for this section: the poll-only arm has to
   // keep behaving exactly as it did before there was a callback at all.
   //
-  // `createWorkflowCtx` is the only tier that can drive the answered branch:
+  // `createWorkflowContext` is the only tier that can drive the answered branch:
   // its `waitFor` reads `hooks` by token, so supplying a payload IS the delivery
   // landing and omitting one IS the window closing. The eval tier cannot —
   // nothing there can signal — so it only ever sees the fallback, which is
@@ -806,7 +808,7 @@ describe("awaitTranscript — the polling port, and the callback over it", () =>
       { status: "processing" },
       { status: "completed", text: "Done.", audio_duration: 60 },
     ]);
-    const ctx = createWorkflowCtx({
+    const ctx = createWorkflowContext({
       hooks: { [NUDGE]: { transcript_id: "t_1", status: "completed" } },
     });
 
@@ -831,7 +833,7 @@ describe("awaitTranscript — the polling port, and the callback over it", () =>
       { status: "processing" },
       { status: "completed", text: "The real transcript.", audio_duration: 60 },
     ]);
-    const ctx = createWorkflowCtx({
+    const ctx = createWorkflowContext({
       hooks: { [NUDGE]: { transcript_id: "t_1", status: "completed", text: "A LIE." } },
     });
 
@@ -850,7 +852,7 @@ describe("awaitTranscript — the polling port, and the callback over it", () =>
     // read as a failed run and answer by deleting the transcript. So the wait
     // may not be inside the loop, and this is what pins that: twenty turns, ONE
     // `waitFor`, and every other wait a plain sleep.
-    const ctx = createWorkflowCtx({ hooks: { [NUDGE]: {} } });
+    const ctx = createWorkflowContext({ hooks: { [NUDGE]: {} } });
     stubSlowJob(20);
 
     await awaitTranscript("t_1", ctx, NUDGE);
@@ -869,7 +871,7 @@ describe("awaitTranscript — the polling port, and the callback over it", () =>
       { status: "processing" },
       { status: "completed", text: "Done.", audio_duration: 60 },
     ]);
-    const ctx = createWorkflowCtx();
+    const ctx = createWorkflowContext();
 
     const state = await awaitTranscript("t_1", ctx, NUDGE);
 
@@ -885,7 +887,7 @@ describe("awaitTranscript — the polling port, and the callback over it", () =>
     // window — so whichever arm a run is on, a caller hears the sentence at the
     // same point. The note goes out at the TOP of a poll, so attempt 2 is the
     // first turn with a whole closed window behind it.
-    const ctx = createWorkflowCtx();
+    const ctx = createWorkflowContext();
     stubSlowJob(20);
 
     await awaitTranscript("t_1", ctx, NUDGE);
@@ -904,7 +906,7 @@ describe("awaitTranscript — the polling port, and the callback over it", () =>
     // The mirror of the case above, and what stops the note being a thing every
     // callback run says: the delivery lands, attempt 2 finds the job done, and
     // nobody is told a recording is a long one.
-    const ctx = createWorkflowCtx({ hooks: { [NUDGE]: {} } });
+    const ctx = createWorkflowContext({ hooks: { [NUDGE]: {} } });
     stubSlowJob(1);
 
     await awaitTranscript("t_1", ctx, NUDGE);
@@ -930,7 +932,9 @@ describe("askWhetherToKeep — the expense port", () => {
    * What is pinned is unchanged: the three outcomes and the safe default.
    */
   const gateCtx = (answer?: { keep: boolean }) =>
-    createWorkflowCtx(answer === undefined ? {} : { hooks: { [retentionToken("s_1")]: answer } });
+    createWorkflowContext(
+      answer === undefined ? {} : { hooks: { [retentionToken("s_1")]: answer } },
+    );
 
   test("keeps the transcript when the caller says to, and deletes nothing", async () => {
     const provider = installStubStepFetch();
@@ -1002,7 +1006,7 @@ describe("compensate — the saga port", () => {
         { label: "first", undo: async () => void order.push("first") },
       ],
       "because",
-      createWorkflowCtx(),
+      createWorkflowContext(),
     );
     expect(order).toEqual(["second", "first"]);
   });
@@ -1024,7 +1028,7 @@ describe("compensate — the saga port", () => {
           { label: "fine", undo: async () => void order.push("fine") },
         ],
         "because",
-        createWorkflowCtx(),
+        createWorkflowContext(),
       ),
     ).resolves.toBeUndefined();
     expect(order).toEqual(["fine"]);
@@ -1035,7 +1039,7 @@ describe("compensate — the saga port", () => {
     // run that narrated an unwind it did not perform would be lying to the
     // caller reading its progress.
     await expect(
-      compensate([], "nothing was acquired", createWorkflowCtx()),
+      compensate([], "nothing was acquired", createWorkflowContext()),
     ).resolves.toBeUndefined();
   });
 });

package/dist/templates/recap-workflow/workflows/recap.ts

@@ -99,7 +99,7 @@
  * Everything the desk claims to do. `submitRecording`, `checkTranscript` and
  * `discardTranscript` are AssemblyAI's pre-recorded API (`POST`, `GET` and
  * `DELETE` on `/v2/transcript`), and `summarize` is a real model call through
- * `stepGenerateJsonClassified`. The BATCH API is what makes the polling port honest: it
+ * `stepGenerateJsonOrFail`. The BATCH API is what makes the polling port honest: it
  * answers with a job id in milliseconds and finishes minutes later, so the wait
  * is the provider's, not a `setTimeout` this template chose. (Its sibling
  * `transcription-workflow` takes the other endpoint — the sync one, which answers in
@@ -111,13 +111,13 @@
  * just your shell.
  */
 
-import type { WorkflowCtx } from "@alexkroman1/aai";
-import { report, requireStepEnv, stepFetch, stepWebhookUrl } from "@alexkroman1/aai/step";
+import type { WorkflowContext } from "@alexkroman1/aai";
+import { requireStepEnv, stepFetch, stepReport, stepWebhookUrl } from "@alexkroman1/aai/step";
 import {
   FatalError,
-  stepFetchOk,
-  stepGenerateJsonClassified,
-  stepTranscribeSubmitClassified,
+  stepFetchOrFail,
+  stepGenerateJsonOrFail,
+  stepTranscribeSubmitOrFail,
   toStepError,
 } from "@alexkroman1/aai/step-errors";
 import { errorMessage, omitUndefined } from "@alexkroman1/aai/utils";
@@ -239,7 +239,7 @@ const POINTS = 3;
 /**
  * The shape the model must answer in.
  *
- * `stepGenerateJsonClassified` validates against this and throws PLAINLY when the reply
+ * `stepGenerateJsonOrFail` validates against this and throws PLAINLY when the reply
  * misses, which is the retry policy in one distinction: a model that answered in
  * prose may answer correctly next time, where a 401 will not. `spoken` is the
  * field this template exists for — without it the announced turn has nothing to
@@ -347,7 +347,7 @@ export type Compensation = { label: string; undo: () => Promise<void> };
  * `agent.ts` reads back down the phone, so it is shaped for an ear rather than
  * a page.
  */
-export async function recapFlow(input: { url: string; requestedBy: string }, ctx: WorkflowCtx) {
+export async function recapFlow(input: { url: string; requestedBy: string }, ctx: WorkflowContext) {
   // The compensation stack, newest first — `unshift` after each successful
   // acquisition, exactly as Temporal's `openAccount` does. Registering the undo
   // AFTER the step it undoes is the whole discipline: a step that never
@@ -462,7 +462,7 @@ export async function recapFlow(input: { url: string; requestedBy: string }, ctx
  */
 export async function awaitTranscript(
   id: string,
-  ctx: WorkflowCtx,
+  ctx: WorkflowContext,
   nudge?: string,
 ): Promise<TranscriptState> {
   // Which turn says "still going". A pure function of `nudge`, which the body
@@ -518,7 +518,7 @@ export async function askWhetherToKeep(
   requestedBy: string,
   transcriptId: string,
   compensations: Compensation[],
-  ctx: WorkflowCtx,
+  ctx: WorkflowContext,
 ): Promise<Retention> {
   await ctx.step("noteGate", () =>
     note(
@@ -560,7 +560,7 @@ export async function askWhetherToKeep(
 export async function compensate(
   compensations: Compensation[],
   because: string,
-  ctx: WorkflowCtx,
+  ctx: WorkflowContext,
 ): Promise<void> {
   if (compensations.length === 0) return;
   // The narration is a STEP like every other, so an unwind interrupted by a
@@ -607,9 +607,9 @@ export async function submitRecording(
   url: string,
   webhookUrl?: string,
 ): Promise<{ id: string; callback: boolean }> {
-  await report(`Submitting ${new URL(url).hostname} for transcription…`);
+  await stepReport(`Submitting ${new URL(url).hostname} for transcription…`);
 
-  // `stepTranscribeSubmitClassified` owns the endpoint, the raw-key auth, the
+  // `stepTranscribeSubmitOrFail` owns the endpoint, the raw-key auth, the
   // PLURAL `speech_models` field and the failure classification — the
   // `Classified` suffix being that last part: it is `stepTranscribeSubmit` with
   // `throwStepError` already applied, so a provider refusal stays terminal and a
@@ -625,7 +625,7 @@ export async function submitRecording(
   // What must not creep in is a `?? null` or a `?? ""` to "be explicit": either
   // one puts the key back, and a provider handed a null for a URL is entitled to
   // refuse the whole submission.
-  const job = await stepTranscribeSubmitClassified(url, {
+  const job = await stepTranscribeSubmitOrFail(url, {
     params: { speaker_labels: true, webhook_url: webhookUrl },
   });
   return { id: job.id, callback: webhookUrl !== undefined };
@@ -698,7 +698,7 @@ export async function checkTranscript(id: string): Promise<TranscriptState> {
     );
   }
 
-  await report(`Transcript ${parsed.data.status}.`);
+  await stepReport(`Transcript ${parsed.data.status}.`);
   return {
     status: parsed.data.status,
     // `omitUndefined` rather than a spread-ternary per field: under
@@ -730,7 +730,7 @@ export async function checkTranscript(id: string): Promise<TranscriptState> {
  * a replay is exactly that world.
  */
 export async function discardTranscript(id: string): Promise<void> {
-  await report(`Discarding transcript ${id}.`);
+  await stepReport(`Discarding transcript ${id}.`);
   // Not through `request` above, because a 404 is a SUCCESS here — see below.
   // `stepFetch` for the same reason it does; only the status handling differs.
   const response = await stepFetch(`${TRANSCRIPT_ENDPOINT}/${id}`, {
@@ -756,7 +756,7 @@ export async function discardTranscript(id: string): Promise<void> {
  * journal instead of submitting the recording again.
  */
 export async function summarize(url: string, transcript: TranscriptState): Promise<Recap> {
-  await report("Writing the recap.");
+  await stepReport("Writing the recap.");
 
   const text = (transcript.text ?? "").slice(0, MAX_TRANSCRIPT_CHARS);
   if (text.trim() === "") {
@@ -765,13 +765,13 @@ export async function summarize(url: string, transcript: TranscriptState): Promi
     throw new FatalError("That recording came back with no speech in it.");
   }
 
-  // `stepGenerateJsonClassified` unwraps the fence a model puts around JSON
+  // `stepGenerateJsonOrFail` unwraps the fence a model puts around JSON
   // however firmly it is told not to, parses it, and validates it — all four
   // things this step used to re-derive. The `Classified` half is what makes a
   // terminal gateway failure (a bad key, a rejected request) stop rather than
   // burn the remaining attempts, where a reply that missed the SHAPE throws
   // plainly and retries.
-  const parsed = await stepGenerateJsonClassified(text, {
+  const parsed = await stepGenerateJsonOrFail(text, {
     schema: RecapReply,
     system:
       "You write up recordings for someone who will hear the result on a phone call. " +
@@ -792,13 +792,13 @@ export async function summarize(url: string, transcript: TranscriptState): Promi
 /**
  * Say one line into the run's progress channel.
  *
- * A step for one reason: the body REPLAYS, so a `report()` written there is
+ * A step for one reason: the body REPLAYS, so a `stepReport()` written there is
  * re-emitted on every resume. Everything the body itself wants to narrate —
  * the slow-recording note, the unwind — comes through here, and `agent.ts`'s
  * `recap_progress` is what reads it back down the phone.
  */
 export async function note(line: string): Promise<void> {
-  await report(line);
+  await stepReport(line);
 }
 
 // ---- HTTP -------------------------------------------------------------------
@@ -810,10 +810,7 @@ export async function note(line: string): Promise<void> {
  * Note the header is a bare key: AssemblyAI's `authorization` takes the key
  * itself, with no `Bearer` prefix.
  */
-async function request(
-  url: string,
-  init: { method?: string; body?: string } = {},
-): Promise<Response> {
+async function request(url: string): Promise<Response> {
   // Through `stepFetch`, not `fetch`: it pins HTTP/1.1, so several concurrent
   // runs (and this workflow POLLS, so one run is many requests) get a socket
   // each rather than N streams on one connection — and a connection failure
@@ -821,14 +818,13 @@ async function request(
   // `TypeError: fetch failed`, which for a template whose whole subject is
   // durability is the difference between a diagnosable resume and a mystery.
   // `sdk/step-fetch.ts` carries the measurements.
-  // `stepFetchOk` makes the three-way retry decision: a 401 or a 400 answers the
+  // `stepFetchOrFail` makes the three-way retry decision: a 401 or a 400 answers the
   // same way on the fourth attempt and burns the step, a 429 or a 5xx is what
   // retries are for, and a `Retry-After` the provider named is waited out rather
   // than replaced by the DevKit's one-second default — which matters here more
   // than usual, because a fan-out of segments hits a rate limit together. The
   // DELETE below stays on plain `stepFetch`, because there a 404 is a SUCCESS.
-  return await stepFetchOk(url, {
-    ...init,
+  return await stepFetchOrFail(url, {
     headers: { authorization: requireStepEnv(API_KEY_ENV), "content-type": "application/json" },
     signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
   });

package/dist/templates/redline/agent.eval.test.ts

@@ -29,7 +29,7 @@
 // journal, no replay, and no per-step retry, so a rate-limited live run FAILS
 // where a deployed one would have ridden it out. The tier that really resumes a
 // run is `aai-cli`'s `dev-workflow.scenario.test.ts`.
-import { stubGatewayRoute } from "@alexkroman1/aai/testing";
+import { routeStepFetch, stubGatewayRoute } from "@alexkroman1/aai/testing";
 import { installStubStepFetch } from "@alexkroman1/aai/testing/vitest";
 import { describeWorkflowEval } from "@alexkroman1/aai-runtime/eval/vitest";
 import { expect } from "vitest";
@@ -75,13 +75,10 @@ const critique = (verdict: "ship" | "revise", score = 8): string =>
  */
 function scriptGateway(contents: readonly string[]) {
   const model = stubGatewayRoute(contents);
-  installStubStepFetch((request) => {
-    const answered = model.route(request);
-    if (answered === undefined) {
-      throw new Error(`unexpected step request in an eval: ${request.method} ${request.url}`);
-    }
-    return answered;
-  });
+  // `routeStepFetch` defaults to throwing on an unrecognised request, which is
+  // what this file wants and what it used to spell out: every step in this body
+  // is a model call, so anything the route does not recognise is a finding.
+  installStubStepFetch(routeStepFetch([model.route]));
   return model;
 }
 

package/dist/templates/redline/agent.test.ts

@@ -228,7 +228,7 @@ describe("the steps", () => {
  * to take the same branch on every walk.
  *
  * The model is the whole world here (`writeDraft`, `critiqueDraft` and
- * `reviseDraft` are all `stepGenerate*Classified`), so `stubGateway`'s scripted
+ * `reviseDraft` are all `stepGenerate*OrFail`), so `stubGateway`'s scripted
  * replies ARE the run, and its call log is what proves a replay did not pay for
  * a round twice. Scripted in body order, with the last reply repeating.
  */

package/dist/templates/redline/client.tsx

@@ -59,9 +59,11 @@ import "@alexkroman1/aai-ui/styles.css";
 import { plural } from "@alexkroman1/aai/utils";
 import type { WorkflowInputOf, WorkflowOutputOf } from "@alexkroman1/aai/workflow-api";
 import {
+  BulletList,
+  Facts,
   Form,
   type FormValues,
-  page,
+  mountPage,
   SubmitButton,
   TextAreaField,
   useWorkflowSubmit,
@@ -70,7 +72,6 @@ import {
   WorkflowProgress,
   type WorkflowRun,
 } from "@alexkroman1/aai-ui";
-import { useState } from "react";
 import type { redline } from "./agent.ts";
 
 /**
@@ -124,13 +125,10 @@ export function toInput(values: FormValues): WorkflowInputOf<typeof redline> {
 }
 
 function RedlineDesk() {
-  // Did THIS load start the run? A reload cannot have, and that is the only way
-  // the page can tell "writing what you just briefed" from "picking up where
-  // you left off" — the hook reports the run, not who asked for it.
-  const [startedHere, setStartedHere] = useState(false);
   // The reload is covered by the hook's own key — see the module doc for why
   // this desk wants the tab-scoped one it mints rather than a key of its own.
-  const { submit, run, pending, error, reset } = useWorkflowSubmit<typeof redline>(WORKFLOW);
+  const { submit, run, pending, error, reset, startedHere } =
+    useWorkflowSubmit<typeof redline>(WORKFLOW);
 
   return (
     <main className="mx-auto flex max-w-2xl flex-col gap-8 p-8">
@@ -142,13 +140,7 @@ function RedlineDesk() {
         </p>
       </header>
 
-      <Form
-        onSubmit={(values) => {
-          setStartedHere(true);
-          return submit(toInput(values));
-        }}
-        error={error}
-      >
+      <Form onSubmit={(values) => submit(toInput(values))} error={error}>
         {/* The scalars: brief, audience, rounds. Declared, not written. */}
         <WorkflowFields workflow={WORKFLOW} />
         {/* The array the schema declares and no generic control can render. */}
@@ -177,7 +169,6 @@ function RedlineDesk() {
             // The recovered run is dismissed as deliberately as one this load
             // started: `reset()` is not undone by a second lookup (the lookup
             // is a mount-time act), so Clear really does clear.
-            setStartedHere(false);
             reset();
           }}
         />
@@ -193,15 +184,16 @@ function Rounds({ rounds }: { rounds: Redline["rounds"] }) {
     <ol className="flex flex-col gap-3">
       {rounds.map((entry) => (
         <li key={entry.round} className="flex flex-col gap-1 border-l pl-4">
-          <p className="text-xs uppercase tracking-[1.2px] opacity-60">
-            Round {entry.round} · {entry.critique.score}/10 ·{" "}
-            {entry.critique.verdict === "ship" ? "ship it" : "revise"}
-          </p>
-          <ul className="flex list-disc flex-col gap-1 pl-5 text-sm">
-            {entry.critique.notes.map((note) => (
-              <li key={note}>{note}</li>
-            ))}
-          </ul>
+          <Facts
+            size="xs"
+            className="uppercase tracking-[1.2px]"
+            items={[
+              `Round ${entry.round}`,
+              `${entry.critique.score}/10`,
+              entry.critique.verdict === "ship" ? "ship it" : "revise",
+            ]}
+          />
+          <BulletList items={entry.critique.notes} size="sm" />
         </li>
       ))}
     </ol>
@@ -224,7 +216,7 @@ function RunPanel({ run, onClear }: { run: WorkflowRun<Redline>; onClear: () =>
       {/* The run's own narration — the complement of the status line, which is
           `running` for a run's whole life, so a one-round redline and a
           three-round one look identical while they happen. These lines come from
-          the run itself (`report()` in `workflows/redline.ts`), and they REPLAY,
+          the run itself (`stepReport()` in `workflows/redline.ts`), and they REPLAY,
           so a reload mid-run catches up rather than starting from whatever
           arrives next. */}
       <WorkflowProgress runId={run.runId} />
@@ -233,20 +225,30 @@ function RunPanel({ run, onClear }: { run: WorkflowRun<Redline>; onClear: () =>
           without a cast. */}
       {run.status === "completed" && (
         <>
-          <p className="text-xs opacity-60">
-            {run.output.words} words · {run.output.roundsRun}{" "}
-            {plural(run.output.roundsRun, "round")} ·{" "}
-            {/* Which of the two stop conditions ended the loop is the one thing
-                a reader cannot infer from the round count alone. */}
-            {run.output.shipped ? "the critic stopped it" : "the round budget stopped it"}
-          </p>
+          {/* Which of the two stop conditions ended the loop is the one thing a
+              reader cannot infer from the round count alone, so it is a fact of
+              its own rather than something left to the round count. */}
+          <Facts
+            size="xs"
+            items={[
+              `${run.output.words} words`,
+              `${run.output.roundsRun} ${plural(run.output.roundsRun, "round")}`,
+              run.output.shipped ? "the critic stopped it" : "the round budget stopped it",
+            ]}
+          />
           <Rounds rounds={run.output.rounds} />
           <article className="whitespace-pre-wrap text-sm leading-relaxed">
             {run.output.draft}
           </article>
         </>
       )}
-      {run.status === "failed" && <p className="text-red-600">{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">
+          {run.error}
+        </p>
+      )}
     </section>
   );
 }
@@ -263,4 +265,4 @@ function RunPanel({ run, onClear }: { run: WorkflowRun<Redline>; onClear: () =>
  */
 const STATUS_LINE = { ...WORKFLOW_STATUS_LABELS, running: "Writing…" };
 
-page({ name: "Redline", component: RedlineDesk });
+mountPage({ name: "Redline", component: RedlineDesk });

package/dist/templates/redline/workflows/redline.ts

@@ -32,12 +32,12 @@
  * three functions read more tidily than one.
  */
 
-import type { WorkflowCtx } from "@alexkroman1/aai";
-import { report } from "@alexkroman1/aai/step";
+import type { WorkflowContext } from "@alexkroman1/aai";
+import { stepReport } from "@alexkroman1/aai/step";
 import {
   FatalError,
-  stepGenerateClassified,
-  stepGenerateJsonClassified,
+  stepGenerateJsonOrFail,
+  stepGenerateOrFail,
 } from "@alexkroman1/aai/step-errors";
 import { countWords } from "@alexkroman1/aai/utils";
 import { z } from "zod";
@@ -98,7 +98,7 @@ export interface Round {
  * the page's render model — and `WorkflowOutputOf<typeof redline>` in
  * `client.tsx` is that type, derived rather than restated.
  */
-export async function redlineFlow(input: RedlineInput, ctx: WorkflowCtx) {
+export async function redlineFlow(input: RedlineInput, ctx: WorkflowContext) {
   // The three `maxAttempts` below were `maxRetries` properties on the functions
   // (3, 5, 3 — retries AFTER the first attempt, so 4, 6, 4 in all). The policy
   // is an argument to the CALL now, which is where it belongs: the same function
@@ -153,12 +153,12 @@ export async function writeDraft(input: RedlineInput): Promise<string> {
     );
   }
 
-  await report(`Writing the first draft for ${input.audience}.`);
+  await stepReport(`Writing the first draft for ${input.audience}.`);
   // No empty-reply guard here or in `reviseDraft`, and that is not an omission:
   // `stepGenerate` already refuses an empty completion, as a RETRYABLE
   // `StepGenerateError` — which is the right answer, and one a hand-written
   // check would have to re-derive.
-  const draft = await stepGenerateClassified(briefBlock(input), { system: WRITER_SYSTEM });
+  const draft = await stepGenerateOrFail(briefBlock(input), { system: WRITER_SYSTEM });
   return draft.trim();
 }
 
@@ -175,14 +175,14 @@ export async function critiqueDraft(
   input: RedlineInput,
   round: number,
 ): Promise<Critique> {
-  await report(`Round ${round}: reading it back critically.`);
+  await stepReport(`Round ${round}: reading it back critically.`);
   // `stepGenerateJson` owns the fence, the parse, the non-object case and the
   // shape — and throws PLAINLY when any of them misses, unlike the fatal one
   // above: a model that answered with prose may well obey on the next attempt.
-  const parsed = await stepGenerateJsonClassified(
-    `${briefBlock(input)}\n\nThe submission:\n${draft}`,
-    { schema: CritiqueReply, system: CRITIC_SYSTEM },
-  );
+  const parsed = await stepGenerateJsonOrFail(`${briefBlock(input)}\n\nThe submission:\n${draft}`, {
+    schema: CritiqueReply,
+    system: CRITIC_SYSTEM,
+  });
 
   const critique: Critique = {
     verdict: parsed.verdict,
@@ -192,7 +192,7 @@ export async function critiqueDraft(
     score: clampScore(parsed.score),
     notes: parsed.notes.slice(0, MAX_NOTES),
   };
-  await report(
+  await stepReport(
     critique.verdict === "ship"
       ? `Round ${round}: the critic would ship it (${critique.score}/10).`
       : `Round ${round}: ${critique.notes.length} note(s) to address (${critique.score}/10).`,
@@ -207,8 +207,8 @@ export async function reviseDraft(
   input: RedlineInput,
   round: number,
 ): Promise<string> {
-  await report(`Round ${round}: revising.`);
-  const revised = await stepGenerateClassified(
+  await stepReport(`Round ${round}: revising.`);
+  const revised = await stepGenerateOrFail(
     [
       briefBlock(input),
       `Your current draft:\n${draft}`,
@@ -241,8 +241,8 @@ export function clampScore(score: number): number {
 // There is no local `ask()` any more, and its absence is the point. The SDK
 // classifies the gateway's failure (`StepGenerateError.retryable`) and stops
 // there — whether a terminal failure should burn the step's remaining attempts
-// is the caller's call — so `stepGenerateClassified` and
-// `stepGenerateJsonClassified` (`@alexkroman1/aai/step-errors`) are that call
+// is the caller's call — so `stepGenerateOrFail` and
+// `stepGenerateJsonOrFail` (`@alexkroman1/aai/step-errors`) are that call
 // made one way: terminal stays terminal, and a rate limit becomes a
 // `RetryableError` carrying the delay the gateway itself named, which beats
 // `RetryableError`'s own one-second default. Three templates each wrapped the