@alexkroman1/aai-cli 6.3.1 → 6.5.0

package/dist/templates/transcription-workflow/api-help.tsx

@@ -0,0 +1,214 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * "You do not need this page" — the HTTP API, on the page.
+ *
+ * A workflow app's whole surface is `GET|POST /workflows/*`, and the page is one
+ * caller of it. That is the most useful thing about the shape and the least
+ * discoverable: nothing in a form suggests that the same work is three `curl`
+ * calls, that a run id is the entire handle (no session, no cookie), or that a
+ * transcript can be collected days later from another machine. So the recipes are
+ * rendered where somebody is already looking, rather than left in a README they
+ * would have to know exists.
+ *
+ * ## It links to the LIVE listing
+ *
+ * `GET /workflows` serves each workflow's name, description and input schema — the
+ * same JSON `<WorkflowFields>` renders this form from. So the link is not
+ * documentation about the API, it is the API answering for itself, on this
+ * deployment, at this version. A reader who wants the schema gets the real one;
+ * a reader whose agent is behind `AAI_WORKFLOW_API_TOKEN` gets a 401, which is
+ * also the truth.
+ *
+ * ## The three recipes are the three flows
+ *
+ * The first two differ only in who names the upload — which is the whole of what
+ * lets one of them start before the bytes are in — and the third does none of that
+ * work at all. Showing them side by side is the clearest statement of the trade
+ * available, and cheaper than the prose that would otherwise have to make it.
+ *
+ * They are also KEPT HONEST by being runnable: every one of these was executed
+ * against a real dev server, which is how two bugs in the streaming path were
+ * found (a missing wake after the upload, and a poll that slept on a stale view).
+ */
+
+/** @jsxImportSource react */
+
+import type { ReactNode } from "react";
+
+/** The API root, relative to wherever this page is served from. */
+const API = "workflows";
+
+/**
+ * One shell recipe, with a heading and a note.
+ *
+ * Rendered in a `<pre>` rather than assembled from styled spans: it exists to be
+ * SELECTED and pasted, and any markup inside the block is markup a copy picks up.
+ */
+function Recipe({
+  title,
+  note,
+  script,
+}: {
+  title: string;
+  note: string;
+  script: string;
+}): ReactNode {
+  return (
+    <section className="flex flex-col gap-2">
+      <h4 className="text-xs font-medium uppercase tracking-[1.2px]">{title}</h4>
+      <p className="text-xs opacity-70">{note}</p>
+      <pre className="overflow-x-auto rounded-md border p-3 text-xs leading-relaxed">{script}</pre>
+    </section>
+  );
+}
+
+/** Store the whole file, then start a run on its id. */
+const CLASSIC = `# 1. store the recording. Answers 201 once the LAST byte is in, which is why
+#    this shape cannot start the run any earlier.
+ID=$(curl -s -X POST "$AGENT/workflows/uploads?name=standup.wav" \
+  -H 'content-type: audio/wav' --data-binary @standup.wav | jq -r .id)
+
+# 2. run it. \`wait\` holds the request open for up to 60s; drop it to get
+#    { runId } straight back and poll instead.
+curl -s -X POST "$AGENT/workflows/runs" \
+  -H 'content-type: application/json' \
+  -d "{\\"workflow\\":\\"transcribe\\",\\"wait\\":60000,
+       \\"input\\":{\\"recording\\":\\"$ID\\"}}" | jq -r '.run.output.transcript'`;
+
+/** Start the run first, then stream the file to the id it is watching. */
+const STREAMING = `# No splitting, no ffmpeg — the file goes in ONE request. The only difference
+# from the recipe above is that YOU pick the upload id, so it is already valid
+# when the run starts and the run reads the bytes as they land.
+
+# 1. pick an id and start the run on it. Nothing has been uploaded yet.
+ID=$(openssl rand -hex 16)
+RUN=$(curl -s -X POST "$AGENT/workflows/runs" \
+  -H 'content-type: application/json' \
+  -d "{\\"workflow\\":\\"transcribeStream\\",
+       \\"input\\":{\\"recording\\":\\"$ID\\"}}" | jq -r .runId)
+
+# 2. PUT the whole file. The upload record exists from the first byte with
+#    complete:false, and its size grows — which is what the run polls.
+curl -s -X PUT "$AGENT/workflows/uploads/$ID?name=standup.wav" \
+  -H 'content-type: audio/wav' --data-binary @standup.wav | jq -c '{size, complete}'
+
+# 3. wake it. The run sleeps between polls, so without this it notices the file
+#    is finished up to one poll interval late — every time.
+curl -s -X POST "$AGENT/workflows/runs/$RUN/wake" > /dev/null
+
+# 4. collect it whenever — a run id is the whole handle.
+curl -s "$AGENT/workflows/runs/$RUN?wait=60000" | jq -r '.run.output.transcript'
+
+# While it runs, from any other shell:
+#   curl -s "$AGENT/workflows/uploads/$ID/info"        # how much has arrived
+#   curl -sN "$AGENT/workflows/runs/$RUN/stream"       # what the run is saying`;
+
+/** Hand the whole thing to the async API. */
+const BATCH = `# The same two requests as the first recipe — only the workflow name differs.
+# No cutting happens anywhere: the run uploads your file to the async API,
+# polls the job, and reads the text. It also accepts mp3 and m4a, which the
+# two sync flows refuse.
+ID=$(curl -s -X POST "$AGENT/workflows/uploads?name=standup.m4a" \
+  -H 'content-type: audio/mp4' --data-binary @standup.m4a | jq -r .id)
+
+# No \`wait\` here: an async job takes minutes, well past the 60s ceiling a
+# synchronous read can hold. Start it, then follow the run.
+RUN=$(curl -s -X POST "$AGENT/workflows/runs" \
+  -H 'content-type: application/json' \
+  -d "{\\"workflow\\":\\"transcribeBatch\\",
+       \\"input\\":{\\"recording\\":\\"$ID\\"}}" | jq -r .runId)
+
+curl -sN "$AGENT/workflows/runs/$RUN/events"          # status, as it changes
+curl -s "$AGENT/workflows/runs/$RUN" | jq -r '.output.transcript // .status'`;
+
+/** Every route this app answers, and what each is for. */
+const ROUTES: readonly { route: string; does: string }[] = [
+  { route: "GET  /workflows", does: "the three workflows and their input schemas" },
+  { route: "POST /workflows/runs", does: "start a run · body names workflow and input" },
+  { route: "GET  /workflows/runs", does: "runs so far · filter by workflow, key, limit" },
+  { route: "GET  /workflows/runs/:id", does: "one run · add wait=<ms> to block on it" },
+  { route: "GET  /workflows/runs/:id/events", does: "SSE, status transitions" },
+  { route: "GET  /workflows/runs/:id/stream", does: "SSE, what the run has written" },
+  { route: "POST /workflows/runs/:id/wake", does: "end a pending sleep early" },
+  { route: "DELETE /workflows/runs/:id", does: "cancel it" },
+  { route: "POST /workflows/uploads", does: "store a file, id minted by the store" },
+  {
+    route: "PUT  /workflows/uploads/:id",
+    does: "store a file under YOUR id, readable as it arrives",
+  },
+  {
+    route: "POST /workflows/uploads/:id/parts",
+    does: "declare an upload its parts fill in · ?total=<bytes>",
+  },
+  {
+    route: "PUT  /workflows/uploads/:id/parts",
+    does: "one window of it · ?offset=<byte>, sent concurrently",
+  },
+  { route: "GET  /workflows/uploads/:id", does: "read the bytes back · Range honoured" },
+  { route: "GET  /workflows/uploads/:id/info", does: "name, bytes stored so far, and complete" },
+];
+
+/**
+ * The whole API, collapsed by default.
+ *
+ * `<details>` rather than a state hook: the browser owns disclosure, it is
+ * keyboard-accessible and findable by in-page search without anyone wiring either,
+ * and a page that renders a transcript should not re-render because somebody
+ * expanded a help panel.
+ */
+export function ApiHelp(): ReactNode {
+  return (
+    <details className="rounded-md border">
+      <summary className="cursor-pointer p-4 text-sm font-medium">
+        Use the API without this page
+      </summary>
+      <div className="flex flex-col gap-6 border-t p-4">
+        <p className="text-sm opacity-70">
+          This page is one caller. Everything it does is plain HTTP on this agent's own origin,
+          unauthenticated unless the deployment sets{" "}
+          <code className="text-xs">AAI_WORKFLOW_API_TOKEN</code> (then every route wants{" "}
+          <code className="text-xs">Authorization: Bearer …</code>). A run id is the whole handle —
+          no session, no cookie — so a transcript can be collected from another machine, days later.
+        </p>
+        <p className="text-sm">
+          {/* The API answering for itself: same JSON this form was rendered from. */}
+          <a className="underline" href={API} target="_blank" rel="noreferrer">
+            {`GET ${API}`}
+          </a>{" "}
+          <span className="opacity-70">
+            — the live listing, including each workflow's input schema. Set{" "}
+            <code className="text-xs">AGENT</code> to this page's origin for the recipes below.
+          </span>
+        </p>
+
+        <Recipe
+          title="Store it, then transcribe"
+          note="Sync API. One request per phase, and the upload has to finish before there is a run."
+          script={CLASSIC}
+        />
+        <Recipe
+          title="Transcribe while it uploads"
+          note="Sync API, one upload request, no splitting. The run starts on an id you chose and reads the bytes as they land."
+          script={STREAMING}
+        />
+        <Recipe
+          title="Let the provider do it"
+          note="Async API. No cutting and no seams, it accepts compressed audio, and the wait belongs to the provider's queue."
+          script={BATCH}
+        />
+
+        <section className="flex flex-col gap-2">
+          <h4 className="text-xs font-medium uppercase tracking-[1.2px]">Every route</h4>
+          <ul className="flex flex-col gap-1">
+            {ROUTES.map((entry) => (
+              <li key={entry.route} className="flex flex-col gap-0.5 text-xs sm:flex-row sm:gap-3">
+                <code className="shrink-0 sm:w-72">{entry.route}</code>
+                <span className="opacity-70">{entry.does}</span>
+              </li>
+            ))}
+          </ul>
+        </section>
+      </div>
+    </details>
+  );
+}

