@alexkroman1/aai-cli 6.10.1 → 7.0.0

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

@@ -0,0 +1,201 @@
+// 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 { 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 { masterArgs } from "./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 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" +
+      `- 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,
+    },
+    // 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} ${plural(reply.risks.length, "risk")} and ` +
+      `${reply.actions.length} ${plural(reply.actions.length, "action")}.`,
+  );
+  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 `@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.
+ * 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(
+        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

@@ -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 classification that hands the verdict to
+ * the DevKit, and that belongs somewhere a spec can reach it.
+ */
+
+import { stepTranscribeSyncClassified } from "@alexkroman1/aai/step-errors";
+
+/**
+ * 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.
+ *
+ * `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
+ * 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 stepTranscribeSyncClassified(bytes, { filename, label });
+  return text;
+}

package/dist/templates/dispatch-center/agent.test.ts

@@ -1,11 +1,20 @@
-import type { ToolContext } from "@alexkroman1/aai";
-import { createToolContext } from "@alexkroman1/aai/testing";
+import type {
+  DialogPosition,
+  InferToolOutput,
+  ToolContext,
+  ToolDef,
+  ToolInputSchema,
+} from "@alexkroman1/aai";
+import { isToolFailure } from "@alexkroman1/aai";
+import { createToolContext, ok } from "@alexkroman1/aai/testing";
 import { describe, expect, test } from "vitest";
-import { dispatchSlot } from "./shared.ts";
+import { callFlow, dispatchSlot } from "./shared.ts";
+import incidentAddNote from "./tools/incident_add_note.ts";
 import incidentCreate from "./tools/incident_create.ts";
 import incidentEscalate from "./tools/incident_escalate.ts";
 import incidentTriage from "./tools/incident_triage.ts";
 import incidentUpdateStatus from "./tools/incident_update_status.ts";
+import opsRunScenario from "./tools/ops_run_scenario.ts";
 import resourcesDispatch from "./tools/resources_dispatch.ts";
 import resourcesUpdateStatus from "./tools/resources_update_status.ts";
 
@@ -14,14 +23,31 @@ import resourcesUpdateStatus from "./tools/resources_update_status.ts";
  *  construction. */
 const makeCtx = (): ToolContext => createToolContext();
 
+/**
+ * What a gated tool's own `execute` returned, read off the tool itself.
+ *
+ * `callFlow.tool` threads its result type out now, so `InferToolOutput` answers
+ * `DialogToolResult<R> | ToolFailure` — this is that minus the envelope and the
+ * refusal arm. It replaces the inline `{ dispatched: { callsign: string }[] }`
+ * shapes the assertions below used to restate, which were a second copy of each
+ * tool's return type that could not go stale loudly.
+ *
+ * The unwrap itself is `ok` from `@alexkroman1/aai/testing`; the hand-rolled
+ * copy that used to sit here was byte-identical to three other templates'.
+ */
+type Result<T extends ToolDef<ToolInputSchema>> = Extract<
+  InferToolOutput<T>,
+  { result: unknown }
+>["result"];
+
+/** Where the call is, without going through a tool. */
+const at = (ctx: ToolContext): DialogPosition => callFlow.position(ctx);
+
 async function createIncidentFor(
   ctx: ToolContext,
   description = "structure fire with heavy smoke",
 ): Promise<string> {
-  const result = (await incidentCreate.execute(
-    { location: "400 Oak Street", description },
-    ctx,
-  )) as { incidentId: string };
+  const result = await incidentCreate.execute({ location: "400 Oak Street", description }, ctx);
   return result.incidentId;
 }
 
