@alexkroman1/aai-cli 6.10.1 → 7.0.0

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

@@ -0,0 +1,155 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * A WORKFLOW APP that goes audio in, audio out: upload a recording and it comes
+ * back with a summary you can read AND one you can listen to.
+ *
+ * `link-digest` is the template to read first: it owns the shape —
+ * `workflowApp()`, no session, no tools, a form that starts a run and a page
+ * that watches it — and none of that is restated here. `transcription-workflow`
+ * owns the other half of the background: uploads, and what it costs to cut a
+ * long recording up. What THIS one adds is the return trip.
+ *
+ * ```text
+ *   a WAV  →  transcript  →  summary  →  a WAV of the summary
+ *              async STT     LLM Gateway   streaming TTS
+ * ```
+ *
+ * ## The last arrow is the one that needed the SDK to grow
+ *
+ * The first three are ordinary step work. The fourth was impossible until two
+ * things existed, and they are what this template is the reference use of:
+ *
+ * - **`stepSpeak`** (`@alexkroman1/aai/step`) synthesizes from inside a step.
+ *   The session TTS surface cannot be used here at all: a `TtsSession` is an
+ *   event stream wired into a live pipeline's playback, with a turn tracker and
+ *   barge-in behind it, and a step has no turn to be part of and has to return
+ *   a VALUE.
+ * - **`writeUpload`** (same subpath) puts that value where a browser can reach
+ *   it. A run's OUTPUT is read back as JSON, so audio cannot travel in one —
+ *   the same rule that keeps a recording's bytes out of a run's INPUT, arriving
+ *   at the other end of the run.
+ *
+ * And **`api.download(id)`** is the browser half: the run's output names an
+ * upload id, and the page turns it into a `Blob` it can play and offer as a
+ * file. `workflows/summarize.ts` carries the rest, including why the model is
+ * asked for a spoken script as well as a bullet list.
+ *
+ * ## What it needs
+ *
+ * - **`ASSEMBLYAI_API_KEY` in the agent env** — `.env` under `aai dev`,
+ *   `aai secret put ASSEMBLYAI_API_KEY` once deployed. One key covers all
+ *   three services this uses: transcription, the LLM Gateway, and the voice.
+ *   `requiredEnv` below is what makes a deploy check for it rather than letting
+ *   the first run find out.
+ * - **Storage** (`aai storage enable`, Settings → Database in the studio, or
+ *   `DATABASE_URL` under `aai dev`). REQUIRED here, and more so than for most
+ *   workflow apps: an upload's record is a row, and this app uses uploads at
+ *   BOTH ends — the recording coming in and the summary going out.
+ *
+ * ## The recording is UPLOADED, and the run carries its id
+ *
+ * A workflow's input is journaled and replayed on every resume, so a
+ * recording's BYTES cannot live in it. So the file goes to
+ * `POST /workflows/uploads` (the browser does this for you: `uploads` below is
+ * what makes `<WorkflowFields>` render a file picker, and `useWorkflowSubmit`
+ * stores the file before starting the run), the input carries the returned id,
+ * and the step that needs the bytes streams them out with `readUpload`.
+ *
+ * ## It is scriptable, which is the other half of having an API
+ *
+ * The page is one caller. Three requests do the whole thing from a shell —
+ * upload, start a run, then fetch the summary's audio by the id the run
+ * reported:
+ *
+ * ```sh
+ * ID=$(curl -s -X POST "https://<your-agent>/workflows/uploads?name=standup.wav" \
+ *   -H 'content-type: audio/wav' --data-binary @standup.wav | jq -r .id)
+ *
+ * OUT=$(curl -s -X POST https://<your-agent>/workflows/runs \
+ *   -H 'content-type: application/json' \
+ *   -d "{\"workflow\":\"spokenSummary\",\"wait\":30000,\"input\":{\"recording\":\"$ID\"}}")
+ *
+ * curl -s "https://<your-agent>/workflows/uploads/$(echo "$OUT" | jq -r .run.output.audio)" \
+ *   -o summary.wav
+ * ```
+ */
+
+import { workflow, workflowApp } from "@alexkroman1/aai";
+import { ASSEMBLYAI_TTS_DEFAULT_VOICE, ASSEMBLYAI_TTS_VOICES } from "@alexkroman1/aai/tts";
+import type { WorkflowDef } from "@alexkroman1/aai/workflow-api";
+import { z } from "zod";
+import { type SpokenSummary, spokenSummaryFlow } from "./workflows/summarize.ts";
+
+/**
+ * The voices the form offers.
+ *
+ * READ from the SDK's catalog rather than listed, because a wrong voice id is a
+ * SILENT failure — it is a free-form string the service rejects in band after
+ * the socket is open, so the synthesis simply produces nothing. Narrowed to the
+ * English ones because the summary is written in the transcript's language and
+ * the prompt does not translate; every voice in the catalog speaks exactly one.
+ */
+const VOICES = Object.entries(ASSEMBLYAI_TTS_VOICES)
+  .filter(([, spec]) => spec.language === "en")
+  .map(([id]) => id);
+
+/**
+ * The same list as a TUPLE, which is what `z.enum` takes.
+ *
+ * Destructured rather than cast: a `.map` produces an array, and
+ * `as [string, ...string[]]` would be a template teaching a cast. The default
+ * covers the empty case honestly — a catalog with no English voice falls back
+ * to the SDK's own default rather than rendering a picker with no options.
+ */
+const [FIRST_VOICE = ASSEMBLYAI_TTS_DEFAULT_VOICE, ...OTHER_VOICES] = VOICES;
+
+/**
+ * The run input, as its own const.
+ *
+ * Named rather than inline because {@link spokenSummary} carries an explicit
+ * type, and that annotation is what lets `workflows/summarize.ts` name
+ * `WorkflowInputOf<typeof spokenSummary>` for its body's parameter: the body's
+ * own signature would otherwise be part of what infers this declaration's type,
+ * and TypeScript refuses the cycle (`TS7022`).
+ */
+const spokenSummaryInput = z.object({
+  // A plain string, because an upload id is what the run really receives.
+  // What makes it a file picker rather than a text box is the `uploads` line
+  // below.
+  recording: z.string().describe("A recording to summarize — WAV, MP3 or M4A"),
+  // An enum, so the form renders a SELECT rather than a text box — which is
+  // the whole reason the list is derived above rather than left free-form.
+  // Optional, so the SDK's own default voice applies when nobody chooses.
+  voice: z
+    .enum([FIRST_VOICE, ...OTHER_VOICES])
+    .optional()
+    .describe("Voice to read the summary in"),
+});
+
+/**
+ * The declaration: schema, description, and the directive body.
+ *
+ * Exported so `WorkflowOutputOf<typeof spokenSummary>` names the output type in
+ * one place — including from `client.tsx`, where `import type` is erased and so
+ * bundles nothing server-side — and so `workflows/summarize.ts` can name
+ * `WorkflowInputOf<typeof spokenSummary>` for the body's parameter.
+ */
+export const spokenSummary: WorkflowDef<typeof spokenSummaryInput, SpokenSummary> = workflow({
+  description: "Transcribe a recording, summarize it, and read the summary back as audio",
+  input: spokenSummaryInput,
+  // The one line that makes the form take a file: `<WorkflowFields>` renders a
+  // picker for this property, `useWorkflowSubmit` stores the chosen file, and
+  // the step that transcribes it reads it back with `readUpload`.
+  uploads: ["recording"],
+  run: spokenSummaryFlow,
+});
+
+export default workflowApp({
+  name: "Spoken Summary",
+  workflows: { spokenSummary },
+  // Checked at deploy time, so a missing key is a warning naming it rather than
+  // a run that fails on its second step. A workflow app declares no providers,
+  // so this is the only thing that can name the credential its steps read — and
+  // this one key covers transcription, the model and the voice alike.
+  requiredEnv: ["ASSEMBLYAI_API_KEY"],
+});