package/dist/templates/transcription-workflow/client.tsx

@@ -33,6 +33,62 @@
  * never travel in one; this page contains no upload code because the SDK owns
  * that.
  *
+ * ## Two modes, and the toggle is the template's subject
+ *
+ * The desk offers both flows the agent declares, and the page is where the
+ * difference is legible: pick "while it uploads" and there is a run to watch
+ * before any bytes are in, pick "after it uploads" and there is not. They share
+ * everything else — one `<Form>`, one picker, one progress log, one transcript —
+ * because they take the same input and return the same shape, and the only thing
+ * the page chooses is which HOOK submits it.
+ *
+ * `useWorkflowStream` is the streaming half: it mints the upload id, starts the run
+ * on it, sends the file, and wakes the run when the bytes land. `useWorkflowSubmit`
+ * is the classic half and is unchanged.
+ *
+ * Streaming is the DEFAULT because it is faster on any real recording. The classic
+ * path stays selectable because it is the shape to read first.
+ *
+ * ## The third control is about the UPLOAD, not the flow
+ *
+ * "Split the file across connections" (`parallel`) is orthogonal to the three modes
+ * and applies to all of them, which is why it is a checkbox beside the radios
+ * rather than a fourth option. A single request moves a file at one connection's
+ * throughput, which over any distance is a fraction of the link — so the SDK cuts
+ * the file into megabyte-aligned parts and sends four at once. Nothing about the
+ * workflow changes: the agent reassembles them, `readUpload` reads the same
+ * windows, and the streaming flow still watches the file grow (what it polls is the
+ * CONTIGUOUS prefix, which is honest whether one connection or four are filling
+ * it).
+ *
+ * It is selectable rather than always-on for the reason the modes are: this is the
+ * template where a reader runs both over the same recording and sees what each
+ * costs. It also degrades on its own — a small file, or an agent deployed before
+ * the `/parts` routes existed, sends the single request instead — so leaving it on
+ * is safe.
+ *
+ * ## The transcript ARRIVES, rather than appearing at the end
+ *
+ * A run's `output` exists only when its last segment does, so a page with only
+ * that shows a status line for the whole fan-out and then everything at once — on
+ * a 97-minute recording, minutes of it. Each segment is emitted the moment it
+ * lands (`emit(TRANSCRIPT_STREAM, …)` in `workflows/transcribe.ts`) and
+ * `useWorkflowProgress` reads that stream, so the panel renders the transcript
+ * growing.
+ *
+ * Three things make it honest rather than decorative:
+ *
+ * - **The page stitches with the RUN's own function.** `stitchChunks` is
+ *   `workflows/stitch.ts`, imported by both, so the live text and the stored one
+ *   cannot drift into two different transcripts of one recording.
+ * - **It is a SEPARATE stream from the progress log.** `report()`'s lines go to
+ *   the default one, which `<WorkflowProgress>` renders verbatim; objects in
+ *   there would come out as `[object Object]` between the sentences.
+ * - **The finished run wins.** Once `output` exists the panel renders that
+ *   instead — it is the authoritative text, counted and measured, and a live
+ *   transcript that stayed on screen beside it would be a second answer with no
+ *   way to tell which was current.
+ *
  * ## Two waits, two bars
  *
  * A recording is the one input big enough that STORING it is itself a wait, and
