@alexkroman1/aai-cli 13.2.0 → 14.0.0

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

@@ -46,7 +46,13 @@ describe("the agent declares itself a workflow app", () => {
   test("under the name the page starts a run by", () => {
     // `useWorkflowSubmit("redline")` in client.tsx names this key. Nothing else
     // records it, so a rename here is a 400 there rather than a compile error.
-    expect(Object.keys(agentDef.workflows ?? {})).toEqual(["redline"]);
+    // `toContain` rather than an exact key list: adding a second workflow is an
+    // invited edit and must not redden a test the author did not write. The
+    // NAME is still pinned, deliberately — the page starts a run by this
+    // string, so renaming the key is a runtime 400 rather than a compile
+    // error, and this pin is the only thing that says so. Rename it here and
+    // in `client.tsx` together.
+    expect(Object.keys(agentDef.workflows ?? {})).toContain("redline");
     expect(agentDef.workflows?.redline).toBe(redline);
   });
 
@@ -222,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

@@ -31,11 +31,13 @@
  * in React state — so a refresh lost it while the loop carried on writing,
  * grading and revising without anywhere to report to. On a desk whose whole
  * subject is a loop that runs several long-form model calls, that is the one
- * failure worth two lines of wiring: `key` is the handle that survives a reload
- * and `recover` is what reads it back, so the draft, the critique trail and the
- * Clear button are all there again.
+ * failure the hook now covers on its own: `useWorkflowSubmit` records every run
+ * under a correlation KEY it mints for this page and asks for that key's newest
+ * run as it mounts, so the draft, the critique trail and the Clear button are
+ * all there again with nothing written here.
  *
- * **The key is opaque and lives in `sessionStorage`, and the brief is why.** A
+ * **The key it mints is opaque and lives in `sessionStorage`, and the brief is
+ * why this page wants exactly that one.** A
  * `?key=` parameter in the page's own URL would survive more — a new tab, a
  * bookmark, a link sent to the person who asked for the piece — and that is
  * exactly what it must not do here. There is no per-user filtering behind
@@ -48,26 +50,28 @@
  *
  * Deriving the key from the brief is worse again: two people briefing the same
  * thing would recover each other's runs, and the key would then carry what they
- * typed into a lookup token the platform deliberately stopped logging.
+ * typed into a lookup token the platform deliberately stopped logging. Both are
+ * things a page could still ask for by passing its own `key`, and this one has
+ * no reason to.
  */
 
 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,
-  useRunKey,
   useWorkflowSubmit,
   WORKFLOW_STATUS_LABELS,
   WorkflowFields,
   WorkflowProgress,
   type WorkflowRun,
 } from "@alexkroman1/aai-ui";
-import { useState } from "react";
 import type { redline } from "./agent.ts";
 
 /**
@@ -121,19 +125,10 @@ export function toInput(values: FormValues): WorkflowInputOf<typeof redline> {
 }
 
 function RedlineDesk() {
-  // This tab's handle on its own drafts — opaque, short, and remembered for the
-  // next load, which is what `recover` produces to find the run again.
-  const key = useRunKey();
-  // 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);
-  const { submit, run, pending, error, reset } = useWorkflowSubmit<typeof redline>(WORKFLOW, {
-    // Neither half is useful alone: without the key there is nothing to find
-    // the run by, and without `recover` the key is only ever written.
-    key,
-    recover: true,
-  });
+  // 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, startedHere } =
+    useWorkflowSubmit<typeof redline>(WORKFLOW);
 
   return (
     <main className="mx-auto flex max-w-2xl flex-col gap-8 p-8">
@@ -145,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. */}
@@ -180,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();
           }}
         />
@@ -196,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>
@@ -227,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} />
@@ -236,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>
   );
 }
@@ -266,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

package/dist/templates/research-workflow/agent.eval.test.ts

@@ -29,7 +29,7 @@
 // endpointing, barge-in, whether two sentences merged into one turn.
 
 import agentDef from "virtual:aai/agent";
-import { stubGatewayRoute } from "@alexkroman1/aai/testing";
+import { routeStepFetch, stubGatewayRoute } from "@alexkroman1/aai/testing";
 import { installStubStepFetch } from "@alexkroman1/aai/testing/vitest";
 import { type EvalToolCall, type EvalWorkflows, toolResultIn } from "@alexkroman1/aai-runtime/eval";
 import { describeEval } from "@alexkroman1/aai-runtime/eval/vitest";
