@alexkroman1/aai-cli 6.11.0 → 8.0.0

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

@@ -27,16 +27,21 @@
  *   runs a real one.
  */
 
-import type { ToolContext, WorkflowClient, WorkflowRunSnapshot } from "@alexkroman1/aai";
+import type { WorkflowClient } from "@alexkroman1/aai";
 import {
-  createProgressStream,
   createRunSnapshot,
-  createStubWorkflows,
   createToolContext,
-  runTool,
+  parseSchemaInput,
+  schemaInputIssues,
+  toolRunner,
   withDiscoveredTools,
 } from "@alexkroman1/aai/testing";
-import { installStubGateway as stubGateway } from "@alexkroman1/aai/testing/vitest";
+import {
+  installStubStepFetch,
+  mockWorkflows,
+  installStubGateway as stubGateway,
+} from "@alexkroman1/aai/testing/vitest";
+import type { WorkflowRunSnapshot } from "@alexkroman1/aai/workflow-api";
 import { beforeEach, describe, expect, test, vi } from "vitest";
 import { createHook, type Hook, sleep } from "workflow";
 import authoredAgent from "./agent.ts";
@@ -80,24 +85,27 @@ const agentDef = withDiscoveredTools(
   import.meta.glob("./tools/*.ts", { eager: true }),
 );
 
-/** Every tool here is driven through the agent's own table, by the name the model calls. */
-const run = (name: string, args: Record<string, unknown>, ctx: ToolContext): Promise<unknown> =>
-  runTool(agentDef, name, args, ctx);
+/**
+ * Every tool here is driven through the agent's own table, by the name the model
+ * calls.
+ *
+ * The second parameter is args-or-context, which is `runTool`'s own shape: four
+ * of this desk's five tools take no arguments, and the `{}` those calls were
+ * obliged to pass sat between the two values a reader cares about.
+ */
+const run = toolRunner(agentDef);
 
-/** A `ctx.workflows` that records `start` and answers `find` from a fixture. */
+/**
+ * A `ctx.workflows` that records `start` and answers the lookups from a fixture.
+ *
+ * `mockWorkflows` (`@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 createStubWorkflows({
-    start: vi.fn(async () => "wrun_stub"),
-    get: vi.fn(async () => runs[0]),
-    find: vi.fn(async () => runs),
-    recent: vi.fn(async () => runs),
-    cancel: vi.fn(async () => true),
-    wakeUp: vi.fn(async () => 0),
-    // A tail of 0 means "one line written", which is the case the tools read.
-    streamTail: vi.fn(async () => 0),
-    stream: vi.fn(async () => createProgressStream([])),
-    listing: () => [{ name: "recap" }],
-  });
+  return mockWorkflows({ runs, names: ["recap"] });
 }
 
 /** A finished recap, as the workflow's output reaches the tools. */