package/dist/templates/spoken-summary/client.tsx

@@ -0,0 +1,185 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * The page: a form, a progress log, a summary, and a player.
+ *
+ * `link-digest` shows these primitives raw and `transcription-workflow` shows
+ * the form layer in full; neither is restated here. What this page adds is the
+ * one thing a workflow app could not do before — **playing a file the RUN
+ * produced.**
+ *
+ * ## An upload id is not a URL, and `api.download` is why
+ *
+ * The run's output carries `audio`, which is an upload id in the agent's own
+ * store. The obvious next line is `<audio src={`/workflows/uploads/${id}`}>`,
+ * and it is wrong in a way that only shows up after a deploy: the byte route
+ * takes the same `Authorization` header every other route does, and neither
+ * `<audio src>` nor `<a href>` can send one. So a page built on a URL works
+ * against `aai dev`, where there is no token, and 401s the moment the agent has
+ * one.
+ *
+ * `api.download(id)` reads it with the header and answers a `Blob`;
+ * `URL.createObjectURL` turns that into something both elements take. The
+ * object URL is REVOKED when the run changes, which is not tidiness — an object
+ * URL pins its blob for the life of the document, so a page that summarized
+ * five recordings would be holding five files it can no longer reach.
+ *
+ * ## The form is DECLARED, not written
+ *
+ * There is no field markup here at all. `<WorkflowFields>` renders a control
+ * per property of the workflow's own input schema, read from `GET /workflows` —
+ * so the file picker exists because `agent.ts` declares `recording` in
+ * `uploads`, and the voice SELECT exists because it declares `voice` as an
+ * enum. Adding a field there adds a control here with no edit.
+ */
+
+import "@alexkroman1/aai-ui/styles.css";
+// ERASED at build time, so naming the agent's own type costs the browser bundle
+// nothing — and it is what stops this file restating a shape
+// `workflows/summarize.ts` already declares.
+import { formatDuration } from "@alexkroman1/aai/utils";
+import type { WorkflowOutputOf } from "@alexkroman1/aai/workflow-api";
+import {
+  createWorkflowApi,
+  Form,
+  page,
+  SubmitButton,
+  UploadProgressBar,
+  useDownloadUrl,
+  useWorkflowSubmit,
+  WorkflowFields,
+  WorkflowProgress,
+} from "@alexkroman1/aai-ui";
+import type { spokenSummary } from "./agent.ts";
+
+/** What a completed run reports, derived from the workflow rather than restated. */
+type Summary = WorkflowOutputOf<typeof spokenSummary>;
+
+/**
+ * The workflow's name, as a page starts a run by one.
+ *
+ * A rename in `agent.ts` is a runtime 400 rather than a compile error, which is
+ * why `agent.test.ts` pins this string.
+ */
+const WORKFLOW = "spokenSummary";
+
+/**
+ * Hoisted out of the component deliberately.
+ *
+ * The hooks hold the client in a ref precisely so a fresh object per render
+ * cannot restart their watch, but building one in render is still a new `fetch`
+ * closure every time and reads as though it were free.
+ */
+const api = createWorkflowApi();
+
+/**
+ * The spoken text as a one-cue WebVTT track, inline.
+ *
+ * A data URL rather than another stored file: the words are already on the page
+ * and the whole track is a few hundred bytes, so a second upload — and a second
+ * `download` round trip to read it — would buy nothing.
+ */
+function captionsUrl(text: string, durationMs: number): string {
+  // `hh:mm:ss.mmm`, which is the only timestamp shape WebVTT accepts.
+  const end = new Date(durationMs).toISOString().slice(11, 23);
+  const vtt = `WEBVTT\n\n00:00:00.000 --> ${end}\n${text}\n`;
+  return `data:text/vtt;charset=utf-8,${encodeURIComponent(vtt)}`;
+}
+
+export function App() {
+  // The generic is what makes `run.status === "completed"` narrow to a TYPED
+  // `run.output` instead of `unknown`.
+  const { submit, run, pending, upload, pauseUpload, resumeUpload, error } =
+    useWorkflowSubmit<Summary>(WORKFLOW, { api });
+  const output = run?.status === "completed" ? run.output : undefined;
+  // `useDownloadUrl` is the SDK's: the byte route takes the agent's bearer, so the
+  // bytes have to be FETCHED and handed to the element as an object URL — and the
+  // object URL has to be revoked, which is the half a page written by hand forgets.
+  const audio = useDownloadUrl(output?.audio, { api });
+
+  return (
+    <main className="mx-auto flex max-w-2xl flex-col gap-6 p-8">
+      <header className="flex flex-col gap-1">
+        <h1 className="text-2xl font-medium">Spoken Summary</h1>
+        <p className="text-sm opacity-70">
+          Upload a recording. It comes back summarized — in writing, and read aloud.
+        </p>
+      </header>
+
+      <Form onSubmit={submit} error={error} className="flex flex-col gap-4">
+        {/* Every control, from the workflow's own input schema. See the module doc. */}
+        <WorkflowFields workflow={WORKFLOW} />
+        <SubmitButton pending={pending} pendingLabel="Working…">
+          Summarize
+        </SubmitButton>
+      </Form>
+
+      {/* The upload is its own wait, and the one nothing else can describe: the
+          run does not EXIST until the bytes are in, so there is no run id and
+          nothing for `<WorkflowProgress>` to read. */}
+      <UploadProgressBar upload={upload} onPause={pauseUpload} onResume={resumeUpload} />
+
+      {/* What the run itself says, from `report()` in the workflow's steps. */}
+      <WorkflowProgress runId={run?.runId} api={api} />
+
+      {run?.status === "failed" && <p className="text-red-600">That one failed: {run.error}</p>}
+
+      {output !== undefined && (
+        <article className="flex flex-col gap-5">
+          <div className="flex flex-col gap-1">
+            <h2 className="text-xl">{output.headline}</h2>
+            <p className="text-sm opacity-70">
+              {output.source} · {formatDuration(output.durationMs)} · {output.words} words
+            </p>
+          </div>
+
+          <ul className="flex list-disc flex-col gap-1 pl-5">
+            {output.points.map((point) => (
+              <li key={point}>{point}</li>
+            ))}
+          </ul>
+
+          <section className="flex flex-col gap-2">
+            <h3 className="text-sm font-medium opacity-70">
+              Read aloud · {formatDuration(output.audioDurationMs)}
+            </h3>
+            {audio.pending && <p className="text-sm opacity-70">Fetching the audio…</p>}
+            {audio.error !== undefined && (
+              <p className="text-red-600">Could not load the audio: {audio.error}</p>
+            )}
+            {audio.url !== undefined && (
+              <>
+                <audio controls src={audio.url} className="w-full">
+                  {/* A real caption track, not a suppression: the summary was
+                      written before it was spoken, so the words are already
+                      here and one cue spanning the clip is an honest
+                      transcript of it. */}
+                  <track
+                    kind="captions"
+                    srcLang="en"
+                    label="Summary"
+                    default
+                    src={captionsUrl(output.spoken, output.audioDurationMs)}
+                  />
+                </audio>
+                {/* `download` works on an object URL because the bytes are
+                    already in the tab; it is the href that could not carry the
+                    agent's bearer, not the attribute. */}
+                <a href={audio.url} download="summary.wav" className="text-sm underline">
+                  Download summary.wav
+                </a>
+              </>
+            )}
+            <p className="text-sm opacity-70">{output.spoken}</p>
+          </section>
+
+          <details className="text-sm">
+            <summary className="cursor-pointer opacity-70">Transcript</summary>
+            <p className="mt-2 whitespace-pre-wrap">{output.transcript}</p>
+          </details>
+        </article>
+      )}
+    </main>
+  );
+}
+
+page({ name: "Spoken Summary", component: App });

