@alexkroman1/aai-cli 6.4.0 → 6.5.1

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

@@ -42,15 +42,52 @@
  * 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 cuts the file with the cutter this
- * template supplies (`cut-wav.ts`, which is `workflows/wav.ts` run in the browser),
- * uploads each part under one group token, and wakes the run as each lands.
- * `useWorkflowSubmit` is the classic half and is unchanged.
+ * `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, and because it is
- * the one that works on a file this browser cannot parse — the cutter needs a WAV
- * header, where the server-side flow reaches the same conclusion in its first step.
+ * 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
  *
@@ -77,6 +114,7 @@ import {
   page,
   SubmitButton,
   UploadProgressBar,
+  useWorkflowProgress,
   useWorkflowRuns,
   useWorkflowStream,
   useWorkflowSubmit,
@@ -84,9 +122,16 @@ import {
   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.
@@ -142,12 +187,16 @@ const HISTORY_LIMIT = 10;
 
 function TranscriptionDesk() {
   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);
-  const stored = useWorkflowSubmit<Transcript>(WORKFLOWS.classic);
-  const batched = useWorkflowSubmit<Transcript>(WORKFLOWS.batch);
+  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.
@@ -184,6 +233,8 @@ function TranscriptionDesk() {
 
       <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. */}
@@ -256,6 +307,49 @@ function ModePicker({
   );
 }
 
+/**
+ * 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.
  *
@@ -338,6 +432,11 @@ 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. */}
@@ -356,6 +455,45 @@ 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.
  *

package/dist/templates/transcription-workflow/workflows/batch.ts

@@ -40,12 +40,14 @@
  *
  * That is also why the step that does it is the step the DevKit retries: a streaming
  * body is consumed once, so a retry has to re-read the upload from the start, which
- * it does.
+ * it does. One window of READ-AHEAD keeps the store and the socket busy at the same
+ * time; `windows` carries the argument.
  */
 
 import { throwFatalStepError, toStepError } from "@alexkroman1/aai/step-errors";
-import { readUpload, report, requireStepEnv, stepFetch, uploadInfo } from "@alexkroman1/aai/utils";
+import { readUpload, report, stepFetch, uploadInfo } from "@alexkroman1/aai/utils";
 import { sleep } from "workflow";
+import { apiKeyOrFatal } from "./sync-api.ts";
 import { countWords, startClock, type Transcript } from "./transcribe.ts";
 
 /** The async API's base. */
@@ -65,9 +67,6 @@ const API = "https://api.assemblyai.com";
  */
 const MODELS = ["universal-3-5-pro"];
 
-/** The key a step reads out of the agent env. Declared in `agent.ts`'s `requiredEnv`. */
-const API_KEY_ENV = "ASSEMBLYAI_API_KEY";
-
 /** How much of our stored upload one outbound window carries. */
 const UPLOAD_WINDOW_BYTES = 4 * 1024 * 1024;
 
@@ -100,8 +99,13 @@ const MAX_POLLS = 360;
 export async function transcribeBatchFlow(input: { recording: string }): Promise<Transcript> {
   "use workflow";
 
-  const startedAt = await startClock();
-  const { audioUrl } = await uploadToProvider(input.recording);
+  // Both at once: the clock does not depend on the upload, and issuing them
+  // together costs one round trip instead of two before a byte moves. Their issue
+  // order is still decided by this line rather than by which lands first.
+  const [startedAt, { audioUrl }] = await Promise.all([
+    startClock(),
+    uploadToProvider(input.recording),
+  ]);
   const job = await createJob(audioUrl);
 
   for (let poll = 0; poll < MAX_POLLS; poll += 1) {
@@ -241,26 +245,33 @@ export async function readTranscript(
 }
 
 /**
- * The stored upload as a sequence of windows.
+ * The stored upload as a sequence of windows, with the next one already in flight.
  *
  * A generator rather than one `readUpload`, because the whole point is that the file
  * is never held: each window is read, sent, and dropped. `readUpload` clamps to what
  * is stored, so the loop ends on the real end of the file even if `size` moved.
+ *
+ * **One window of READ-AHEAD**, which is the whole concurrency available here: the
+ * consumer is a socket and the producer is the app's own store, and read-then-send
+ * makes them strictly alternate — the store idles while bytes go out, and the socket
+ * idles while the next window is fetched. Starting the next read before yielding the
+ * current window overlaps them, so a gigabyte upload pays the larger of the two
+ * rather than their sum. Exactly one, not a queue: a deeper buffer holds more of a
+ * file this generator exists to avoid holding, and there is nothing to gain past
+ * keeping both ends busy.
  */
 async function* windows(uploadId: string, size: number): AsyncGenerator<Uint8Array> {
-  for (let at = 0; at < size; at += UPLOAD_WINDOW_BYTES) {
-    const slice = await readUpload(uploadId, { start: at, end: at + UPLOAD_WINDOW_BYTES });
-    if (slice.bytes.length === 0) return;
-    yield slice.bytes;
-  }
-}
-
-/** The API key, or a terminal failure — three more attempts find the same gap. */
-function apiKeyOrFatal(): string {
-  try {
-    return requireStepEnv(API_KEY_ENV);
-  } catch (err: unknown) {
-    return throwFatalStepError(err);
+  const read = (at: number): Promise<Uint8Array> =>
+    readUpload(uploadId, { start: at, end: at + UPLOAD_WINDOW_BYTES }).then((slice) => slice.bytes);
+  let at = 0;
+  let next = at < size ? read(at) : undefined;
+  while (next !== undefined) {
+    const bytes = await next;
+    if (bytes.length === 0) return;
+    at += UPLOAD_WINDOW_BYTES;
+    // Issued BEFORE the yield, so the store is fetching while the socket sends.
+    next = at < size ? read(at) : undefined;
+    yield bytes;
   }
 }
 

package/dist/templates/transcription-workflow/workflows/stitch.ts

@@ -0,0 +1,133 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * Joining segment transcripts back into one — and the only module here the PAGE
+ * imports.
+ *
+ * That is the whole reason it exists as its own file. Segments are transcribed
+ * one per step and each one is emitted the moment it lands (`emit("transcript",
+ * …)` in `transcribe.ts`), so the page can render the answer growing rather than
+ * a spinner — and to render it, the page has to do exactly what `mergeTranscript`
+ * does at the end: put the pieces in order and drop the words the overlap made
+ * duplicates.
+ *
+ * Two copies of that would drift, and they would drift INVISIBLY: a live
+ * transcript that stitches differently from the stored one reads as the model
+ * having changed its mind. So the seam logic is here, imported by the run and by
+ * the browser, with nothing else in the module — no directive, no I/O, no SDK
+ * import — so pulling it into the client bundle costs a few hundred bytes.
+ *
+ * `wav.ts` and `sync-api.ts` sit under `workflows/` on the same terms: the WDK
+ * builder scans this directory and transforms only what carries a directive.
+ */
+
+/**
+ * The stream a run publishes its segments into as they land.
+ *
+ * Declared HERE because it is the one string the run and the page have to agree
+ * on: a step emits into it and `client.tsx` subscribes by it, and a typo is a
+ * panel that renders nothing with nothing saying why. Both sync flows write it;
+ * the async flow has one segment and nothing to stream.
+ */
+export const TRANSCRIPT_STREAM = "transcript";
+
+/**
+ * One segment as it goes over {@link TRANSCRIPT_STREAM}.
+ *
+ * Its own type rather than the step's journaled result widened, because the two
+ * have different readers: `mergeTranscript` needs an index and words, while
+ * somebody watching a partial transcript needs to know WHICH part of the
+ * recording each piece is — the list has holes in it until the run finishes, and
+ * "0:00–1:30" beside a paragraph is what explains a jump.
+ */
+export type TranscriptChunk = {
+  index: number;
+  /** Where this piece starts in the recording. */
+  startMs: number;
+  /** Where it ends. */
+  endMs: number;
+  text: string;
+};
+
+/** Most words {@link stitchTranscript} will look back over to find a repeated seam. */
+const MAX_SEAM_WORDS = 40;
+
+/** A word, stripped of the punctuation the decoder added, for seam comparison. */
+function seamKey(word: string): string {
+  return word.toLowerCase().replace(/[^\p{L}\p{N}']/gu, "");
+}
+
+/**
+ * Join segment transcripts, dropping the words the overlap made duplicates.
+ *
+ * Segments overlap by `SEGMENT_OVERLAP_SECONDS` (see `wav.ts` for why), so the
+ * last few words of one segment are the first few of the next — verbatim when
+ * the decoder heard them the same way, which is the common case because it heard
+ * the same audio. This finds the longest such run and removes one copy.
+ *
+ * Comparison is on `seamKey`, not the raw words: the two passes punctuate
+ * differently at their own edges (one ends a sentence where the other is
+ * mid-clause), so `"today."` and `"today"` are the same word and a raw compare
+ * finds no seam at all. The text KEPT is the raw text — only the match is
+ * normalized.
+ *
+ * A missed seam repeats a few words, which a reader can see and forgive. A
+ * false one would delete speech, so the search is bounded at
+ * {@link MAX_SEAM_WORDS} and always prefers the LONGEST match: a single repeated
+ * "the" is not evidence of anything, and requiring the longest run is what stops
+ * it counting as one when a longer match is available.
+ *
+ * **A gap is not a seam, which is what makes this safe to run on a PARTIAL
+ * list.** The page stitches whatever segments have arrived, and while a run is in
+ * flight that list has holes in it — segment 4 may land before segment 3. Two
+ * pieces that were never adjacent share no overlap, so no seam is found and both
+ * are kept whole: the live text reads with a jump in it until the missing piece
+ * arrives, rather than quietly losing a sentence.
+ */
+export function stitchTranscript(parts: readonly string[]): string {
+  const merged: string[] = [];
+  for (const part of parts) {
+    const next = part.split(/\s+/).filter(Boolean);
+    if (next.length === 0) continue;
+    if (merged.length === 0) {
+      merged.push(...next);
+      continue;
+    }
+    merged.push(...next.slice(seamLength(merged, next)));
+  }
+  return merged.join(" ");
+}
+
+/** How many leading words of `next` repeat the tail of `merged`. */
+function seamLength(merged: readonly string[], next: readonly string[]): number {
+  const limit = Math.min(MAX_SEAM_WORDS, merged.length, next.length);
+  // Longest first, so a short accidental match never wins over a real seam.
+  for (let length = limit; length > 0; length--) {
+    const tail = merged.slice(merged.length - length);
+    if (tail.every((word, at) => seamKey(word) === seamKey(next[at] ?? ""))) return length;
+  }
+  return 0;
+}
+
+/**
+ * Order the chunks that have arrived and stitch them — what the PAGE renders.
+ *
+ * Sorted here rather than by the caller because arrival order is the one thing a
+ * live reader definitely does not have: segments are transcribed concurrently and
+ * each is emitted the moment it lands, so chunk 4 routinely precedes chunk 3.
+ *
+ * A COPY, because the caller's list is React state.
+ */
+export function stitchChunks(chunks: readonly TranscriptChunk[]): string {
+  return stitchTranscript([...chunks].sort((a, b) => a.index - b.index).map((chunk) => chunk.text));
+}
+
+/** Words in a string. The run and the page count them the same way. */
+export function countWords(text: string): number {
+  return text.split(/\s+/).filter(Boolean).length;
+}
+
+/** `m:ss` for the progress log — a byte offset means nothing to a reader. */
+export function clock(ms: number): string {
+  const seconds = Math.max(0, Math.round(ms / 1000));
+  return `${Math.floor(seconds / 60)}:${String(seconds % 60).padStart(2, "0")}`;
+}

package/dist/templates/transcription-workflow/workflows/stream.ts

@@ -101,20 +101,29 @@
  * shape and is never slower, which is why the page offers both rather than replacing
  * one with the other.
  *
- * ## And a batch has to finish before the next poll
+ * ## A ROUND has to finish before the next poll
  *
- * The DevKit correlates a journal entry to a step call by ISSUE ORDER, which is what
- * rules out a work-stealing pool — `mapInBatches`'s own doc carries the argument. So
- * a segment that becomes readable while a batch is running waits for that batch. On
- * a slow uplink that costs nothing (segments arrive slower than they transcribe); on
- * a fast one it is why the two flows converge rather than the streaming one winning.
+ * Everything the body decides comes from a journaled poll, so the set of segments it
+ * fans out over is fixed for the length of that fan-out: one that becomes readable
+ * while a round is in flight waits for the round. That is a smaller wait than it was
+ * — `mapConcurrent` is a window over a cursor rather than sequential batches, so a
+ * round now ends when its LAST segment lands rather than at the sum of each batch's
+ * slowest — but it is not zero, and it is why the two flows converge on a fast
+ * uplink rather than the streaming one winning. On a slow uplink it costs nothing:
+ * segments arrive slower than they transcribe.
+ *
+ * Feeding new segments into a running fan-out would remove it and is deliberately
+ * not done: which items are in flight would then depend on when bytes arrived, and
+ * the DevKit correlates a journal entry to a step call by ISSUE ORDER. A round is
+ * what keeps that order a pure function of journaled values.
  */
 
 import { throwFatalStepError } from "@alexkroman1/aai/step-errors";
-import { mapInBatches, readUpload, report, uploadInfo } from "@alexkroman1/aai/utils";
+import { mapConcurrent, readUpload, report, uploadInfo } from "@alexkroman1/aai/utils";
 import { sleep } from "workflow";
 import {
   clock,
+  fatalOnUnsupported,
   mergeTranscript,
   type SegmentTranscript,
   segmentConcurrency,
@@ -209,10 +218,11 @@ export async function transcribeStreamFlow(input: { recording: string }) {
         lastSize = at.size;
         for (const segment of ready) done.add(segment.index);
         // One step per segment, bounded, in an order a replay reproduces exactly —
-        // `ready` is derived from a journaled poll, and `mapInBatches` issues its
-        // calls in array order. THE SAME STEP the classic flow uses.
+        // `ready` is derived from a journaled poll, and `mapConcurrent` issues its
+        // calls in list order. THE SAME STEP the classic flow uses, so a segment
+        // transcribed here reaches the page's live transcript identically.
         parts.push(
-          ...(await mapInBatches(
+          ...(await mapConcurrent(
             ready,
             segmentConcurrency((plan as StreamPlan).format),
             (segment) => transcribeSegment(input.recording, (plan as StreamPlan).format, segment),
@@ -314,16 +324,6 @@ function expectedSegments(plan: StreamPlan, size: number): number {
   return plan.segments.filter((segment) => segment.start < size).length;
 }
 
-/** Run a `wav.ts` helper, turning its "cannot cut this" into a terminal failure. */
-function fatalOnUnsupported<T>(read: () => T): T {
-  try {
-    return read();
-  } catch (err: unknown) {
-    if (err instanceof UnsupportedRecordingError) return throwFatalStepError(err);
-    throw err;
-  }
-}
-
 /**
  * Give up on an upload that stopped arriving.
  *

package/dist/templates/transcription-workflow/workflows/sync-api.ts

@@ -104,8 +104,14 @@ export async function transcribeWav(
   return (body.text ?? "").trim();
 }
 
-/** The API key, or a terminal failure — three more attempts find the same gap. */
-function apiKeyOrFatal(): string {
+/**
+ * The API key, or a terminal failure — three more attempts find the same gap.
+ *
+ * Exported because `batch.ts` calls the same provider on the same key and had
+ * written this, and its own `API_KEY_ENV`, again. The key belongs to the
+ * PROVIDER; only the endpoint and its failure shapes belong to this module.
+ */
+export function apiKeyOrFatal(): string {
   try {
     return requireStepEnv(API_KEY_ENV);
   } catch (err: unknown) {