@@ -52,10 +78,9 @@ describe("dispatch-center template", () => {
     const ctx = makeCtx();
     const incidentId = await createIncidentFor(ctx, "cardiac arrest, patient not breathing");
 
-    const result = (await resourcesDispatch.execute({ incidentId, callsigns: ["auto"] }, ctx)) as {
-      dispatched: { callsign: string }[];
-      failed?: { callsign: string; reason: string }[];
-    };
+    const result = ok<Result<typeof resourcesDispatch>>(
+      await resourcesDispatch.execute({ incidentId, callsigns: ["auto"] }, ctx),
+    );
 
     expect(result.failed).toBeUndefined();
     expect(result.dispatched.length).toBeGreaterThan(0);
@@ -68,10 +93,10 @@ describe("dispatch-center template", () => {
     // mutex in updateState makes each one run against the previous one's
     // finished state, so neither incident's changes are half-applied when
     // the other's mutator runs.
-    const [a, b] = (await Promise.all([
+    const [a, b] = await Promise.all([
       incidentCreate.execute({ location: "1 First St", description: "gas leak" }, ctx),
       incidentCreate.execute({ location: "2 Second St", description: "vehicle crash" }, ctx),
-    ])) as { incidentId: string }[];
+    ]);
 
     const state = dispatchSlot.get(ctx);
     expect(a?.incidentId).not.toBe(b?.incidentId);
@@ -124,21 +149,120 @@ describe("dispatch-center template", () => {
     const incidentId = await createIncidentFor(ctx);
     await incidentUpdateStatus.execute({ incidentId, status: "resolved" }, ctx);
 
-    const escalated = (await incidentEscalate.execute({ incidentId, reason: "flare-up" }, ctx)) as {
-      error?: string;
-    };
-    expect(escalated.error).toMatch(/resolved/);
+    // Each is a refusal the BODY answered, so it arrives unwrapped as a
+    // `ToolFailure` rather than under the position envelope — which is what the
+    // narrowing says, where the old cast to `{ error?: string }` said nothing
+    // and would have read `undefined` off a success just as quietly.
+    const escalated = await incidentEscalate.execute({ incidentId, reason: "flare-up" }, ctx);
+    expect(isToolFailure(escalated) && escalated.error).toMatch(/resolved/);
 
-    const reResolved = (await incidentUpdateStatus.execute(
-      { incidentId, status: "resolved" },
-      ctx,
-    )) as { error?: string };
-    expect(reResolved.error).toMatch(/resolved/);
+    const reResolved = await incidentUpdateStatus.execute({ incidentId, status: "resolved" }, ctx);
+    expect(isToolFailure(reResolved) && reResolved.error).toMatch(/resolved/);
 
-    const dispatchedTo = (await resourcesDispatch.execute(
+    const dispatchedTo = await resourcesDispatch.execute(
       { incidentId, callsigns: ["Medic-1"] },
       ctx,
-    )) as { error?: string };
-    expect(dispatchedTo.error).toMatch(/resolved/);
+    );
+    expect(isToolFailure(dispatchedTo) && dispatchedTo.error).toMatch(/resolved/);
+  });
+});
+
+describe("the call flow", () => {
+  test("a fresh shift is in standby, and every incident tool refuses there", async () => {
+    const ctx = makeCtx();
+    expect(at(ctx).state).toBe("standby");
+
+    // Each of these used to run and answer `Incident INC-0001 not found` — a
+    // data answer to a positional question. The refusal now names where the
+    // shift is and quotes what to do about it.
+    for (const call of [
+      incidentTriage.execute({ incidentId: "INC-0001" }, ctx),
+      resourcesDispatch.execute({ incidentId: "INC-0001", callsigns: ["Medic-1"] }, ctx),
+      incidentUpdateStatus.execute({ incidentId: "INC-0001", status: "on_scene" }, ctx),
+      incidentEscalate.execute({ incidentId: "INC-0001", reason: "spreading" }, ctx),
+      incidentAddNote.execute({ incidentId: "INC-0001", note: "caller hung up" }, ctx),
+      resourcesUpdateStatus.execute({ callsign: "Medic-1", status: "en_route" }, ctx),
+    ]) {
+      const refusal = await call;
+      expect(isToolFailure(refusal)).toBe(true);
+      expect(isToolFailure(refusal) && refusal.error).toMatch(/standby/);
+    }
+
+    // And nothing ran: a refusal must not have touched the board.
+    expect(dispatchSlot.get(ctx).incidentCounter).toBe(0);
+  });
+
+  test("logging, triaging and dispatching walk the call through its three steps", async () => {
+    const ctx = makeCtx();
+
+    const created = await incidentCreate.execute(
+      { location: "400 Oak Street", description: "structure fire with heavy smoke" },
+      ctx,
+    );
+    // `state`/`instruction`, not `at`/`next`: this ungated tool spreads the
+    // `DialogPosition` verbatim now, so it reports its position under the same
+    // keys every gated tool's result carries.
+    expect(created.state).toBe("working.triaging");
+    expect(created.instruction).toMatch(/incident_triage/);
+
+    const triaged = ok<Result<typeof incidentTriage>>(
+      await incidentTriage.execute({ incidentId: created.incidentId, severity: "critical" }, ctx),
+    );
+    expect(triaged.triageScore).toBeGreaterThan(0);
+    expect(at(ctx).state).toBe("working.dispatching");
+
+    ok(
+      await resourcesDispatch.execute({ incidentId: created.incidentId, autoDispatch: true }, ctx),
+    );
+    expect(at(ctx).state).toBe("working.monitoring");
+    expect(at(ctx).instruction).toMatch(/radio in/);
+  });
+
+  test("a dispatch that rolled nothing leaves the call where it was", async () => {
+    const ctx = makeCtx();
+    const incidentId = await createIncidentFor(ctx);
+    await incidentTriage.execute({ incidentId }, ctx);
+    expect(at(ctx).state).toBe("working.dispatching");
+
+    // Every requested callsign is unknown, so no unit moved — and the call has
+    // not moved on either.
+    const result = ok<Result<typeof resourcesDispatch>>(
+      await resourcesDispatch.execute({ incidentId, callsigns: ["Ghost-1"] }, ctx),
+    );
+    expect(result.dispatched).toHaveLength(0);
+    expect(at(ctx).state).toBe("working.dispatching");
+  });
+
+  test("a new call is legal mid-incident and puts the flow back on triage", async () => {
+    const ctx = makeCtx();
+    const first = await createIncidentFor(ctx);
+    await incidentTriage.execute({ incidentId: first }, ctx);
+    await resourcesDispatch.execute({ incidentId: first, autoDispatch: true }, ctx);
+    expect(at(ctx).state).toBe("working.monitoring");
+
+    await createIncidentFor(ctx, "chemical spill spreading toward a storm drain");
+    expect(at(ctx).state).toBe("working.triaging");
+
+    // The first incident is still workable — the position tracks the call in
+    // hand, and the tools are addressed by id.
+    ok(await incidentAddNote.execute({ incidentId: first, note: "crews on scene" }, ctx));
+  });
+
+  test("a failed tool does not advance the flow", async () => {
+    const ctx = makeCtx();
+    const incidentId = await createIncidentFor(ctx);
+    await incidentUpdateStatus.execute({ incidentId, status: "resolved" }, ctx);
+    const before = at(ctx).state;
+
+    const refused = await incidentTriage.execute({ incidentId, severity: "critical" }, ctx);
+    expect(isToolFailure(refused)).toBe(true);
+    expect(at(ctx).state).toBe(before);
+  });
+
+  test("a training scenario logs incidents like a real call does", async () => {
+    const ctx = makeCtx();
+    const result = await opsRunScenario.execute({ scenario: "mass_casualty" }, ctx);
+    expect(result.incidentsCreated.length).toBeGreaterThan(1);
+    expect(result.state).toBe("working.triaging");
   });
 });