@alexkroman1/aai-cli 6.10.1 → 7.0.0

package/dist/templates/call-audit/agent.ts

@@ -0,0 +1,171 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * A WORKFLOW APP that audits a recorded call, with **ffmpeg in the pipeline on
+ * both sides of the model.**
+ *
+ * ```text
+ *   any recording  →  levelled PCM  →  cut at the pauses  →  transcript
+ *                        ffmpeg            ffmpeg               sync STT
+ *
+ *                  →  headline, risks, actions  →  a script  →  an MP3
+ *                          LLM Gateway              schema      TTS + ffmpeg
+ * ```
+ *
+ * ## Which template to read first
+ *
+ * This one is the deepest of the workflow apps, so it is the wrong place to start.
+ *
+ * - `link-digest` owns the SHAPE — `workflowApp()`, no session, no tools, a form
+ *   that starts a run and a page that watches it.
+ * - `transcription-workflow` owns the FAN-OUT — why the sync transcription
+ *   endpoint's 120-second cap forces one, and how a run survives dying on segment
+ *   27 of 60.
+ * - `spoken-summary` owns the audio ROUND TRIP — `stepSpeak`, `writeUpload`, and
+ *   why a page needs `api.download` rather than a URL.
+ *
+ * **What this template adds is a decoder**, and everything downstream changes
+ * because of it. `workflows/audit.ts` carries the table comparing it against
+ * `transcription-workflow` row by row; the summary is that normalizing FIRST lets
+ * the desk cut a recording *in its pauses* instead of every 90 seconds, which
+ * deletes the segment overlap, the seam-matching stitcher, the WAV header parser
+ * and one of the two provider caps it had to plan against.
+ *
+ * ## Five ffmpeg jobs, and each one is a decision
+ *
+ * `workflows/media.ts` is where they are built, and it is the file to read: every
+ * argv is a pure function, so the argv is a value a spec asserts on rather than a
+ * string embedded in a step that spawns.
+ *
+ * | | what it does | why it is not obvious |
+ * | --- | --- | --- |
+ * | `ffprobe` | what the file WAS | on a temp file, because a pipe cannot seek an m4a's trailing index |
+ * | `loudnorm` pass 1 | measure five numbers | `-f null -`: decode everything, write nothing |
+ * | `loudnorm` pass 2 | apply them | one linear gain, so speech does not pump |
+ * | `silencedetect` | find every pause | same pass as above — a filter chain, not a second decode |
+ * | `libmp3lame` | master the summary | 4.3 MB of WAV becomes ~110 KB |
+ *
+ * The two analyses read their answers back by **different routes**, and that is the
+ * single most surprising thing in the template: loudness arrives on stderr (one
+ * block, printed last, so the SDK's capped stderr TAIL holds it) and the pauses
+ * arrive in a FILE (one event per pause, so a tail would silently drop the
+ * earliest ones and the desk would mis-cut only long recordings). `media.ts`'s
+ * module doc carries it.
+ *
+ * ## What it needs
+ *
+ * - **`ASSEMBLYAI_API_KEY` in the agent env** — `.env` under `aai dev`,
+ *   `aai secret put ASSEMBLYAI_API_KEY` once deployed. `requiredEnv` below is what
+ *   makes a deploy check for it rather than letting the first run find out. One key
+ *   covers transcription, the model and the voice alike.
+ * - **Storage** (`aai storage enable`, Settings → Database in the studio, or
+ *   `DATABASE_URL` under `aai dev`). REQUIRED, unlike most workflow apps: an
+ *   upload's record is a row, and this desk both reads an upload and writes two.
+ * - **ffmpeg** — every deployed guest's image installs it (and `ffprobe` with it).
+ *   Under `aai dev` it is whatever is on `PATH`, or what `AAI_FFMPEG_PATH` /
+ *   `AAI_FFPROBE_PATH` name. That is the one place dev/prod parity is partial, so
+ *   a missing binary is reported as an instruction rather than as
+ *   `spawn ffmpeg ENOENT`.
+ *
+ * ## It is scriptable, which is the other half of having an API
+ *
+ * The page is one caller. Two requests do the same thing from a shell — upload,
+ * then start a run naming the id, with `wait` holding the request open:
+ *
+ * ```sh
+ * ID=$(curl -s -X POST "https://<your-agent>/workflows/uploads?name=call.m4a" \
+ *   -H 'content-type: audio/mp4' --data-binary @call.m4a | jq -r .id)
+ *
+ * curl -X POST https://<your-agent>/workflows/runs \
+ *   -H 'content-type: application/json' \
+ *   -d "{\"workflow\":\"audit\",\"wait\":60000,\"input\":{\"recording\":\"$ID\"}}"
+ * ```
+ *
+ * The spoken audit comes back as an upload id in the run's output; the byte route
+ * (`GET /workflows/uploads/<id>`) takes the same bearer every other route does.
+ */
+
+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 { auditFlow, type CallAudit } from "./workflows/audit.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 audit 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 audit} carries an explicit type, and
+ * that annotation is what lets `workflows/audit.ts` name
+ * `WorkflowInputOf<typeof audit>` 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 auditInput = 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.
+  //
+  // "Anything" is not marketing: the first step hands the file to ffmpeg, so the
+  // accepted set is ffmpeg's rather than this template's — a video's audio track
+  // included, since the conversion drops the video.
+  recording: z.string().describe("Any recording — WAV, MP3, M4A, or a video's audio track"),
+  // 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 audit in"),
+});
+
+/**
+ * The declaration: schema, description, and the directive body.
+ *
+ * Exported so `WorkflowOutputOf<typeof audit>` 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/audit.ts` can name `WorkflowInputOf<typeof audit>`
+ * for the body's parameter.
+ */
+export const audit: WorkflowDef<typeof auditInput, CallAudit> = workflow({
+  description: "Level a call recording, transcribe it at its pauses, and audit what was said",
+  input: auditInput,
+  // The one line that makes the form take a file: `<WorkflowFields>` renders a
+  // picker for this property, `useWorkflowSubmit` stores the chosen file, and the
+  // ingest step reads it back with `readUpload`.
+  uploads: ["recording"],
+  run: auditFlow,
+});
+
+export default workflowApp({
+  name: "Call Audit",
+  workflows: { audit },
+  // Checked at deploy time, so a missing key is a warning naming it rather than a run
+  // that fails on its third step. A workflow app declares no providers, so this is the
+  // only thing that can name the credential its steps read.
+  //
+  // ffmpeg is NOT here and cannot be: `requiredEnv` checks the agent's environment,
+  // and a binary on `PATH` is not an environment variable. The deployed guest always
+  // has one; under `aai dev` the failure names its own remedy.
+  requiredEnv: ["ASSEMBLYAI_API_KEY"],
+});

