@alexkroman1/aai-cli 6.11.0 → 8.0.0

package/dist/templates/call-audit/workflows/ingest.ts

@@ -18,7 +18,7 @@
  *
  * Splitting steps buys a cheaper retry: a failure re-runs one stage instead of
  * five. It costs a MATERIALIZATION each, because a temp file cannot cross a step
- * boundary (see `temp-media.ts`) — so a five-step version reads the whole
+ * boundary (see `@alexkroman1/aai/step-files`) — so a five-step version reads the whole
  * recording out of the upload store five times, and on a 700 MB file that is the
  * expensive part by an order of magnitude. The decode passes are cheap: ffmpeg
  * resamples two orders of magnitude faster than realtime, so a two-hour recording
@@ -42,16 +42,33 @@
  * printed last, so a capped tail holds it) and the pauses arrive in a **file**
  * (one event per pause, so their size grows with the recording and a tail would
  * silently drop the earliest ones). Both are read here.
+ *
+ * ## Everything ffmpeg-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`. The import statements are at the top, as the SDK's own examples
+ * write them, and every name they bind is referenced only inside
+ * {@link ingestRecording}'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.
+ *
+ * `analyse` stays here for the other half of that rule: everything IT names is
+ * pure, so it may survive into the bundle.
  */
 
 import { readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
-import { isFfmpegError, probeMedia, runFfmpeg } from "@alexkroman1/aai/ffmpeg";
-import { throwFatalStepError, throwStepError } from "@alexkroman1/aai/step-errors";
-import { pcmDurationMs, report, uploadInfo, writeUpload } from "@alexkroman1/aai/utils";
+import { probeMedia, runFfmpeg } from "@alexkroman1/aai/ffmpeg";
+import { pcmDurationMs, report, uploadInfo } from "@alexkroman1/aai/step";
+import { throwFatalStepError, throwFfmpegStepError } from "@alexkroman1/aai/step-errors";
+import { readUploadToFile, withTempDir, writeUploadFromFile } from "@alexkroman1/aai/step-files";
+import { formatBytes, formatDuration, plural } from "@alexkroman1/aai/utils";
 import {
   ANALYSIS_FORMAT,
-  clock,
   type Loudness,
   MediaAnalysisError,
   measureLoudnessArgs,
@@ -61,14 +78,13 @@ import {
   type Silence,
   speechFraction,
 } from "./media.ts";
-import { fileChunks, materializeUpload, withTempDir } from "./temp-media.ts";
 
 /**
  * How long any one ffmpeg invocation may run before it is killed.
  *
  * Well past what the work takes, because 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; see {@link classifyFfmpeg}.
+ * `timeout` is retryable and an `exit` is not; `throwFfmpegStepError` decides.
  */
 const FFMPEG_TIMEOUT_MS = 20 * 60_000;
 
@@ -108,119 +124,99 @@ export async function ingestRecording(uploadId: string): Promise<Ingested> {
   "use step";
 
   const stored = await uploadInfo(uploadId);
-  await report(`Reading ${stored.name || uploadId} (${mb(stored.size)}).`);
-
-  return await withTempDir(async (dir) => {
-    const source = join(dir, "source");
-    const normalized = join(dir, "audio.pcm");
-    const silenceLog = join(dir, "silence.txt");
-
-    await materializeUpload(uploadId, stored.size, source);
-
-    // What it WAS, for the progress log and the page. Worth one ffprobe: "41
-    // minutes of aac" explains the shape of the run, where "the recording" leaves
-    // a reader guessing what the desk decided. On a temp FILE rather than a pipe,
-    // so a trailing index is readable.
-    const probed = await probeMedia(source, { timeoutMs: FFMPEG_TIMEOUT_MS }).catch(classifyFfmpeg);
-    const codec = probed.audio?.codec ?? "unknown";
-    await report(
-      `Levelling ${describeSource(codec, probed.durationSec)} to ${ANALYSIS_FORMAT.sampleRate / 1000} kHz mono.`,
-    );
-
-    // Pass one: measure. `-f null -` decodes every frame and writes no audio, so
-    // this costs a decode and produces five numbers.
-    const measured = await runFfmpeg(measureLoudnessArgs(source), {
-      timeoutMs: FFMPEG_TIMEOUT_MS,
-    }).catch(classifyFfmpeg);
-    const loudness = analyse(() => parseLoudness(measured.stderr));
-
-    // Pass two: apply the measurement, find the pauses, write the audio.
-    await runFfmpeg(normalizeArgs(source, loudness, normalized, silenceLog), {
-      timeoutMs: FFMPEG_TIMEOUT_MS,
-    }).catch(classifyFfmpeg);
-
-    // The duration comes from the BYTE COUNT, not from the original's header or
-    // from ffprobe. It is the only measurement that agrees with the byte offsets
-    // the fan-out will use — a container's declared duration can disagree with
-    // what was actually decoded (an AAC file's encoder padding puts this one ~16ms
-    // over), and a segment planned against the wrong one runs off the end.
-    const bytes = (await stat(normalized)).size;
-    const durationMs = pcmDurationMs(bytes, ANALYSIS_FORMAT);
-
-    // Verified on ffmpeg 6.1: `ametadata` creates the file at filter-init, so a
-    // recording with no pause in it leaves an EMPTY log rather than no log. A
-    // missing file here is therefore a real failure and not a case to tolerate.
-    const log = await readFile(silenceLog, "utf-8");
-    const silences = analyse(() => parseSilences(log, durationMs / 1000));
-
-    const written = await writeUpload(fileChunks(normalized), {
-      // Named after the original, so a download reads as the recording it came
-      // from. `.pcm` because that is what it is — raw samples with no header, and
-      // a `.wav` name on a headerless file is one no player will open.
-      name: `${baseName(stored.name || uploadId)}.pcm`,
-      // Not `audio/wav`: the type is served back on the byte route, and claiming a
-      // container this file does not have would be a lie a browser acts on. Not
-      // `audio/L16` either, which looks right and is not — that type is defined as
-      // BIG-endian 16-bit PCM, where this is `s16le`. Nothing plays this file; the
-      // fan-out reads byte ranges out of it and puts a real header back on each one
-      // with `encodeWav`.
-      type: "application/octet-stream",
-    });
-
-    await report(
-      `Levelled ${clock(durationMs)} from ${loudness.inputLufs} LUFS, ` +
-        `${Math.round(speechFraction(silences, durationMs / 1000) * 100)}% speech across ` +
-        `${silences.length} pause${silences.length === 1 ? "" : "s"}.`,
-    );
-
-    return {
-      audio: written.id,
-      source: stored.name || uploadId,
-      codec,
-      durationMs,
-      bytes,
-      loudness,
-      silences,
-    };
-  });
+  await report(`Reading ${stored.name || uploadId} (${formatBytes(stored.size)}).`);
+
+  return await withTempDir(
+    async (dir) => {
+      const source = join(dir, "source");
+      const normalized = join(dir, "audio.pcm");
+      const silenceLog = join(dir, "silence.txt");
+
+      await readUploadToFile(uploadId, source, { size: stored.size });
+
+      // What it WAS, for the progress log and the page. Worth one ffprobe: "41
+      // minutes of aac" explains the shape of the run, where "the recording" leaves
+      // a reader guessing what the desk decided. On a temp FILE rather than a pipe,
+      // so a trailing index is readable.
+      const probed = await probeMedia(source, { timeoutMs: FFMPEG_TIMEOUT_MS }).catch(
+        throwFfmpegStepError,
+      );
+      const codec = probed.audio?.codec ?? "unknown";
+      await report(
+        `Levelling ${describeSource(codec, probed.durationSec)} to ${ANALYSIS_FORMAT.sampleRate / 1000} kHz mono.`,
+      );
+
+      // Pass one: measure. `-f null -` decodes every frame and writes no audio, so
+      // this costs a decode and produces five numbers.
+      const measured = await runFfmpeg(measureLoudnessArgs(source), {
+        timeoutMs: FFMPEG_TIMEOUT_MS,
+      }).catch(throwFfmpegStepError);
+      const loudness = analyse(() => parseLoudness(measured.stderr));
+
+      // Pass two: apply the measurement, find the pauses, write the audio.
+      await runFfmpeg(normalizeArgs(source, loudness, normalized, silenceLog), {
+        timeoutMs: FFMPEG_TIMEOUT_MS,
+      }).catch(throwFfmpegStepError);
+
+      // The duration comes from the BYTE COUNT, not from the original's header or
+      // from ffprobe. It is the only measurement that agrees with the byte offsets
+      // the fan-out will use — a container's declared duration can disagree with
+      // what was actually decoded (an AAC file's encoder padding puts this one ~16ms
+      // over), and a segment planned against the wrong one runs off the end.
+      const bytes = (await stat(normalized)).size;
+      const durationMs = pcmDurationMs(bytes, ANALYSIS_FORMAT);
+
+      // Verified on ffmpeg 6.1: `ametadata` creates the file at filter-init, so a
+      // recording with no pause in it leaves an EMPTY log rather than no log. A
+      // missing file here is therefore a real failure and not a case to tolerate.
+      const log = await readFile(silenceLog, "utf-8");
+      const silences = analyse(() => parseSilences(log, durationMs / 1000));
+
+      const written = await writeUploadFromFile(normalized, {
+        // Named after the original, so a download reads as the recording it came
+        // from. `.pcm` because that is what it is — raw samples with no header, and
+        // a `.wav` name on a headerless file is one no player will open.
+        name: `${baseName(stored.name || uploadId)}.pcm`,
+        // Not `audio/wav`: the type is served back on the byte route, and claiming a
+        // container this file does not have would be a lie a browser acts on. Not
+        // `audio/L16` either, which looks right and is not — that type is defined as
+        // BIG-endian 16-bit PCM, where this is `s16le`. Nothing plays this file; the
+        // fan-out reads byte ranges out of it and puts a real header back on each one
+        // with `encodeWav`.
+        type: "application/octet-stream",
+      });
+
+      await report(
+        `Levelled ${formatDuration(durationMs)} from ${loudness.inputLufs} LUFS, ` +
+          `${Math.round(speechFraction(silences, durationMs / 1000) * 100)}% speech across ` +
+          `${silences.length} ${plural(silences.length, "pause")}.`,
+      );
+
+      return {
+        audio: written.id,
+        source: stored.name || uploadId,
+        codec,
+        durationMs,
+        bytes,
+        loudness,
+        silences,
+      };
+    },
+    { prefix: "aai-call-audit-" },
+  );
 }
 
 /**
  * Retries beyond the default 3.
  *
  * Not because a conversion is flaky — a corrupt file fails identically forever,
- * and {@link classifyFfmpeg} is what stops the DevKit retrying that. It is the
+ * 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.
  */
 ingestRecording.maxRetries = 5;
 
-/**
- * Turn an ffmpeg failure into the DevKit's verdict.
- *
- * The whole reason `FfmpegError.kind` exists, used the way it was meant to be: an
- * `exit` is ffmpeg having read the file and refused it, so every retry re-reads
- * the same bytes and reaches the same conclusion while burning the budget a real
- * transient needs. A `timeout` or an `aborted` is worth another attempt, and a
- * `missing-binary` is `aai dev` on a laptop with no ffmpeg — fatal, and already
- * carrying the install instructions in its message.
- *
- * **The retryable arm goes through `throwStepError` even though it classifies
- * nothing**, which is deliberate. `toStepError` reaches a verdict from a
- * `Response` or from an SDK error that already carries one; an `FfmpegError` is
- * neither, so it is rethrown UNCHANGED — which the DevKit treats as retryable by
- * default, the outcome this arm wants. Constructing a `RetryableError` here
- * instead would replace ffmpeg's own message and its `argv` with a sentence, and
- * the argv is the thing you paste into a shell.
- */
-export function classifyFfmpeg(err: unknown): never {
-  if (isFfmpegError(err) && (err.kind === "timeout" || err.kind === "aborted")) {
-    return throwStepError(err);
-  }
-  return throwFatalStepError(err);
-}
-
 /**
  * Run a `media.ts` reader, turning "I cannot read this analysis" into a terminal
  * failure.
@@ -243,7 +239,8 @@ export function analyse<T>(read: () => T): T {
 
 /** `41:20 of aac`, or as much of that as ffprobe would say. */
 function describeSource(codec: string, durationSec: number | undefined): string {
-  const length = durationSec === undefined ? undefined : clock(Math.round(durationSec * 1000));
+  const length =
+    durationSec === undefined ? undefined : formatDuration(Math.round(durationSec * 1000));
   return length === undefined ? codec : `${length} of ${codec}`;
 }
 
@@ -252,8 +249,3 @@ function baseName(name: string): string {
   const dot = name.lastIndexOf(".");
   return dot > 0 ? name.slice(0, dot) : name;
 }
-
-/** A size a person can read, because the number that matters is the scale. */
-function mb(bytes: number): string {
-  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
-}

package/dist/templates/call-audit/workflows/media.ts

@@ -58,7 +58,8 @@
  * longer than the cap gets the blind cut, and says so.
  */
 
-import { isRecord, type PcmFormat } from "@alexkroman1/aai/utils";
+import type { PcmFormat } from "@alexkroman1/aai/step";
+import { isRecord } from "@alexkroman1/aai/utils";
 
 /**
  * The format every recording is converted to before anything measures it.
@@ -578,17 +579,6 @@ export function speechFraction(silences: readonly Silence[], durationSec: number
   return Math.max(0, Math.min(1, (durationSec - quiet) / durationSec));
 }
 
-/** `1:04:09`, or `4:09` under an hour — the shape a reader scans for. */
-export function clock(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}`;
-}
-
 /**
  * A second, as a byte offset on a sample-frame boundary.
  *

package/dist/templates/call-audit/workflows/summarize.ts

@@ -35,18 +35,12 @@
 import { stat, writeFile } from "node:fs/promises";
 import { join } from "node:path";
 import { runFfmpeg } from "@alexkroman1/aai/ffmpeg";
-import { throwStepError } from "@alexkroman1/aai/step-errors";
-import {
-  omitUndefined,
-  report,
-  stepGenerateJson,
-  stepSpeak,
-  writeUpload,
-} from "@alexkroman1/aai/utils";
+import { report, stepSpeak } from "@alexkroman1/aai/step";
+import { stepGenerateJsonClassified, throwFfmpegStepError } from "@alexkroman1/aai/step-errors";
+import { withTempDir, writeUploadFromFile } from "@alexkroman1/aai/step-files";
+import { formatBytes, formatDuration, omitUndefined, plural } from "@alexkroman1/aai/utils";
 import { z } from "zod";
-import { classifyFfmpeg } from "./ingest.ts";
-import { clock, masterArgs } from "./media.ts";
-import { fileChunks, withTempDir } from "./temp-media.ts";
+import { masterArgs } from "./media.ts";
 
 /** Risks the summary is reduced to. Enough to be useful, few enough to act on. */
 const MAX_RISKS = 4;
@@ -114,8 +108,8 @@ export async function summarize(
   "use step";
 
   await report("Reading the transcript.");
-  const reply = await stepGenerateJson(
-    `Audit this transcript of a recorded call (${source}, ${clock(durationMs)}).\n\n` +
+  const reply = await stepGenerateJsonClassified(
+    `Audit this transcript of a recorded call (${source}, ${formatDuration(durationMs)}).\n\n` +
       "Answer with JSON only, in this shape:\n" +
       `{"headline": "...", "risks": ["..."], "actions": ["..."], "spoken": "..."}\n\n` +
       "- headline: one line naming what the call was about.\n" +
@@ -133,13 +127,14 @@ export async function summarize(
       system: "You audit recorded calls. You answer with JSON and nothing else.",
       schema: AuditReply,
     },
-    // Classified off the gateway's own status: a 429 is worth another attempt and a
-    // 400 is not, and `throwStepError` is what tells the DevKit which.
-  ).catch(throwStepError);
+    // The `Classified` caller is `stepGenerateJson` plus `throwStepError`, which is
+    // what reads the gateway's own status: a 429 is worth another attempt and a 400
+    // is not, and that is what tells the DevKit which.
+  );
 
   await report(
-    `Found ${reply.risks.length} risk${reply.risks.length === 1 ? "" : "s"} and ` +
-      `${reply.actions.length} action${reply.actions.length === 1 ? "" : "s"}.`,
+    `Found ${reply.risks.length} ${plural(reply.risks.length, "risk")} and ` +
+      `${reply.actions.length} ${plural(reply.actions.length, "action")}.`,
   );
   return {
     headline: reply.headline,
@@ -156,7 +151,7 @@ export async function summarize(
  * records: a step is replayed by its RETURN VALUE, so an id is replayed and bytes
  * are not. Split in two, the audio would have to cross the queue between them —
  * megabytes of it, on every resume — and the temp file the mastering pass needs
- * cannot cross a step boundary at all (see `temp-media.ts`). Together, a resumed
+ * cannot cross a step boundary at all (see `@alexkroman1/aai/step-files`). Together, a resumed
  * run replays the id and re-reads a file that is already there.
  *
  * The cost is that a retried step writes a second upload and abandons the first.
@@ -170,37 +165,37 @@ export async function narrate(
 
   const spoken = await stepSpeak(script, omitUndefined({ voice }));
 
-  return await withTempDir(async (dir) => {
-    const wav = join(dir, "spoken.wav");
-    const mp3 = join(dir, "summary.mp3");
-
-    // `writeFile` rather than a stream, and this is the one place in the template
-    // where holding the whole thing in memory is right: `stepSpeak` already
-    // returned it as a single `Uint8Array`, so streaming it to disk would be
-    // copying from the heap to the heap on the way. It is bounded by the script,
-    // which the schema keeps under 150 words.
-    await writeFile(wav, spoken.audio);
-
-    await runFfmpeg(masterArgs(wav, mp3), { timeoutMs: MASTER_TIMEOUT_MS }).catch(classifyFfmpeg);
-    const bytes = (await stat(mp3)).size;
-
-    const stored = await writeUpload(fileChunks(mp3), {
-      // Named, because this is what a person sees on the download link rather than
-      // an opaque id — and typed, because the byte route serves the type it was
-      // given and a browser will not play a file it was handed as bytes.
-      name: "audit.mp3",
-      type: "audio/mpeg",
-    });
-
-    await report(
-      `Recorded a ${Math.round(spoken.durationMs / 1000)}s audit in ${spoken.voice}'s voice — ` +
-        `${kb(bytes)} of MP3, from ${kb(spoken.audio.byteLength)} of WAV.`,
-    );
-    return { audio: stored.id, durationMs: spoken.durationMs, bytes };
-  });
-}
-
-/** A size a person can read, in the unit this file's output actually lands in. */
-function kb(bytes: number): string {
-  return `${Math.round(bytes / 1024)} KB`;
+  return await withTempDir(
+    async (dir) => {
+      const wav = join(dir, "spoken.wav");
+      const mp3 = join(dir, "summary.mp3");
+
+      // `writeFile` rather than a stream, and this is the one place in the template
+      // where holding the whole thing in memory is right: `stepSpeak` already
+      // returned it as a single `Uint8Array`, so streaming it to disk would be
+      // copying from the heap to the heap on the way. It is bounded by the script,
+      // which the schema keeps under 150 words.
+      await writeFile(wav, spoken.audio);
+
+      await runFfmpeg(masterArgs(wav, mp3), { timeoutMs: MASTER_TIMEOUT_MS }).catch(
+        throwFfmpegStepError,
+      );
+      const bytes = (await stat(mp3)).size;
+
+      const stored = await writeUploadFromFile(mp3, {
+        // Named, because this is what a person sees on the download link rather than
+        // an opaque id — and typed, because the byte route serves the type it was
+        // given and a browser will not play a file it was handed as bytes.
+        name: "audit.mp3",
+        type: "audio/mpeg",
+      });
+
+      await report(
+        `Recorded a ${Math.round(spoken.durationMs / 1000)}s audit in ${spoken.voice}'s voice — ` +
+          `${formatBytes(bytes)} of MP3, from ${formatBytes(spoken.audio.byteLength)} of WAV.`,
+      );
+      return { audio: stored.id, durationMs: spoken.durationMs, bytes };
+    },
+    { prefix: "aai-call-audit-" },
+  );
 }

