@alexkroman1/aai-cli 6.10.0 → 6.11.0

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

@@ -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. */
@@ -339,8 +337,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,25 @@
 // 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/utils` — 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 { throwStepError } from "@alexkroman1/aai/step-errors";
+import { stepTranscribeSync } from "@alexkroman1/aai/utils";
 
 /**
  * Time one transcription, so the progress log carries LATENCY.
@@ -65,6 +55,14 @@ 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.
  *
+ * `.catch(throwStepError)` 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 stepTranscribeSync(bytes, { filename, label }).catch(throwStepError);
+  return text;
 }

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

@@ -7,15 +7,21 @@
  * every directive body obeys — replayed from the top, so no live handles and no
  * undurable decisions; step arguments and return values are serialized, so pass
  * an id and not a payload — and both hold here unchanged. What this template
- * adds is the shape a real provider limit forces on a workflow, and it is three
+ * adds is the shape a real provider limit forces on a workflow, and it is four
  * steps in a straight line:
  *
  * ```text
+ *   normalizeRecording  one step   →  an upload id in a format that can be cut
  *   splitRecording      one step   →  the format + a byte range per segment
  *   transcribeSegment   N steps    →  one sync API request each, bounded
  *   mergeTranscript     one step   →  the stitched transcript
  * ```
  *
+ * The first is the newest and the one a reader is least likely to expect, since
+ * everything below it is arithmetic over a WAV and real recordings are not WAVs.
+ * `normalize.ts` is where ffmpeg enters, and its module doc carries why the
+ * conversion is file-to-file and why a temp file may not outlive its step.
+ *
  * ## Why the SYNC endpoint, and why that forces a fan-out
  *
  * AssemblyAI has two pre-recorded APIs. The BATCH one takes a job and a webhook
@@ -59,6 +65,7 @@
 
 import { throwFatalStepError } from "@alexkroman1/aai/step-errors";
 import { emit, mapConcurrent, readUpload, report, uploadInfo } from "@alexkroman1/aai/utils";
+import { normalizeRecording } from "./normalize.ts";
 import {
   clock,
   countWords,
@@ -69,6 +76,7 @@ import {
 import { elapsed, timed, transcribeWav } from "./sync-api.ts";
 import {
   bytesPerSecond,
+  HEADER_PROBE_BYTES,
   parseWav,
   planSegments,
   SEGMENT_OVERLAP_SECONDS,
@@ -186,15 +194,6 @@ export function segmentConcurrency(format: WavFormat): number {
   return Math.max(1, Math.min(MAX_SEGMENT_CONCURRENCY, Math.floor(BYTES_IN_FLIGHT / perSegment)));
 }
 
-/**
- * Bytes probed for the WAV header.
- *
- * The canonical header is 44 bytes; a recorder that writes a `LIST` or `bext`
- * chunk in front of the samples pushes the `data` chunk further out, and 64 KB
- * covers every such file anyone has produced by accident.
- */
-const HEADER_PROBE_BYTES = 64 * 1024;
-
 /**
  * What a finished run reports, whichever flow produced it.
  *
@@ -234,7 +233,16 @@ export async function transcribeFlow(input: { recording: string }) {
   // round trip instead of two before any audio is read. The ORDER is still a
   // pure function of this line — the two calls go out synchronously, left to
   // right — which is what a replay reproduces.
-  const [startedAt, plan] = await Promise.all([startClock(), splitRecording(input.recording)]);
+  //
+  // The clock starts before the conversion rather than after it, because a
+  // reader comparing the three flows over one file is comparing what the desk
+  // COST them, and re-encoding an m4a is part of that.
+  const [startedAt, ready] = await Promise.all([startClock(), normalizeRecording(input.recording)]);
+
+  // `ready.recording` from here on, not `input.recording`: a converted file is a
+  // DIFFERENT upload, and cutting the original by offsets planned against the
+  // converted one is a fan-out of garbage that still reports success.
+  const plan = await splitRecording(ready.recording);
 
   // One step per segment, bounded, in an order a replay reproduces exactly.
   // A failed segment fails the RUN, deliberately: every sibling that finished is
@@ -242,11 +250,12 @@ export async function transcribeFlow(input: { recording: string }) {
   // what is missing, where catching here to salvage a partial transcript would
   // return a recording with a silent hole in it and report success.
   const parts = await mapConcurrent(plan.segments, segmentConcurrency(plan.format), (segment) =>
-    transcribeSegment(input.recording, plan.format, segment),
+    transcribeSegment(ready.recording, plan.format, segment),
   );
 
-  // Whatever this returns is what a caller reads as `output` on a completed run
-  // — so it is what the page renders, typed through `WorkflowOutputOf`.
+  // The ORIGINAL id, and only here: `mergeTranscript` uses it for the filename a
+  // reader sees, and `standup.m4a` is the recording they uploaded — where the
+  // converted copy is an artifact of how the desk works.
   return await mergeTranscript(input.recording, plan.durationMs, parts, startedAt);
 }
 

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

@@ -26,6 +26,21 @@
  * anything else by name rather than trying to be clever — an MP3 or an M4A frame
  * boundary cannot be found by arithmetic, and finding it means shipping a
  * decoder into a step.
+ *
+ * ## Who READS the refusals below
+ *
+ * {@link UnsupportedRecordingError} is raised from here and handled in two
+ * completely different ways, which is worth knowing before editing a message:
+ *
+ * - The plain `transcribe` flow CONVERTS rather than refusing. `normalize.ts`
+ *   calls {@link parseWav} as a QUESTION — a throw is its signal to hand the file
+ *   to ffmpeg — so on that path no message here reaches a person, and a file this
+ *   module rejects for a huge {@link MAX_BYTES_PER_SECOND} is one that
+ *   normalization fixes by downsampling.
+ * - `transcribeStream` still refuses, and has to: it cuts a recording while the
+ *   bytes are still arriving, and a partial file is not something ffmpeg can
+ *   transcode. There the sentences below are the whole of what a person is told,
+ *   so they keep naming the `ffmpeg` line that fixes the file.
  */
 
 /** What the sync endpoint will accept in one request. */