package/dist/templates/call-audit/client.tsx

@@ -0,0 +1,198 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * The page: a form, a progress log, the audit, and a player.
+ *
+ * `link-digest` shows these primitives raw, `transcription-workflow` shows the form
+ * layer in full, and `spoken-summary` shows how a page plays a file the RUN
+ * produced. None of that is restated here — this page is deliberately the least
+ * novel file in the template, because the subject is the pipeline.
+ *
+ * Two things it does add, and both are about being honest about the pipeline:
+ *
+ * - **The PIPELINE panel.** A reader cannot tell from a transcript whether the desk
+ *   cut it in the pauses or fell back to cutting by arithmetic, and that difference
+ *   is exactly what explains a mangled word at a seam. So `blindCuts` is rendered
+ *   rather than hidden, alongside what the recording measured before levelling.
+ * - **`useDownloadUrl`, not a URL.** The run's output carries an upload id. The
+ *   obvious `<audio src={`/workflows/uploads/${id}`}>` 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. The hook is `aai-ui`'s rather than four
+ *   lines here, because the two lines that matter are the ones around them: the
+ *   `URL.revokeObjectURL` on cleanup, and the guard that stops a slow first
+ *   download landing under a second run's output.
+ */
+
+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/audit.ts`
+// already declares.
+import { formatBytes, 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 { audit } from "./agent.ts";
+
+/** What a completed run reports, derived from the workflow rather than restated. */
+type Audit = WorkflowOutputOf<typeof audit>;
+
+/**
+ * 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 = "audit";
+
+/**
+ * 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();
+
+/** One labelled number in the pipeline panel. */
+function Stat({ label, value }: { label: string; value: string }) {
+  return (
+    <div className="flex flex-col">
+      <dt className="text-xs uppercase tracking-wide opacity-60">{label}</dt>
+      <dd className="text-sm">{value}</dd>
+    </div>
+  );
+}
+
+/** A list that renders nothing rather than an empty box — see `risks` in the schema. */
+function Findings({ title, items }: { title: string; items: string[] }) {
+  if (items.length === 0) return null;
+  return (
+    <section className="flex flex-col gap-1">
+      <h3 className="text-sm font-medium opacity-70">{title}</h3>
+      <ul className="flex list-disc flex-col gap-1 pl-5">
+        {items.map((item) => (
+          <li key={item}>{item}</li>
+        ))}
+      </ul>
+    </section>
+  );
+}
+
+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<Audit>(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-3xl flex-col gap-6 p-8">
+      <header className="flex flex-col gap-1">
+        <h1 className="text-2xl font-medium">Call Audit</h1>
+        <p className="text-sm opacity-70">
+          Upload a call recording — any format. It comes back levelled, transcribed at its pauses,
+          and audited for risks and actions.
+        </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="Auditing…">
+          Audit the call
+        </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 — which
+          for this template is the ffmpeg narration: what the file was, what it
+          measured, how many pauses were found. */}
+      <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-6">
+          <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>
+
+          {/* What the pipeline did, which is this template's subject. Rendered rather
+              than logged because `blindCuts` is the one number that explains a bad
+              seam, and a reader has no other way to know. */}
+          <dl className="grid grid-cols-2 gap-3 rounded border border-current/10 p-4 sm:grid-cols-3">
+            <Stat label="Source codec" value={output.codec} />
+            <Stat label="Loudness in" value={`${output.loudnessBefore} LUFS`} />
+            <Stat label="Speech" value={`${output.speechPercent}%`} />
+            <Stat label="Segments" value={String(output.segments)} />
+            <Stat
+              label="Cut in speech"
+              value={output.blindCuts === 0 ? "none" : String(output.blindCuts)}
+            />
+            <Stat label="Run time" value={formatDuration(output.elapsedMs)} />
+          </dl>
+
+          <Findings title="Risks" items={output.risks} />
+          <Findings title="Actions" items={output.actions} />
+
+          <section className="flex flex-col gap-2">
+            <h3 className="text-sm font-medium opacity-70">
+              Read aloud · {formatDuration(output.audioDurationMs)} ·{" "}
+              {formatBytes(output.audioBytes)}
+            </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 && (
+              <>
+                {/* No `<track>`, and that is a judgement rather than an
+                    oversight: the spoken text is rendered in full immediately
+                    below this player, which is the same information a caption
+                    track would carry. `spoken-summary` serves a one-cue WebVTT
+                    data URL instead — worth reading for how, if a real track is
+                    what a page needs. */}
+                <audio controls src={audio.url} className="w-full" />
+                {/* `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="audit.mp3" className="text-sm underline">
+                  Download audit.mp3
+                </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: "Call Audit", component: App });