@@ -122,13 +130,19 @@ describe("the agent declares its workflow", () => {
   });
 
   test("with an input schema, so a bad URL fails at the call site", async () => {
-    const ok = await recap.input?.["~standard"].validate({
+    // `parseSchemaInput` / `schemaInputIssues` rather than a reach through
+    // `["~standard"].validate`: that is the vendor WIRE contract, and whether it
+    // answers synchronously or with a promise is the vendor's business — a
+    // missing `await` there leaves `.issues` undefined and the refusing half
+    // passes for the wrong reason.
+    const parsed = await parseSchemaInput(recap.input, {
       url: "https://example.com/a.mp3",
       requestedBy: "s",
     });
-    expect(ok?.issues).toBeUndefined();
-    const bad = await recap.input?.["~standard"].validate({ url: "not a url", requestedBy: "s" });
-    expect(bad?.issues).toBeDefined();
+    expect(parsed).toMatchObject({ url: "https://example.com/a.mp3" });
+    expect(
+      await schemaInputIssues(recap.input, { url: "not a url", requestedBy: "s" }),
+    ).toBeDefined();
   });
 
   test("and names the credential its steps read, so a deploy checks for it", () => {
@@ -156,7 +170,7 @@ describe("request_recap", () => {
   test("starts a run keyed by the session, so a later turn can find it", async () => {
     const workflows = stubWorkflows();
     const ctx = createToolContext({ workflows });
-    const result = await run("request_recap", {}, ctx);
+    const result = await run("request_recap", ctx);
 
     expect(workflows.start).toHaveBeenCalledWith(
       recap,
@@ -170,7 +184,7 @@ describe("request_recap", () => {
 
   test("passes the definition rather than its name", async () => {
     const workflows = stubWorkflows();
-    await run("request_recap", {}, createToolContext({ workflows }));
+    await run("request_recap", createToolContext({ workflows }));
     // The def overload is what types the input and turns a rename into a compile
     // error; a string would still work at runtime and lose both.
     expect(vi.mocked(workflows.start).mock.calls[0]?.[0]).toBe(recap);
@@ -193,7 +207,7 @@ describe("request_recap", () => {
     // failure it prevents is not tidiness: a caller who asks twice would
     // otherwise pay for the same recording being transcribed twice.
     const workflows = stubWorkflows([createRunSnapshot({ workflow: "recap", status: "running" })]);
-    const result = await run("request_recap", {}, createToolContext({ workflows }));
+    const result = await run("request_recap", createToolContext({ workflows }));
     expect(result).toMatchObject({ started: false, runId: "wrun_1" });
     expect(workflows.start).not.toHaveBeenCalled();
   });
@@ -202,7 +216,7 @@ describe("request_recap", () => {
     const workflows = stubWorkflows([
       createRunSnapshot({ workflow: "recap", status: "completed", output: finishedOutput() }),
     ]);
-    const result = await run("request_recap", {}, createToolContext({ workflows }));
+    const result = await run("request_recap", createToolContext({ workflows }));
     expect(result).toMatchObject({ started: true });
     expect(workflows.start).toHaveBeenCalledTimes(1);
   });
@@ -211,7 +225,7 @@ describe("request_recap", () => {
 describe("recap_status", () => {
   test("says nothing was started when the key has no runs", async () => {
     const ctx = createToolContext({ workflows: stubWorkflows([]) });
-    const result = await run("recap_status", {}, ctx);
+    const result = await run("recap_status", ctx);
     expect(result).toMatchObject({ runs: [], note: "Nothing started yet." });
   });
 
@@ -221,7 +235,7 @@ describe("recap_status", () => {
     const workflows = stubWorkflows([
       createRunSnapshot({ workflow: "recap", status: "completed", output: finishedOutput() }),
     ]);
-    const result = (await run("recap_status", {}, createToolContext({ workflows }))) as {
+    const result = (await run("recap_status", createToolContext({ workflows }))) as {
       runs: string[];
     };
     expect(result.runs[0]).toContain("air quality");
@@ -239,7 +253,6 @@ describe("recap_status", () => {
     ];
     const result = (await run(
       "recap_status",
-      {},
       createToolContext({ workflows: stubWorkflows(runs) }),
     )) as { runs: string[] };
     expect(result.runs[0]).toContain("transcript deleted");
@@ -249,7 +262,7 @@ describe("recap_status", () => {
     const ctx = createToolContext({
       workflows: stubWorkflows([createRunSnapshot({ workflow: "recap", status: "running" })]),
     });
-    const result = (await run("recap_status", {}, ctx)) as { runs: string[] };
+    const result = (await run("recap_status", ctx)) as { runs: string[] };
     expect(result.runs[0]).toContain("Still working");
   });
 
@@ -262,7 +275,6 @@ describe("recap_status", () => {
     ];
     const result = (await run(
       "recap_status",
-      {},
       createToolContext({ workflows: stubWorkflows(runs) }),
     )) as { runs: string[] };
     expect(result.runs[0]).toContain("rolled back");
@@ -272,7 +284,7 @@ describe("recap_status", () => {
   test("bounds how many past runs it reads aloud", async () => {
     const workflows = stubWorkflows([]);
     const ctx = createToolContext({ workflows });
-    await run("recap_status", {}, ctx);
+    await run("recap_status", ctx);
     // A voice reply cannot be a list of twenty runs.
     expect(workflows.find).toHaveBeenCalledWith(recap, ctx.sessionId, { limit: 3 });
   });
@@ -281,28 +293,30 @@ describe("recap_status", () => {
 describe("recap_progress", () => {
   test("reads the run's own progress line rather than its status", async () => {
     const workflows = stubWorkflows([createRunSnapshot({ workflow: "recap", status: "running" })]);
-    vi.mocked(workflows.stream).mockResolvedValue(createProgressStream(["Transcript processing."]));
-    const result = await run("recap_progress", {}, createToolContext({ workflows }));
+    vi.mocked(workflows.lastLine).mockResolvedValue("Transcript processing.");
+    const result = await run("recap_progress", createToolContext({ workflows }));
     expect(result).toMatchObject({ progress: "Transcript processing." });
   });
 
   test("asks for the LAST line, not the whole log", async () => {
     // Every poll narrates, so a twenty-minute run's whole log is eighty lines.
+    // `lastLine` is the whole request — the bound that keeps an empty channel
+    // from hanging belongs to the method, so nothing here composes
+    // `streamTail` and `stream`.
     const workflows = stubWorkflows([createRunSnapshot({ workflow: "recap", status: "running" })]);
-    vi.mocked(workflows.stream).mockResolvedValue(createProgressStream(["a"]));
-    await run("recap_progress", {}, createToolContext({ workflows }));
-    expect(workflows.stream).toHaveBeenCalledWith("wrun_1", { startIndex: -1 });
+    vi.mocked(workflows.lastLine).mockResolvedValue("a");
+    await run("recap_progress", createToolContext({ workflows }));
+    expect(workflows.lastLine).toHaveBeenCalledWith("wrun_1");
   });
 
-  test("a run that has written nothing yet says so WITHOUT opening the stream", async () => {
-    // Not a shortcut: an empty progress channel is never closed, so reading one
-    // waits for a line that arrives whenever the next step writes — i.e. the
-    // tool hangs instead of answering.
+  test("a run that has written nothing yet says so", async () => {
+    // `lastLine` resolves `undefined` for an empty channel, and this is the arm
+    // the tool branches on. That an empty channel does not HANG — it is never
+    // closed, so a stream opened on one waits for a line that may never come —
+    // is `lastLine`'s own guarantee now, and `aai`'s to test.
     const workflows = stubWorkflows([createRunSnapshot({ workflow: "recap", status: "running" })]);
-    vi.mocked(workflows.streamTail).mockResolvedValue(-1);
-    const result = await run("recap_progress", {}, createToolContext({ workflows }));
+    const result = await run("recap_progress", createToolContext({ workflows }));
     expect(result).toMatchObject({ note: expect.stringContaining("nothing to report") });
-    expect(workflows.stream).not.toHaveBeenCalled();
   });
 });
 
@@ -343,7 +357,7 @@ describe("keep_transcript — the signal", () => {
 describe("cancel_recap", () => {
   test("cancels the live run", async () => {
     const workflows = stubWorkflows([createRunSnapshot({ workflow: "recap", status: "running" })]);
-    const result = await run("cancel_recap", {}, createToolContext({ workflows }));
+    const result = await run("cancel_recap", createToolContext({ workflows }));
     expect(workflows.cancel).toHaveBeenCalledWith("wrun_1");
     expect(result).toMatchObject({ cancelled: true });
   });
@@ -354,7 +368,7 @@ describe("cancel_recap", () => {
     // stops replaying the run, so the compensations never fire. A template that
     // implied otherwise would be teaching the wrong thing.
     const workflows = stubWorkflows([createRunSnapshot({ workflow: "recap", status: "running" })]);
-    const result = (await run("cancel_recap", {}, createToolContext({ workflows }))) as {
+    const result = (await run("cancel_recap", createToolContext({ workflows }))) as {
       note: string;
     };
     expect(result.note).toContain("left behind");
@@ -365,13 +379,13 @@ describe("cancel_recap", () => {
       createRunSnapshot({ workflow: "recap", status: "completed", output: finishedOutput() }),
     ]);
     vi.mocked(workflows.cancel).mockResolvedValue(false);
-    const result = await run("cancel_recap", {}, createToolContext({ workflows }));
+    const result = await run("cancel_recap", createToolContext({ workflows }));
     expect(result).toMatchObject({ cancelled: false, note: "That one had already finished." });
   });
 
   test("says nothing was started when the key has no runs", async () => {
     const workflows = stubWorkflows([]);
-    const result = await run("cancel_recap", {}, createToolContext({ workflows }));
+    const result = await run("cancel_recap", createToolContext({ workflows }));
     expect(result).toMatchObject({ cancelled: false, note: "Nothing started yet." });
     expect(workflows.cancel).not.toHaveBeenCalled();
   });
@@ -379,20 +393,22 @@ describe("cancel_recap", () => {
 
 // ---- The steps --------------------------------------------------------------
 
-/** A provider answering `body` with `status`, recording what it was asked. */
+/**
+ * A provider answering `body` with `status`, recording what it was asked.
+ *
+ * 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`
+ * 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,
+ * and `link-digest/agent.test.ts` states the rule this one used to break.
+ *
+ * `installStubStepFetch` unpublishes on `onTestFinished`, so there is no restore
+ * registry here and a stub cannot reach the next file.
+ */
 function stubProvider(body: unknown, status = 200) {
-  const calls: { url: string; init: RequestInit }[] = [];
-  vi.stubGlobal(
-    "fetch",
-    vi.fn(async (url: string, init: RequestInit = {}) => {
-      calls.push({ url, init });
-      return new Response(typeof body === "string" ? body : JSON.stringify(body), {
-        status,
-        headers: { "Content-Type": "application/json" },
-      });
-    }),
-  );
-  return calls;
+  return installStubStepFetch(() => ({ status, body })).calls;
 }
 
 describe("submitRecording", () => {
@@ -407,10 +423,10 @@ describe("submitRecording", () => {
     expect(await submitRecording("https://example.com/a.mp3")).toEqual({ id: "t_1" });
 
     const call = calls[0];
-    expect(call?.init.method).toBe("POST");
+    expect(call?.method).toBe("POST");
     // `speaker_labels` is this desk's own request, carried through the SDK's
     // `params` passthrough; the model field is the SDK's and is PLURAL.
-    expect(JSON.parse(String(call?.init.body))).toMatchObject({
+    expect(JSON.parse(String(call?.body))).toMatchObject({
       audio_url: "https://example.com/a.mp3",
       speaker_labels: true,
     });
@@ -418,8 +434,7 @@ describe("submitRecording", () => {
     // OpenAI-compatible LLM gateway `summarize` calls. The SDK spells the
     // header `Authorization`; HTTP header names are case-insensitive, so the
     // lookup is too rather than pinning one casing.
-    const headers = call?.init.headers as Record<string, string> | undefined;
-    const auth = Object.entries(headers ?? {}).find(
+    const auth = Object.entries(call?.headers ?? {}).find(
       ([name]) => name.toLowerCase() === "authorization",
     );
     expect(auth?.[1]).toBe("sk-test");
@@ -488,7 +503,7 @@ describe("discardTranscript — the compensation", () => {
   test("deletes the transcript this run created", async () => {
     const calls = stubProvider({ id: "t_1" });
     await expect(discardTranscript("t_1")).resolves.toBeUndefined();
-    expect(calls[0]?.init.method).toBe("DELETE");
+    expect(calls[0]?.method).toBe("DELETE");
     expect(calls[0]?.url).toContain("/t_1");
   });
 
@@ -580,19 +595,11 @@ describe("awaitTranscript — the polling port", () => {
 
   /** A provider whose status endpoint answers `statuses` in order. */
   function stubStatuses(statuses: readonly Record<string, unknown>[]) {
-    let call = 0;
-    vi.stubGlobal(
-      "fetch",
-      vi.fn(async () => {
-        const body = statuses[Math.min(call, statuses.length - 1)];
-        call += 1;
-        return new Response(JSON.stringify(body), {
-          status: 200,
-          headers: { "Content-Type": "application/json" },
-        });
-      }),
-    );
-    return () => call;
+    // Into `stepFetch`'s slot, for the reason `stubProvider` above gives.
+    const stub = installStubStepFetch(() => ({
+      body: statuses[Math.min(stub.calls.length - 1, statuses.length - 1)],
+    }));
+    return () => stub.calls.length;
   }
 
   test("keeps polling while the job is queued or processing", async () => {
@@ -665,15 +672,14 @@ describe("askWhetherToKeep — the expense port", () => {
 
   test("keeps the transcript when the caller says to, and deletes nothing", async () => {
     vi.mocked(createHook).mockReturnValue(hookAnswering({ keep: true }));
-    const fetchSpy = vi.fn();
-    vi.stubGlobal("fetch", fetchSpy);
+    const provider = installStubStepFetch();
 
     const compensations = [{ label: "transcript t_1", undo: async () => undefined }];
     expect(await askWhetherToKeep("s_1", "t_1", compensations)).toEqual({
       kept: true,
       answered: true,
     });
-    expect(fetchSpy).not.toHaveBeenCalled();
+    expect(provider.calls).toEqual([]);
     // The undo stays on the stack: a later failure still has something to reverse.
     expect(compensations).toHaveLength(1);
   });
@@ -687,7 +693,7 @@ describe("askWhetherToKeep — the expense port", () => {
       kept: false,
       answered: true,
     });
-    expect(calls[0]?.init.method).toBe("DELETE");
+    expect(calls[0]?.method).toBe("DELETE");
     // Leaving it would be harmless — the undo tolerates a 404 — and would still
     // narrate an unwind that reverses something already gone.
     expect(compensations).toHaveLength(0);
@@ -700,7 +706,7 @@ describe("askWhetherToKeep — the expense port", () => {
     const calls = stubProvider({ id: "t_1" });
 
     expect(await askWhetherToKeep("s_1", "t_1", [])).toEqual({ kept: false, answered: false });
-    expect(calls[0]?.init.method).toBe("DELETE");
+    expect(calls[0]?.method).toBe("DELETE");
   });
 
   test("claims the token BEFORE the caller is asked to answer it", async () => {
@@ -711,13 +717,10 @@ describe("askWhetherToKeep — the expense port", () => {
     vi.mocked(createHook).mockReturnValue(
       hookAnswering({ keep: true }, () => order.push("claimed")),
     );
-    vi.stubGlobal(
-      "fetch",
-      vi.fn(async () => {
-        order.push("asked");
-        return new Response("{}", { status: 200 });
-      }),
-    );
+    installStubStepFetch(() => {
+      order.push("asked");
+      return { body: {} };
+    });
 
     await askWhetherToKeep("s_1", "t_1", []);
     expect(order[0]).toBe("claimed");

package/dist/templates/recap-workflow/tools/recap_progress.ts

@@ -11,17 +11,14 @@ export default tool({
     // otherwise nothing to say — and this run has real news in between,
     // since every poll narrates.
     //
-    // `streamTail` FIRST, and not as an optimization: a progress channel is
-    // never closed — no step knows it is the last one — so reading a stream
-    // with nothing in it waits forever rather than ending. `-1` is "nothing
-    // written yet", and it is the only safe way to learn that.
-    if ((await ctx.workflows.streamTail(latest.runId)) < 0) {
-      return { note: "Submitted, nothing to report yet." };
-    }
-    // A negative `startIndex` reads from the END, which is what a voice
-    // reply wants — the last line, not a recital of the whole log.
-    const stream = await ctx.workflows.stream(latest.runId, { startIndex: -1 });
-    for await (const line of stream) return { progress: String(line) };
-    return { note: "Submitted, nothing to report yet." };
+    // `lastLine` rather than `streamTail` + `stream` composed here: a progress
+    // channel is never closed — no step knows it is the last one — so a stream
+    // opened on a run that has written nothing waits forever, which down a phone
+    // is a turn that stops with no error and nothing in a log. The bound that
+    // prevents it belongs to the method now, and `undefined` is "nothing yet".
+    const line = await ctx.workflows.lastLine(latest.runId);
+    return line === undefined
+      ? { note: "Submitted, nothing to report yet." }
+      : { progress: String(line) };
   },
 });

package/dist/templates/recap-workflow/tools/recap_status.ts

@@ -1,9 +1,5 @@
-import {
-  isTerminal,
-  tool,
-  type WorkflowOutputOf,
-  type WorkflowRunSnapshot,
-} from "@alexkroman1/aai";
+import { tool } from "@alexkroman1/aai";
+import { isTerminal, type WorkflowRunOf } from "@alexkroman1/aai/workflow-api";
 import { recap } from "../shared.ts";
 
 /** How many past runs the status tool will look at. Newest first. */
@@ -14,10 +10,13 @@ const RECENT_RUNS = 3;
  *
  * This is the QUERY, and `isTerminal` is what makes it typed: it narrows to the
  * three finished statuses, which is what puts `run.output` and `run.error`
- * within reach without a cast. `WorkflowOutputOf` names the output type from the
- * declaration, so this signature never reaches past it into the body.
+ * within reach without a cast. `WorkflowRunOf` is the snapshot with that output
+ * already named from the declaration — the
+ * `WorkflowRunSnapshot<WorkflowOutputOf<typeof recap>>` this file used to
+ * compose by hand, for a three-name import — so the signature never reaches past
+ * the declaration into the body, and it is still the discriminated union.
  */
-function describeRun(run: WorkflowRunSnapshot<WorkflowOutputOf<typeof recap>>): string {
+function describeRun(run: WorkflowRunOf<typeof recap>): string {
   if (!isTerminal(run)) return "Still working on that one.";
   switch (run.status) {
     case "completed": {

package/dist/templates/recap-workflow/tools/request_recap.ts

@@ -1,4 +1,5 @@
-import { isTerminal, tool } from "@alexkroman1/aai";
+import { tool } from "@alexkroman1/aai";
+import { isTerminal } from "@alexkroman1/aai/workflow-api";
 import { z } from "zod";
 import { recap, SAMPLE_RECORDING } from "../shared.ts";
 

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

@@ -55,7 +55,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
- * `stepGenerate`. The BATCH API is what makes the polling port honest: it
+ * `stepGenerateJsonClassified`. 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
@@ -67,17 +67,14 @@
  * just your shell.
  */
 
-import { throwStepError, toStepError } from "@alexkroman1/aai/step-errors";
+import { report, requireStepEnv, stepFetch } from "@alexkroman1/aai/step";
 import {
-  errorMessage,
-  isRecord,
-  omitUndefined,
-  report,
-  requireStepEnv,
-  stepFetch,
-  stepGenerateJson,
-  stepTranscribeSubmit,
-} from "@alexkroman1/aai/utils";
+  stepFetchOk,
+  stepGenerateJsonClassified,
+  stepTranscribeSubmitClassified,
+  toStepError,
+} from "@alexkroman1/aai/step-errors";
+import { errorMessage, isRecord, omitUndefined } from "@alexkroman1/aai/utils";
 import { createHook, FatalError, sleep } from "workflow";
 import { z } from "zod";
 import { retentionToken } from "./tokens.ts";
@@ -151,7 +148,7 @@ const POINTS = 3;
 /**
  * The shape the model must answer in.
  *
- * `stepGenerateJson` validates against this and throws PLAINLY when the reply
+ * `stepGenerateJsonClassified` 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
@@ -257,7 +254,7 @@ export async function recapFlow(input: { url: string; requestedBy: string }) {
  * to completion in a worker, where the body is what may suspend. Splitting it
  * out keeps `recapFlow` readable and costs nothing, since the WDK transform
  * rewrites a step's DECLARATION rather than its call sites, so a step called
- * from a helper is still a real step (`mapInBatches` rests on the same
+ * from a helper is still a real step (`mapConcurrent` rests on the same
  * property).
  *
  * The loop is deterministic despite looking like it is not: every branch turns
@@ -359,13 +356,14 @@ export async function submitRecording(url: string): Promise<{ id: string }> {
 
   await report(`Submitting ${new URL(url).hostname} for transcription…`);
 
-  // `stepTranscribeSubmit` owns the endpoint, the raw-key auth, the PLURAL
-  // `speech_models` field and the failure classification. `speaker_labels` is
-  // this desk's own request, which is what `params` is for — the async API's
+  // `stepTranscribeSubmitClassified` 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
+  // rate limit waits out the delay the provider itself named. `speaker_labels`
+  // is this desk's own request, which is what `params` is for — the async API's
   // surface is large and the SDK deliberately does not mirror it.
-  return await stepTranscribeSubmit(url, { params: { speaker_labels: true } }).catch(
-    throwStepError,
-  );
+  return await stepTranscribeSubmitClassified(url, { params: { speaker_labels: true } });
 }
 
 /**
@@ -467,19 +465,20 @@ export async function summarize(url: string, transcript: TranscriptState): Promi
     throw new FatalError("That recording came back with no speech in it.");
   }
 
-  // `stepGenerateJson` 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. `throwStepError` 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 stepGenerateJson(text, {
+  // `stepGenerateJsonClassified` 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, {
     schema: RecapReply,
     system:
       "You write up recordings for someone who will hear the result on a phone call. " +
       `Reply with JSON only: {"headline": string, "points": string[], "spoken": string}. ` +
       `Give exactly ${POINTS} points. "spoken" is ONE sentence, under 30 words, ` +
       "written to be read aloud. No markdown fence, no preamble.",
-  }).catch(throwStepError);
+  });
 
   return {
     url,
@@ -519,27 +518,24 @@ async function request(
   url: string,
   init: { method?: string; body?: string } = {},
 ): Promise<Response> {
-  // `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 arrives as a
-  // `StepTransportError` naming its cause instead of a bare
+  // 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
+  // arrives as a `StepTransportError` naming its cause instead of a bare
   // `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.
-  const response = await stepFetch(url, {
+  // `stepFetchOk` 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,
     headers: { authorization: requireStepEnv(API_KEY_ENV), "content-type": "application/json" },
     signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
   });
-  // The three-way retry decision, made by the SDK: 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.
-  if (!response.ok) {
-    throw toStepError(response, `${init.method ?? "GET"} ${url} failed: HTTP ${response.status}`);
-  }
-  return response;
 }
 
 /** A string field of a JSON body, when it really is one. */