@alexkroman1/aai-cli 6.10.1 → 7.0.0

package/dist/templates/solo-rpg/tools/save_game.ts

@@ -1,17 +1,26 @@
 import { z } from "zod";
-import { gameSlot, saveSlotKey, saveSlotParam, saveState } from "../shared.ts";
+import { gameSlot, saveSlotKey, saveSlotParam, saveState, storyFlow } from "../shared.ts";
 
 // Requires storage — `aai storage enable` (or DATABASE_URL in .env under
 // `aai dev`); the rest of the game works without it.
 //
-// `gameSlot.tool` even though the body AWAITS: the reading half places no
-// constraint on the body (only `updateTool` must be synchronous, because its
-// draft is stored when it returns). What it does place is the frozen value, and
-// a save is the purest read there is.
-export default gameSlot.tool({
+/**
+ * Gated on `playing` or `gameOver` — i.e. anything but `awaitingSetup`.
+ *
+ * Saving before a character exists writes an empty campaign under a slot name,
+ * and `load_game` would then cheerfully restore it over a real game. That is a
+ * position, so it is a `when`.
+ *
+ * The body AWAITS, which a flow tool allows: only `slot.updateTool` must be
+ * synchronous, because its draft is stored when it returns. What a save needs is
+ * the frozen value, and `gameSlot.get` is what hands it over.
+ */
+export default storyFlow.tool({
   description: "Save current game to persistent storage.",
   inputSchema: z.object({ slot: saveSlotParam }),
-  async execute(args, game, ctx) {
+  when: ["playing", "gameOver"],
+  async execute(args, ctx) {
+    const game = gameSlot.get(ctx);
     await saveState(ctx, saveSlotKey(args.slot), game);
     return {
       saved: true,

package/dist/templates/solo-rpg/tools/setup_character.ts

@@ -14,10 +14,24 @@ import {
   makeNpc,
   shuffle,
   stateSummary,
+  storyFlow,
   TIME_PHASES,
   TONES,
 } from "../shared.ts";
 
+/**
+ * **Not a `storyFlow.tool`, deliberately.** Setting up is legal in every state —
+ * a player may start over at any point, an ended story included — so a `when`
+ * listing all of them would be a gate that gates nothing. It drives the flow
+ * itself, which is what `dialog.reset` and `dialog.send` are public for, and reports
+ * the position it landed in so the narrator reads what the opening turn expects.
+ *
+ * **`reset` before `send`, because a restart is not a transition.** This body
+ * replaces the campaign with a pristine `DEFAULT_STATE`; resetting the flow is
+ * the same statement on the other side, and it is what makes starting over work
+ * from `gameOver` — a final state delivers no events, so a `SETUP` transition
+ * out of it would be dead config.
+ */
 export default tool({
   description:
     "Set up the entire game in one call. Starts a completely fresh game (any previous unsaved game is replaced), generates stats, initializes state, and marks the game as ready. After this returns, just narrate the opening scene. No need to call update_state — everything is already done.",
@@ -186,12 +200,16 @@ export default tool({
       storyComplete: false,
     };
 
-    // Mark initialized
+    // Mark initialized. `initialized` is the CLIENT's render flag; the flow is
+    // what gates the tools, and `SETUP` is what puts it in `playing` — so the
+    // roll tools become available in the same call that gives them stats to
+    // roll against.
     state.initialized = true;
-    state.phase = "playing";
     state.sceneCount = 1;
 
     gameSlot.set(ctx, state);
+    storyFlow.reset(ctx);
+    const at = storyFlow.send(ctx, { type: "SETUP" });
 
     return {
       success: true,
@@ -201,6 +219,8 @@ export default tool({
       archetypeLabel: ARCHETYPES[args.archetype as keyof typeof ARCHETYPES] || args.archetype,
       openingSituation: args.openingSituation,
       creativitySeed: creativitySeed(),
+      // The position spread verbatim — the same keys every gated tool reports.
+      ...at,
       // The real saved state — never hardcoded values
       ...stateSummary(state),
     };

package/dist/templates/solo-rpg/tools/update_state.ts

@@ -15,13 +15,23 @@ import {
   makeNpc,
   nextSeqId,
   stateSummary,
+  storyFlow,
   TIME_PHASES,
-  updateCrisisFlags,
 } from "../shared.ts";
 
-export default gameSlot.updateTool({
+/**
+ * Gated on `playing`: there is nothing to sync before a character exists (that
+ * is `setup_character`'s whole job, and the prompt says not to call this after
+ * it), and nothing to sync after the story has ended.
+ *
+ * It sends `SETTLED`, because moving the scene on is what SPENDS a standing
+ * roll: once the narrator has changed the location or logged the scene, the
+ * player's window to burn momentum on the last roll has closed.
+ */
+export default storyFlow.tool({
   description:
     "Lightweight state sync for during gameplay. Handles location changes, NPC additions, clock additions, time changes, and session log entries. Resource changes (health/spirit/supply/momentum) are auto-applied by action_roll — only use those fields here for manual adjustments like resting or trading. Pass only what changed.",
+  when: "playing",
   inputSchema: z.object({
     location: z.string().max(200).describe("New location name").optional(),
     locationDesc: z.string().max(500).describe("Short location description").optional(),
@@ -54,117 +64,120 @@ export default gameSlot.updateTool({
     storyComplete: z.boolean().describe("Mark story as complete").optional(),
     logEntry: z.string().max(500).describe("Short log entry for this scene").optional(),
   }),
-  execute(args, state) {
-    const warnings: string[] = [];
-    const clockEvents: { clock: string; trigger: string }[] = [];
+  execute: (args, ctx) =>
+    gameSlot.update(ctx, (state) => {
+      const warnings: string[] = [];
+      const clockEvents: { clock: string; trigger: string }[] = [];
 
-    // Resources
-    if (args.health !== undefined) state.health = Math.max(0, Math.min(MAX_RESOURCE, args.health));
-    if (args.spirit !== undefined) state.spirit = Math.max(0, Math.min(MAX_RESOURCE, args.spirit));
-    if (args.supply !== undefined) state.supply = Math.max(0, Math.min(MAX_RESOURCE, args.supply));
-    if (args.momentum !== undefined)
-      state.momentum = Math.max(MIN_MOMENTUM, Math.min(state.maxMomentum, args.momentum));
+      // Resources
+      if (args.health !== undefined)
+        state.health = Math.max(0, Math.min(MAX_RESOURCE, args.health));
+      if (args.spirit !== undefined)
+        state.spirit = Math.max(0, Math.min(MAX_RESOURCE, args.spirit));
+      if (args.supply !== undefined)
+        state.supply = Math.max(0, Math.min(MAX_RESOURCE, args.supply));
+      if (args.momentum !== undefined)
+        state.momentum = Math.max(MIN_MOMENTUM, Math.min(state.maxMomentum, args.momentum));
 
-    // Location
-    if (args.location !== undefined) state.currentLocation = args.location;
-    if (args.locationDesc !== undefined) state.currentSceneContext = args.locationDesc;
-    if (args.timeOfDay !== undefined) state.timeOfDay = args.timeOfDay;
+      // Location
+      if (args.location !== undefined) state.currentLocation = args.location;
+      if (args.locationDesc !== undefined) state.currentSceneContext = args.locationDesc;
+      if (args.timeOfDay !== undefined) state.timeOfDay = args.timeOfDay;
 
-    // Add NPC
-    if (args.addNpcName) {
-      if (state.npcs.length >= MAX_NPCS) {
-        warnings.push(
-          `NPC limit of ${MAX_NPCS} reached — mark an existing NPC deceased or background instead.`,
-        );
-      } else {
-        state.npcs.push(
-          makeNpc({
-            id: nextSeqId(state.npcs, "npc"),
-            name: args.addNpcName,
-            description: args.addNpcDesc,
-            disposition: args.addNpcDisposition,
-            agenda: args.addNpcAgenda,
-          }),
-        );
+      // Add NPC
+      if (args.addNpcName) {
+        if (state.npcs.length >= MAX_NPCS) {
+          warnings.push(
+            `NPC limit of ${MAX_NPCS} reached — mark an existing NPC deceased or background instead.`,
+          );
+        } else {
+          state.npcs.push(
+            makeNpc({
+              id: nextSeqId(state.npcs, "npc"),
+              name: args.addNpcName,
+              description: args.addNpcDesc,
+              disposition: args.addNpcDisposition,
+              agenda: args.addNpcAgenda,
+            }),
+          );
+        }
       }
-    }
 
-    // Update NPC
-    if (args.updateNpcId) {
-      const npc = state.npcs.find((n) => n.id === args.updateNpcId);
-      if (npc) {
-        if (args.updateNpcDisposition !== undefined) npc.disposition = args.updateNpcDisposition;
-        if (args.updateNpcBond !== undefined) npc.bond = args.updateNpcBond;
-        if (args.updateNpcStatus !== undefined) npc.status = args.updateNpcStatus;
-      } else {
-        warnings.push(`No NPC with id ${args.updateNpcId}.`);
+      // Update NPC
+      if (args.updateNpcId) {
+        const npc = state.npcs.find((n) => n.id === args.updateNpcId);
+        if (npc) {
+          if (args.updateNpcDisposition !== undefined) npc.disposition = args.updateNpcDisposition;
+          if (args.updateNpcBond !== undefined) npc.bond = args.updateNpcBond;
+          if (args.updateNpcStatus !== undefined) npc.status = args.updateNpcStatus;
+        } else {
+          warnings.push(`No NPC with id ${args.updateNpcId}.`);
+        }
       }
-    }
 
-    // Add clock
-    if (args.addClockName) {
-      if (state.clocks.length >= MAX_CLOCKS) {
-        warnings.push(`Clock limit of ${MAX_CLOCKS} reached — remove a finished clock first.`);
-      } else {
-        state.clocks.push({
-          id: nextSeqId(state.clocks, "clock"),
-          name: args.addClockName,
-          clockType: args.addClockType ?? "threat",
-          segments: args.addClockSegments ?? DEFAULT_CLOCK_SEGMENTS,
-          filled: 0,
-          triggerDescription: args.addClockTrigger ?? "",
-        });
+      // Add clock
+      if (args.addClockName) {
+        if (state.clocks.length >= MAX_CLOCKS) {
+          warnings.push(`Clock limit of ${MAX_CLOCKS} reached — remove a finished clock first.`);
+        } else {
+          state.clocks.push({
+            id: nextSeqId(state.clocks, "clock"),
+            name: args.addClockName,
+            clockType: args.addClockType ?? "threat",
+            segments: args.addClockSegments ?? DEFAULT_CLOCK_SEGMENTS,
+            filled: 0,
+            triggerDescription: args.addClockTrigger ?? "",
+          });
+        }
       }
-    }
 
-    // Advance clock
-    if (args.advanceClockName) {
-      const clock = state.clocks.find((c) => c.name === args.advanceClockName);
-      if (clock && clock.filled < clock.segments) {
-        clock.filled = Math.min(clock.segments, clock.filled + 1);
-        if (clock.filled >= clock.segments) {
-          clockEvents.push({ clock: clock.name, trigger: clock.triggerDescription });
+      // Advance clock
+      if (args.advanceClockName) {
+        const clock = state.clocks.find((c) => c.name === args.advanceClockName);
+        if (clock && clock.filled < clock.segments) {
+          clock.filled = Math.min(clock.segments, clock.filled + 1);
+          if (clock.filled >= clock.segments) {
+            clockEvents.push({ clock: clock.name, trigger: clock.triggerDescription });
+          }
         }
       }
-    }
-
-    // Remove clock
-    if (args.removeClockName) {
-      state.clocks = state.clocks.filter((c) => c.name !== args.removeClockName);
-    }
 
-    // Story arc
-    if (args.advanceAct && state.storyBlueprint) {
-      state.storyBlueprint.currentAct = Math.min(
-        state.storyBlueprint.acts.length,
-        state.storyBlueprint.currentAct + 1,
-      );
-    }
-    if (args.storyComplete && state.storyBlueprint) {
-      state.storyBlueprint.storyComplete = true;
-    }
+      // Remove clock
+      if (args.removeClockName) {
+        state.clocks = state.clocks.filter((c) => c.name !== args.removeClockName);
+      }
 
-    // Session log
-    if (args.logEntry) {
-      pushCapped(
-        state.sessionLog,
-        {
-          scene: state.sceneCount,
-          summary: args.logEntry,
-          location: state.currentLocation,
-        },
-        MAX_SESSION_LOG,
-      );
-    }
+      // Story arc
+      if (args.advanceAct && state.storyBlueprint) {
+        state.storyBlueprint.currentAct = Math.min(
+          state.storyBlueprint.acts.length,
+          state.storyBlueprint.currentAct + 1,
+        );
+      }
+      if (args.storyComplete && state.storyBlueprint) {
+        state.storyBlueprint.storyComplete = true;
+      }
 
-    // Crisis check
-    updateCrisisFlags(state);
+      // Session log
+      if (args.logEntry) {
+        pushCapped(
+          state.sessionLog,
+          {
+            scene: state.sceneCount,
+            summary: args.logEntry,
+            location: state.currentLocation,
+          },
+          MAX_SESSION_LOG,
+        );
+      }
 
-    return {
-      success: true,
-      ...(warnings.length > 0 ? { warnings } : {}),
-      clockEvents,
-      ...stateSummary(state),
-    };
-  },
+      return {
+        success: true,
+        ...(warnings.length > 0 ? { warnings } : {}),
+        clockEvents,
+        ...stateSummary(state),
+      };
+    }),
+  sendFrom: (result) =>
+    result.gameOver ? { type: "DOWNED" as const } : { type: "SETTLED" as const },
 });

package/dist/templates/spoken-summary/agent.test.ts

@@ -0,0 +1,314 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * Specs for the spoken-summary app's declaration and its four legs.
+ *
+ * **The body itself is not driven here**, and that is a property of what a
+ * workflow template demonstrates rather than a gap: imported through vitest
+ * with no bundler in the path, a `"use step"` function is an ordinary async
+ * function — so its HTTP handling, its fatal/retryable classification and what
+ * it returns are all testable, while durability, suspension and replay are not.
+ * A body test that looked like a durability test would be the worse failure;
+ * the real thing is exercised end to end by `aai-cli`'s
+ * `dev-workflow.scenario.test.ts`.
+ *
+ * The two legs worth their own sections are the ones the SDK grew for this
+ * template. `speak` is where a step SPEAKS and STORES, and the assertion that
+ * matters is that it returns an id rather than bytes — a step is journaled by
+ * its return value, and audio in one is megabytes replayed on every resume.
+ */
+
+import { readUpload, uploadInfo } from "@alexkroman1/aai/step";
+import {
+  installStubGateway,
+  installStubReporter,
+  installStubSpeech,
+  installStubTranscribe,
+  installStubUploads,
+} from "@alexkroman1/aai/testing/vitest";
+import { beforeEach, describe, expect, test, vi } from "vitest";
+import { FatalError, RetryableError } from "workflow";
+import agentDef, { spokenSummary } from "./agent.ts";
+import { speak, spokenSummaryFlow, summarize } from "./workflows/summarize.ts";
+import { createJob, pollTranscript, uploadToProvider } from "./workflows/transcribe.ts";
+
+/** The id every spec below uploads under. */
+const UPLOAD_ID = "upl_test";
+
+beforeEach(() => {
+  // WRITABLE, because this app's whole second half stores a file — and it is
+  // opt-in precisely so a step that wrote one nobody meant it to would fail.
+  // `install*` rather than `stub*`: the fake registers its own `onTestFinished`,
+  // which is what replaced the hand-kept restore registry this file used to hold.
+  installStubUploads(
+    { [UPLOAD_ID]: { bytes: new Uint8Array(64), name: "standup.wav", type: "audio/wav" } },
+    { writable: true },
+  );
+  // The step env, which is where `requireStepEnv` and `stepSpeak` read the key.
+  // `vi.stubEnv` rather than an assignment: `unstubEnvs` undoes it before every
+  // test, so nothing here has to remember to put it back.
+  vi.stubEnv("ASSEMBLYAI_API_KEY", "test-key");
+});
+
+describe("the declaration", () => {
+  test("is a workflow app with the one workflow the page starts by name", () => {
+    // The page calls `api.start("spokenSummary", …)`, so a rename here is a
+    // runtime 400 rather than a compile error. This is what pins it.
+    expect(Object.keys(agentDef.workflows ?? {})).toEqual(["spokenSummary"]);
+    expect(agentDef.page).toBe("static");
+  });
+
+  test("declares no providers and exactly the one credential its steps read", () => {
+    // A workflow app has no session, so nothing else in its config could name
+    // one — and one AssemblyAI key covers transcription, the model and the voice.
+    expect(agentDef.requiredEnv).toEqual(["ASSEMBLYAI_API_KEY"]);
+  });
+
+  test("takes the recording as an UPLOAD, which is what makes the form a file picker", () => {
+    expect(spokenSummary.uploads).toEqual(["recording"]);
+  });
+
+  test("offers real voice ids, so the synthesis cannot fail silently in band", async () => {
+    const parsed = spokenSummary.input?.["~standard"].validate({
+      recording: UPLOAD_ID,
+      voice: "not-a-voice",
+    });
+
+    expect((await parsed)?.issues).toBeTruthy();
+    expect(
+      (await spokenSummary.input?.["~standard"].validate({ recording: UPLOAD_ID, voice: "jane" }))
+        ?.issues,
+    ).toBeUndefined();
+  });
+});
+
+describe("transcribing", () => {
+  test("streams the stored recording to the provider and keeps the URL it answered", async () => {
+    const provider = installStubTranscribe({ audioUrl: "https://cdn/aai/1" });
+    installStubReporter();
+
+    await expect(uploadToProvider(UPLOAD_ID)).resolves.toEqual({
+      audioUrl: "https://cdn/aai/1",
+    });
+    expect(provider.calls[0]?.leg).toBe("upload");
+    // The bytes really went, and they went as the file rather than as JSON.
+    expect(provider.calls[0]?.body?.length).toBe(64);
+  });
+
+  test("a 429 from the provider is RETRYABLE and a 400 is not", async () => {
+    const first = installStubTranscribe({ failure: { status: 429, message: "slow down" } });
+    installStubReporter();
+    await expect(createJob("https://cdn/aai/1")).rejects.toBeInstanceOf(RetryableError);
+    // Unpublished by hand: this is a boundary WITHIN one test, which the
+    // per-test auto-restore cannot give.
+    first.restore();
+
+    installStubTranscribe({ failure: { status: 400, message: "bad model" } });
+    await expect(createJob("https://cdn/aai/1")).rejects.toBeInstanceOf(FatalError);
+  });
+
+  test("a job the provider gave up on is FATAL — no number of polls changes it", async () => {
+    installStubTranscribe({ jobError: "corrupt audio" });
+
+    await expect(pollTranscript(UPLOAD_ID, "t_1")).rejects.toThrow("corrupt audio");
+    await expect(pollTranscript(UPLOAD_ID, "t_1")).rejects.toBeInstanceOf(FatalError);
+  });
+
+  test("`done` is decided here, so the body never reads a provider's vocabulary", async () => {
+    installStubTranscribe({ pendingPolls: 1 });
+
+    await expect(pollTranscript(UPLOAD_ID, "t_1")).resolves.toEqual({ done: false });
+  });
+
+  test("a finished poll carries the transcript, named by the FILENAME", async () => {
+    // ONE request, not two: this used to poll for a status and then fetch the
+    // identical URL again for the text the poll already had in its hand.
+    const provider = installStubTranscribe({ text: "  we shipped it  ", durationSec: 12.4 });
+    installStubReporter();
+
+    await expect(pollTranscript(UPLOAD_ID, "t_1")).resolves.toEqual({
+      done: true,
+      transcript: { source: "standup.wav", durationMs: 12_400, text: "we shipped it" },
+    });
+    expect(provider.calls).toHaveLength(1);
+  });
+
+  test("a recording of silence is FATAL rather than an empty summary", async () => {
+    // The failure this template is most likely to meet: silence transcribes
+    // successfully to nothing, and everything downstream would then be asked to
+    // summarize and speak no words at all.
+    installStubTranscribe({ text: "   ", durationSec: 3 });
+
+    await expect(pollTranscript(UPLOAD_ID, "t_1")).rejects.toThrow("no speech in that recording");
+    await expect(pollTranscript(UPLOAD_ID, "t_1")).rejects.toBeInstanceOf(FatalError);
+  });
+});
+
+describe("summarizing", () => {
+  test("asks the model for a spoken script as well as points, and keeps both", async () => {
+    const calls = installStubGateway(
+      JSON.stringify({
+        headline: "Launch is on",
+        points: ["Ship Tuesday", "Two bugs left"],
+        spoken: "The launch is on for Tuesday, with two bugs still open.",
+      }),
+    );
+    installStubReporter();
+
+    const summary = await summarize("we ship tuesday");
+
+    expect(summary.headline).toBe("Launch is on");
+    expect(summary.points).toEqual(["Ship Tuesday", "Two bugs left"]);
+    expect(summary.spoken).toBe("The launch is on for Tuesday, with two bugs still open.");
+    // The prompt really carries the transcript, and really asks for the two
+    // shapes — a page that got bullets read aloud is the failure this prevents.
+    expect(calls[0]?.prompt).toContain("we ship tuesday");
+    expect(calls[0]?.prompt).toContain("READ ALOUD");
+  });
+
+  test("caps the points at what the schema promises the page", async () => {
+    installStubGateway(
+      JSON.stringify({
+        headline: "Many things",
+        points: ["a", "b", "c", "d", "e", "f"],
+        spoken: "Several things happened.",
+      }),
+    );
+    installStubReporter();
+
+    expect((await summarize("…")).points).toHaveLength(4);
+  });
+
+  test("a reply with no spoken script FAILS rather than defaulting to silence", async () => {
+    installStubGateway(JSON.stringify({ headline: "Launch is on", points: ["Ship Tuesday"] }));
+    installStubReporter();
+
+    await expect(summarize("…")).rejects.toThrow(/did not match the shape/);
+  });
+});
+
+describe("speaking", () => {
+  test("stores a WAV and returns its ID — never the bytes", async () => {
+    const speech = installStubSpeech({ pcmBytes: 48_000 });
+    installStubReporter();
+
+    const spoken = await speak("The launch is on for Tuesday.");
+
+    // An id, because a step is journaled by its return value: audio in one is
+    // megabytes replayed on every resume.
+    expect(spoken).toEqual({ audio: "upl_stub_1", durationMs: 1000 });
+    expect(speech.calls[0]?.text).toBe("The launch is on for Tuesday.");
+  });
+
+  test("what it stored is a real WAV, named and typed for the browser", async () => {
+    installStubSpeech({ pcmBytes: 4000 });
+    installStubReporter();
+
+    const { audio } = await speak("Hello.");
+
+    await expect(uploadInfo(audio)).resolves.toMatchObject({
+      name: "summary.wav",
+      // The byte route serves this as `Content-Type`, and a browser will not
+      // play inline a file it was handed as octet-stream.
+      type: "audio/wav",
+      size: 44 + 4000,
+    });
+    const { bytes } = await readUpload(audio, { end: 12 });
+    expect(String.fromCharCode(...bytes.subarray(0, 4))).toBe("RIFF");
+    expect(String.fromCharCode(...bytes.subarray(8, 12))).toBe("WAVE");
+  });
+
+  test("passes a chosen voice through, and omits it entirely when none was chosen", async () => {
+    const speech = installStubSpeech();
+    installStubReporter();
+
+    await speak("Hello.", "michael");
+    await speak("Hello.");
+
+    expect(speech.calls[0]?.voice).toBe("michael");
+    // The SDK's own default, not one this template restates.
+    expect(speech.calls[1]?.voice).toBe("jane");
+  });
+});
+
+describe("the whole run", () => {
+  /**
+   * Answer every leg's HTTP, so the BODY can be driven end to end.
+   *
+   * Imported through vitest with no bundler in the path, a `"use workflow"`
+   * function is an ordinary async function — so what this exercises is the
+   * ORDER the legs are wired in and the shape they hand each other, which is
+   * the one thing the per-leg specs above cannot see. Durability, suspension
+   * and replay are not testable here and are not what this claims.
+   *
+   * The job answers `completed` on its FIRST poll, deliberately: a second poll
+   * would reach the durable `sleep`, which outside a real run is not a wait
+   * this spec should be taking.
+   *
+   * **The model call goes through this too, not `installStubGateway`.** A
+   * published `stepFetch` is what `stepGenerate` makes its request with, so a
+   * global-fetch stub is never reached once one exists — which is exactly the
+   * point a published `stepFetch` exists to make, and exactly why
+   * `stubTranscribe` takes an `otherwise`: publishing REPLACES, so a flow that
+   * transcribes AND calls a model cannot install two fakes.
+   *
+   * The three transcription legs are the SDK's fake rather than this file's
+   * hand-typed wire — it routes them off the SDK's own endpoint constants, so a
+   * spec cannot pass because the fake and the step agree on a typo.
+   */
+  function stubProvider(reply: { headline: string; points: string[]; spoken: string }) {
+    return installStubTranscribe({
+      audioUrl: "https://cdn/aai/1",
+      jobIdPrefix: "t_",
+      text: "we ship tuesday and two bugs are left",
+      durationSec: 42,
+      otherwise: (request) =>
+        request.url.includes("llm-gateway")
+          ? { body: { choices: [{ message: { content: JSON.stringify(reply) } }] } }
+          : undefined,
+    });
+  }
+
+  test("transcribes, summarizes, speaks, and reports the file it made", async () => {
+    stubProvider({
+      headline: "Launch is on",
+      points: ["Ship Tuesday"],
+      spoken: "The launch is on for Tuesday.",
+    });
+    installStubReporter();
+    installStubSpeech();
+
+    const summary = await spokenSummaryFlow({ recording: UPLOAD_ID });
+
+    expect(summary).toEqual({
+      source: "standup.wav",
+      durationMs: 42_000,
+      words: 8,
+      headline: "Launch is on",
+      points: ["Ship Tuesday"],
+      spoken: "The launch is on for Tuesday.",
+      transcript: "we ship tuesday and two bugs are left",
+      // The output carries an ID, never the audio — the rule the whole
+      // template exists to demonstrate.
+      audio: "upl_stub_1",
+      audioDurationMs: 250,
+    });
+  });
+
+  test("the voice the form chose reaches the synthesizer", async () => {
+    stubProvider({ headline: "Launch is on", points: ["Ship Tuesday"], spoken: "Spoken." });
+    installStubReporter();
+    const speech = installStubSpeech();
+
+    await spokenSummaryFlow({ recording: UPLOAD_ID, voice: "michael" });
+
+    expect(speech.calls[0]).toMatchObject({ text: "Spoken.", voice: "michael" });
+  });
+
+  test("a recording the provider gave up on fails the run rather than half-summarizing", async () => {
+    installStubTranscribe({ jobError: "corrupt audio" });
+    installStubReporter();
+    installStubSpeech();
+
+    await expect(spokenSummaryFlow({ recording: UPLOAD_ID })).rejects.toThrow("corrupt audio");
+  });
+});