package/dist/templates/spoken-summary/workflows/summarize.ts

@@ -0,0 +1,237 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * The workflow body, and the two legs after the transcript: a model reads it,
+ * and a voice reads the model back.
+ *
+ * ```text
+ *   transcribe   (workflows/transcribe.ts)   →  the words
+ *   summarize    one step, LLM Gateway       →  a headline, points, and a script
+ *   speak        one step, streaming TTS     →  a WAV, stored, and its id
+ * ```
+ *
+ * ## Audio in, audio out — and the second half is the part that needed the SDK
+ *
+ * Reading a file and transcribing it is what `transcription-workflow` already
+ * shows. What this template is for is the return trip, which until recently a
+ * workflow could not make at all:
+ *
+ * - **`stepSpeak`** synthesizes from inside a step. The session TTS surface
+ *   cannot: a `TtsSession` is an event stream wired into a live pipeline's
+ *   playback, and a step has no turn to be part of and has to return a VALUE.
+ * - **`writeUpload`** puts that value somewhere. A run's OUTPUT is read back as
+ *   JSON, so audio cannot travel in one — the same rule that keeps a
+ *   recording's bytes out of a run's INPUT, arriving at the other end of the
+ *   run. The bytes go to the store, the output carries the id, and the page
+ *   turns it back into something to play with `api.download(id)`.
+ *
+ * Both are on `@alexkroman1/aai/step`, imported from THERE rather than the
+ * root: a `workflows/*.ts` module is bundled separately by the WDK builder, so
+ * the root barrel's module graph would ride into the step bundle.
+ *
+ * ## The model is asked for TWO things, and the difference is the point
+ *
+ * `points` is for reading and `spoken` is for hearing, and a template that
+ * synthesized the bullet list would produce something nobody wants to listen
+ * to — a voice reading "one. two. three." with no connective tissue. So the
+ * schema asks for a script as well, in sentences, and that is what
+ * {@link speak} is handed. It is the same decision `recap-workflow` makes for
+ * the sentence it reads down a phone, and it is one prompts get wrong when the
+ * shape does not force it.
+ *
+ * ## Why each leg is its own step
+ *
+ * They fail differently and cost differently. The transcription is minutes of a
+ * provider's queue; the model call is seconds and rate-limited; the synthesis
+ * is a socket. Splitting them means a rate-limited model call replays the
+ * transcript from the journal instead of transcribing the recording again, and
+ * a synthesis that failed does not re-run the model — which is the ordinary
+ * reason to split steps, made sharp here because the first leg is the
+ * expensive one.
+ */
+
+import { report, stepSpeak, TRANSCRIBE_API, writeUpload } from "@alexkroman1/aai/step";
+import { stepGenerateJsonClassified } from "@alexkroman1/aai/step-errors";
+import { countWords, omitUndefined } from "@alexkroman1/aai/utils";
+// ERASED at build time, so the body can name the schema's own output type without
+// a runtime cycle back through `agent.ts` — the same mechanism `client.tsx` uses
+// for `WorkflowOutputOf`.
+import type { WorkflowInputOf } from "@alexkroman1/aai/workflow-api";
+import { sleep } from "workflow";
+import { z } from "zod";
+import type { spokenSummary } from "../agent.ts";
+import {
+  createJob,
+  MAX_POLLS,
+  POLL_INTERVAL,
+  pollTranscript,
+  type Transcript,
+  uploadToProvider,
+} from "./transcribe.ts";
+
+/** Points the summary is reduced to. Enough to be a summary, few enough to scan. */
+const POINTS = 4;
+
+/**
+ * Characters of transcript handed to the model.
+ *
+ * The pass-an-id-not-a-payload rule meeting a case where the payload IS the
+ * work: the text has to cross the queue between two steps, so it is bounded
+ * rather than trusted. 40k characters is roughly four hours of speech — past
+ * where another paragraph changes a four-point summary.
+ */
+const MAX_TRANSCRIPT_CHARS = 40_000;
+
+/**
+ * The shape the model must answer in, as something that CHECKS.
+ *
+ * `stepGenerateJson` validates against this and throws plainly when the reply
+ * misses, which is what a retry is for: a model that answered with prose may
+ * well obey on the next attempt.
+ */
+const SummaryReply = z.object({
+  headline: z.string().trim().min(1),
+  points: z.array(z.string().trim().min(1)).min(1),
+  // NOT `.default("")` — the whole second half of this workflow has nothing to
+  // say without it, and a default would turn a missing field into a silent
+  // half-second of audio rather than a retry.
+  spoken: z.string().trim().min(1),
+});
+
+/** What a finished run reports. Small and JSON-shaped, like every step result. */
+export type SpokenSummary = {
+  /** The uploaded file's own name. */
+  source: string;
+  /** The recording's length, as the provider measured it. */
+  durationMs: number;
+  /** Words in the transcript. */
+  words: number;
+  /** One line naming what the recording was about. */
+  headline: string;
+  /** The summary, for reading. */
+  points: string[];
+  /** The summary, for hearing — what {@link speak} was handed. */
+  spoken: string;
+  /** The whole transcript, so the page can show its work. */
+  transcript: string;
+  /**
+   * The upload id of the spoken summary — a WAV, in this app's own store.
+   *
+   * An ID rather than the bytes, and that is the rule rather than a
+   * preference: a run's output is read back as JSON. `api.download(id)` is the
+   * browser half.
+   */
+  audio: string;
+  /** How long the spoken summary lasts. */
+  audioDurationMs: number;
+};
+
+/** Transcribe a recording, summarize it, and read the summary back. */
+export async function spokenSummaryFlow(
+  input: WorkflowInputOf<typeof spokenSummary>,
+): Promise<SpokenSummary> {
+  "use workflow";
+
+  const transcript = await transcribe(input.recording);
+  const summary = await summarize(transcript.text);
+  const spoken = await speak(summary.spoken, input.voice);
+
+  return {
+    source: transcript.source,
+    durationMs: transcript.durationMs,
+    words: countWords(transcript.text),
+    headline: summary.headline,
+    points: summary.points,
+    spoken: summary.spoken,
+    transcript: transcript.text,
+    audio: spoken.audio,
+    audioDurationMs: spoken.durationMs,
+  };
+}
+
+/**
+ * The whole first leg, factored out of the body.
+ *
+ * A plain async function rather than a step, and NOT because it is small: it
+ * calls steps and it `sleep`s durably between polls, neither of which a step
+ * may do. So it runs as part of the BODY and is replayed with it — which is
+ * legal here for the ordinary reason, that everything it does is either a step
+ * call or a `sleep`, so a replay re-derives exactly the same sequence.
+ */
+async function transcribe(recording: string): Promise<Transcript> {
+  const { audioUrl } = await uploadToProvider(recording);
+  const job = await createJob(audioUrl);
+
+  for (let poll = 0; poll < MAX_POLLS; poll += 1) {
+    const progress = await pollTranscript(recording, job.id);
+    if (progress.done) return progress.transcript;
+    await sleep(POLL_INTERVAL);
+  }
+  // A plain throw: this is the BODY, where the fatal/retryable distinction has
+  // nothing to apply to. The transcript is not lost, so the message says where
+  // it is rather than only that the wait ran out.
+  throw new Error(
+    `Transcript ${job.id} was still unfinished after ${MAX_POLLS} polls. It is not lost — ` +
+      `read it directly with GET ${TRANSCRIBE_API}/v2/transcript/${job.id}.`,
+  );
+}
+
+/** Reduce the transcript to a headline, {@link POINTS} points, and a script. */
+export async function summarize(
+  text: string,
+): Promise<{ headline: string; points: string[]; spoken: string }> {
+  "use step";
+
+  await report("Summarizing the transcript.");
+  const reply = await stepGenerateJsonClassified(
+    "Summarize this transcript of a recording.\n\n" +
+      "Answer with JSON only, in this shape:\n" +
+      `{"headline": "...", "points": ["..."], "spoken": "..."}\n\n` +
+      "- headline: one line naming what the recording was about.\n" +
+      `- points: at most ${POINTS} short points, each a complete thought. Concrete ` +
+      `specifics — decisions, numbers, names, what happens next — never "the ` +
+      `speaker discussed several topics".\n` +
+      "- spoken: the same summary written to be READ ALOUD. Full sentences that " +
+      "flow, under 120 words, no bullet markers, no headings, no markdown. " +
+      "Someone will hear this without seeing the points.\n\n" +
+      `Transcript:\n${text.slice(0, MAX_TRANSCRIPT_CHARS)}`,
+    {
+      system: "You summarize recordings. You answer with JSON and nothing else.",
+      schema: SummaryReply,
+    },
+    // The `Classified` caller is `stepGenerateJson` plus `throwStepError`, which
+    // reads the gateway's own status: a 429 is worth another attempt and a 400
+    // is not, and that is what tells the DevKit which.
+  );
+
+  return { headline: reply.headline, points: reply.points.slice(0, POINTS), spoken: reply.spoken };
+}
+
+/**
+ * Read the summary aloud, store the WAV, and answer with its id.
+ *
+ * **Both halves belong in ONE step**, and the reason is what a journal records:
+ * a step is replayed by its RETURN VALUE, so an id is replayed and bytes are
+ * not. Split in two, the audio would have to cross the queue between them —
+ * megabytes of it, on every resume. Together, a resumed run replays the id and
+ * re-reads a file that is already there.
+ */
+export async function speak(
+  script: string,
+  voice?: string,
+): Promise<{ audio: string; durationMs: number }> {
+  "use step";
+
+  const spoken = await stepSpeak(script, omitUndefined({ voice }));
+  const stored = await writeUpload(spoken.audio, {
+    // Named, because this is what a person sees on the download link rather
+    // than an opaque id — and typed, because the byte route serves the type it
+    // was given and a browser will not play a file it was handed as bytes.
+    name: "summary.wav",
+    type: "audio/wav",
+  });
+
+  await report(
+    `Recorded a ${Math.round(spoken.durationMs / 1000)}s summary in ${spoken.voice}'s voice.`,
+  );
+  return { audio: stored.id, durationMs: spoken.durationMs };
+}