@@ -58,14 +114,24 @@ import {
   page,
   SubmitButton,
   UploadProgressBar,
+  useWorkflowProgress,
   useWorkflowRuns,
+  useWorkflowStream,
   useWorkflowSubmit,
   WorkflowFields,
   WorkflowProgress,
   type WorkflowRun,
 } from "@alexkroman1/aai-ui";
-import { useEffect, useState } from "react";
+import { useEffect, useMemo, useState } from "react";
 import type { transcribe } from "./agent.ts";
+import { ApiHelp } from "./api-help.tsx";
+import {
+  clock,
+  countWords,
+  stitchChunks,
+  TRANSCRIPT_STREAM,
+  type TranscriptChunk,
+} from "./workflows/stitch.ts";
 
 /**
  * What a finished run reports.
@@ -76,15 +142,70 @@ import type { transcribe } from "./agent.ts";
  */
 type Transcript = WorkflowOutputOf<typeof transcribe>;
 
-/** The workflow this page drives. Matches the key in `workflowApp({ workflows })`. */
-const WORKFLOW = "transcribe";
+/**
+ * The three workflows this page drives, keyed by the mode that picks one.
+ *
+ * The STRINGS matter: a page starts a run by name, so a rename in `agent.ts` is a
+ * runtime 400 rather than a compile error. `agent.test.ts` pins all three.
+ */
+const WORKFLOWS = {
+  streaming: "transcribeStream",
+  classic: "transcribe",
+  batch: "transcribeBatch",
+} as const;
+
+/** Which flow the form submits through. */
+type Mode = keyof typeof WORKFLOWS;
+
+/**
+ * What each mode is called, and what picking it changes.
+ *
+ * The notes are the template's actual subject, so they say what the trade IS rather
+ * than which is "best" — the answer depends on the file and the link, and the whole
+ * reason all three ship is that a reader can run them over the same recording.
+ */
+const MODES: readonly { mode: Mode; label: string; note: string }[] = [
+  {
+    mode: "streaming",
+    label: "While it uploads",
+    note: "Sync API. The run starts first and transcribes each segment as its bytes land, so progress is visible while the file is still moving.",
+  },
+  {
+    mode: "classic",
+    label: "After it uploads",
+    note: "Sync API. Store the whole recording, then fan out over it. The simplest shape, and the quickest on a fast link.",
+  },
+  {
+    mode: "batch",
+    label: "Let the provider do it",
+    note: "Async API. One job, no cutting, no seams — and it accepts MP3 and M4A, which the two above refuse.",
+  },
+];
 
 /** Most past runs the history list shows. */
 const HISTORY_LIMIT = 10;
 
 function TranscriptionDesk() {
-  const { submit, run, upload, pending, error, reset } = useWorkflowSubmit<Transcript>(WORKFLOW);
-  const history = useWorkflowRuns<Transcript>(WORKFLOW, { limit: HISTORY_LIMIT });
+  const [mode, setMode] = useState<Mode>("streaming");
+  // Whether the browser cuts the recording up and sends the pieces at once. One
+  // piece of state for all three hooks, because it describes the UPLOAD and every
+  // mode has one — see the module doc.
+  const [parallel, setParallel] = useState(true);
+  // ALL THREE hooks are called every render, because a hook may not be conditional —
+  // and that costs nothing here: none of them does anything until its `submit` is
+  // called, and `useWorkflowRun` underneath them holds no id until then either.
+  const streamed = useWorkflowStream<Transcript>(WORKFLOWS.streaming, { parallel });
+  const stored = useWorkflowSubmit<Transcript>(WORKFLOWS.classic, { parallel });
+  const batched = useWorkflowSubmit<Transcript>(WORKFLOWS.batch, { parallel });
+  // The batch flow uploads the same way the classic one does — the id comes from the
+  // store — so it is the SAME hook against a different workflow. Only the streaming
+  // mode needs the other one, because only it needs the id before the bytes.
+  const active = mode === "streaming" ? streamed : mode === "batch" ? batched : stored;
+  const { submit, run, upload, pending, error, reset } = active;
+  // History is per WORKFLOW, so the list follows the mode: two flows that produce
+  // the same output are still two different things to have run, and merging them
+  // would put a run under a heading that cannot explain it.
+  const history = useWorkflowRuns<Transcript>(WORKFLOWS[mode], { limit: HISTORY_LIMIT });
   // Which past run the reader is looking at, if any. Its own state rather than
   // a route, because a workflow app is one page and a run id is not a place.
   const [openId, setOpenId] = useState<string | undefined>(undefined);
@@ -110,10 +231,16 @@ function TranscriptionDesk() {
         </p>
       </header>
 
-      {/* No mapping: the collected values already match the input schema. */}
+      <ModePicker mode={mode} onPick={setMode} disabled={pending} />
+
+      <UploadPicker parallel={parallel} onPick={setParallel} disabled={pending} />
+
+      {/* No mapping: the collected values already match the input schema. All three
+          workflows declare `recording` as an upload, so the same picker serves every
+          mode — how the bytes travel is not a question to ask a person. */}
       <Form onSubmit={(values) => submit(values)} error={error}>
         {/* The NAME, so the schema is fetched here rather than by this page. */}
-        <WorkflowFields workflow={WORKFLOW} />
+        <WorkflowFields workflow={WORKFLOWS[mode]} />
         {/* Unguarded on purpose: it renders nothing until there are bytes in
             flight, and nothing again once they have landed. */}
         <UploadProgressBar upload={upload} />
@@ -128,10 +255,101 @@ function TranscriptionDesk() {
         openId={openId}
         onOpen={(runId) => setOpenId((current) => (current === runId ? undefined : runId))}
       />
+
+      {/* The most useful thing about a workflow app is the least discoverable:
+          this page is one caller of an ordinary HTTP API. See `api-help.tsx`. */}
+      <ApiHelp />
     </main>
   );
 }
 
+/**
+ * Which flow submits, as two radios.
+ *
+ * Radios rather than a toggle or a select, because the choice has a REASON per
+ * option and a radio group is the one control with room to show it — the note
+ * under each label is what makes this a decision rather than a switch somebody
+ * flips to see what happens.
+ *
+ * Disabled while a submission is in flight: the two hooks hold separate run state,
+ * so switching mid-run would swap the panel for the other hook's (empty) one and
+ * read as the run having vanished.
+ */
+function ModePicker({
+  mode,
+  onPick,
+  disabled,
+}: {
+  mode: Mode;
+  onPick: (next: Mode) => void;
+  disabled: boolean;
+}) {
+  return (
+    <fieldset className="flex flex-col gap-3" disabled={disabled}>
+      <legend className="text-sm font-medium uppercase tracking-[1.2px]">Transcribe</legend>
+      {MODES.map((option) => (
+        <label key={option.mode} className="flex items-start gap-3 text-sm">
+          <input
+            type="radio"
+            name="mode"
+            className="mt-1"
+            value={option.mode}
+            checked={mode === option.mode}
+            onChange={() => onPick(option.mode)}
+          />
+          <span className="flex flex-col gap-0.5">
+            <span>{option.label}</span>
+            <span className="text-xs opacity-70">{option.note}</span>
+          </span>
+        </label>
+      ))}
+    </fieldset>
+  );
+}
+
+/**
+ * How the recording travels, as one checkbox.
+ *
+ * Beside the mode radios rather than among them because it answers a different
+ * question — those pick the WORKFLOW, this picks how its input gets there — and
+ * every mode is uploading a file either way.
+ *
+ * Disabled mid-submission for the same reason the radios are: the bytes are
+ * already moving, and a control that looks live while changing nothing is worse
+ * than one that is plainly unavailable.
+ */
+function UploadPicker({
+  parallel,
+  onPick,
+  disabled,
+}: {
+  parallel: boolean;
+  onPick: (next: boolean) => void;
+  disabled: boolean;
+}) {
+  return (
+    <fieldset className="flex flex-col gap-3" disabled={disabled}>
+      <legend className="text-sm font-medium uppercase tracking-[1.2px]">Upload</legend>
+      <label className="flex items-start gap-3 text-sm">
+        <input
+          type="checkbox"
+          className="mt-1"
+          name="parallel"
+          checked={parallel}
+          onChange={(event) => onPick(event.target.checked)}
+        />
+        <span className="flex flex-col gap-0.5">
+          <span>Split the file across connections</span>
+          <span className="text-xs opacity-70">
+            Sends the recording as several parts at once instead of in one request, which is most of
+            the wait on a long file. Falls back to the single request on a small one.
+          </span>
+        </span>
+      </label>
+    </fieldset>
+  );
+}
+
 /**
  * Every recent run, newest first, with its transcript one click away.
  *
@@ -214,13 +432,19 @@ function RunPanel({ run, onClear }: { run: WorkflowRun<Transcript>; onClear?: ()
           finished run up in the panel below shows how it got there. */}
       <WorkflowProgress runId={run.runId} />
 
