@alexkroman1/aai-cli 6.11.0 → 7.0.0

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

@@ -0,0 +1,209 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * Delivering the digest — the half of this template that is about a THIRD
+ * PARTY's contract rather than about podcasts.
+ *
+ * Slack has two things people call "a webhook URL" and they take different
+ * bodies. Getting this wrong is the single most common way a run of this
+ * template ends in a red 400 with nobody able to say why, so the distinction is
+ * modelled here rather than left to whoever pastes the URL:
+ *
+ * | URL | What it wants |
+ * | --- | --- |
+ * | `hooks.slack.com/services/…` | A classic incoming webhook: Block Kit |
+ * | `hooks.slack.com/triggers/…` | A workflow trigger: FLAT string variables |
+ *
+ * Send Block Kit to a trigger URL and Slack rejects the whole payload, because
+ * a trigger's body is a flat map of the variables its workflow declared — there
+ * is no `blocks` variable and there never will be. {@link renderSlackPayload}
+ * branches on the URL for exactly that reason, and it is a pure function so the
+ * branch is testable without a network.
+ *
+ * ## Why the trigger case needs a parameter NAME from the user
+ *
+ * A trigger's variables are named by whoever built the Slack workflow. This
+ * template cannot know that name, so it is an input field defaulting to `text`
+ * — the name Slack's own example uses. That is an unusual thing to put in a
+ * form and it is the honest option: the alternative is guessing, and a guess
+ * fails with `invalid_arguments` and no indication of which name was wrong.
+ */
+
+import { report, stepFetch } from "@alexkroman1/aai/step";
+import { toStepError } from "@alexkroman1/aai/step-errors";
+import { responseErrorMessage } from "@alexkroman1/aai/utils";
+import { FatalError } from "workflow";
+import type { EpisodeDigest } from "./digest.ts";
+
+/** Slack is not slow; a post that has not answered in 30s is not going to. */
+const POST_TIMEOUT_MS = 30_000;
+
+/** Everything the message needs, so rendering can stay a pure function. */
+export type SlackDigestInput = {
+  slackWebhookUrl: string;
+  slackWorkflowTextParam: string;
+  podcastChannels: string;
+  episodes: EpisodeDigest[];
+  digestNumber: number;
+  totalDigests: number;
+};
+
+/**
+ * The step: post one digest, and classify the failure honestly.
+ *
+ * The 4xx/5xx split is the whole reason this is not a one-line `stepFetch`. A
+ * revoked webhook, an unpublished workflow and a wrong variable name all answer
+ * 4xx and will answer 4xx identically on every retry — retrying them burns the
+ * DevKit's attempts and delays the real error by minutes. A 5xx is Slack having
+ * a bad minute, which is precisely what retries are for, and `toStepError`
+ * carries any `Retry-After` Slack named into the schedule.
+ */
+export async function sendDigestToSlack(input: SlackDigestInput): Promise<string> {
+  "use step";
+
+  await report("Posting the digest to Slack.");
+  const response = await stepFetch(input.slackWebhookUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(renderSlackPayload(input)),
+    signal: AbortSignal.timeout(POST_TIMEOUT_MS),
+  });
+  if (response.ok) return (await response.text()) || "ok";
+
+  // `responseErrorMessage` rather than `await response.text()` and a hand-rolled
+  // truncation: it prefers a JSON `error` field when the body has one — which
+  // Slack's does — and falls back to the status with a bounded preview.
+  const detail = await responseErrorMessage(response, "Slack webhook post");
+  if (response.status >= 400 && response.status < 500) {
+    throw new FatalError(`${slackAdvice(input.slackWebhookUrl, detail)} (HTTP ${response.status})`);
+  }
+  throw toStepError(response, `Slack webhook post failed: HTTP ${response.status}. ${detail}`);
+}
+
+/**
+ * The sentence a person can act on, chosen from what the URL and body say.
+ *
+ * `workflow_not_published` is called out by name because it is the one 4xx with
+ * a fix that is not "check your URL" — the URL is fine and the workflow behind
+ * it was never published — and nothing in Slack's generic message says so.
+ */
+export function slackAdvice(webhookUrl: string, detail: string): string {
+  if (isSlackWorkflowTriggerUrl(webhookUrl)) {
+    if (detail.includes("workflow_not_published")) {
+      return "That Slack workflow trigger exists but its workflow is not published. Publish it in Slack, then start a new run.";
+    }
+    return `Slack rejected the workflow trigger: ${detail}. Check that the text parameter matches a variable the workflow declares.`;
+  }
+  return `Slack rejected the incoming webhook: ${detail}. Check that the webhook is still active and has not been revoked.`;
+}
+
+/** A workflow trigger, which takes flat variables and not Block Kit. */
+export function isSlackWorkflowTriggerUrl(url: string): boolean {
+  try {
+    const parsed = new URL(url);
+    return (
+      parsed.hostname.toLowerCase() === "hooks.slack.com" &&
+      parsed.pathname.startsWith("/triggers/")
+    );
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Accepted at the form's edge: an incoming webhook or a workflow trigger, on
+ * one of Slack's two webhook hosts.
+ *
+ * A host check rather than "is it a URL", and this is a security boundary as
+ * much as a usability one: this value becomes the target of a POST carrying
+ * summarized content, so anything that is not Slack is an exfiltration target
+ * somebody typed into a form. Refusing at `start()` is a 400 at the call site;
+ * refusing later would be a failed run after transcription had already been paid for.
+ */
+export function isSlackWebhookUrl(value: string): boolean {
+  try {
+    const parsed = new URL(value);
+    const host = parsed.hostname.toLowerCase();
+    return (
+      parsed.protocol === "https:" &&
+      (host === "hooks.slack.com" || host === "hooks.slack-gov.com") &&
+      parsed.pathname.length > 1
+    );
+  } catch {
+    return false;
+  }
+}
+
+/** Block Kit, or flat variables — see the module doc. */
+export function renderSlackPayload(input: SlackDigestInput): Record<string, unknown> {
+  if (isSlackWorkflowTriggerUrl(input.slackWebhookUrl)) {
+    return { [input.slackWorkflowTextParam || "text"]: renderPlainTextDigest(input) };
+  }
+  return renderSlackMessage(input);
+}
+
+/** The trigger body: one string, because that is all a variable can hold. */
+export function renderPlainTextDigest(input: SlackDigestInput): string {
+  return [
+    digestHeadline(input),
+    `Feeds: ${input.podcastChannels}`,
+    "",
+    ...input.episodes.flatMap((episode) => [
+      `${episode.title} — ${episode.podcastTitle}`,
+      episode.url,
+      episode.summary,
+      ...episode.keyPoints.map((point) => `- ${point}`),
+      "",
+    ]),
+  ]
+    .join("\n")
+    .trim();
+}
+
+/** The incoming-webhook body: Block Kit, with `text` as the notification line. */
+function renderSlackMessage(input: SlackDigestInput): Record<string, unknown> {
+  return {
+    // Not decoration — this is what a push notification and a screen reader
+    // read. A Block Kit payload with no `text` notifies as "[no preview]".
+    text: `${digestHeadline(input)}: ${input.episodes.length} episode summaries`,
+    blocks: [
+      { type: "header", text: { type: "plain_text", text: digestHeadline(input) } },
+      {
+        type: "section",
+        text: { type: "mrkdwn", text: `Feeds: ${escapeSlack(input.podcastChannels)}` },
+      },
+      { type: "divider" },
+      ...input.episodes.flatMap((episode) => [
+        {
+          type: "section",
+          text: { type: "mrkdwn", text: renderEpisodeBlock(episode) },
+        },
+        { type: "divider" },
+      ]),
+    ],
+  };
+}
+
+function renderEpisodeBlock(episode: EpisodeDigest): string {
+  return [
+    `*<${escapeSlack(episode.url)}|${escapeSlack(episode.title)}>*`,
+    `_${escapeSlack(episode.podcastTitle)}_`,
+    escapeSlack(episode.summary),
+    ...episode.keyPoints.map((point) => `• ${escapeSlack(point)}`),
+  ].join("\n");
+}
+
+function digestHeadline(input: SlackDigestInput): string {
+  return `Podcast digest ${input.digestNumber}/${input.totalDigests}`;
+}
+
+/**
+ * The three characters Slack's mrkdwn reserves.
+ *
+ * Only three, and only these: Slack's own escaping rules say `&`, `<` and `>`
+ * and nothing else, so escaping more would put backslashes in front of
+ * apostrophes in every summary. `&` first, or the ampersands introduced by the
+ * other two get double-escaped.
+ */
+export function escapeSlack(text: string): string {
+  return text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}

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": {