@alexkroman1/aai-cli 6.3.1 → 6.4.0

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

@@ -0,0 +1,341 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * The streaming desk: transcribe the recording WHILE it uploads.
+ *
+ * Read `transcribe.ts` first. This does the same three jobs — plan, transcribe,
+ * stitch — with the same two steps doing the middle and the end, and the only thing
+ * it changes is WHEN. That one change is the reason it exists:
+ *
+ * | | `transcribe` | `transcribeStream` |
+ * | --- | --- | --- |
+ * | the run starts | after the last byte is stored | before the first one is |
+ * | the client sends | `POST /workflows/uploads` | `PUT /workflows/uploads/<id>` |
+ * | who names the upload | the store | the CLIENT |
+ * | the body | plans once, fans out once | polls, fans out over what has arrived |
+ *
+ * ## The client names the upload, and that is the whole trick
+ *
+ * An ordinary upload cannot help here: `POST` answers with an id once the last byte
+ * is stored, so there is nothing to put in a run input until the upload is over. A
+ * STREAMED upload is named by its caller — `useWorkflowStream` mints an id, starts
+ * the run on it, and PUTs the file in one request — so the record exists from the
+ * first byte with `complete: false` and its `size` grows as bytes land.
+ *
+ * The reader needed almost nothing for this, which is why this flow is so close to
+ * the other one: `readUpload` already clamped its window to what is stored (so a
+ * plan computed from a header could end one byte past the file), and that clamp is
+ * exactly "read what has arrived". So `transcribeSegment` below is `transcribe.ts`'s
+ * OWN step, unchanged, called on windows this body has checked are present.
+ *
+ * ## `complete`, never a stalled `size`
+ *
+ * The exit is the upload's `complete` flag. A `size` that has stopped growing means
+ * only that nothing arrived recently, which is what a slow link and a dead client
+ * both look like — so a body that took a stalled size for the end would return a
+ * transcript of most of a recording and report success. The stall is what
+ * {@link MAX_IDLE_POLLS} is for, and it FAILS the run rather than finishing it.
+ *
+ * ## It really does overlap, and the granularity is a SEGMENT
+ *
+ * Watched directly — the same 10-minute recording at 2 MB/s, polling the upload's
+ * `size` and counting `Transcribed …` lines in the run's own log:
+ *
+ * ```text
+ *    1s    2 MB uploaded   0 segments transcribed
+ *   14s   26 MB            1          <- first one, at 24% of the file
+ *   23s   45 MB            2
+ *   32s   63 MB            3
+ *   41s   82 MB            4
+ *   48s   94 MB            5
+ *   54s  106 MB            6
+ *   55s  ---- PUT returns ----
+ *   60s  109 MB            7          <- run completed
+ * ```
+ *
+ * **Six of seven segments were transcribed before the upload finished.** So the run
+ * does not wait for the file — and it does not start on the first CHUNK either, which
+ * is worth being exact about: a segment is the smallest thing the sync endpoint can
+ * decode, so the floor is "one segment has landed", not "some bytes have". Three
+ * granularities stack up to that:
+ *
+ * - a segment is `SEGMENT_SECONDS + SEGMENT_OVERLAP_SECONDS` of audio — ~17.6 MB at
+ *   48 kHz stereo, which is ~9s of a 2 MB/s uplink;
+ * - the store publishes `size` a `UPLOAD_CHUNK_BYTES` chunk at a time (1 MiB), so the
+ *   view a poll reads is at most a megabyte stale;
+ * - the body sleeps {@link POLL_INTERVAL} between polls when nothing is ready, cut
+ *   short by the client's wake.
+ *
+ * 9s + one poll is the 14s above. Nothing here can go below a segment without a
+ * different provider API — which is what the third flow (`batch.ts`) is.
+ *
+ * ## What it actually saves, measured
+ *
+ * Run against a real dev server on a 10-minute 48 kHz stereo recording (115 MB, 7
+ * segments), with `curl --limit-rate` standing in for an uplink:
+ *
+ * | uplink | classic (upload + run) | streaming (upload + tail) | saved |
+ * | --- | --- | --- | --- |
+ * | loopback | 0.3 + 5.3 = 5.5s | 0.2 + 5.3 = 5.5s | 0s |
+ * | 8 MB/s | 13.8 + 4.2 = 18.0s | 13.9 + 3.2 = 17.1s | 0.9s |
+ * | 2 MB/s | 55.1 + 4.3 = 59.4s | 55.1 + 2.2 = 57.3s | 2.1s |
+ *
+ * Read the TAIL column, which is the whole mechanism: it shrinks as the uplink slows
+ * (5.3s -> 3.2s -> 2.2s) because more of the transcription has already happened
+ * behind the upload by the time the last byte lands. The floor is one segment.
+ *
+ * **So the saving is roughly ONE segment's latency, not a proportion of the file** —
+ * and the reason is structural rather than a tuning problem. Every segment but the
+ * last is transcribed during the upload, and the last one cannot start until its
+ * bytes land, so both flows end at `upload + one segment`. The transcription is the
+ * small term for any file this endpoint accepts: it runs 20-200x faster than
+ * realtime, so a recording long enough for the difference to matter is a recording
+ * whose upload dominates either way.
+ *
+ * It grows with LENGTH rather than with size, because concurrency is capped: a
+ * 97-minute recording is ~65 segments in ~9 rounds, and eight of those rounds happen
+ * behind the upload instead of after it.
+ *
+ * What it always buys, at any length, is the thing a table cannot show: the page
+ * shows real progress — segment timings, arriving — while the bytes are still
+ * moving, instead of a bar and then a wait. The classic flow remains the simpler
+ * 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
+ *
+ * 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.
+ */
+
+import { throwFatalStepError } from "@alexkroman1/aai/step-errors";
+import { mapInBatches, readUpload, report, uploadInfo } from "@alexkroman1/aai/utils";
+import { sleep } from "workflow";
+import {
+  clock,
+  mergeTranscript,
+  type SegmentTranscript,
+  segmentConcurrency,
+  startClock,
+  transcribeSegment,
+} from "./transcribe.ts";
+import {
+  offsetToMs,
+  parseWav,
+  planSegments,
+  type Segment,
+  UnsupportedRecordingError,
+  type WavFormat,
+} from "./wav.ts";
+
+/** How long the body waits between polls when nothing new has arrived. */
+const POLL_INTERVAL = "5s";
+
+/**
+ * Consecutive polls with NO new bytes before the run gives up.
+ *
+ * An upload that died stays incomplete forever, so without a bound the run polls for
+ * as long as the world will replay it. At {@link POLL_INTERVAL} this is five minutes
+ * of silence — far longer than any stall a live uplink produces, and short enough
+ * that the failure reaches whoever is watching.
+ *
+ * It resets on every byte, so a slow upload is bounded by its own quietest gap
+ * rather than by its total length: a two-hour recording on a bad connection is fine
+ * as long as something arrives every five minutes.
+ */
+const MAX_IDLE_POLLS = 60;
+
+/** Bytes probed for the WAV header — the same window `splitRecording` uses. */
+const HEADER_PROBE_BYTES = 64 * 1024;
+
+/** What one poll of the upload found. */
+export type UploadProgressView = {
+  /** Bytes stored so far. */
+  size: number;
+  /** Whether that is all of them. The ONLY field an exit may be decided on. */
+  complete: boolean;
+};
+
+/** The cut, derived once from the header. */
+export type StreamPlan = {
+  format: WavFormat;
+  segments: Segment[];
+};
+
+/**
+ * Transcribe a recording that is still uploading.
+ *
+ * The input is what `POST /workflows/runs` carries — see `agent.ts`. `recording` is
+ * an upload id exactly as in the classic flow; what differs is that the client chose
+ * it and the bytes are still on their way.
+ */
+export async function transcribeStreamFlow(input: { recording: string }) {
+  "use workflow";
+
+  const startedAt = await startClock();
+  let plan: StreamPlan | undefined;
+  // Body state, and legal because every value in it came out of a journaled step
+  // result — a replay rebuilds the identical sets in the identical order.
+  const done = new Set<number>();
+  const parts: SegmentTranscript[] = [];
+  let idlePolls = 0;
+  let lastSize = -1;
+
+  for (;;) {
+    const at = await probeUpload(input.recording);
+
+    // The header has to be present before anything can be planned, and it is the
+    // first thing to arrive. `complete` also qualifies, for a recording shorter
+    // than the probe window.
+    if (!plan && (at.size >= HEADER_PROBE_BYTES || at.complete)) {
+      plan = await planStreamed(input.recording);
+    }
+
+    if (plan) {
+      // A segment is READY when its whole window is stored — except once the upload
+      // is complete, where `at.size` is the true total and the plan came from the
+      // header's DECLARED length: a recording that came up short leaves a final
+      // segment ending past the file, and `readUpload` clamping is what makes that
+      // the right answer rather than an error.
+      const ready = plan.segments.filter(
+        (segment) =>
+          !done.has(segment.index) &&
+          (segment.end <= at.size || (at.complete && segment.start < at.size)),
+      );
+      if (ready.length > 0) {
+        idlePolls = 0;
+        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.
+        parts.push(
+          ...(await mapInBatches(
+            ready,
+            segmentConcurrency((plan as StreamPlan).format),
+            (segment) => transcribeSegment(input.recording, (plan as StreamPlan).format, segment),
+          )),
+        );
+        // Straight back to the top WITHOUT sleeping, and this line was measured
+        // rather than reasoned about. A batch takes seconds, so by the time it
+        // finishes the upload has moved on and the view above is stale — deciding
+        // anything on it means sleeping through news that has already arrived.
+        // Measured by deleting this one statement, 10-minute recording at 8 MB/s:
+        // the tail goes 3.2s -> 9.5s and the run 17.1s -> 23.4s. A poll is one cheap
+        // step; sleeping is only right when there was nothing to do.
+        continue;
+      }
+    }
+
+    // Nothing to work on, so this view is current and the exit can be trusted.
+    if (at.complete && plan && done.size >= expectedSegments(plan, at.size)) break;
+    // A stall, not an ending — see MAX_IDLE_POLLS.
+    if (at.size === lastSize) idlePolls += 1;
+    else {
+      idlePolls = 0;
+      lastSize = at.size;
+    }
+    if (idlePolls > MAX_IDLE_POLLS) abandon(input.recording, at);
+    await sleep(POLL_INTERVAL);
+  }
+
+  const finished = plan;
+  if (!finished) abandon(input.recording, { size: 0, complete: false });
+  return await mergeTranscript(
+    input.recording,
+    offsetToMs(finished.format, Math.min(finished.format.dataEnd, lastSize)),
+    parts,
+    startedAt,
+  );
+}
+
+/**
+ * How much of the upload is stored, and whether that is all of it.
+ *
+ * A step because it is I/O, which a body may not do — and because what the body does
+ * next is derived from its RESULT, so journaling it is what makes the run take the
+ * same branches on a replay. It narrates nothing: sixty "still uploading" lines
+ * would bury the ones that matter, and `transcribeSegment` is where the log comes
+ * from.
+ */
+export async function probeUpload(id: string): Promise<UploadProgressView> {
+  "use step";
+
+  const info = await uploadInfo(id);
+  return { size: info.size, complete: info.complete };
+}
+
+/**
+ * Read the header and decide where to cut — from the DECLARED length.
+ *
+ * The one real difference from `splitRecording` next door, and it is a one-argument
+ * difference: that step passes the upload's own size, which for a file still
+ * arriving is only what has landed so far and would plan a fraction of the
+ * recording. `Number.POSITIVE_INFINITY` makes `parseWav` return the length the
+ * header DECLARES, which is known from the first 64 KB — so the whole plan exists
+ * before most of the audio does.
+ *
+ * A WAV declaring no length at all cannot be planned this way and is refused by
+ * name: there is nothing to compute a segment list from until the file has finished,
+ * which is what the classic flow is for.
+ */
+export async function planStreamed(id: string): Promise<StreamPlan> {
+  "use step";
+
+  const head = await readUpload(id, { end: HEADER_PROBE_BYTES });
+  const format = fatalOnUnsupported(() => parseWav(head.bytes, Number.POSITIVE_INFINITY));
+  if (!Number.isFinite(format.dataEnd)) {
+    return throwFatalStepError(
+      new UnsupportedRecordingError(
+        "That WAV declares no data length, so its segments cannot be planned before it has " +
+          "finished uploading. Use the `transcribe` workflow, which stores the file first.",
+      ),
+    );
+  }
+  const segments = fatalOnUnsupported(() => planSegments(format));
+  await report(
+    `Planned ${clock(segments.at(-1)?.endMs ?? 0)} of audio as ${segments.length} segment${
+      segments.length === 1 ? "" : "s"
+    } while it uploads.`,
+  );
+  return { format, segments };
+}
+
+/**
+ * How many segments a finished upload of `size` bytes really has.
+ *
+ * Not `plan.segments.length`: the plan came from the header's declared length, and a
+ * recording that came up short has segments that start past the end of the file.
+ * Counting those would leave the run waiting for audio nobody is going to send.
+ */
+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.
+ *
+ * A PLAIN throw, not `throwFatalStepError`: this is the BODY, and the
+ * fatal/retryable distinction belongs to a step — it is what tells the DevKit
+ * whether to run that step again. A body that throws fails the run, which is what
+ * should happen here, and dressing it up as a step error would suggest a retry
+ * policy with nothing to apply to.
+ */
+function abandon(id: string, at: UploadProgressView): never {
+  throw new Error(
+    `Gave up waiting for ${id}: ${at.size} byte(s) stored and still incomplete. ` +
+      `Nothing new arrived for ${MAX_IDLE_POLLS} polls — the uploader stopped.`,
+  );
+}

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