package/dist/templates/call-audit/workflows/sync-api.ts

@@ -7,12 +7,11 @@
  * `transcription-workflow` has one: `stepTranscribeSync` is the SDK's — the URL,
  * the raw-key auth (no `Bearer`, which is a 401 that reads like a wrong key), the
  * multipart shape, the deadline and the three-way failure verdict all live there —
- * so what is left at the call site is the `.catch` that hands the verdict to the
- * DevKit, and that belongs somewhere a spec can reach it.
+ * so what is left at the call site is the classification that hands the verdict to
+ * the DevKit, and that belongs somewhere a spec can reach it.
  */
 
-import { throwStepError } from "@alexkroman1/aai/step-errors";
-import { stepTranscribeSync } from "@alexkroman1/aai/utils";
+import { stepTranscribeSyncClassified } from "@alexkroman1/aai/step-errors";
 
 /**
  * Transcribe one complete WAV.
@@ -22,8 +21,9 @@ import { stepTranscribeSync } from "@alexkroman1/aai/utils";
  * stores headerless PCM on purpose (see `media.ts`) and puts a header back with
  * `encodeWav` for exactly this call.
  *
- * `.catch(throwStepError)` is the whole of what this adds, and it is where the
- * three-way call is made: a `FatalError` stops the DevKit retrying something that
+ * `stepTranscribeSyncClassified` — the SDK's own `stepTranscribeSync` plus
+ * `throwStepError`, and nothing else — is the whole of what this adds, 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 fan-out
@@ -39,6 +39,6 @@ export async function transcribeSpan(
   filename: string,
   label: string,
 ): Promise<string> {
-  const { text } = await stepTranscribeSync(bytes, { filename, label }).catch(throwStepError);
+  const { text } = await stepTranscribeSyncClassified(bytes, { filename, label });
   return text;
 }