+      {/* While it runs, the transcript so far. Unguarded on the run's status
+          beyond this: the component renders nothing until a segment has landed,
+          and stops the moment there is an `output` to render instead. */}
+      {!isTerminal(run) && <LiveTranscript runId={run.runId} />}
+
       {/* Discriminated on `status`, so `output` and `error` are reachable
           without a cast — the reason a snapshot is a union rather than a flat
           object with optional fields. */}
       {run.status === "completed" && (
         <>
           <p className="text-xs opacity-60">
-            {run.output.segments} segments · {Math.round(run.output.durationMs / 1000)}s ·{" "}
+            {run.output.segments} {run.output.segments === 1 ? "segment" : "segments"} ·{" "}
+            {duration(run.output.durationMs)} of audio · took {duration(run.output.elapsedMs)} ·{" "}
             {run.output.words} words
           </p>
           <pre className="whitespace-pre-wrap text-sm leading-relaxed">{run.output.transcript}</pre>
@@ -231,6 +455,66 @@ function RunPanel({ run, onClear }: { run: WorkflowRun<Transcript>; onClear?: ()
   );
 }
 
+/**
+ * The transcript as it arrives, stitched from the segments that have landed.
+ *
+ * The other half of `<WorkflowProgress>` above it: that one renders what the run
+ * SAYS about itself, this one renders what it has produced. Both are the same
+ * mechanism — a run's output stream — separated by the namespace, which is what
+ * lets this one be typed.
+ *
+ * It renders NOTHING until a segment lands, so a page can mount it unguarded:
+ * before the first chunk there is nothing to say that the progress log is not
+ * already saying better.
+ *
+ * The count is derived from the stitched text rather than summed per chunk,
+ * because the seams overlap — adding up the segments would over-count every one
+ * of them by a couple of seconds' worth of words.
+ */
+function LiveTranscript({ runId }: { runId: string }) {
+  const { progress } = useWorkflowProgress<TranscriptChunk>(runId, {
+    namespace: TRANSCRIPT_STREAM,
+  });
+  // Memoized on the ARRAY, which the hook appends to per read: stitching is a
+  // seam search per segment, and a fan-out re-renders this panel on every
+  // progress poll whether or not anything arrived.
+  const transcript = useMemo(() => stitchChunks(progress), [progress]);
+  if (progress.length === 0) return null;
+
+  // The furthest point reached, not the count: segments land out of order, so
+  // "6 segments" says nothing about how much of the recording is covered.
+  const covered = Math.max(...progress.map((chunk) => chunk.endMs));
+  return (
+    <div className="flex flex-col gap-2">
+      <p className="text-xs opacity-60">
+        {countWords(transcript)} words so far · through {clock(covered)}
+      </p>
+      <pre className="whitespace-pre-wrap text-sm leading-relaxed opacity-80">{transcript}</pre>
+    </div>
+  );
+}
+
+/**
+ * A duration a person can read.
+ *
+ * `${Math.round(ms / 1000)}s` was what this printed, and an hour-long recording came
+ * out as `3746s` — which a reader asked whether they should parse as 37.46 seconds.
+ * A raw second count stops being readable at about ninety of them, and the recordings
+ * this desk is FOR are the ones past that.
+ *
+ * The hours component is omitted when it is zero rather than padded to `0:02:26`, so
+ * a two-minute clip reads as `2:26` and only a long one grows a field.
+ */
+function duration(ms: number): string {
+  const total = Math.max(0, Math.round(ms / 1000));
+  const seconds = String(total % 60).padStart(2, "0");
+  const minutes = Math.floor(total / 60) % 60;
+  const hours = Math.floor(total / 3600);
+  return hours > 0
+    ? `${hours}:${String(minutes).padStart(2, "0")}:${seconds}`
+    : `${minutes}:${seconds}`;
+}
+
 /**
  * One line describing where a run has got to.
  *