@alexkroman1/aai-cli 6.10.1 → 7.0.0

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

@@ -0,0 +1,247 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * The step that makes the rest of the desk possible on a real file: whatever was
+ * uploaded, converted to the one format the arithmetic works on.
+ *
+ * `wav.ts` explains why this desk cuts linear-PCM WAV and nothing else — a byte
+ * offset is only a timestamp when every sample is the same size — and for a long
+ * time the remedy for anything else was a SENTENCE telling the caller to run
+ * `ffmpeg -i in.m4a -c:a pcm_s16le out.wav` on their own machine first. Every
+ * recording anyone actually has is an `.m4a` off a phone or an `.mp3` out of a
+ * conferencing tool, so that sentence was the desk's real front door, and it
+ * opened onto the user's shell. The platform installs ffmpeg in every guest
+ * image; this file is the desk using it.
+ *
+ * ```text
+ *   normalizeRecording   one step   →  an upload id the rest of the flow can cut
+ * ```
+ *
+ * ## `parseWav` is asked as a QUESTION
+ *
+ * The obvious implementation probes the file with `ffprobe` and passes it
+ * through when the codec looks like PCM. It is wrong in a way that only shows up
+ * on a Windows recorder's output: a `WAVE_FORMAT_EXTENSIBLE` file reports
+ * `pcm_s16le` to ffprobe and is refused by {@link parseWav}, whose encoding
+ * check reads the format tag ffprobe does not surface. The desk would convert
+ * nothing and then fail to cut it.
+ *
+ * So the test is {@link parseWav} ITSELF, run against the same
+ * {@link HEADER_PROBE_BYTES} window `splitRecording` will use. A throw is the
+ * signal to convert. That makes the pass-through decision and the cut decision
+ * the same decision by construction — there is no second opinion to disagree —
+ * and it means the desk fixes anything the parser rejects for any reason,
+ * including a 192 kHz 32-bit stereo WAV that trips
+ * {@link MAX_BYTES_PER_SECOND}, which downsampling genuinely repairs.
+ *
+ * The fast path costs one 64 KB read and no subprocess at all: a WAV that was
+ * already cuttable is returned by the id it came in under, so nothing is copied
+ * and nothing is re-encoded.
+ *
+ * ## File → file, not bytes → bytes
+ *
+ * `transcodeToWav(bytes)` is one line and is the wrong call here, and
+ * `@alexkroman1/aai/step-files` is the three functions that replace it —
+ * `readUploadToFile`, `withTempDir` and `writeUploadFromFile`. Its module doc
+ * carries the whole argument (a pipe cannot seek, so an `.m4a` with a trailing
+ * `moov` index fails; piped output is capped at 64 MiB, half an hour of this
+ * desk's audio) plus the rule that a temp file may not outlive its step. This
+ * step is the case those were written for.
+ *
+ * ## Everything node-shaped is named from inside the step BODY
+ *
+ * `@alexkroman1/aai/ffmpeg` and `@alexkroman1/aai/step-files` both reach a
+ * `node:` builtin, and a name this module holds at MODULE scope keeps its import
+ * in the workflow bundle — which is compiled as a `node:vm` Script with no
+ * `require`. Every name they bind is referenced only inside
+ * {@link normalizeRecording}'s body, which the workflow transform removes along
+ * with the imports it is the only user of. A module-scope FUNCTION naming one is
+ * what breaks a run at replay; this template used to carry a whole
+ * `ffmpeg-verdict.ts` because of it, and `throwFfmpegStepError` — which reaches
+ * no `node:` builtin at all — is what dissolved the boundary.
+ */
+
+import { basename, extname, join } from "node:path";
+import { probeMedia, runFfmpeg, wavEncodeArgs } from "@alexkroman1/aai/ffmpeg";
+import { readUpload, report, uploadInfo } from "@alexkroman1/aai/step";
+import { throwFfmpegStepError } from "@alexkroman1/aai/step-errors";
+import { readUploadToFile, withTempDir, writeUploadFromFile } from "@alexkroman1/aai/step-files";
+import { formatBytes, formatDuration } from "@alexkroman1/aai/utils";
+import { HEADER_PROBE_BYTES, parseWav, UnsupportedRecordingError } from "./wav.ts";
+
+/**
+ * The rate everything is converted TO.
+ *
+ * 16 kHz because that is what speech models are trained at — a higher rate
+ * carries no information the decoder uses and costs proportional bytes in a
+ * fan-out whose width is bounded by bytes in flight (`BYTES_IN_FLIGHT` in
+ * `transcribe.ts`). A converted two-hour recording is 230 MB of 16 kHz mono
+ * against 1.4 GB of 48 kHz stereo, which is the difference between a fan-out
+ * that saturates on width and one that saturates on the queue.
+ */
+export const NORMALIZED_SAMPLE_RATE = 16_000;
+
+/**
+ * Channels everything is converted TO.
+ *
+ * Mono, and it is a real loss rather than a free win: a stereo call recording
+ * with one party per channel is exactly the file where the channels are the most
+ * interesting thing about it, and downmixing throws that away. This desk
+ * transcribes rather than diarizes, so it takes the 2x saving; a desk that wants
+ * the speakers apart splits the channels first and transcribes each one.
+ */
+export const NORMALIZED_CHANNELS = 1;
+
+/**
+ * How long a conversion may run before it is killed.
+ *
+ * Well past what the work takes — ffmpeg decodes and resamples faster than
+ * realtime by two orders of magnitude, so a two-hour recording is under a
+ * minute — and the reason for a bound at all is a file that makes a decoder
+ * pathological rather than one that is merely long. A `timeout` is retryable
+ * and an `exit` is not; `throwFfmpegStepError` decides.
+ */
+const CONVERT_TIMEOUT_MS = 15 * 60_000;
+
+/** What the flow is handed: the id to cut, and whether it had to be made. */
+export type NormalizedRecording = {
+  /**
+   * The upload id every later step reads.
+   *
+   * The SAME id that came in when the file was already cuttable, and a new one
+   * when it was converted — which is why the flow threads this rather than its
+   * own input from here on.
+   */
+  recording: string;
+  /** Whether ffmpeg ran. Reported, so a reader can tell a fast path from a slow one. */
+  converted: boolean;
+};
+
+/**
+ * Make sure the recording is something the desk can cut, converting if not.
+ *
+ * A step, for the ordinary two reasons — it does I/O, and its RESULT is what
+ * every later step addresses — plus one specific to what it produces: the
+ * conversion writes a file, and journaling the id means a resumed run reads the
+ * file that already exists instead of paying for a second one.
+ */
+export async function normalizeRecording(uploadId: string): Promise<NormalizedRecording> {
+  "use step";
+
+  const stored = await uploadInfo(uploadId);
+  const head = await readUpload(uploadId, { end: HEADER_PROBE_BYTES });
+
+  if (cuttable(head.bytes, stored.size)) {
+    // No subprocess, no copy, no second upload. The overwhelmingly common case
+    // for a desk whose form says WAV, and the reason the check is a 64 KB read.
+    await report(`${stored.name || uploadId} is already linear-PCM WAV — cutting it as it is.`);
+    return { recording: uploadId, converted: false };
+  }
+
+  // Named before any work starts, because everything below is minutes of it on a
+  // long recording and a run that says nothing until the conversion finishes looks
+  // stuck. It is also the line that distinguishes "this file needs converting" from
+  // the fast path above.
+  await report(
+    `Converting ${stored.name || uploadId} (${formatBytes(stored.size)}) — not a WAV we can cut.`,
+  );
+
+  // The temp directory's lifetime is this lexical scope, and the `finally` inside
+  // `withTempDir` is what makes that true on the failure paths too: a guest's disk
+  // is small and a step that leaves a copy of every recording it touched fills it.
+  return await withTempDir(
+    async (dir) => {
+      const source = join(dir, "source");
+      const converted = join(dir, "converted.wav");
+
+      await readUploadToFile(uploadId, source, { size: stored.size });
+
+      // What it WAS, for the progress line. Worth one ffprobe: "converted 41
+      // minutes of aac" is a line that explains the run's shape, where
+      // "converted the recording" leaves a reader wondering what the desk decided.
+      // On a temp file rather than a pipe, so a trailing index is readable.
+      const info = await probeMedia(source, { timeoutMs: CONVERT_TIMEOUT_MS }).catch(
+        throwFfmpegStepError,
+      );
+      await report(
+        `It is ${describeSource(info.audio?.codec, info.durationSec)} — re-encoding to ` +
+          `${NORMALIZED_SAMPLE_RATE / 1000} kHz mono WAV.`,
+      );
+
+      await runFfmpeg(
+        [
+          // The argv is the caller's, verbatim — `runFfmpeg` adds nothing. So the
+          // standing flags are here: quiet, non-interactive, overwrite. `-nostdin`
+          // matters most in a guest, where there is no terminal and an ffmpeg that
+          // decides to read stdin is a process that never exits.
+          "-hide_banner",
+          "-loglevel",
+          "error",
+          "-nostdin",
+          "-y",
+          "-i",
+          source,
+          ...wavEncodeArgs({
+            sampleRate: NORMALIZED_SAMPLE_RATE,
+            channels: NORMALIZED_CHANNELS,
+          }),
+          converted,
+        ],
+        { timeoutMs: CONVERT_TIMEOUT_MS },
+      ).catch(throwFfmpegStepError);
+
+      const written = await writeUploadFromFile(converted, {
+        // Named after the ORIGINAL, so a download reads as the recording it came
+        // from. The extension has to change with the bytes: a file served as
+        // `audio/wav` under a `.m4a` name is one no player will open.
+        name: `${basename(stored.name || uploadId, extname(stored.name || uploadId))}.wav`,
+        type: "audio/wav",
+      });
+
+      await report(
+        `Converted to ${formatBytes(written.size)} of WAV (from ${formatBytes(stored.size)}).`,
+      );
+      return { recording: written.id, converted: true };
+    },
+    // Named after the pipeline: the directory is gone by the time anyone looks,
+    // so the prefix's real audience is a person reading `ls /tmp` during a run
+    // that hung, and the spec that asserts nothing was left behind.
+    { prefix: "aai-normalize-" },
+  );
+}
+
+/**
+ * Retries beyond the default 3.
+ *
+ * Not because a conversion is flaky — a corrupt file fails identically forever,
+ * and `throwFfmpegStepError` is what stops the DevKit retrying that. It is the
+ * two I/O halves that are worth another attempt: this step reads a whole
+ * recording out of the store and writes a whole one back, and either can lose a
+ * connection on a file this size.
+ */
+normalizeRecording.maxRetries = 5;
+
+/**
+ * Whether `splitRecording` will be able to read this header.
+ *
+ * The question, not a guess at it — see the module doc. Only
+ * {@link UnsupportedRecordingError} is answered `false`: anything else thrown by
+ * the parser is a bug in the parser, and swallowing it here would turn that into
+ * a mysterious re-encode of a file that was fine.
+ */
+export function cuttable(head: Uint8Array, totalBytes: number): boolean {
+  try {
+    parseWav(head, totalBytes);
+    return true;
+  } catch (err: unknown) {
+    if (err instanceof UnsupportedRecordingError) return false;
+    throw err;
+  }
+}
+
+/** `41:20 of aac`, or as much of that as ffprobe would say. */
+function describeSource(codec: string | undefined, durationSec: number | undefined): string {
+  const length =
+    durationSec === undefined ? undefined : formatDuration(Math.round(durationSec * 1000));
+  if (length !== undefined && codec !== undefined) return `${length} of ${codec}`;
+  return length ?? codec ?? "the recording";
+}

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

@@ -120,14 +120,3 @@ function seamLength(merged: readonly string[], next: readonly string[]): number
 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

@@ -138,11 +138,11 @@
  * what keeps that order a pure function of journaled values.
  */
 
+import { mapConcurrent, readUpload, report, uploadInfo } from "@alexkroman1/aai/step";
 import { throwFatalStepError } from "@alexkroman1/aai/step-errors";
-import { mapConcurrent, readUpload, report, uploadInfo } from "@alexkroman1/aai/utils";
+import { formatDuration, plural } from "@alexkroman1/aai/utils";
 import { sleep } from "workflow";
 import {
-  clock,
   fatalOnUnsupported,
   mergeTranscript,
   type SegmentTranscript,
@@ -151,6 +151,7 @@ import {
   transcribeSegment,
 } from "./transcribe.ts";
 import {
+  HEADER_PROBE_BYTES,
   offsetToMs,
   parseWav,
   planSegments,
@@ -176,9 +177,6 @@ const POLL_INTERVAL = "5s";
  */
 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. */
@@ -326,9 +324,8 @@ export async function planStreamed(id: string): Promise<StreamPlan> {
   }
   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.`,
+    `Planned ${formatDuration(segments.at(-1)?.endMs ?? 0)} of audio as ` +
+      `${segments.length} ${plural(segments.length, "segment")} while it uploads.`,
   );
   return { format, segments };
 }
@@ -339,8 +336,12 @@ export async function planStreamed(id: string): Promise<StreamPlan> {
  * 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.
+ *
+ * Exported for its spec. It is the one piece of this flow's exit condition that is
+ * a pure function of journaled values, so it is the one a test can pin — and the
+ * failure it guards is a run that never ends rather than one that fails.
  */
-function expectedSegments(plan: StreamPlan, size: number): number {
+export function expectedSegments(plan: StreamPlan, size: number): number {
   return plan.segments.filter((segment) => segment.start < size).length;
 }
 

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

@@ -1,35 +1,24 @@
 // Copyright 2026 the AAI authors. MIT license.
 /**
- * One request to AssemblyAI's synchronous transcription endpoint.
+ * What both SYNC flows share, now that the endpoint itself is the SDK's.
  *
- * 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.
+ * This module used to BE the endpoint: the URL, the model header, the raw-key auth,
+ * the deadline, the multipart shape and the three-way failure classification. All of
+ * that is `stepTranscribeSync` on `@alexkroman1/aai/step` — the same request, with
+ * `transcription-workflow`'s own hard-won details (the unprefixed key, the
+ * `X-AAI-Model` header, `stepFetch` rather than `fetch` so a fan-out's rate limit
+ * arrives as a status rather than as a stream reset) carried into it.
  *
- * 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.
+ * What is left is what belongs to the CALLER rather than to the endpoint, and it is
+ * all measurement: both flows time each request, because per-part latency is the one
+ * number that says which bound is actually binding.
+ *
+ * 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.
  */
 
-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;
+import { stepTranscribeSyncClassified } from "@alexkroman1/aai/step-errors";
 
 /**
  * Time one transcription, so the progress log carries LATENCY.
@@ -65,6 +54,15 @@ export function elapsed(ms: number): string {
  * callers arrive at that differently: one re-attaches a header to a window it
  * read, the other is handed parts that already carry one.
  *
+ * `stepTranscribeSyncClassified` — the SDK's own `stepTranscribeSync` plus
+ * `throwStepError`, and nothing else — is the whole of what this adds to the SDK
+ * call, and it is where the three-way call is made: 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.
+ *
  * @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.
@@ -74,72 +72,6 @@ export async function transcribeWav(
   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.
- *
- * 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) {
-    // `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}` : ""}`,
-  );
+  const { text } = await stepTranscribeSyncClassified(bytes, { filename, label });
+  return text;
 }