@alexkroman1/aai-cli 5.14.0 → 6.1.0

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

@@ -0,0 +1,762 @@
+// Copyright 2026 the AAI authors. MIT license.
+/// <reference types="vite/client" />
+
+/**
+ * Specs for the recap desk — the template that ports the Temporal workflow
+ * patterns onto a voice call.
+ *
+ * Three tiers, and the line between them is what this file is careful about:
+ *
+ * - **The tools**, against a stubbed `ctx.workflows`. That is the only honest
+ *   way to unit-test them (the real client needs a Workflow DevKit world), and
+ *   it is enough: what the agent half promises is that the handoff passes a
+ *   correlation key, that a second request finds the live run instead of paying
+ *   for a second transcription, and that a cancel says out loud what cancelling
+ *   does not do.
+ * - **The steps**, directly. Imported through vitest with no bundler in the
+ *   path a `"use step"` function is an ordinary async function, so its HTTP
+ *   handling, its retryable/fatal split and its JSON contract with the model are
+ *   all testable.
+ * - **The body's two helpers** — the poll loop and the compensation unwind —
+ *   with `sleep` stubbed. What that asserts is ORDERING and BRANCHING, which is
+ *   ordinary logic and worth pinning; it asserts nothing about durability,
+ *   replay or suspension, and could not. `recapFlow` itself is deliberately not
+ *   driven here for exactly that reason — a body test dressed up as a durability
+ *   test would be the worse failure. `aai-cli`'s
+ *   `dev-workflow.scenario.test.ts` is the tier that builds a project and
+ *   runs a real one.
+ */
+
+import type { ToolContext, WorkflowClient, WorkflowRunSnapshot } from "@alexkroman1/aai";
+import {
+  createProgressStream,
+  createRunSnapshot,
+  createStubWorkflows,
+  createToolContext,
+  runTool,
+  withDiscoveredTools,
+} from "@alexkroman1/aai/testing";
+import { installStubGateway as stubGateway } from "@alexkroman1/aai/testing/vitest";
+import { beforeEach, describe, expect, test, vi } from "vitest";
+import { createHook, type Hook, sleep } from "workflow";
+import authoredAgent from "./agent.ts";
+import { recap } from "./shared.ts";
+import {
+  askWhetherToKeep,
+  awaitTranscript,
+  checkTranscript,
+  compensate,
+  discardTranscript,
+  submitRecording,
+  summarize,
+  type TranscriptState,
+} from "./workflows/recap.ts";
+import { retentionToken } from "./workflows/tokens.ts";
+
+/**
+ * The DevKit, with only its timer replaced.
+ *
+ * `sleep` throws outside a run, so the poll loop cannot be exercised at all
+ * without this — and everything else the module imports from `workflow`
+ * (`FatalError`, `RetryableError`) is a real class the steps' own specs assert
+ * against, so it is `importActual` plus one override rather than a fake module.
+ */
+vi.mock("workflow", async (importActual) => ({
+  ...(await importActual<typeof import("workflow")>()),
+  sleep: vi.fn(async () => undefined),
+  createHook: vi.fn(),
+}));
+
+/**
+ * The def a DEPLOYED agent runs: authored, plus what `tools/` declares.
+ *
+ * The glob is written HERE rather than reached for from a shared helper because
+ * this file SHIPS: it is what a scaffolded project runs, so it may not import
+ * anything outside its own template, and `import.meta.glob` is expanded against
+ * the file containing it either way. This is the pattern a user writes.
+ */
+const agentDef = withDiscoveredTools(
+  authoredAgent,
+  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);
+
+/** A `ctx.workflows` that records `start` and answers `find` from a fixture. */
+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" }],
+  });
+}
+
+/** A finished recap, as the workflow's output reaches the tools. */
+function finishedOutput(over: { kept?: boolean; answered?: boolean } = {}) {
+  return {
+    url: "https://assembly.ai/wildfires.mp3",
+    headline: "Smoke reaches the east coast",
+    points: ["a", "b", "c"],
+    spoken: "Wildfire smoke drifted east and pushed air quality into the unhealthy range.",
+    minutes: 4,
+    kept: true,
+    answered: true,
+    requestedBy: "s_1",
+    ...over,
+  };
+}
+
+describe("the agent declares its workflow", () => {
+  test("under the name ctx.workflows.start resolves it by", () => {
+    expect(Object.keys(agentDef.workflows ?? {})).toEqual(["recap"]);
+    expect(agentDef.workflows?.recap).toBe(recap);
+  });
+
+  test("with an input schema, so a bad URL fails at the call site", async () => {
+    const ok = await recap.input?.["~standard"].validate({
+      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();
+  });
+
+  test("and names the credential its steps read, so a deploy checks for it", () => {
+    // The steps reach the key with `requireStepEnv`, which no part of the agent
+    // config would otherwise mention.
+    expect(agentDef.requiredEnv).toContain("ASSEMBLYAI_API_KEY");
+  });
+
+  test("as a VOICE agent, not a workflow app", () => {
+    // The distinction this template exists on: a caller is on the line, so the
+    // run is a handoff. `link-digest` is the other shape.
+    expect(agentDef.page).toBeUndefined();
+    // Discovered, not declared: every name here is a file in `tools/`.
+    expect(Object.keys(agentDef.tools).sort()).toEqual([
+      "cancel_recap",
+      "keep_transcript",
+      "recap_progress",
+      "recap_status",
+      "request_recap",
+    ]);
+  });
+});
+
+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);
+
+    expect(workflows.start).toHaveBeenCalledWith(
+      recap,
+      { url: expect.stringContaining("http"), requestedBy: ctx.sessionId },
+      // `key` is the DURABLE handle — a later call finds the run by it — and
+      // `notify` is the live one: this session is told when the run lands.
+      { key: ctx.sessionId, notify: expect.stringContaining("one-sentence") },
+    );
+    expect(result).toMatchObject({ started: true, runId: "wrun_stub" });
+  });
+
+  test("passes the definition rather than its name", async () => {
+    const workflows = stubWorkflows();
+    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);
+  });
+
+  test("uses the caller's recording when they named one", async () => {
+    const workflows = stubWorkflows();
+    await run(
+      "request_recap",
+      { url: "https://example.com/board.mp3" },
+      createToolContext({ workflows }),
+    );
+    expect(vi.mocked(workflows.start).mock.calls[0]?.[1]).toMatchObject({
+      url: "https://example.com/board.mp3",
+    });
+  });
+
+  test("REFUSES a second run while one is live, and hands back the one that exists", async () => {
+    // Temporal's workflow-id reuse policy, spelled with what this SDK has. The
+    // 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 }));
+    expect(result).toMatchObject({ started: false, runId: "wrun_1" });
+    expect(workflows.start).not.toHaveBeenCalled();
+  });
+
+  test("starts a fresh run once the previous one is terminal", async () => {
+    const workflows = stubWorkflows([
+      createRunSnapshot({ workflow: "recap", status: "completed", output: finishedOutput() }),
+    ]);
+    const result = await run("request_recap", {}, createToolContext({ workflows }));
+    expect(result).toMatchObject({ started: true });
+    expect(workflows.start).toHaveBeenCalledTimes(1);
+  });
+});
+
+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);
+    expect(result).toMatchObject({ runs: [], note: "Nothing started yet." });
+  });
+
+  test("reads back the ONE-SENTENCE version of a finished recap", async () => {
+    // The output carries a `spoken` field for exactly this: the headline and
+    // three points are for an eye, and this tool answers an ear.
+    const workflows = stubWorkflows([
+      createRunSnapshot({ workflow: "recap", status: "completed", output: finishedOutput() }),
+    ]);
+    const result = (await run("recap_status", {}, createToolContext({ workflows }))) as {
+      runs: string[];
+    };
+    expect(result.runs[0]).toContain("air quality");
+  });
+
+  test("names the transcript's fate, so an unanswered gate is not silent", async () => {
+    // The caller who never got round to answering should hear that the
+    // transcript is gone, not just the recap.
+    const runs = [
+      createRunSnapshot({
+        workflow: "recap",
+        status: "completed",
+        output: finishedOutput({ kept: false, answered: false }),
+      }),
+    ];
+    const result = (await run(
+      "recap_status",
+      {},
+      createToolContext({ workflows: stubWorkflows(runs) }),
+    )) as { runs: string[] };
+    expect(result.runs[0]).toContain("transcript deleted");
+  });
+
+  test("reports a live run as still working rather than as empty", async () => {
+    const ctx = createToolContext({
+      workflows: stubWorkflows([createRunSnapshot({ workflow: "recap", status: "running" })]),
+    });
+    const result = (await run("recap_status", {}, ctx)) as { runs: string[] };
+    expect(result.runs[0]).toContain("Still working");
+  });
+
+  test("says a failed run was ROLLED BACK, because it was", async () => {
+    // The saga's whole point, said out loud: the run compensated before it
+    // failed, so there is nothing left on the account and nothing for the caller
+    // to chase.
+    const runs = [
+      createRunSnapshot({ workflow: "recap", status: "failed", error: "provider unavailable" }),
+    ];
+    const result = (await run(
+      "recap_status",
+      {},
+      createToolContext({ workflows: stubWorkflows(runs) }),
+    )) as { runs: string[] };
+    expect(result.runs[0]).toContain("rolled back");
+    expect(result.runs[0]).toContain("provider unavailable");
+  });
+
+  test("bounds how many past runs it reads aloud", async () => {
+    const workflows = stubWorkflows([]);
+    const ctx = createToolContext({ workflows });
+    await run("recap_status", {}, ctx);
+    // A voice reply cannot be a list of twenty runs.
+    expect(workflows.find).toHaveBeenCalledWith(recap, ctx.sessionId, { limit: 3 });
+  });
+});
+
+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 }));
+    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.
+    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 });
+  });
+
+  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.
+    const workflows = stubWorkflows([createRunSnapshot({ workflow: "recap", status: "running" })]);
+    vi.mocked(workflows.streamTail).mockResolvedValue(-1);
+    const result = await run("recap_progress", {}, createToolContext({ workflows }));
+    expect(result).toMatchObject({ note: expect.stringContaining("nothing to report") });
+    expect(workflows.stream).not.toHaveBeenCalled();
+  });
+});
+
+describe("keep_transcript — the signal", () => {
+  test("signals the run's retention hook on the token BOTH sides derive", async () => {
+    // The token is the contract. `workflows/tokens.ts` is the one place it is
+    // spelled, which is what stops the body waiting on a string the tool never
+    // sends — a drift whose only symptom is `signal` answering false.
+    const workflows = stubWorkflows();
+    const signal = vi.fn(async () => true);
+    const ctx = createToolContext({ workflows: { ...workflows, signal } });
+    const result = await run("keep_transcript", { keep: true }, ctx);
+
+    expect(signal).toHaveBeenCalledWith(retentionToken(ctx.sessionId), { keep: true });
+    expect(result).toMatchObject({ answered: true, keep: true });
+  });
+
+  test("carries a DECLINE, not just an approval", async () => {
+    // Three outcomes, and this is the one a boolean gate loses if the tool only
+    // ever signals on yes: "delete it" has to reach the run before the window
+    // closes, or the caller waits two minutes for something they already said.
+    const signal = vi.fn(async () => true);
+    const ctx = createToolContext({ workflows: { ...stubWorkflows(), signal } });
+    await run("keep_transcript", { keep: false }, ctx);
+    expect(signal).toHaveBeenCalledWith(expect.any(String), { keep: false });
+  });
+
+  test("a token nobody holds is reported as SETTLED, not as a failure", async () => {
+    // The ordinary case: the window closed, or the caller answered a question
+    // nobody asked.
+    const signal = vi.fn(async () => false);
+    const ctx = createToolContext({ workflows: { ...stubWorkflows(), signal } });
+    const result = await run("keep_transcript", { keep: true }, ctx);
+    expect(result).toMatchObject({ answered: false, note: expect.stringContaining("settled") });
+  });
+});
+
+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 }));
+    expect(workflows.cancel).toHaveBeenCalledWith("wrun_1");
+    expect(result).toMatchObject({ cancelled: true });
+  });
+
+  test("says the transcript is LEFT BEHIND, because cancellation is not cooperative here", async () => {
+    // The one Temporal behaviour that did not port. Temporal delivers
+    // cancellation into the workflow, so the saga's catch runs; `cancel` here
+    // 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 {
+      note: string;
+    };
+    expect(result.note).toContain("left behind");
+  });
+
+  test("a run that had already finished is reported honestly, not as a failure", async () => {
+    const workflows = stubWorkflows([
+      createRunSnapshot({ workflow: "recap", status: "completed", output: finishedOutput() }),
+    ]);
+    vi.mocked(workflows.cancel).mockResolvedValue(false);
+    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 }));
+    expect(result).toMatchObject({ cancelled: false, note: "Nothing started yet." });
+    expect(workflows.cancel).not.toHaveBeenCalled();
+  });
+});
+
+// ---- The steps --------------------------------------------------------------
+
+/** A provider answering `body` with `status`, recording what it was asked. */
+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;
+}
+
+describe("submitRecording", () => {
+  beforeEach(() => {
+    // `stepEnv` falls back to the process env when no host has published one,
+    // which is exactly the case a spec is. `unstubEnvs` clears it per test.
+    vi.stubEnv("ASSEMBLYAI_API_KEY", "sk-test");
+  });
+
+  test("posts the recording and returns the job id", async () => {
+    const calls = stubProvider({ id: "t_1", status: "queued" });
+    expect(await submitRecording("https://example.com/a.mp3")).toEqual({ id: "t_1" });
+
+    const call = calls[0];
+    expect(call?.init.method).toBe("POST");
+    expect(JSON.parse(String(call?.init.body))).toMatchObject({
+      audio_url: "https://example.com/a.mp3",
+    });
+    // AssemblyAI's `authorization` takes the key RAW — no `Bearer` prefix,
+    // unlike the OpenAI-compatible LLM gateway `summarize` calls.
+    const headers = call?.init.headers as Record<string, string> | undefined;
+    expect(headers?.authorization).toBe("sk-test");
+  });
+
+  test("fails FATALLY on a bad key and plainly on a rate limit", async () => {
+    // The retry policy in one assertion: a 401 answers the same way on the
+    // fourth attempt, a 429 is what retries are for.
+    stubProvider({ error: "nope" }, 401);
+    await expect(submitRecording("https://example.com/a.mp3")).rejects.toThrow(/HTTP 401/);
+    stubProvider({ error: "slow down" }, 429);
+    await expect(submitRecording("https://example.com/a.mp3")).rejects.toThrow(/HTTP 429/);
+  });
+
+  test("refuses a response that names no transcript id", async () => {
+    // Nothing downstream can poll without one, and a run that discovers that at
+    // the first poll has already lost the id it needed to compensate with.
+    stubProvider({ status: "queued" });
+    await expect(submitRecording("https://example.com/a.mp3")).rejects.toThrow(/transcript id/);
+  });
+});
+
+describe("checkTranscript", () => {
+  beforeEach(() => {
+    vi.stubEnv("ASSEMBLYAI_API_KEY", "sk-test");
+  });
+
+  test("reports a completed job with its text and duration", async () => {
+    stubProvider({ status: "completed", text: "Hello there.", audio_duration: 254 });
+    expect(await checkTranscript("t_1")).toEqual({
+      status: "completed",
+      text: "Hello there.",
+      audioDuration: 254,
+    });
+  });
+
+  test("carries the provider's own failure message through", async () => {
+    stubProvider({ status: "error", error: "Transcoding failed" });
+    expect(await checkTranscript("t_1")).toMatchObject({
+      status: "error",
+      error: "Transcoding failed",
+    });
+  });
+
+  test("omits absent fields rather than setting them to undefined", async () => {
+    // `exactOptionalPropertyTypes` makes those different types, and the result
+    // crosses a queue — a key set to `undefined` does not survive the trip.
+    stubProvider({ status: "processing" });
+    expect(Object.keys(await checkTranscript("t_1"))).toEqual(["status"]);
+  });
+
+  test("refuses a status it does not recognise instead of polling forever", async () => {
+    // The loop's exit conditions are `completed` and `error`; an unknown status
+    // is neither, so it would poll to the bound and then fail with the wrong
+    // reason.
+    stubProvider({ status: "transcribing" });
+    await expect(checkTranscript("t_1")).rejects.toThrow(/unknown transcript status/);
+  });
+});
+
+describe("discardTranscript — the compensation", () => {
+  beforeEach(() => {
+    vi.stubEnv("ASSEMBLYAI_API_KEY", "sk-test");
+  });
+
+  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]?.url).toContain("/t_1");
+  });
+
+  test("treats a 404 as success, because an undo must be safe to run twice", async () => {
+    // The property every compensation needs: a replay re-enters a world where
+    // the undo may already have happened, and an undo that fails there would
+    // fail the unwind for having succeeded.
+    stubProvider("", 404);
+    await expect(discardTranscript("t_1")).resolves.toBeUndefined();
+  });
+
+  test("still fails on a real error, so the DevKit retries it", async () => {
+    stubProvider("", 503);
+    await expect(discardTranscript("t_1")).rejects.toThrow(/HTTP 503/);
+  });
+});
+
+describe("summarize", () => {
+  /** A finished transcript, typed rather than cast — the shape a step really gets. */
+  function transcript(over: Partial<TranscriptState> = {}): TranscriptState {
+    return { status: "completed", text: "We talked about smoke.", audioDuration: 254, ...over };
+  }
+
+  beforeEach(() => {
+    vi.stubEnv("ASSEMBLYAI_API_KEY", "sk-test");
+  });
+
+  test("returns the recap the model produced, with the recording's length in minutes", async () => {
+    stubGateway('{"headline":"Smoke","points":["a","b","c"],"spoken":"Smoke drifted east."}');
+    expect(await summarize("https://example.com/a.mp3", transcript())).toEqual({
+      url: "https://example.com/a.mp3",
+      headline: "Smoke",
+      points: ["a", "b", "c"],
+      spoken: "Smoke drifted east.",
+      // Rounded from the provider's seconds — a voice reply says "four minutes",
+      // never "254 seconds".
+      minutes: 4,
+    });
+  });
+
+  test("unwraps a fenced reply rather than failing on it", async () => {
+    stubGateway('```json\n{"headline":"H","points":["a"],"spoken":"S."}\n```');
+    expect((await summarize("https://x/a.mp3", transcript())).headline).toBe("H");
+  });
+
+  test("throws PLAINLY when the model answered with prose, so the step retries", async () => {
+    // The distinction that is the whole retry policy: a model that ignored the
+    // format may well obey on the next attempt, where a 401 will not.
+    stubGateway("Here is a recap of the recording.");
+    // The SDK's message, not this template's: `stepGenerateJson` owns the
+    // unwrap/parse/validate chain now, and a plain throw is what the DevKit
+    // retries.
+    await expect(summarize("https://x/a.mp3", transcript())).rejects.toThrow(/Expected JSON/);
+  });
+
+  test("rejects a reply missing the spoken sentence as firmly as no JSON at all", async () => {
+    // Without it the announced turn has nothing to read, which is the one field
+    // this template's output exists for.
+    stubGateway('{"headline":"H","points":["a"]}');
+    await expect(summarize("https://x/a.mp3", transcript())).rejects.toThrow(/did not match/);
+  });
+
+  test("fails FATALLY on a transcript with no speech in it", async () => {
+    // A completed transcript holds the same nothing on every attempt — silence,
+    // or a file with no speech. Retrying it five times buys nothing.
+    stubGateway('{"headline":"H","points":["a"],"spoken":"S."}');
+    await expect(summarize("https://x/a.mp3", transcript({ text: "   " }))).rejects.toThrow(
+      /no speech/,
+    );
+  });
+
+  test("fails FATALLY with no API key rather than retrying five times", async () => {
+    vi.stubEnv("ASSEMBLYAI_API_KEY", "");
+    stubGateway('{"headline":"H","points":["a"],"spoken":"S."}');
+    await expect(summarize("https://x/a.mp3", transcript())).rejects.toThrow(/ASSEMBLYAI_API_KEY/);
+  });
+
+  test("retries beyond the default, because a rate limit and a bad format both happen", () => {
+    expect(summarize.maxRetries).toBeGreaterThan(3);
+  });
+});
+
+// ---- The body's helpers -----------------------------------------------------
+
+describe("awaitTranscript — the polling port", () => {
+  beforeEach(() => {
+    vi.stubEnv("ASSEMBLYAI_API_KEY", "sk-test");
+  });
+
+  /** 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;
+  }
+
+  test("keeps polling while the job is queued or processing", async () => {
+    const polls = stubStatuses([
+      { status: "queued" },
+      { status: "processing" },
+      { status: "completed", text: "Done.", audio_duration: 60 },
+    ]);
+    const state = await awaitTranscript("t_1");
+    expect(state).toMatchObject({ status: "completed", text: "Done." });
+    expect(polls()).toBe(3);
+  });
+
+  test("stops on the provider's own terminal failure instead of waiting it out", async () => {
+    // `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")).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")).rejects.toThrow(/Gave up/);
+  });
+});
+
+describe("askWhetherToKeep — the expense port", () => {
+  beforeEach(() => {
+    vi.stubEnv("ASSEMBLYAI_API_KEY", "sk-test");
+    // The window has NOT elapsed unless a test says so. A `sleep` that resolves
+    // would race the hook's own answer, and which one won would come down to
+    // microtask order rather than to the branch under test.
+    vi.mocked(sleep).mockReturnValue(new Promise<void>(() => undefined));
+    vi.mocked(createHook).mockReturnValue(hookAnswering(undefined));
+  });
+
+  /**
+   * A hook that resolves with `payload`, or never — which is what the timeout
+   * branch has to see.
+   *
+   * Built by hanging the hook's own members on a REAL promise rather than by
+   * writing a `then` property: a `Hook` is a thenable, and a hand-written one
+   * is both a lint finding and a worse model of the thing.
+   *
+   * `createHook()` throws outside a run, so this is the only way to reach the
+   * gate's branching at all. What it pins is the three OUTCOMES and the safe
+   * default; suspension, token registration and replay are not testable here
+   * and are not claimed to be.
+   */
+  function hookAnswering(
+    payload: { keep: boolean } | undefined,
+    onClaim: () => void = () => undefined,
+  ): Hook<{ keep: boolean }> {
+    const settled: Promise<{ keep: boolean }> =
+      payload === undefined ? new Promise(() => undefined) : Promise.resolve(payload);
+    return Object.assign(settled, {
+      token: "retention:stub",
+      getConflict: async () => {
+        onClaim();
+        return null;
+      },
+      dispose: () => undefined,
+      [Symbol.dispose]: () => undefined,
+      [Symbol.asyncIterator]: async function* () {
+        yield await settled;
+      },
+    });
+  }
+
+  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 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();
+    // The undo stays on the stack: a later failure still has something to reverse.
+    expect(compensations).toHaveLength(1);
+  });
+
+  test("deletes on a DECLINE, and drops the undo it just performed", async () => {
+    vi.mocked(createHook).mockReturnValue(hookAnswering({ keep: false }));
+    const calls = stubProvider({ id: "t_1" });
+
+    const compensations = [{ label: "transcript t_1", undo: async () => undefined }];
+    expect(await askWhetherToKeep("s_1", "t_1", compensations)).toEqual({
+      kept: false,
+      answered: true,
+    });
+    expect(calls[0]?.init.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);
+  });
+
+  test("DELETES when nobody answers, which is what makes the window mean anything", async () => {
+    // The safe default, and the whole reason the gate is a gate: a no-answer
+    // branch that kept the data would be a prompt with a grace period.
+    vi.mocked(sleep).mockResolvedValue(undefined);
+    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");
+  });
+
+  test("claims the token BEFORE the caller is asked to answer it", async () => {
+    // `createHook()` registers nothing until the workflow suspends, so an answer
+    // sent before the claim lands is answered "nobody is listening" — which is
+    // indistinguishable from being late.
+    const order: string[] = [];
+    vi.mocked(createHook).mockReturnValue(
+      hookAnswering({ keep: true }, () => order.push("claimed")),
+    );
+    vi.stubGlobal(
+      "fetch",
+      vi.fn(async () => {
+        order.push("asked");
+        return new Response("{}", { status: 200 });
+      }),
+    );
+
+    await askWhetherToKeep("s_1", "t_1", []);
+    expect(order[0]).toBe("claimed");
+  });
+});
+
+describe("compensate — the saga port", () => {
+  test("unwinds newest-first, which is the order acquisitions were stacked in", async () => {
+    // `recapFlow` pushes with `unshift`, so the list is already newest-first and
+    // this walks it forwards. A dependency acquired later has to come off first.
+    const order: string[] = [];
+    await compensate(
+      [
+        { label: "second", undo: async () => void order.push("second") },
+        { label: "first", undo: async () => void order.push("first") },
+      ],
+      "because",
+    );
+    expect(order).toEqual(["second", "first"]);
+  });
+
+  test("a failing undo does not stop the ones behind it", async () => {
+    // Ported deliberately from Temporal's `compensate`, which swallows: the run
+    // already failed for a reason the caller needs, and a second-order undo
+    // failure must not replace it or strand the rest of the stack.
+    const order: string[] = [];
+    await expect(
+      compensate(
+        [
+          {
+            label: "broken",
+            undo: async () => {
+              throw new Error("the provider declined the delete");
+            },
+          },
+          { label: "fine", undo: async () => void order.push("fine") },
+        ],
+        "because",
+      ),
+    ).resolves.toBeUndefined();
+    expect(order).toEqual(["fine"]);
+  });
+
+  test("does nothing at all when nothing was acquired", async () => {
+    // The case where the FIRST step failed: there is nothing to reverse, and a
+    // run that narrated an unwind it did not perform would be lying to the
+    // caller reading its progress.
+    await expect(compensate([], "nothing was acquired")).resolves.toBeUndefined();
+  });
+});