@@ -57,6 +72,22 @@ export const MAX_SEGMENT_BYTES = 40 * 1024 * 1024;
 /** The sync endpoint refuses audio shorter than this. */
 export const MIN_SEGMENT_MS = 80;
 
+/**
+ * Bytes probed for the WAV header.
+ *
+ * The canonical header is 44 bytes; a recorder that writes a `LIST` or `bext`
+ * chunk in front of the samples pushes the `data` chunk further out, and 64 KB
+ * covers every such file anyone has produced by accident.
+ *
+ * Declared HERE because three callers need the same window, and the third one is
+ * what made a shared constant the rule rather than a preference: `splitRecording`
+ * cuts on it, `planFromHead` in `stream.ts` cuts on it, and `normalize.ts` decides
+ * whether to CONVERT on it. Two of those probing a different amount than the third
+ * is a file the desk converts and then cannot cut, or refuses and then converts —
+ * both silent, and neither reproducible from any one module.
+ */
+export const HEADER_PROBE_BYTES = 64 * 1024;
+
 /**
  * The largest `bytesPerSecond` this desk will cut, and the reason it is checked
  * at PARSE time rather than at cut time.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexkroman1/aai-cli",
-  "version": "6.10.0",
+  "version": "6.11.0",
   "type": "module",
   "bin": {
     "aai": "bin.mjs"
@@ -44,8 +44,8 @@
     "p-timeout": "^7.0.1",
     "vite": "^8.2.1",
     "zod": "^4.4.3",
-    "@alexkroman1/aai": "6.10.0",
-    "@alexkroman1/aai-ui": "6.10.0"
+    "@alexkroman1/aai": "6.11.0",
+    "@alexkroman1/aai-ui": "6.11.0"
   },
   "devDependencies": {
     "playwright": "^1.62.1",