package/dist/templates/call-audit/workflows/audit.ts

@@ -0,0 +1,298 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * The workflow body, and the fan-out it plans.
+ *
+ * ```text
+ *   now                 one step   →  when the run began
+ *   ingestRecording     one step   →  levelled PCM + every pause   (ingest.ts)
+ *   planSegments        the BODY   →  where to cut                 (media.ts, pure)
+ *   transcribeSegment   N steps    →  one sync API request each, bounded
+ *   summarize           one step   →  headline, risks, actions      (summarize.ts)
+ *   narrate             one step   →  an MP3 of the summary         (summarize.ts)
+ *   now                 one step   →  when it finished
+ * ```
+ *
+ * Read `transcription-workflow` first: it owns the fan-out — why the sync
+ * endpoint forces one, how `mapConcurrent` keeps a replay's call order stable,
+ * why a segment is addressed by byte range and never carried — and none of that
+ * is restated here. **What this template adds is what changes when a DECODER is
+ * in the pipeline**, and it is worth reading the two side by side, because the
+ * difference is subtraction:
+ *
+ * | | `transcription-workflow` | here |
+ * | --- | --- | --- |
+ * | accepts | any audio, converts to WAV | any audio, converts to raw PCM |
+ * | header | parsed (`parseWav`, ~180 lines) | **none — byte 0 is second 0** |
+ * | cut at | every 90s, wherever that lands | **the middle of a pause** |
+ * | overlap | 2s per segment, transcribed twice | **none** |
+ * | stitching | seam matching, drops repeated words | **ordered concatenation** |
+ * | caps to plan against | 120s AND 40 MB, whichever binds | **120s** |
+ * | levelling | none | `loudnorm`, two-pass |
+ *
+ * Every row on the right is a consequence of one decision: normalize FIRST, to a
+ * format this desk chose. `media.ts` carries the argument for each.
+ *
+ * ## The plan is made in the BODY, and that is legal
+ *
+ * `planSegments` runs in the directive body rather than in a step, which looks
+ * like a rule violation and is not: it is a pure function of `ingested.silences`
+ * and `ingested.durationMs`, both of which came out of a journaled step result.
+ * So a replay re-derives the identical list in the identical order, which is
+ * exactly what `mapConcurrent` needs — the DevKit correlates a journal entry to a
+ * step call by the ORDER the call was issued in.
+ *
+ * Putting it in a step would journal the same list twice (once as part of the
+ * ingest result, once as the plan) and buy nothing.
+ */
+
+import { encodeWav, mapConcurrent, readUpload, report } from "@alexkroman1/aai/step";
+import { countWords, formatDuration } 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 type { audit } from "../agent.ts";
+import { ingestRecording } from "./ingest.ts";
+import {
+  ANALYSIS_FORMAT,
+  durationSeconds,
+  planSegments,
+  type Segment,
+  speechFraction,
+} from "./media.ts";
+import { narrate, summarize } from "./summarize.ts";
+import { transcribeSpan } from "./sync-api.ts";
+
+/**
+ * How many segments to keep in flight.
+ *
+ * A CONSTANT here, where `transcription-workflow` derives one per recording — and
+ * the difference is the payoff of normalizing. That template cuts whatever format
+ * it was handed, so the byte cost of a segment is a property of the file: the same
+ * 32 segments are 94 MB of 16 kHz mono or 1.28 GB of a format at the endpoint's
+ * ceiling, and only one of those is safe to have in flight. It has to divide a
+ * measured byte budget to find a width.
+ *
+ * Here the format is {@link ANALYSIS_FORMAT} for every recording, so a segment is
+ * at most 3.5 MB and 32 of them are 113 MB — comfortably inside the ~640 MB that
+ * template measured as the point where the endpoint starts returning `503`s. So
+ * the byte bound never binds and what is left is the endpoint's own knee, which it
+ * measured at 32. Its `BYTES_IN_FLIGHT` and `MAX_SEGMENT_CONCURRENCY` docs carry
+ * both measurements; this is the one number that survives them.
+ */
+export const SEGMENT_CONCURRENCY = 32;
+
+/** What one segment's request came back with — the STEP's result, journaled. */
+export type SegmentText = {
+  index: number;
+  text: string;
+};
+
+/** What a finished run reports. Small and JSON-shaped, like every step result. */
+export type CallAudit = {
+  /** The uploaded file's own name. */
+  source: string;
+  /** What ffprobe made of it before the conversion — `aac`, `mp3`, `pcm_s16le`. */
+  codec: string;
+  /** Length of the audio. */
+  durationMs: number;
+  /** How long the RUN took, wall clock. */
+  elapsedMs: number;
+  /** How many requests the transcript was assembled from. */
+  segments: number;
+  /**
+   * Segments whose end landed in speech because no pause was in range.
+   *
+   * `0` on an ordinary recording. Surfaced because it is the one thing that can
+   * make this desk's transcript as seam-damaged as a blind cut's, and a reader
+   * looking at a mangled word deserves to know which case they are in.
+   */
+  blindCuts: number;
+  /** Share of the recording that is speech rather than pause, 0-100. */
+  speechPercent: number;
+  /** Integrated loudness BEFORE levelling, LUFS — what the recording arrived at. */
+  loudnessBefore: number;
+  words: number;
+  transcript: string;
+  /** One line naming what the call was about. */
+  headline: string;
+  /** What a reader should worry about. */
+  risks: string[];
+  /** What somebody has to do next. */
+  actions: string[];
+  /** The summary, written to be heard. */
+  spoken: string;
+  /**
+   * Upload id of the spoken summary — an MP3, 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;
+  /** Size of the MP3, which is the number that makes the mastering pass worth it. */
+  audioBytes: number;
+};
+
+/**
+ * Audit a call recording: level it, transcribe it, summarize it, read it back.
+ *
+ * The input is what `POST /workflows/runs` carries — see `agent.ts` for the schema
+ * it is validated against before a run exists.
+ */
+export async function auditFlow(input: WorkflowInputOf<typeof audit>): Promise<CallAudit> {
+  "use workflow";
+
+  // Both at once: neither needs the other, and issued together they are one round
+  // trip instead of two before any audio moves. The ORDER is still a pure function
+  // of this expression — the two calls go out synchronously, left to right — which
+  // is what a replay reproduces.
+  const [startedAt, ingested] = await Promise.all([now(), ingestRecording(input.recording)]);
+
+  // Pure, in the body, from journaled values. See the module doc. Planned against
+  // the stored BYTE COUNT rather than the reported duration — `durationSeconds`
+  // carries why those are not interchangeable.
+  const segments = planSegments(ingested.silences, ingested.bytes);
+
+  // One step per segment, bounded, in an order a replay reproduces exactly. A
+  // failed segment fails the RUN deliberately: every sibling that finished is
+  // already journaled, so a resume replays those for free and re-issues only what
+  // is missing — where catching here to salvage a partial transcript would return
+  // a recording with a silent hole in it and report success.
+  const parts = await mapConcurrent(segments, SEGMENT_CONCURRENCY, (segment) =>
+    transcribeSegment(ingested.audio, segment),
+  );
+
+  const transcript = joinSegments(segments, parts);
+  const summary = await summarize(transcript, ingested.source, ingested.durationMs);
+  const spoken = await narrate(summary.spoken, input.voice);
+  const finishedAt = await now();
+
+  // Whatever this returns is what a caller reads as `output` on a completed run —
+  // so it is what the page renders, typed through `WorkflowOutputOf`. Assembled in
+  // the body rather than in a step because every field is already journaled: a
+  // step here would re-record values it was handed.
+  return {
+    source: ingested.source,
+    codec: ingested.codec,
+    durationMs: ingested.durationMs,
+    elapsedMs: finishedAt - startedAt,
+    segments: segments.length,
+    blindCuts: segments.filter((segment) => segment.cutInSpeech).length,
+    speechPercent: Math.round(
+      speechFraction(ingested.silences, durationSeconds(ingested.bytes)) * 100,
+    ),
+    loudnessBefore: ingested.loudness.inputLufs,
+    words: countWords(transcript),
+    transcript,
+    headline: summary.headline,
+    risks: summary.risks,
+    actions: summary.actions,
+    spoken: summary.spoken,
+    audio: spoken.audio,
+    audioDurationMs: spoken.durationMs,
+    audioBytes: spoken.bytes,
+  };
+}
+
+/**
+ * Transcribe one segment through the sync API.
+ *
+ * One step each, so a run that dies part-way resumes having replayed the finished
+ * ones from the journal — no re-reading, no re-billing — and issues exactly the
+ * calls that are missing.
+ *
+ * **`encodeWav` is what makes a byte range decodable.** The stored audio is
+ * headerless PCM, and the endpoint decodes each request independently, so a slice
+ * of it is meaningless bytes until a header says what they are. That header is the
+ * SDK's (`@alexkroman1/aai/step`) rather than this template's: the equivalent
+ * function in `transcription-workflow` is 25 lines of `DataView` writes with a
+ * comment about which of the two declared lengths a decoder trusts, and there is
+ * no reason for a second copy of it to exist.
+ */
+export async function transcribeSegment(audioId: string, segment: Segment): Promise<SegmentText> {
+  "use step";
+
+  // One line per segment, which is what makes the fan-out legible to a page: the
+  // status is `running` for the whole thing, so without this a sixty-segment
+  // recording and a one-segment recording look identical while they run.
+  //
+  // ORDER is not guaranteed here and does not need to be — the calls go out
+  // together, so their lines interleave by completion, and `segment.index` is what
+  // puts the TRANSCRIPT back in order.
+  await report(`Transcribing ${formatDuration(segment.startMs)}–${formatDuration(segment.endMs)}.`);
+
+  // `[start, end)`, the same half-open pair `planSegments` produced — the store
+  // owns the conversion to HTTP's inclusive range, so there is no `- 1` here to get
+  // wrong.
+  const audio = await readUpload(audioId, { start: segment.startByte, end: segment.endByte });
+  const text = await transcribeSpan(
+    encodeWav(audio.bytes, ANALYSIS_FORMAT),
+    `segment-${segment.index}.wav`,
+    `Segment ${segment.index} (${formatDuration(segment.startMs)})`,
+  );
+
+  return { index: segment.index, text };
+}
+
+/**
+ * Retries beyond the default 3, because a rate limit is the expected failure and a
+ * segment that 429s is not a segment that is wrong.
+ */
+transcribeSegment.maxRetries = 5;
+
+/**
+ * When it is now, as epoch ms.
+ *
+ * A STEP, and that is the whole reason it exists rather than a `Date.now()` in the
+ * body: a body replays from the top on every resume, so a clock read there returns
+ * a different value each time and every duration derived from it would be a
+ * different duration. A step's result is journaled, so this is the moment the run
+ * really reached this line however many times it is replayed.
+ *
+ * Called twice — once at each end — rather than a `startClock`/`elapsed` pair,
+ * because the alternative is a step taking every field of the output so it can
+ * subtract inside itself. Two journal entries and a subtraction in the body is the
+ * smaller thing.
+ */
+export async function now(): Promise<number> {
+  "use step";
+
+  return Date.now();
+}
+
+/**
+ * Join the segment transcripts into one.
+ *
+ * Ordered concatenation, and the absence of anything cleverer is the point:
+ * segments do not overlap, so there is nothing to de-duplicate. The equivalent in
+ * `transcription-workflow` is a seam matcher that looks back up to 40 words for a
+ * repeated run and drops it — necessary there, because a blind cut forces a
+ * two-second overlap to avoid splitting a word, and heuristic by nature.
+ *
+ * The one judgement left is the SEPARATOR, and the plan already knows the answer.
+ * A cut placed in a pause is a turn or sentence boundary, so a paragraph break
+ * reads correctly; a blind cut lands mid-sentence, so it gets a space. That is the
+ * one place `cutInSpeech` changes an output rather than a report.
+ */
+export function joinSegments(segments: readonly Segment[], parts: readonly SegmentText[]): string {
+  // `mapConcurrent` resolves in ITEM order however the calls settled, so this is
+  // already ordered — sorted anyway, because a merge is where an ordering mistake
+  // would be invisible rather than loud.
+  const byIndex = new Map(parts.map((part) => [part.index, part.text]));
+  let joined = "";
+  for (const segment of segments) {
+    const text = (byIndex.get(segment.index) ?? "").trim();
+    if (text === "") continue;
+    if (joined === "") {
+      joined = text;
+      continue;
+    }
+    // The separator belongs to the boundary BEFORE this segment, which is the
+    // previous segment's end — so the flag read here is the earlier one's.
+    const previous = segments[segment.index - 1];
+    joined += previous?.cutInSpeech === true ? ` ${text}` : `\n\n${text}`;
+  }
+  return joined;
+}