@@ -132,11 +132,11 @@ type ScriptedSteps = {
 function scriptSteps(options: { hold?: boolean } = {}): ScriptedSteps {
   const gate = Promise.withResolvers<void>();
   const model = stubGatewayRoute(MODEL_SCRIPT);
+  // Throwing on an unrecognised request is `routeStepFetch`'s default and is
+  // what this file wants: every step here is a model call.
+  const route = routeStepFetch([model.route]);
   const stub = installStubStepFetch(async (request) => {
-    const answered = model.route(request);
-    if (answered === undefined) {
-      throw new Error(`unexpected step request in an eval: ${request.method} ${request.url}`);
-    }
+    const answered = route(request);
     // `model.calls` has already recorded this one, so a length of 1 IS the first
     // answer — and holding after the route rather than before it keeps the reply
     // this returns the one the script owed that call.

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

@@ -16,7 +16,7 @@
  * exported async function, so its prompt handling, its parsing and its
  * `FatalError` guards are all testable without an engine.
  *
- * The BODY is driven here only through `createWorkflowCtx`, which records what
+ * The BODY is driven here only through `createWorkflowContext`, which records what
  * it asked for and replays nothing. That is a choice rather than a limit now:
  * `runWorkflow` from `@alexkroman1/aai-runtime/testing` will run this body on
  * the real engine, and `link-digest` is the template that shows it — three
@@ -31,13 +31,16 @@ import { FatalError, RetryableError } from "@alexkroman1/aai/step-errors";
 import {
   createRunSnapshot,
   createToolContext,
-  createWorkflowCtx,
+  createWorkflowContext,
   parseSchemaInput,
   type StubGatewayCall,
   schemaInputIssues,
   toolRunner,
 } from "@alexkroman1/aai/testing";
-import { mockWorkflows, installStubGateway as stubGateway } from "@alexkroman1/aai/testing/vitest";
+import {
+  installStubWorkflows,
+  installStubGateway as stubGateway,
+} from "@alexkroman1/aai/testing/vitest";
 import { visitWebpage, webSearch } from "@alexkroman1/aai/tools";
 import type { WorkflowRunSnapshot } from "@alexkroman1/aai/workflow-api";
 import { runWorkflow } from "@alexkroman1/aai-runtime/testing";
@@ -89,7 +92,7 @@ const run = toolRunner(agentDef);
  *
  * Returned WITHOUT a cast, which is the property worth keeping: a cast would
  * also stop reporting the day `WorkflowClient` grows a method, and this stub is
- * how the template's tools reach the client at all. `mockWorkflows`
+ * how the template's tools reach the client at all. `installStubWorkflows`
  * (`@alexkroman1/aai/testing/vitest`) is what keeps that affordable — a `vi.fn`
  * per method over one `runs` list, filling in what this desk does not drive, so
  * the day the client does grow a method only the tests using it change.
@@ -101,12 +104,18 @@ function stubWorkflows(runs: WorkflowRunSnapshot[] = []): WorkflowClient {
   // Name only: `WorkflowSummary.description` is optional, so passing this
   // desk's through would mean handing `description: undefined` to a field that
   // does not accept it. Nothing here reads the description anyway.
-  return mockWorkflows({ runs, names: ["research"] });
+  return installStubWorkflows({ runs, names: ["research"] });
 }
 
 describe("the agent declares its workflow", () => {
   test("under the name ctx.workflows.start resolves it by", () => {
-    expect(Object.keys(agentDef.workflows ?? {})).toEqual(["research"]);
+    // `toContain` rather than an exact key list: a second workflow is an
+    // invited edit and must not redden a test the author did not write. The
+    // NAME is still pinned, deliberately — this key is a STRING to everything
+    // outside this file (the REST route, `ctx.workflows.get`, a schedule), so
+    // renaming it is a runtime 404 rather than a compile error, and nothing
+    // else says so.
+    expect(Object.keys(agentDef.workflows ?? {})).toContain("research");
     expect(agentDef.workflows?.research).toBe(research);
   });
 
@@ -439,7 +448,7 @@ describe("the steps that research", () => {
     // could not have said differently.
     // `planAngles`' result is what the fan-out iterates, so it is supplied
     // rather than run — the rest of the body needs no page and no model.
-    const ctx = createWorkflowCtx({
+    const ctx = createWorkflowContext({
       runSteps: false,
       // Every step the body READS needs a value: with `runSteps: false` nothing
       // runs, so this is the skeleton of a run rather than a run. That is the
@@ -550,7 +559,7 @@ describe("the steps that research", () => {
 /**
  * `researchFlow` itself, on the real replay engine.
  *
- * The block above drives this body through `createWorkflowCtx`, which records
+ * The block above drives this body through `createWorkflowContext`, which records
  * what it ASKED for and replays nothing — right for the retry policy and the
  * step order, and silent about the desk's actual promise: **answer the caller
  * now, finish the work later**. `runWorkflow`