@alexkroman1/aai-cli 13.3.0 → 15.0.0

package/dist/templates/podcast-digest/workflows/slack.ts

@@ -7,7 +7,7 @@
  * webhook shapes and the branch between them, Block Kit assembly, mrkdwn
  * escaping, the 4xx/5xx split and the advice each refusal deserves. All of it
  * is `@alexkroman1/aai/channels` now — `slackChannel()` names the destination,
- * `sendToChannelClassified` posts and classifies — and what is left here is the
+ * `sendToChannelOrFail` posts and classifies — and what is left here is the
  * part that is actually about podcasts: turning episode digests into a
  * {@link ChannelMessage}.
  *
@@ -22,13 +22,13 @@
  * The step BOUNDARY is not here — only a body holds a `ctx`, and the call this
  * file is reached through is `ctx.step("postDigest", …)` in `digest.ts`. What
  * stays here is what a step DOES: the digest rendered as a `ChannelMessage` and
- * one `sendToChannelClassified` call. Deciding which steps exist is the
+ * one `sendToChannelOrFail` call. Deciding which steps exist is the
  * template's job; what happens inside one is the SDK's.
  */
 
 import { type ChannelMessage, slackChannel } from "@alexkroman1/aai/channels";
-import { report } from "@alexkroman1/aai/step";
-import { sendToChannelClassified } from "@alexkroman1/aai/step-errors";
+import { stepReport } from "@alexkroman1/aai/step";
+import { sendToChannelOrFail } from "@alexkroman1/aai/step-errors";
 import type { EpisodeDigest } from "./digest.ts";
 
 /** Everything the message needs, so rendering can stay a pure function. */
@@ -46,14 +46,14 @@ export type SlackDigestInput = {
  *
  * It is three lines because the interesting decisions moved. `slackChannel()` builds
  * the descriptor, {@link renderDigestMessage} says what the message contains,
- * and `sendToChannelClassified` does the render-post-classify round — throwing
+ * and `sendToChannelOrFail` does the render-post-classify round — throwing
  * a `FatalError` on a 4xx (a revoked webhook and a wrong variable name answer
  * identically on every retry, so retrying only delays the real error) and a
  * `RetryableError` carrying Slack's own `Retry-After` on a 5xx.
  */
 export async function sendDigestToSlack(input: SlackDigestInput): Promise<string> {
-  await report("Posting the digest to Slack.");
-  return await sendToChannelClassified(
+  await stepReport("Posting the digest to Slack.");
+  return await sendToChannelOrFail(
     slackChannel({ webhookUrl: input.slackWebhookUrl, textParam: input.slackWorkflowTextParam }),
     renderDigestMessage(input),
   );

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

@@ -40,7 +40,7 @@
 //
 //     What no eval here can show is a delivery RESUMING a run, so no case claims
 //     it. The answered arm is `agent.test.ts`'s, through
-//     `createWorkflowCtx({ hooks })`, which is the only tier that can send a
+//     `createWorkflowContext({ hooks })`, which is the only tier that can send a
 //     payload at all; a real HTTP POST to the public callback route is
 //     `aai-cli`'s `dev-workflow.scenario.test.ts`'s, and is not yet written.
 //   * **The provider is scripted, in BOTH modes**, through `stepFetch`'s
@@ -62,7 +62,7 @@
  * this file SHIPS — see `agent.test.ts`.
  */
 import agentDef from "virtual:aai/agent";
-import { stubGatewayRoute } from "@alexkroman1/aai/testing";
+import { routeStepFetch, type StepRoute, stubGatewayRoute } from "@alexkroman1/aai/testing";
 import { installStubStepFetch } from "@alexkroman1/aai/testing/vitest";
 import {
   describeToolCalls,
@@ -138,22 +138,30 @@ function stubProvider(options: { hold?: boolean; ending?: Ending } = {}): Script
   const gate = Promise.withResolvers<void>();
   const model = stubGatewayRoute(RECAP_JSON);
   let polls = 0;
-  const stub = installStubStepFetch(async (request) => {
-    const recapped = model.route(request);
-    if (recapped) return recapped;
+  // Two legs: the model, then the provider's job API. Anything neither answers is a
+  // finding, which is `routeStepFetch`'s default rather than this file's throw.
+  // Annotated, so the leg's contract is visible where it is written: answer the
+  // requests you recognise, `undefined` for everything else, and let
+  // `routeStepFetch` decide what an unrecognised one means.
+  const provider: StepRoute = (request) => {
     if (request.method === "POST") return { body: { id: TRANSCRIPT_ID, status: "queued" } };
     // The compensation. A real DELETE removes the transcript from the account,
     // which is what makes "a failed run leaves nothing behind" a claim rather
     // than a comment — so the assertion that matters is that this was CALLED.
     if (request.method === "DELETE") return { body: {} };
-    if (request.method === "GET") {
-      polls += 1;
-      if (options.hold === true && polls === 1) await gate.promise;
-      return options.ending === "error"
-        ? { body: { status: "error", error: "that recording could not be decoded" } }
-        : { body: { status: "completed", text: TRANSCRIPT_TEXT, audio_duration: 254 } };
-    }
-    throw new Error(`unexpected step request in an eval: ${request.method} ${request.url}`);
+    if (request.method !== "GET") return;
+    polls += 1;
+    return options.ending === "error"
+      ? { body: { status: "error", error: "that recording could not be decoded" } }
+      : { body: { status: "completed", text: TRANSCRIPT_TEXT, audio_duration: 254 } };
+  };
+  const route = routeStepFetch([model.route, provider]);
+  const stub = installStubStepFetch(async (request) => {
+    const answered = route(request);
+    // Held AFTER routing, so the poll this returns is the one the script owed
+    // it — and `polls` has already counted this request.
+    if (options.hold === true && request.method === "GET" && polls === 1) await gate.promise;
+    return answered;
   });
   return { calls: stub.calls, release: () => gate.resolve() };
 }

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.
  */