@alexkroman1/aai-cli 6.10.0 → 6.11.0

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

@@ -0,0 +1,206 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * The two steps after the transcript: a model reads the call, and a voice reads
+ * the model back — through ffmpeg on the way out.
+ *
+ * ```text
+ *   summarize   one step, LLM Gateway        →  headline, risks, actions, script
+ *   narrate     one step, TTS + ffmpeg       →  an MP3, stored, and its id
+ * ```
+ *
+ * `spoken-summary` owns the audio ROUND TRIP and is the template to read for it:
+ * why `stepSpeak` exists at all (a `TtsSession` is an event stream wired into a
+ * live pipeline's playback, and a step has no turn to be part of and has to return
+ * a VALUE), why `writeUpload` is its other half, and why speaking and storing must
+ * be one step. None of that is restated here.
+ *
+ * **What this file adds is the pass AFTER the synthesis**, and it is the second
+ * half of what having a decoder in the pipeline buys. `stepSpeak` answers with a
+ * 24 kHz WAV, which is correct and is not a deliverable:
+ *
+ * - **It is uncompressed.** A 90-second summary is 4.3 MB, and the page downloads
+ *   the whole thing through `api.download` before it can play a note of it. The
+ *   same summary as VBR MP3 is ~110 KB, which is a fortieth.
+ * - **Its level is whatever the voice service chose.** Played straight after a
+ *   recording this desk levelled to −16 LUFS, a summary at −24 sounds broken. The
+ *   mastering pass puts both on the same scale, which is the whole reason to have
+ *   one number for the desk rather than one per stage.
+ *
+ * So the audio the page plays has been through ffmpeg twice — once on the way in
+ * to make it analysable, once on the way out to make it shippable. `media.ts`'s
+ * `masterArgs` is the second, and it explains why that one is a SINGLE `loudnorm`
+ * pass where the ingest is two.
+ */
+
+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 { z } from "zod";
+import { classifyFfmpeg } from "./ingest.ts";
+import { clock, masterArgs } from "./media.ts";
+import { fileChunks, withTempDir } from "./temp-media.ts";
+
+/** Risks the summary is reduced to. Enough to be useful, few enough to act on. */
+const MAX_RISKS = 4;
+
+/** Actions the summary is reduced to. */
+const MAX_ACTIONS = 4;
+
+/**
+ * Characters of transcript handed to the model.
+ *
+ * The pass-an-id-not-a-payload rule meeting a case where the payload IS the work:
+ * the text has to cross the queue between two steps, so it is bounded rather than
+ * trusted. 40k characters is roughly four hours of speech — past where another
+ * paragraph changes a four-point summary.
+ */
+const MAX_TRANSCRIPT_CHARS = 40_000;
+
+/** How long the mastering pass may run. Seconds of work; the bound is for a pathological input. */
+const MASTER_TIMEOUT_MS = 5 * 60_000;
+
+/**
+ * The shape the model must answer in, as something that CHECKS.
+ *
+ * `stepGenerateJson` validates against this and throws plainly when the reply
+ * misses, which is what a retry is for: a model that answered with prose may well
+ * obey on the next attempt.
+ */
+const AuditReply = z.object({
+  headline: z.string().trim().min(1),
+  // Allowed to be EMPTY, unlike `spoken` below, and the asymmetry is deliberate: a
+  // call with nothing worrying in it is a real call, and a schema that demanded a
+  // risk would get an invented one. An empty array is an answer.
+  risks: z.array(z.string().trim().min(1)),
+  actions: z.array(z.string().trim().min(1)),
+  // NOT `.default("")` — the whole second half of this workflow has nothing to say
+  // without it, and a default would turn a missing field into a silent half-second
+  // of audio rather than a retry.
+  spoken: z.string().trim().min(1),
+});
+
+/** What the model made of the call. */
+export type CallSummary = {
+  headline: string;
+  risks: string[];
+  actions: string[];
+  /** The same summary, written to be READ ALOUD — see {@link summarize}. */
+  spoken: string;
+};
+
+/**
+ * Reduce the transcript to a headline, the risks, the actions, and a script.
+ *
+ * **The model is asked for TWO summaries, and the difference is the point.**
+ * `risks`/`actions` are for reading and `spoken` is for hearing; a template that
+ * synthesized its own bullet list produces a voice reading "one. two. three." with
+ * no connective tissue. So the schema asks for a script as well, in sentences, and
+ * that is what {@link narrate} is handed. It is a decision a prompt alone does not
+ * hold, which is why the field is required rather than defaulted.
+ */
+export async function summarize(
+  transcript: string,
+  source: string,
+  durationMs: number,
+): Promise<CallSummary> {
+  "use step";
+
+  await report("Reading the transcript.");
+  const reply = await stepGenerateJson(
+    `Audit this transcript of a recorded call (${source}, ${clock(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" +
+      `- risks: at most ${MAX_RISKS} things a reader should worry about — a ` +
+      "commitment nobody owns, a number that was guessed at, a disagreement left " +
+      "unresolved. Quote or name the specifics. An EMPTY array if the call really " +
+      "had none; never invent one.\n" +
+      `- actions: at most ${MAX_ACTIONS} things somebody has to do next, each ` +
+      "naming who if the call named them.\n" +
+      "- spoken: the same audit written to be READ ALOUD. Full sentences that " +
+      "flow, under 150 words, no bullet markers, no headings, no markdown. " +
+      "Someone will hear this without seeing the lists.\n\n" +
+      `Transcript:\n${transcript.slice(0, MAX_TRANSCRIPT_CHARS)}`,
+    {
+      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);
+
+  await report(
+    `Found ${reply.risks.length} risk${reply.risks.length === 1 ? "" : "s"} and ` +
+      `${reply.actions.length} action${reply.actions.length === 1 ? "" : "s"}.`,
+  );
+  return {
+    headline: reply.headline,
+    risks: reply.risks.slice(0, MAX_RISKS),
+    actions: reply.actions.slice(0, MAX_ACTIONS),
+    spoken: reply.spoken,
+  };
+}
+
+/**
+ * Read the audit aloud, master it, store it, and answer with its id.
+ *
+ * **All four halves belong in ONE step**, and the reason is what a journal
+ * 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
+ * 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.
+ * Cheap next to a step that cannot retry.
+ */
+export async function narrate(
+  script: string,
+  voice?: string,
+): Promise<{ audio: string; durationMs: number; bytes: number }> {
+  "use step";
+
+  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`;
+}

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

@@ -0,0 +1,44 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * The one transcription request, and its classification.
+ *
+ * No directive, so it sits under `workflows/` untransformed and is called FROM a
+ * step, inheriting its environment. It is its own module for the same reason
+ * `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.
+ */
+
+import { throwStepError } from "@alexkroman1/aai/step-errors";
+import { stepTranscribeSync } from "@alexkroman1/aai/utils";
+
+/**
+ * Transcribe one complete WAV.
+ *
+ * `bytes` must be a whole file, header included — the endpoint decodes each
+ * request independently, so a headerless span is bytes it will refuse. This desk
+ * 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
+ * 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
+ * hits a 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), because it is what a reader of the log has in front of
+ *   them.
+ */
+export async function transcribeSpan(
+  bytes: Uint8Array,
+  filename: string,
+  label: string,
+): Promise<string> {
+  const { text } = await stepTranscribeSync(bytes, { filename, label }).catch(throwStepError);
+  return text;
+}

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

@@ -0,0 +1,138 @@
+// Copyright 2026 the AAI authors. MIT license.
+/**
+ * Moving bytes between the upload store and a local file, which is what an
+ * ffmpeg step spends most of its lines on.
+ *
+ * No directive, so it sits under `workflows/` untransformed and is called FROM
+ * steps, inheriting their environment. It exists because both ffmpeg steps in
+ * this template need the same three things and the third one is the one that is
+ * easy to get wrong.
+ *
+ * ## Why a temp file at all
+ *
+ * `@alexkroman1/aai/ffmpeg` takes bytes as happily as a path, and for a short
+ * clip bytes are the better call. This desk uses paths, for two reasons that are
+ * both properties of real recordings rather than preferences:
+ *
+ * - **A pipe cannot seek.** An `.m4a` off a phone usually carries its `moov`
+ *   index at the END of the file, so ffmpeg reading it from `pipe:0` fails with
+ *   `moov atom not found`. That is the flagship input.
+ * - **Piped output is capped**, at `DEFAULT_MAX_FFMPEG_OUTPUT_BYTES` (64 MiB),
+ *   which is about half an hour of this desk's 16 kHz mono PCM. The desk exists
+ *   for the two-hour call.
+ *
+ * ## A temp file may not outlive its step
+ *
+ * A step is journaled by its RETURN VALUE and may be dispatched into a different
+ * process than its neighbours, so a path in a return value is a path that is
+ * replayed after the file behind it is gone — and the failure mode is a resumed
+ * run reading a directory that another run is using. {@link withTempDir} makes
+ * the lifetime a lexical scope: the directory is created on entry, removed on
+ * exit, and what crosses the step boundary is an upload id.
+ */
+
+import { mkdtemp, open, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { readUpload } from "@alexkroman1/aai/utils";
+
+/**
+ * Bytes moved per `readUpload`, and per write.
+ *
+ * Large enough that a two-hour recording is a few hundred round trips rather
+ * than tens of thousands, and small enough that a step's resident set is a
+ * constant rather than a function of the recording. The number this must NOT be
+ * is "the whole file", which is the shape every first draft has.
+ */
+export const WINDOW_BYTES = 8 * 1024 * 1024;
+
+/**
+ * Run `work` with a private temp directory, and remove it afterwards.
+ *
+ * `join(tmpdir(), …)` rather than a `/tmp` literal, which is this repo's rule
+ * (`guard-invariants` rule 11) and not merely portability theatre: on Windows a
+ * literal `/tmp/x` is DRIVE-RELATIVE, so it resolves somewhere that does not
+ * exist and every write fails with ENOENT. A step runs in a Linux guest when it
+ * is deployed and on the developer's own machine under `aai dev`, which is the
+ * half that makes it matter.
+ *
+ * The removal is in a `finally`, so it also runs on the failure paths — a guest's
+ * disk is small, and a step that leaves a copy of every recording it touched
+ * fills it. `force` so a run that never created its output does not fail HERE and
+ * replace the real error with this one.
+ */
+export async function withTempDir<T>(work: (dir: string) => Promise<T>): Promise<T> {
+  const dir = await mkdtemp(join(tmpdir(), "aai-call-audit-"));
+  try {
+    return await work(dir);
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Write an upload to a local path, a window at a time.
+ *
+ * A `for` loop rather than a fan-out deliberately: the bytes land in one file at
+ * one offset each, so concurrency buys nothing and costs exactly the memory the
+ * windows are here to bound.
+ *
+ * `windowBytes` defaults to {@link WINDOW_BYTES}; see {@link fileChunks} for why
+ * it is a parameter at all.
+ */
+export async function materializeUpload(
+  uploadId: string,
+  size: number,
+  path: string,
+  windowBytes: number = WINDOW_BYTES,
+): Promise<void> {
+  const handle = await open(path, "w");
+  try {
+    for (let at = 0; at < size; at += windowBytes) {
+      const slice = await readUpload(uploadId, {
+        start: at,
+        end: Math.min(at + windowBytes, size),
+      });
+      await handle.write(slice.bytes);
+    }
+  } finally {
+    await handle.close();
+  }
+}
+
+/**
+ * A local file as the stream `writeUpload` takes.
+ *
+ * A generator rather than `readFile`, for the same reason the windows above
+ * exist: the normalized PCM is the largest thing this desk touches, and handing
+ * the store an `AsyncIterable` is what keeps it off the heap.
+ *
+ * **The `.slice()` is load-bearing.** One buffer is reused across reads, so
+ * yielding a view of it hands the consumer memory the next read overwrites — a
+ * bug whose symptom is a stored file made of the LAST chunk repeated, and which
+ * does not reproduce whenever the consumer happens to copy before the next
+ * iteration.
+ *
+ * `windowBytes` is a parameter with a default for exactly that reason, and it is
+ * the one testability seam in this template. The aliasing bug above only manifests
+ * across MULTIPLE reads, so at the real 8 MiB window a spec would have to write a
+ * 16 MB file to reach it — and a first draft of that spec used 200 KB, passed with
+ * the `.slice()` deleted, and would have shipped a test proving nothing. A small
+ * window makes the multi-chunk path a few kilobytes instead.
+ */
+export async function* fileChunks(
+  path: string,
+  windowBytes: number = WINDOW_BYTES,
+): AsyncIterable<Uint8Array> {
+  const handle = await open(path, "r");
+  try {
+    const buffer = new Uint8Array(windowBytes);
+    for (;;) {
+      const { bytesRead } = await handle.read(buffer, 0, buffer.length, null);
+      if (bytesRead === 0) return;
+      yield buffer.subarray(0, bytesRead).slice();
+    }
+  } finally {
+    await handle.close();
+  }
+}

package/dist/templates/recap-workflow/agent.test.ts

@@ -408,13 +408,21 @@ describe("submitRecording", () => {
 
     const call = calls[0];
     expect(call?.init.method).toBe("POST");
+    // `speaker_labels` is this desk's own request, carried through the SDK's
+    // `params` passthrough; the model field is the SDK's and is PLURAL.
     expect(JSON.parse(String(call?.init.body))).toMatchObject({
       audio_url: "https://example.com/a.mp3",
+      speaker_labels: true,
     });
-    // AssemblyAI's `authorization` takes the key RAW — no `Bearer` prefix,
-    // unlike the OpenAI-compatible LLM gateway `summarize` calls.
+    // AssemblyAI takes the key RAW — no `Bearer` prefix, unlike the
+    // OpenAI-compatible LLM gateway `summarize` calls. The SDK spells the
+    // header `Authorization`; HTTP header names are case-insensitive, so the
+    // lookup is too rather than pinning one casing.
     const headers = call?.init.headers as Record<string, string> | undefined;
-    expect(headers?.authorization).toBe("sk-test");
+    const auth = Object.entries(headers ?? {}).find(
+      ([name]) => name.toLowerCase() === "authorization",
+    );
+    expect(auth?.[1]).toBe("sk-test");
   });
 
   test("fails FATALLY on a bad key and plainly on a rate limit", async () => {

package/dist/templates/recap-workflow/workflows/recap.ts

@@ -76,6 +76,7 @@ import {
   requireStepEnv,
   stepFetch,
   stepGenerateJson,
+  stepTranscribeSubmit,
 } from "@alexkroman1/aai/utils";
 import { createHook, FatalError, sleep } from "workflow";
 import { z } from "zod";
@@ -358,14 +359,13 @@ export async function submitRecording(url: string): Promise<{ id: string }> {
 
   await report(`Submitting ${new URL(url).hostname} for transcription…`);
 
-  const response = await request(TRANSCRIPT_ENDPOINT, {
-    method: "POST",
-    body: JSON.stringify({ audio_url: url, speaker_labels: true }),
-  });
-  const body = await response.json();
-  const id = readString(body, "id");
-  if (!id) throw new Error("The provider accepted the recording but named no transcript id.");
-  return { id };
+  // `stepTranscribeSubmit` owns the endpoint, the raw-key auth, the PLURAL
+  // `speech_models` field and the failure classification. `speaker_labels` is
+  // this desk's own request, which is what `params` is for — the async API's
+  // surface is large and the SDK deliberately does not mirror it.
+  return await stepTranscribeSubmit(url, { params: { speaker_labels: true } }).catch(
+    throwStepError,
+  );
 }
 
 /**
@@ -374,6 +374,17 @@ export async function submitRecording(url: string): Promise<{ id: string }> {
  * One poll is one step, so each attempt is journaled on its own: a run that dies
  * mid-wait resumes knowing what the last answer was instead of starting the
  * recording over.
+ *
+ * **Deliberately NOT `stepTranscribePoll`, though its sibling above did move to
+ * the SDK.** That helper answers `done` and THROWS on a job the provider gave
+ * up on, which is the right shape for a flow whose only question is "is the
+ * text ready". This desk's question is different: `status` is a VALUE here,
+ * read by the Query port (`recap_status`) while the run is still going, and an
+ * `error` status is the branch that unwinds the saga's compensation stack
+ * rather than a failure to propagate. Converting this would trade a documented
+ * state machine — the thing this template is actually about — for a throw.
+ * The provider's status union is the template's subject, so it stays in the
+ * template.
  */
 export async function checkTranscript(id: string): Promise<TranscriptState> {
   "use step";