@@ -0,0 +1,139 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * One request to AssemblyAI's synchronous transcription endpoint.
+ *
+ * Extracted when the second flow arrived, and the split is the one that was
+ * already there: both flows send exactly the same request and differ only in
+ * where the bytes came from — a byte WINDOW of one stored recording
+ * (`transcribe.ts`), or one PART of a group that is still being uploaded
+ * (`stream.ts`). Everything that is a property of the endpoint rather than of the
+ * caller lives here: the URL, the model header, the raw-key auth, the deadline,
+ * the multipart shape, and the three-way failure classification.
+ *
+ * No directive, which is what lets it live under `workflows/` beside the bodies:
+ * the WDK builder scans this directory and transforms only what carries one
+ * (`wav.ts` is the same shape). It is called FROM steps, so it inherits their
+ * environment — `requireStepEnv` works here for the same reason it works there.
+ */
+
+import { throwFatalStepError, toStepError } from "@alexkroman1/aai/step-errors";
+import { multipartBody, requireStepEnv, stepFetch } from "@alexkroman1/aai/utils";
+
+/** The synchronous transcription endpoint. Global — it routes to the nearest region. */
+const SYNC_ENDPOINT = "https://sync.assemblyai.com/transcribe";
+
+/** Required on every sync request; the endpoint routes on it. */
+const SYNC_MODEL = "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";
+
+/** The endpoint's own per-request deadline, plus room to upload. */
+const SYNC_TIMEOUT_MS = 60_000;
+
+/**
+ * Time one transcription, so the progress log carries LATENCY.
+ *
+ * The reason this is worth reporting rather than left to a server log: the whole
+ * shape of both flows is a bounded fan-out against an endpoint whose speed is
+ * outside this code, and per-part latency is the one number that says which
+ * bound is actually binding. Eight parts each taking 4s means the concurrency is
+ * the limit; eight parts each taking 20s means the endpoint is. A log that only
+ * says "transcribing" cannot tell those apart, and the choice between raising
+ * `SEGMENT_CONCURRENCY` and leaving it alone is exactly that question.
+ *
+ * `Date.now()` is fine HERE and would not be in a body: a step's internals are
+ * not replayed — only its RESULT is — which is what makes a step the place any
+ * clock, random draw or outside read belongs.
+ */
+export async function timed<T>(work: () => Promise<T>): Promise<{ value: T; ms: number }> {
+  const started = Date.now();
+  const value = await work();
+  return { value, ms: Date.now() - started };
+}
+
+/** `4.2s`, or `840ms` under a second — a reader wants one significant change. */
+export function elapsed(ms: number): string {
+  return ms < 1000 ? `${ms}ms` : `${(ms / 1000).toFixed(1)}s`;
+}
+
+/**
+ * Transcribe one complete WAV.
+ *
+ * `bytes` must be a whole file, header included — the endpoint decodes each
+ * request independently, so a headerless tail is bytes it will refuse. Both
+ * callers arrive at that differently: one re-attaches a header to a window it
+ * read, the other is handed parts that already carry one.
+ *
+ * @param label - How this piece is named in a failure. The CALLER's vocabulary
+ *   (a segment's timestamp, a part's index), because it is what a reader of the
+ *   log has in front of them.
+ */
+export async function transcribeWav(
+  bytes: Uint8Array,
+  filename: string,
+  label: string,
+): Promise<string> {
+  const apiKey = apiKeyOrFatal();
+  const part = multipartBody({ name: "audio", filename, type: "audio/wav", bytes });
+
+  // `stepFetch`, not `fetch`, and here it is load-bearing rather than tidy:
+  // `fetch` speaks HTTP/2 wherever the far side offers it, which puts a whole
+  // batch of segments on ONE connection — and a capacity limit then arrives as a
+  // stream reset carrying no HTTP status for `toStepError` below to read. A
+  // fan-out is exactly the shape that breaks on. `sdk/step-fetch.ts` holds the
+  // measurements; a `StepTransportError` out of here is already retryable and
+  // already names its cause.
+  const response = await stepFetch(SYNC_ENDPOINT, {
+    method: "POST",
+    headers: {
+      // The raw key — this endpoint takes it unprefixed, and a `Bearer ` in
+      // front of it is a 401 that reads like a wrong key.
+      Authorization: apiKey,
+      "X-AAI-Model": SYNC_MODEL,
+      ...part.headers,
+    },
+    body: part.body,
+    // Nothing here has a deadline of its own, and a hung upload inside a step is
+    // a run that never finishes rather than one that retries.
+    signal: AbortSignal.timeout(SYNC_TIMEOUT_MS),
+  });
+  if (!response.ok) throw await syncFailure(response, label);
+
+  const body = (await response.json()) as { text?: string };
+  return (body.text ?? "").trim();
+}
+
+/** 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) {
+    // `throwFatalStepError` rather than `throw new FatalError(…)`: that class
+    // takes only a message — no `cause` — so constructing one inside a `catch`
+    // loses the original where the linter (rightly) expects it preserved. Here
+    // the original is the ARGUMENT, and nothing is swallowed.
+    return throwFatalStepError(err);
+  }
+}
+
+/**
+ * The sync endpoint's failure, with whatever it said about it.
+ *
+ * `toStepError` makes the three-way call: a `FatalError` stops the DevKit
+ * retrying something that will answer the same way, a bare `RetryableError`
+ * retries in ONE SECOND (that class's own default), and a `RetryableError`
+ * carrying `retryAfter` waits exactly as long as the far side asked. The last
+ * matters here because a whole batch hits the rate limit together — a second
+ * later all of them ask again, where on the server's number they drain.
+ */
+async function syncFailure(response: Response, label: string): Promise<Error> {
+  // Two shapes, documented: `{ error_code, message }` for a request problem and
+  // `{ detail }` for auth and rate limits.
+  const body = (await response.json().catch(() => ({}))) as { message?: string; detail?: string };
+  const detail = body.message ?? body.detail;
+  return toStepError(
+    response,
+    `${label} failed: HTTP ${response.status}${detail ? ` — ${detail}` : ""}`,
+  );
+}