@alexkroman1/aai-cli 13.3.0 → 14.0.0

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

@@ -16,7 +16,7 @@
  * ## The argv is ours, so it is BUILT rather than embedded
  *
  * `runFfmpeg` passes `args` through verbatim — no `-y`, no `-loglevel` — so the
- * standing flags are a decision this file makes once ({@link standardFlags}) and
+ * standing flags come from `ffmpegBaseArgs` on `@alexkroman1/aai/ffmpeg`, and
  * every invocation's real argv is a value a test can assert on. It is also why
  * the filter strings below carry no shell quoting: each is ONE element of an
  * argv array, so the commas that chain filters and the colons that separate their
@@ -58,7 +58,9 @@
  * longer than the cap gets the blind cut, and says so.
  */
 
+import { ffmpegBaseArgs } from "@alexkroman1/aai/ffmpeg";
 import type { PcmFormat } from "@alexkroman1/aai/step";
+import { safeJsonParse } from "@alexkroman1/aai/utils";
 import { z } from "zod";
 
 /**
@@ -151,20 +153,6 @@ export const MAX_SEGMENT_SECONDS = 110;
  */
 export const MIN_SEGMENT_SECONDS = 1;
 
-/** The standing flags, on every invocation this desk makes. */
-export function standardFlags(): string[] {
-  return [
-    "-hide_banner",
-    // Progress lines are noise in a captured stderr, and the SDK keeps only a
-    // tail of it — so suppressing them is what leaves room for the diagnosis.
-    "-nostats",
-    // In a guest there is no terminal, and an ffmpeg that decides to read stdin
-    // is a process that never exits.
-    "-nostdin",
-    "-y",
-  ];
-}
-
 /** A loudness measurement, as `loudnorm`'s first pass reports it. */
 export type Loudness = {
   /** Integrated loudness, LUFS. */
@@ -233,9 +221,9 @@ export class MediaAnalysisError extends Error {
  */
 export function measureLoudnessArgs(input: string): string[] {
   return [
-    ...standardFlags(),
-    "-loglevel",
-    "info",
+    // `info`, not the default `error`: `print_format=json` reports through the
+    // LOG, so at `error` this pass runs, succeeds, and prints nothing.
+    ...ffmpegBaseArgs({ loglevel: "info" }),
     "-i",
     input,
     "-af",
@@ -273,7 +261,7 @@ export function parseLoudness(stderr: string): Loudness {
   // different remedies, and the second message quotes the value ffmpeg actually
   // printed — which needs the block still in hand, so the gate cannot be folded
   // into the schema below.
-  const block = LoudnessBlock.safeParse(safeJson(stderr.slice(open, close + 1)));
+  const block = LoudnessBlock.safeParse(safeJsonParse(stderr.slice(open, close + 1)));
   if (!block.success) {
     throw new MediaAnalysisError("The loudness pass printed a block that is not JSON.");
   }
@@ -301,7 +289,7 @@ export function parseLoudness(stderr: string): Loudness {
 /**
  * Is the found `{…}` an object at all?
  *
- * The reachable failure is {@link safeJson} answering `undefined` — a brace pair
+ * The reachable failure is {@link safeJsonParse} answering `undefined` — a brace pair
  * found in ffmpeg's chatter with something other than JSON between them — and
  * that is a different sentence from a value being unreadable, which is why this
  * gate exists at all rather than being folded into {@link LoudnessValues}.
@@ -370,12 +358,10 @@ export function normalizeArgs(
   ].join(":");
 
   return [
-    ...standardFlags(),
     // Quiet, and the analysis still arrives: `ametadata` writes its file
     // directly rather than through the log, which is the property that lets this
     // pass be both silent and complete.
-    "-loglevel",
-    "error",
+    ...ffmpegBaseArgs(),
     "-i",
     input,
     "-af",
@@ -456,7 +442,7 @@ export function parseSilences(log: string, durationSec: number): Silence[] {
  * Exact rather than rounded, and that distinction cost a bug: `pcmDurationMs`
  * answers whole MILLISECONDS, so a 640,500-byte file reports 20,016 ms where it
  * really holds 20,015.625. Planning from the rounded number put the last segment's
- * `endByte` at 640,512 — twelve bytes past the end of the file. `readUpload` clamps
+ * `endByte` at 640,512 — twelve bytes past the end of the file. `stepReadUpload` clamps
  * a window to the stored size, so nothing threw; the plan was simply describing
  * audio that does not exist. Verified against a real ffmpeg, which is the only
  * place a 12-byte error was ever going to show up.
@@ -474,7 +460,7 @@ export function durationSeconds(totalBytes: number): number {
  * Greedy from the front: a segment grows until the next cut candidate would take
  * it past {@link MAX_SEGMENT_SECONDS}, so it ends at the LAST pause that still
  * fits. Segments are therefore contiguous and non-overlapping — together they are
- * the whole recording, each one addressable as a single `readUpload` window.
+ * the whole recording, each one addressable as a single `stepReadUpload` window.
  *
  * Three properties, each of which a simpler version gets wrong:
  *
@@ -600,9 +586,7 @@ export function planSegments(silences: readonly Silence[], totalBytes: number):
  */
 export function masterArgs(input: string, output: string): string[] {
   return [
-    ...standardFlags(),
-    "-loglevel",
-    "error",
+    ...ffmpegBaseArgs(),
     "-i",
     input,
     "-af",
@@ -652,12 +636,3 @@ function value(line: string, key: string): number | undefined {
   const parsed = Number(text);
   return Number.isFinite(parsed) ? parsed : undefined;
 }
-
-/** `JSON.parse` that answers `undefined` rather than throwing, so the caller frames the error. */
-function safeJson(text: string): unknown {
-  try {
-    return JSON.parse(text);
-  } catch {
-    return undefined;
-  }
-}

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

@@ -11,7 +11,7 @@
  * `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
+ * a VALUE), why `stepWriteUpload` 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
@@ -35,8 +35,8 @@
 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 { stepReport, stepSpeak } from "@alexkroman1/aai/step";
+import { stepGenerateJsonOrFail, 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";
@@ -105,8 +105,8 @@ export async function summarize(
   source: string,
   durationMs: number,
 ): Promise<CallSummary> {
-  await report("Reading the transcript.");
-  const reply = await stepGenerateJsonClassified(
+  await stepReport("Reading the transcript.");
+  const reply = await stepGenerateJsonOrFail(
     `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` +
@@ -125,12 +125,12 @@ export async function summarize(
       system: "You audit recorded calls. You answer with JSON and nothing else.",
       schema: AuditReply,
     },
-    // The `Classified` caller is `stepGenerateJson` plus `throwStepError`, which is
+    // The `OrFail` 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(
+  await stepReport(
     `Found ${reply.risks.length} ${plural(reply.risks.length, "risk")} and ` +
       `${reply.actions.length} ${plural(reply.actions.length, "action")}.`,
   );
@@ -186,7 +186,7 @@ export async function narrate(
         type: "audio/mpeg",
       });
 
-      await report(
+      await stepReport(
         `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.`,
       );

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

@@ -11,7 +11,7 @@
  * the DevKit, and that belongs somewhere a spec can reach it.
  */
 
-import { stepTranscribeSyncClassified } from "@alexkroman1/aai/step-errors";
+import { stepTranscribeSyncOrFail } from "@alexkroman1/aai/step-errors";
 
 /**
  * Transcribe one complete WAV.
@@ -21,7 +21,7 @@ import { stepTranscribeSyncClassified } from "@alexkroman1/aai/step-errors";
  * 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
+ * `stepTranscribeSyncOrFail` — 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
@@ -39,6 +39,6 @@ export async function transcribeSpan(
   filename: string,
   label: string,
 ): Promise<string> {
-  const { text } = await stepTranscribeSyncClassified(bytes, { filename, label });
+  const { text } = await stepTranscribeSyncOrFail(bytes, { filename, label });
   return text;
 }

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

@@ -6,7 +6,7 @@ import type {
   ToolInputSchema,
 } from "@alexkroman1/aai";
 import { isToolFailure } from "@alexkroman1/aai";
-import { createToolContext, ok } from "@alexkroman1/aai/testing";
+import { createToolContext, expectToolOk } from "@alexkroman1/aai/testing";
 import { describe, expect, test } from "vitest";
 import { callFlow, dispatchSlot } from "./shared.ts";
 import incidentAddNote from "./tools/incident_add_note.ts";
@@ -32,7 +32,7 @@ const makeCtx = (): ToolContext => createToolContext();
  * 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
+ * The unwrap itself is `expectToolOk` 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<
@@ -78,7 +78,7 @@ describe("dispatch-center template", () => {
     const ctx = makeCtx();
     const incidentId = await createIncidentFor(ctx, "cardiac arrest, patient not breathing");
 
-    const result = ok<Result<typeof resourcesDispatch>>(
+    const result = expectToolOk<Result<typeof resourcesDispatch>>(
       await resourcesDispatch.execute({ incidentId, callsigns: ["auto"] }, ctx),
     );
 
@@ -205,13 +205,13 @@ describe("the call flow", () => {
     expect(created.state).toBe("working.triaging");
     expect(created.instruction).toMatch(/incident_triage/);
 
-    const triaged = ok<Result<typeof incidentTriage>>(
+    const triaged = expectToolOk<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(
+    expectToolOk(
       await resourcesDispatch.execute({ incidentId: created.incidentId, autoDispatch: true }, ctx),
     );
     expect(at(ctx).state).toBe("working.monitoring");
@@ -226,7 +226,7 @@ describe("the call flow", () => {
 
     // Every requested callsign is unknown, so no unit moved — and the call has
     // not moved on either.
-    const result = ok<Result<typeof resourcesDispatch>>(
+    const result = expectToolOk<Result<typeof resourcesDispatch>>(
       await resourcesDispatch.execute({ incidentId, callsigns: ["Ghost-1"] }, ctx),
     );
     expect(result.dispatched).toHaveLength(0);
@@ -245,7 +245,7 @@ describe("the call flow", () => {
 
     // 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));
+    expectToolOk(await incidentAddNote.execute({ incidentId: first, note: "crews on scene" }, ctx));
   });
 
   test("a failed tool does not advance the flow", async () => {

package/dist/templates/dispatch-center/client.tsx

@@ -1,12 +1,16 @@
+import { plural } from "@alexkroman1/aai/utils";
 import "@alexkroman1/aai-ui/styles.css";
-import type { AgentState, ConversationItem, Session } from "@alexkroman1/aai-ui";
+import type { AgentState, ConversationItem } from "@alexkroman1/aai-ui";
 import {
+  AGENT_STATE_LABELS,
   AutoScroll,
-  client,
+  mountClient,
+  SessionErrorBanner,
   useAgentState,
   useConversation,
-  useSession,
+  useSessionActions,
   useSessionSelector,
+  useSessionStatus,
 } from "@alexkroman1/aai-ui";
 import type { DispatchState, IncidentSummary, Severity, Status } from "./shared.ts";
 import { dashboardProjection } from "./shared.ts";
@@ -77,6 +81,20 @@ const STATE_COLORS = {
   error: "#6b7280",
 } satisfies Record<AgentState, string>;
 
+/*
+ * The board's own vocabulary, spread over the package's record rather than
+ * written as a ternary chain. Only three of the seven states get a dispatch
+ * word; the rest come from `AGENT_STATE_LABELS`, so a state added upstream
+ * reads as something rather than falling through to whichever arm the chain
+ * ended on.
+ */
+const STATE_LABELS: Record<AgentState, string> = {
+  ...AGENT_STATE_LABELS,
+  listening: "LISTENING",
+  thinking: "PROCESSING",
+  speaking: "TRANSMITTING",
+};
+
 function Panel({ title, children }: { title: string; children: React.ReactNode }) {
   return (
     <div className="rounded-lg p-3" style={{ background: "#1a1a2e", border: "1px solid #1e293b" }}>
@@ -230,8 +248,16 @@ function Conversation() {
             {streaming}
           </div>
         )}
+        {/* Same contract as the shipped `MessageList`'s indicator: three pulsing
+            dots are the only sign the desk is working, and to a screen reader
+            they are punctuation. */}
         {thinking && (
-          <div className="self-start text-[11px] px-3.5" style={{ color: "#64748b" }}>
+          <div
+            role="status"
+            aria-label="Dispatch is thinking"
+            className="self-start text-[11px] px-3.5"
+            style={{ color: "#64748b" }}
+          >
             <span style={{ animation: "dc-pulse 1.2s ease-in-out infinite" }}>· · ·</span>
           </div>
         )}
@@ -261,7 +287,7 @@ function Conversation() {
  * it one level up dragged the incident board through every snapshot change.
  */
 function StatusReadout() {
-  const state = useSessionSelector((s) => s.state);
+  const state = useSessionStatus();
   return (
     <>
       <span
@@ -278,70 +304,36 @@ function StatusReadout() {
         title={state}
       />
       <span className="text-[11px] font-normal normal-case" style={{ color: "#64748b" }}>
-        {state === "listening"
-          ? "LISTENING"
-          : state === "thinking"
-            ? "PROCESSING"
-            : state === "speaking"
-              ? "TRANSMITTING"
-              : state.toUpperCase()}
+        {STATE_LABELS[state]}
       </span>
     </>
   );
 }
 
-/**
- * The fatal-error banner.
+/*
+ * The shift controls.
  *
- * `role="alert"` is the part that is easy to leave out and is load-bearing: per
- * the `fatalError` latch in the session core this banner is the only remaining
- * signal — the status eyebrow beside it goes back to reading like a live
- * session — and a screen reader is never told an unannounced one appeared. It
- * is what `ConsoleShell` carries, which this template's full-bleed two-pane
- * board cannot use as its frame.
+ * `useSessionActions()` for the methods and two one-field selectors for the
+ * flags, rather than the whole-snapshot `useSession()` this used to hold. The
+ * methods are what the row is really after, and `useSession()` re-renders on
+ * every snapshot change — so four buttons re-rendered at STT-partial rate to
+ * read two booleans that flip once a shift.
  */
-function ErrorBanner() {
-  const error = useSessionSelector((s) => s.error);
-  if (!error) return null;
-  return (
-    <div
-      role="alert"
-      className="px-4 py-2 text-xs"
-      style={{ background: "#450a0a", color: "#fca5a5", borderTop: "1px solid #991b1b" }}
-    >
-      ERROR: {error.message} ({error.code})
-    </div>
-  );
-}
-
-/**
- * Start a fresh conversation without leaving the console.
- *
- * Written out here rather than reached for on the session, because there is no
- * one method that does it: `reset()` clears the CONVERSATION and keeps the
- * session, which is wrong for any agent that also keeps session-scoped state —
- * this one's incident board would come back with the next tool call.
- */
-function newConversation(session: Session): void {
-  session.end();
-  session.start();
-}
-
-/** The shift controls. The one place a whole-session read is what is wanted:
- *  it needs `started`, `running` and four methods, and it is four buttons. */
 function ShiftControls({ logged }: { logged: number }) {
-  const session = useSession();
+  const { start, toggle, restart, end } = useSessionActions();
+  const started = useSessionSelector((s) => s.started);
+  const running = useSessionSelector((s) => s.running);
   return (
     <div
       className="flex items-center gap-2.5 px-4 py-3"
       style={{ background: "#111827", borderTop: "1px solid #1e293b" }}
     >
-      {!session.started ? (
+      {!started ? (
         <button
           type="button"
           className="px-4 py-2 border-none rounded-md font-mono text-xs font-semibold uppercase tracking-wider cursor-pointer text-white"
           style={{ background: "#2563eb" }}
-          onClick={() => session.start()}
+          onClick={() => start()}
         >
           Start Dispatch
         </button>
@@ -351,12 +343,12 @@ function ShiftControls({ logged }: { logged: number }) {
             type="button"
             className="px-4 py-2 border-none rounded-md font-mono text-xs font-semibold uppercase tracking-wider cursor-pointer"
             style={{
-              background: session.running ? "#334155" : "#2563eb",
-              color: session.running ? "#e2e8f0" : "white",
+              background: running ? "#334155" : "#2563eb",
+              color: running ? "#e2e8f0" : "white",
             }}
-            onClick={() => session.toggle()}
+            onClick={() => toggle()}
           >
-            {session.running ? "Pause" : "Resume"}
+            {running ? "Pause" : "Resume"}
           </button>
           {/* The one-click new conversation the default shell's
               `<Controls>` gives every other template — a custom
@@ -375,7 +367,7 @@ function ShiftControls({ logged }: { logged: number }) {
             type="button"
             className="px-4 py-2 border-none rounded-md font-mono text-xs font-semibold uppercase tracking-wider cursor-pointer"
             style={{ background: "#1e293b", color: "#e2e8f0" }}
-            onClick={() => newConversation(session)}
+            onClick={restart}
           >
             New Conversation
           </button>
@@ -388,7 +380,7 @@ function ShiftControls({ logged }: { logged: number }) {
             type="button"
             className="px-4 py-2 border-none rounded-md font-mono text-xs font-semibold uppercase tracking-wider cursor-pointer text-white"
             style={{ background: "#dc2626" }}
-            onClick={() => session.end()}
+            onClick={() => end()}
           >
             End Shift
           </button>
@@ -396,7 +388,7 @@ function ShiftControls({ logged }: { logged: number }) {
       )}
       <div className="flex-1" />
       <span className="text-[10px]" style={{ color: "#475569" }}>
-        {logged} incident{logged !== 1 ? "s" : ""} logged
+        {logged} {plural(logged, "incident")} logged
       </span>
     </div>
   );
@@ -471,7 +463,7 @@ function App() {
             style={{ borderRight: "1px solid #1e293b" }}
           >
             <Conversation />
-            <ErrorBanner />
+            <SessionErrorBanner className="rounded-none border-x-0 border-b-0" />
             <ShiftControls logged={incidentList.length} />
           </div>
 
@@ -524,7 +516,7 @@ function App() {
   );
 }
 
-client({
+mountClient({
   component: App,
   theme: {
     bg: "#0a0a0f",

package/dist/templates/dispatch-center/shared.ts

@@ -71,7 +71,6 @@ export interface Incident {
   createdAt: number;
   updatedAt: number;
   escalationLevel: number;
-  protocolsActivated: string[];
   casualties: { confirmed: number; estimated: number; treated: number };
   hazards: string[];
 }
@@ -82,7 +81,6 @@ export interface DispatchState {
   incidentCounter: number;
   mutualAidCounter: number;
   alertLevel: "green" | "yellow" | "orange" | "red";
-  mutualAidRequested: boolean;
 }
 
 /**
@@ -157,7 +155,6 @@ export function createDefaultState(): DispatchState {
     incidentCounter: 0,
     mutualAidCounter: 0,
     alertLevel: "green",
-    mutualAidRequested: false,
   };
 }
 
@@ -348,7 +345,6 @@ export function createIncident(state: DispatchState, overrides: Partial<Incident
     createdAt: time,
     updatedAt: time,
     escalationLevel: 0,
-    protocolsActivated: [],
     casualties: { confirmed: 0, estimated: 0, treated: 0 },
     hazards: [],
     ...overrides,
@@ -730,8 +726,4 @@ export function recalculateAlertLevel(state: DispatchState): void {
   } else {
     state.alertLevel = "green";
   }
-
-  // Mutual aid tracks system posture: requested at red alert, stood down
-  // when the alert level drops back below red.
-  state.mutualAidRequested = state.alertLevel === "red";
 }

package/dist/templates/dispatch-center/tools/ops_dashboard.ts

@@ -25,7 +25,10 @@ export default dispatchSlot.tool({
 
     return {
       systemAlertLevel: state.alertLevel,
-      mutualAidActive: state.mutualAidRequested,
+      // Derived, not stored: mutual aid is requested at red alert and stood
+      // down when the level drops back below it, so the alert level IS the
+      // fact and the two can never disagree.
+      mutualAidActive: state.alertLevel === "red",
       resourceUtilization: `${utilization}%`,
       resourceSummary,
       activeIncidentCount: activeIncidents.length,

package/dist/templates/embedded-assets/agent.eval.test.ts

@@ -13,8 +13,10 @@
 /**
  * The def a DEPLOYED agent runs: authored, plus what `tools/` declares.
  *
- * The glob is written HERE rather than reached for from a shared helper because
- * this file SHIPS — a scaffolded project has no repo helper to import. Without
+ * Taken from `virtual:aai/agent` rather than a hand-written glob: the plugin
+ * expands it against THIS file's own directory, so the spec needs no glob and
+ * no shared helper — which matters because this file SHIPS, and a scaffolded
+ * project has no repo helper to import. Without
  * it this agent would have no tools and would answer every question from the
  * model's own memory, which is exactly what the cases below forbid.
  *

package/dist/templates/health-assistant/agent.eval.test.ts

@@ -22,8 +22,10 @@
 /**
  * The def a DEPLOYED agent runs: authored, plus what `tools/` declares.
  *
- * The glob is written HERE rather than reached for from a shared helper because
- * this file SHIPS — a scaffolded project has no repo helper to import. Without
+ * Taken from `virtual:aai/agent` rather than a hand-written glob: the plugin
+ * expands it against THIS file's own directory, so the spec needs no glob and
+ * no shared helper — which matters because this file SHIPS, and a scaffolded
+ * project has no repo helper to import. Without
  * it the desk would have no tools and would answer every one of these from
  * memory, which is the failure these cases exist to catch.
  *