@alexkroman1/aai-cli 13.3.0 → 15.0.0

package/dist/templates/call-audit/client.tsx

@@ -76,9 +76,11 @@ import "@alexkroman1/aai-ui/styles.css";
 // already declares.
 import { formatBytes, formatDuration } from "@alexkroman1/aai/utils";
 import {
+  BulletList,
   createWorkflowApi,
+  Facts,
   Form,
-  page,
+  mountPage,
   SubmitButton,
   UploadProgressBar,
   useDownloadUrl,
@@ -86,7 +88,6 @@ import {
   WorkflowFields,
   WorkflowProgress,
 } from "@alexkroman1/aai-ui";
-import { useState } from "react";
 import type { audit } from "./agent.ts";
 
 /**
@@ -130,33 +131,13 @@ function Stat({ label, value }: { label: string; value: string }) {
   );
 }
 
-/** A list that renders nothing rather than an empty box — see `risks` in the schema. */
-function Findings({ title, items }: { title: string; items: string[] }) {
-  if (items.length === 0) return null;
-  return (
-    <section className="flex flex-col gap-1">
-      <h3 className="text-sm font-medium opacity-70">{title}</h3>
-      <ul className="flex list-disc flex-col gap-1 pl-5">
-        {items.map((item) => (
-          <li key={item}>{item}</li>
-        ))}
-      </ul>
-    </section>
-  );
-}
-
 export function App() {
-  // Did THIS load start the run? A reload cannot have, and that is the only way
-  // the page can tell "auditing what you just uploaded" from "picking up where
-  // you left off" — the hook reports the run, not who asked for it.
-  const [startedHere, setStartedHere] = useState(false);
   // The generic is what makes `run.status === "completed"` narrow to a TYPED
   // `run.output` instead of `unknown`. The reload — both halves of it — is the
   // hook's own doing; see the module doc for why the key it mints is the one
   // this desk wants.
-  const { submitForm, run, pending, upload, pauseUpload, resumeUpload, error } = useWorkflowSubmit<
-    typeof audit
-  >(WORKFLOW, { api });
+  const { submitForm, run, pending, upload, pauseUpload, resumeUpload, error, startedHere } =
+    useWorkflowSubmit<typeof audit>(WORKFLOW, { api });
   const output = run?.status === "completed" ? run.output : undefined;
   // `useDownloadUrl` is the SDK's: the byte route takes the agent's bearer, so the
   // bytes have to be FETCHED and handed to the element as an object URL — and the
@@ -173,14 +154,7 @@ export function App() {
         </p>
       </header>
 
-      <Form
-        onSubmit={(values) => {
-          setStartedHere(true);
-          return submitForm(values);
-        }}
-        error={error}
-        className="flex flex-col gap-4"
-      >
+      <Form onSubmit={(values) => submitForm(values)} error={error} className="flex flex-col gap-4">
         {/* Every control, from the workflow's own input schema. See the module doc. */}
         <WorkflowFields workflow={WORKFLOW} />
         <SubmitButton pending={pending} pendingLabel="Auditing…">
@@ -200,20 +174,26 @@ export function App() {
           for `<WorkflowProgress>` to read. */}
       <UploadProgressBar upload={upload} onPause={pauseUpload} onResume={resumeUpload} />
 
-      {/* What the run itself says, from `report()` in the workflow's steps — which
+      {/* What the run itself says, from `stepReport()` in the workflow's steps — which
           for this template is the ffmpeg narration: what the file was, what it
           measured, how many pauses were found. */}
       <WorkflowProgress runId={run?.runId} api={api} />
 
-      {run?.status === "failed" && <p className="text-red-600">That one failed: {run.error}</p>}
+      {/* `role="alert"`, the same contract `<Form>` gives the submit error: this
+          is the outcome the reader waited minutes for. */}
+      {run?.status === "failed" && (
+        <p role="alert" className="text-red-600">
+          That one failed: {run.error}
+        </p>
+      )}
 
       {output !== undefined && (
         <article className="flex flex-col gap-6">
           <div className="flex flex-col gap-1">
             <h2 className="text-xl">{output.headline}</h2>
-            <p className="text-sm opacity-70">
-              {output.source} · {formatDuration(output.durationMs)} · {output.words} words
-            </p>
+            <Facts
+              items={[output.source, formatDuration(output.durationMs), `${output.words} words`]}
+            />
           </div>
 
           {/* What the pipeline did, which is this template's subject. Rendered rather
@@ -231,8 +211,11 @@ export function App() {
             <Stat label="Run time" value={formatDuration(output.elapsedMs)} />
           </dl>
 
-          <Findings title="Risks" items={output.risks} />
-          <Findings title="Actions" items={output.actions} />
+          {/* Either list can come back empty — see `risks` in the schema — and
+              `<BulletList>` renders nothing at all when it does, heading
+              included, rather than a stray heading over an empty box. */}
+          <BulletList title="Risks" items={output.risks} />
+          <BulletList title="Actions" items={output.actions} />
 
           <section className="flex flex-col gap-2">
             <h3 className="text-sm font-medium opacity-70">
@@ -241,7 +224,9 @@ export function App() {
             </h3>
             {audio.pending && <p className="text-sm opacity-70">Fetching the audio…</p>}
             {audio.error !== undefined && (
-              <p className="text-red-600">Could not load the audio: {audio.error}</p>
+              <p role="alert" className="text-red-600">
+                Could not load the audio: {audio.error}
+              </p>
             )}
             {audio.url !== undefined && (
               <>
@@ -251,7 +236,7 @@ export function App() {
                     track would carry. `spoken-summary` serves a one-cue WebVTT
                     data URL instead — worth reading for how, if a real track is
                     what a page needs. */}
-                <audio controls src={audio.url} className="w-full" />
+                <audio aria-label="Audit read aloud" controls src={audio.url} className="w-full" />
                 {/* `download` works on an object URL because the bytes are already in
                     the tab; it is the href that could not carry the agent's bearer,
                     not the attribute. */}
@@ -273,4 +258,4 @@ export function App() {
   );
 }
 
-page({ name: "Call Audit", component: App });
+mountPage({ name: "Call Audit", component: App });

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

@@ -45,8 +45,8 @@
  * ingest result, once as the plan) and buy nothing.
  */
 
-import type { WorkflowCtx } from "@alexkroman1/aai";
-import { encodeWav, mapConcurrent, readUpload, report } from "@alexkroman1/aai/step";
+import type { WorkflowContext } from "@alexkroman1/aai";
+import { encodeWav, mapConcurrent, stepReadUpload, stepReport } from "@alexkroman1/aai/step";
 import { countWords, formatDuration } from "@alexkroman1/aai/utils";
 // ERASED at build time, so the body can name the schema's own output type without
 // a runtime cycle back through `agent.ts` — the same mechanism `client.tsx` uses
@@ -156,7 +156,7 @@ export type CallAudit = {
  */
 export async function auditFlow(
   input: WorkflowInputOf<typeof audit>,
-  ctx: WorkflowCtx,
+  ctx: WorkflowContext,
 ): Promise<CallAudit> {
   // Both at once: neither needs the other, and issued together they are one round
   // trip instead of two before any audio moves. The ORDER is still a pure function
@@ -259,12 +259,14 @@ export async function transcribeSegment(audioId: string, segment: Segment): Prom
   // ORDER is not guaranteed here and does not need to be — the calls go out
   // together, so their lines interleave by completion, and `segment.index` is what
   // puts the TRANSCRIPT back in order.
-  await report(`Transcribing ${formatDuration(segment.startMs)}–${formatDuration(segment.endMs)}.`);
+  await stepReport(
+    `Transcribing ${formatDuration(segment.startMs)}–${formatDuration(segment.endMs)}.`,
+  );
 
   // `[start, end)`, the same half-open pair `planSegments` produced — the store
   // owns the conversion to HTTP's inclusive range, so there is no `- 1` here to get
   // wrong.
-  const audio = await readUpload(audioId, { start: segment.startByte, end: segment.endByte });
+  const audio = await stepReadUpload(audioId, { start: segment.startByte, end: segment.endByte });
   const text = await transcribeSpan(
     encodeWav(audio.bytes, ANALYSIS_FORMAT),
     `segment-${segment.index}.wav`,

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

@@ -63,7 +63,7 @@
 import { readFile, stat } from "node:fs/promises";
 import { join } from "node:path";
 import { probeMedia, runFfmpeg } from "@alexkroman1/aai/ffmpeg";
-import { pcmDurationMs, report, requireCompleteUpload } from "@alexkroman1/aai/step";
+import { pcmDurationMs, stepReport, stepRequireCompleteUpload } 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";
@@ -132,10 +132,10 @@ export type Ingested = {
 // nothing. Removing them is what took the file under the floor: a directive
 // propping a coverage number up is the least useful statement in the tree.
 export async function ingestRecording(uploadId: string): Promise<Ingested> {
-  // `requireCompleteUpload`, not `uploadInfo`: `size` is the readable PREFIX, so
+  // `stepRequireCompleteUpload`, not `stepUploadInfo`: `size` is the readable PREFIX, so
   // an upload still arriving would be copied short and levelled as the whole call.
-  const stored = await requireCompleteUpload(uploadId);
-  await report(`Reading ${stored.name || uploadId} (${formatBytes(stored.size)}).`);
+  const stored = await stepRequireCompleteUpload(uploadId);
+  await stepReport(`Reading ${stored.name || uploadId} (${formatBytes(stored.size)}).`);
 
   return await withTempDir(
     async (dir) => {
@@ -148,7 +148,7 @@ export async function ingestRecording(uploadId: string): Promise<Ingested> {
       // `STEP_FILE_READ_CONCURRENCY` of them. Passing `size` means "I am judging
       // completeness myself", which is what a body polling a still-arriving
       // upload needs and is the opposite of what happened above: this step has
-      // already called `requireCompleteUpload`, so the file IS whole and the
+      // already called `stepRequireCompleteUpload`, so the file IS whole and the
       // windows may land in any order. Omitting it lets `readUploadToFile`
       // establish that for itself and fan out. The cost is one metadata round
       // trip, against the dozens of window reads it overlaps.
@@ -162,7 +162,7 @@ export async function ingestRecording(uploadId: string): Promise<Ingested> {
         throwFfmpegStepError,
       );
       const codec = probed.audio?.codec ?? "unknown";
-      await report(
+      await stepReport(
         `Levelling ${describeSource(codec, probed.durationSec)} to ${ANALYSIS_FORMAT.sampleRate / 1000} kHz mono.`,
       );
 
@@ -206,7 +206,7 @@ export async function ingestRecording(uploadId: string): Promise<Ingested> {
         type: "application/octet-stream",
       });
 
-      await report(
+      await stepReport(
         `Levelled ${formatDuration(durationMs)} from ${loudness.inputLufs} LUFS, ` +
           `${Math.round(speechFraction(silences, durationMs / 1000) * 100)}% speech across ` +
           `${silences.length} ${plural(silences.length, "pause")}.`,

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/code-interpreter/agent.test.ts

@@ -0,0 +1,103 @@
+/** The def a DEPLOYED agent runs: authored, plus the `system-prompt.md` beside it. */
+import agentDef from "virtual:aai/agent";
+import { AgentConfigSchema, toAgentConfig } from "@alexkroman1/aai/manifest";
+import { describe, expect, test } from "vitest";
+
+/**
+ * What this starter's spec may assert.
+ *
+ * Renaming Coda, giving her a voice, swapping a stage or switching the whole
+ * thing to speech-to-speech are the first edits this template invites — and
+ * `aai build` runs these tests before it bundles, so an assertion that pins the
+ * template's own identity turns the first customization into a build failure in
+ * a file the author never wrote. Every test here asserts a property that
+ * survives those edits, on the RESOLVED config rather than on the def's empty
+ * fields.
+ *
+ * What it may NOT assert is whether `run_code` actually RUNS: the builtin is
+ * sandbox-only, so off-platform it declines rather than evaluating
+ * model-written JavaScript in the host process. That is right, and it leaves
+ * "Coda reached for code, and the code came back with 107823" to
+ * `agent.eval.test.ts`, which supplies an executor of its own. What is reachable
+ * in memory is the pairing the template is built on — the builtin it asks for
+ * and the prompt that commands it — and that is what the last two tests are.
+ */
+describe("code-interpreter template", () => {
+  test("config passes manifest validation", () => {
+    // Same conversion `aai build`/`aai deploy` run.
+    expect(() => toAgentConfig(agentDef)).not.toThrow();
+  });
+
+  test("exports an agent the platform can name", () => {
+    // Not the literal: what has to hold is that there IS a name and that the
+    // conversion carries it through — `AgentName` refuses a blank one, and the
+    // studio lists a deployed agent by exactly this string.
+    expect(agentDef.name).toBeTruthy();
+    expect(toAgentConfig(agentDef).name).toBe(agentDef.name);
+  });
+
+  test("whatever mode it ends up in, there is a model to call the tool with", () => {
+    // A builtin is something a MODEL reaches for, so this template is only
+    // itself while some stage can issue a tool call. Asserted per MODE so it
+    // survives the swaps above: declare `stt`/`llm`/`tts` and the rest still
+    // default to the all-AssemblyAI cascade (which is why the def declares no
+    // provider at all and still runs); declare `s2s` and there is no cascade to
+    // fill, which is the one thing that must never happen by fallthrough.
+    const config = toAgentConfig(agentDef);
+    if (config.mode === "s2s") {
+      expect(config.s2s?.kind).toBeTruthy();
+      expect(config.stt).toBeUndefined();
+      expect(config.tts).toBeUndefined();
+      return;
+    }
+    expect(config.llm?.kind).toBeTruthy();
+    if (config.mode === "pipeline") {
+      expect(config.stt?.kind).toBeTruthy();
+      expect(config.tts?.kind).toBeTruthy();
+    }
+  });
+
+  test("run_code survives into the config a deploy carries", () => {
+    // The template's whole capability, asserted on the CONFIG rather than the
+    // def because that is what a deploy ships. `DEFAULT_BUILTIN_TOOLS` is
+    // EMPTY — a builtin is something an agent asks for, never something it has
+    // to notice and switch off — so a dropped `builtinTools` is not a degraded
+    // Coda, it is an agent whose prompt forbids mental arithmetic and leaves it
+    // nothing else to do. Adding builtins beside it is fine; losing this one is
+    // the regression.
+    expect(toAgentConfig(agentDef).builtinTools ?? []).toContain("run_code");
+  });
+
+  test("every builtin the prompt commands by name is one the agent declares", () => {
+    // The pairing that makes this template work, and the failure it catches is
+    // silent in both directions: a prompt commanding `fetch_json` at an agent
+    // that never declared it produces a model apologizing for a tool it cannot
+    // see, and a builtin renamed in `agent.ts` alone leaves the CRITICAL RULES
+    // addressed to nothing. Neither shows up in a diff of either file.
+    const config = toAgentConfig(agentDef);
+    const declared = config.builtinTools ?? [];
+
+    // Which snake_case tokens in the prose are TOOL NAMES is a question for the
+    // SDK's own schema, not for a list restated here: a catalog copied into a
+    // spec goes stale, and matching every underscored word would redden on a
+    // prompt that names a variable in one of its examples.
+    const isBuiltin = (name: string) =>
+      AgentConfigSchema.safeParse({ ...config, builtinTools: [name] }).success;
+    const commanded = [
+      ...new Set(config.systemPrompt.match(/\b[a-z][a-z0-9]*(?:_[a-z0-9]+)+\b/g) ?? []),
+    ].filter(isBuiltin);
+
+    // Non-vacuity, and it earns its keep twice: a prompt naming no builtin at
+    // all would make the loop below assert nothing, and it is also the state a
+    // template gets into when `system-prompt.md` is not applied — the framework
+    // default names no builtin, so an agent running on it lands here rather
+    // than passing quietly with the CRITICAL RULES nowhere in its context.
+    expect(commanded.length).toBeGreaterThan(0);
+    for (const name of commanded) {
+      expect(declared, `the prompt commands ${name}`).toContain(name);
+    }
+    // The converse is deliberately NOT asserted: declaring a builtin the prompt
+    // never mentions is an ordinary edit, and the model is told about it by its
+    // own tool schema.
+  });
+});

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 () => {