@alexkroman1/aai-cli 13.3.0 → 15.0.0

package/dist/templates/link-digest/client.tsx

@@ -2,7 +2,7 @@
 /**
  * The browser half of a workflow app.
  *
- * Mounted with `page()` rather than `client()`: there is no session to build, so
+ * Mounted with `mountPage()` rather than `mountClient()`: there is no session to build, so
  * there is no socket, no audio graph, and no microphone request. Everything else
  * is the same — the same `client.tsx` filename, React, Tailwind, and the same
  * theme tokens the voice components read.
@@ -49,7 +49,7 @@
  *
  * `useWorkflowSubmit` answers "where has this got to" from the world's own
  * record — pending, running, completed. `<WorkflowProgress>` answers "what is it
- * doing" from what the run wrote itself (`report()` in `workflows/digest.ts`). A
+ * doing" from what the run wrote itself (`stepReport()` in `workflows/digest.ts`). A
  * page with only the first shows "Working…" for the length of the run; a page
  * with only the second cannot tell a finished run from a quiet one. Both are
  * cheap: one stream each, ended by the agent when there is nothing left to say.
@@ -62,9 +62,32 @@
  * what narrows it to the newest line, because on a page this small that is the
  * whole of what a status wants; `transcription-workflow` renders the full log,
  * where a fan-out makes the history worth seeing.
+ *
+ * ## Two things that are only ever true for a MOMENT
+ *
+ * The Copy button and the reply to "File it now" are both a word that appears
+ * and then goes away, and both used to be the sort of thing a page writes with
+ * a `useState` and a bare `setTimeout` — which gets two things wrong that only
+ * show up on the second click (a second flash has its window cut short by the
+ * first one's timer) and on unmount (a `setState` into a torn-down tree). They
+ * are `useCopy` and `useFlash` from `@alexkroman1/aai-ui`.
+ *
+ * Reach for `useCopy` when the moment is a clipboard write — it keys the flash
+ * by the copied TEXT, so on a page with several copy buttons only the one
+ * clicked lights up, and it reports a REFUSED write as `"Failed"` rather than
+ * doing nothing visible (there is no clipboard at all on an insecure origin).
+ * Reach for `useFlash` for any other transient word; here it carries what
+ * `wake()` answered, which is a number and not a failure at 0.
  */
 
-import { page, useWorkflowSubmit, WorkflowProgress } from "@alexkroman1/aai-ui";
+import {
+  BulletList,
+  mountPage,
+  useCopy,
+  useFlash,
+  useWorkflowSubmit,
+  WorkflowProgress,
+} from "@alexkroman1/aai-ui";
 import "@alexkroman1/aai-ui/styles.css";
 // ERASED at build time, so naming the agent's own type costs the browser bundle
 // nothing — and it is what stops this file restating a shape `workflows/
@@ -90,12 +113,22 @@ function pendingNote(startedHere: boolean, found: boolean): string {
   return "Still working on the digest this tab started earlier. Reloading is safe.";
 }
 
+/** The digest as one pasteable block — a headline and its bullets. */
+function asText(headline: string, points: readonly string[]): string {
+  return [headline, ...points.map((point) => `- ${point}`)].join("\n");
+}
+
 export function App() {
   const [url, setUrl] = useState("");
-  // Did THIS load start the run? A reload cannot have, and that is the only way
-  // the page can tell "working on what you just submitted" from "picking up
-  // where you left off" — the hook reports the run, not who asked for it.
-  const [startedHere, setStartedHere] = useState(false);
+  // One copier for the page. It would be one per GROUP of copy buttons on a
+  // bigger page — the flash is shared, so clicking a second row clears the
+  // first row's "Copied", which is what stops two rows both claiming to be on
+  // the clipboard.
+  const copier = useCopy();
+  // `wake()` resolves with how many sleeps it ended, and 0 is an ANSWER (the
+  // run had already moved past its wait) rather than a failure — so the button
+  // says which happened, for a moment, and then goes back to being a button.
+  const woken = useFlash<string>();
   // The generic is what makes `run.status === "completed"` narrow to a TYPED
   // `run.output` instead of `unknown`. `error` is the agent's own sentence for a
   // rejected input, which is better copy than anything this page could write, and
@@ -104,14 +137,14 @@ export function App() {
   // No `key` and no `recover`: this tab's handle on its own runs is minted and
   // remembered by the hook, and read back as it mounts. See the module doc for
   // what a page says when it wants a different one.
-  const { submit, run, pending, error, wake } = useWorkflowSubmit<typeof digest>("digest");
+  const { submit, run, pending, error, wake, startedHere } =
+    useWorkflowSubmit<typeof digest>("digest");
 
   // `submit()` resolves as soon as the run exists — deliberately not when it
   // finishes. That is the whole mechanism: the digest sleeps for a while, and
   // this page is free to be closed in the meantime.
   const onSubmit = (event: React.FormEvent) => {
     event.preventDefault();
-    setStartedHere(true);
     void submit({ url });
   };
 
@@ -125,6 +158,11 @@ export function App() {
           required
           value={url}
           onChange={(e) => setUrl(e.target.value)}
+          // A placeholder is not a name: it disappears the moment anything is
+          // typed, and a screen reader reaches an unlabelled box. The declared
+          // fields in `@alexkroman1/aai-ui` say the same thing — a `label`, or
+          // an `aria-label` where the row has no room for one.
+          aria-label="Article URL"
           // A REAL article, because a placeholder is a suggestion and this one
           // gets typed. `https://example.com/article` 404s, and the bare
           // `example.com` a reader trims it to has no prose on it — so the first
@@ -139,7 +177,13 @@ export function App() {
         </button>
       </form>
 
-      {error !== undefined && <p className="text-red-600">{error}</p>}
+      {/* `<Form>` carries `role="alert"` for the templates that declare their
+          fields; a hand-written form has to say it itself. */}
+      {error !== undefined && (
+        <p role="alert" className="text-red-600">
+          {error}
+        </p>
+      )}
 
       {/* A run that has not settled says so. `pending` is not derivable from the
           snapshot alone — an id the agent never knew leaves `run` undefined,
@@ -161,28 +205,46 @@ export function App() {
       {pending && (
         <button
           type="button"
-          onClick={() => void wake()}
+          onClick={() => {
+            void wake().then((count) =>
+              woken.flash(count > 0 ? "Filing it now" : "Already past its wait"),
+            );
+          }}
           className="self-start rounded-md border px-3 py-1 text-sm"
         >
-          File it now
+          {woken.value ?? "File it now"}
         </button>
       )}
 
-      {run?.status === "failed" && <p className="text-red-600">That one failed: {run.error}</p>}
+      {/* `role="alert"`, like the submit error above: this is the outcome the
+          reader has been waiting for, and it can arrive long after they looked
+          away. */}
+      {run?.status === "failed" && (
+        <p role="alert" className="text-red-600">
+          That one failed: {run.error}
+        </p>
+      )}
 
       {run?.status === "completed" && (
         <article className="flex flex-col gap-3">
           <h2 className="text-xl">{run.output.headline}</h2>
-          <ul className="flex list-disc flex-col gap-1 pl-5">
-            {run.output.points.map((point) => (
-              <li key={point}>{point}</li>
-            ))}
-          </ul>
+          <BulletList items={run.output.points} />
           <p className="text-sm opacity-70">Filed {run.output.filedAt}</p>
+          {/* The whole digest as plain text, which is what somebody pasting it
+              into a note wants. `copier.label` is the button's own text: it
+              reads "Copy" until it is clicked, then "Copied" — or "Failed",
+              which is the case a hand-rolled version silently drops. */}
+          <button
+            type="button"
+            onClick={() => copier.copy(asText(run.output.headline, run.output.points))}
+            className="self-start rounded-md border px-3 py-1 text-sm"
+          >
+            {copier.label(asText(run.output.headline, run.output.points))}
+          </button>
         </article>
       )}
     </main>
   );
 }
 
-page({ name: "Link Digest", component: App });
+mountPage({ name: "Link Digest", component: App });

package/dist/templates/link-digest/workflows/digest.ts

@@ -24,10 +24,10 @@
  * fetched text crosses a queue between them, which is what the cap on it is for.
  */
 
-import type { WorkflowCtx } from "@alexkroman1/aai";
+import type { WorkflowContext } from "@alexkroman1/aai";
 import { htmlToText, pageMetadata } from "@alexkroman1/aai/html";
-import { report, stepInfo } from "@alexkroman1/aai/step";
-import { FatalError, stepFetchOk, stepGenerateJsonClassified } from "@alexkroman1/aai/step-errors";
+import { stepInfo, stepReport } from "@alexkroman1/aai/step";
+import { FatalError, stepFetchOrFail, stepGenerateJsonOrFail } from "@alexkroman1/aai/step-errors";
 import { omitUndefined } from "@alexkroman1/aai/utils";
 import { z } from "zod";
 
@@ -107,7 +107,7 @@ export type Article = {
  * literally the page's render model, and `WorkflowOutputOf<typeof digest>` in
  * `client.tsx` is that type, derived rather than restated.
  */
-export async function digestFlow(input: { url: string }, ctx: WorkflowCtx) {
+export async function digestFlow(input: { url: string }, ctx: WorkflowContext) {
   const article = await ctx.step("fetchArticle", () => fetchArticle(input.url));
   // `maxAttempts: 6` was `summarize.maxRetries = 5` — five retries AFTER the
   // first attempt, so six in all. The retry policy moved from a property on the
@@ -138,7 +138,7 @@ export async function digestFlow(input: { url: string }, ctx: WorkflowCtx) {
  */
 export async function fetchArticle(url: string): Promise<Article> {
   const { hostname } = new URL(url);
-  await report(`Reading ${hostname}…`);
+  await stepReport(`Reading ${hostname}…`);
 
   // `stepFetch`, not `fetch`, and the rule has no exception for a step that
   // makes only one request: the global pins nothing, so it offers h2 in ALPN
@@ -147,12 +147,12 @@ export async function fetchArticle(url: string): Promise<Article> {
   // reset with no HTTP status, which `toStepError` below has nothing to read.
   // It also reports a connection failure with its whole `cause` chain instead
   // of a bare `TypeError: fetch failed`. Redirects are followed by default.
-  // `stepFetchOk` rather than `stepFetch` + an `ok` check: it makes the
+  // `stepFetchOrFail` rather than `stepFetch` + an `ok` check: it makes the
   // retryable/terminal split for us — a 404 or a 403 answers the same way on
   // the fourth attempt, while a rate limit is exactly what retries are for, and
   // its `Retry-After` reaches the engine's schedule instead of the default
   // backoff. It also puts the server's own error text in the message.
-  const response = await stepFetchOk(url, {
+  const response = await stepFetchOrFail(url, {
     // Some sites answer a bare request with a challenge page; asking for HTML
     // at least says what we want. Nothing here defeats a real bot wall, and a
     // template pretending otherwise would be the dishonest version.
@@ -191,19 +191,19 @@ export async function summarize(article: Article): Promise<Digest> {
   // built with `omitUndefined` rather than a conditional spread — the guard is
   // then the value, which is the case that primitive is for.
   const model = lastChance ? FALLBACK_MODEL : undefined;
-  await report(
+  await stepReport(
     lastChance
       ? `Last attempt (${step?.attempt} of ${step?.maxAttempts}): asking for something simpler.`
       : "Pulling out the claims worth keeping.",
   );
 
-  // `stepGenerateJsonClassified` unwraps the fence a model puts around JSON,
+  // `stepGenerateJsonOrFail` unwraps the fence a model puts around JSON,
   // parses it, and validates it against `DigestReply` — and throws PLAINLY when
   // any of those misses, which is the whole retry policy in one distinction: a
   // model that answered with prose may answer correctly on the next attempt,
-  // where a 401 will not. The `Classified` suffix is what makes the 401 half
+  // where a 401 will not. The `OrFail` suffix is what makes the 401 half
   // terminal: it is `stepGenerateJson` with `throwStepError` already applied.
-  const parsed = await stepGenerateJsonClassified(
+  const parsed = await stepGenerateJsonOrFail(
     `Title: ${article.title}\nURL: ${article.url}\n\n${article.text}`,
     {
       schema: DigestReply,
@@ -246,7 +246,7 @@ export async function summarize(article: Article): Promise<Digest> {
  * file(digest))`. Anything at BODY level is the bug, not an exception.
  */
 export async function file(_digest: Digest): Promise<string> {
-  await report("Filing the digest.");
+  await stepReport("Filing the digest.");
   // A real desk would write the digest to its database here. The stub writes
   // nothing, which is what the `_` says — and it is a stub because `ctx.db` is
   // the half of a tool context a step still cannot reach.
@@ -282,8 +282,5 @@ export function extractTitle(html: string): string | undefined {
  * structure are bytes the summary does not read.
  */
 export function extractText(html: string): string {
-  return htmlToText(html, { maxChars: MAX_ARTICLE_CHARS })
-    .replace(/\s+/g, " ")
-    .trim()
-    .slice(0, MAX_ARTICLE_CHARS);
+  return htmlToText(html, { maxChars: MAX_ARTICLE_CHARS }).replace(/\s+/g, " ").trim();
 }

package/dist/templates/math-buddy/agent.test.ts

@@ -0,0 +1,126 @@
+/**
+ * The def a DEPLOYED agent runs: authored, plus the `system-prompt.md` beside
+ * it.
+ *
+ * This template declares no `tools/` at all — every calculation is the
+ * `run_code` builtin's — so the prompt is the only thing discovery adds here,
+ * and it is what half the tests below are about. Importing `./agent.ts`
+ * directly would measure a tutor whose prompt is the framework default, i.e.
+ * an agent that was never told to compute in code.
+ */
+import agentDef from "virtual:aai/agent";
+import { toAgentConfig } from "@alexkroman1/aai/manifest";
+import { describe, expect, test } from "vitest";
+
+/**
+ * What a starter's spec may assert.
+ *
+ * `aai build` runs these tests before it bundles, so an assertion pinning this
+ * tutor's own identity — its literal name, the wording of its greeting, the
+ * model id it happens to run today — turns the first customization into a build
+ * failure in a file the author never wrote. Every test here therefore asserts a
+ * property that survives a rename, a voice, a reworded prompt and a model swap,
+ * on the RESOLVED config rather than on the def's empty fields.
+ *
+ * `run_code` is the one thing named literally, and deliberately: taking it away
+ * is not a customization of Math Buddy but a deletion of its subject — the
+ * prompt is nothing but recipes for it — and the tutor left behind does
+ * arithmetic from memory, which reads exactly like a correct answer until it is
+ * wrong.
+ *
+ * What is NOT here is anything about the code the tutor writes or the answer it
+ * comes back with: that needs a model and a sandbox, so it belongs to
+ * `agent.eval.test.ts`, which supplies both. This tier's question is the one
+ * that comes first — was the tutor handed anything to run at all.
+ */
+describe("math-buddy template", () => {
+  test("config passes manifest validation", () => {
+    // Same conversion `aai build`/`aai deploy` run — and the only thing that
+    // says this template's declared LLM descriptor is well formed before a
+    // live session tries to open one from it.
+    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("run_code is declared, and the prompt the deploy carries asks for it", () => {
+    const config = toAgentConfig(agentDef);
+    // Two halves, each of which fails silently and produces a plausible tutor.
+    // Without the declaration the model has nothing to run, so it computes in
+    // its head and says the answer with the same confidence either way. Without
+    // the prompt reaching the CONFIG — the "I edited system-prompt.md and
+    // nothing changed" failure `withSystemPrompt` exists to catch, since the
+    // file is discovered by the build rather than imported by `agent.ts` — the
+    // recipes are gone and what deploys is a general assistant that happens to
+    // have a sandbox attached. The framework default says nothing about
+    // `run_code`, which is what makes the second assertion a real check on
+    // discovery rather than a restatement of the first.
+    expect(config.builtinTools).toContain("run_code");
+    expect(config.systemPrompt).toContain("run_code");
+  });
+
+  test("whichever model this tutor runs on, the conversion carries its tuning", () => {
+    const config = toAgentConfig(agentDef);
+    if (config.mode !== "pipeline") {
+      // Switched the def to `s2s`? Then one model listens and talks, and there
+      // is no separate LLM stage left for anything to be carried on.
+      expect(config.mode).toBe("s2s");
+      expect(config.llm).toBeUndefined();
+      return;
+    }
+    if (agentDef.llm === undefined) {
+      // Dropped the declaration to take the default cascade: it still resolves
+      // to a NAMED model, because the gateway refuses an unknown id with a 400
+      // at the first session — "no model" is not a state a deploy may reach.
+      expect(config.llm?.options.model).toBeTruthy();
+      return;
+    }
+    // A model choice is the only reason this tutor declares a stage at all —
+    // a quick, cheap one, since `run_code` does the arithmetic and what is left
+    // is turn-taking speed. So the descriptor is checked whole rather than by
+    // `kind`: one that arrived with its options dropped would deploy the
+    // gateway's default model instead, quietly slower, with nothing on the line
+    // saying so. Read off the def rather than pinned, because swapping the id
+    // is the first tuning an author of this template tries.
+    expect(config.llm?.kind).toBe(agentDef.llm.kind);
+    expect(config.llm?.options).toEqual(agentDef.llm.options);
+    expect(config.llm?.options.model).toBeTruthy();
+  });
+
+  test("every stage its mode needs is filled, declared or defaulted", () => {
+    // This template's other half: it declares the LLM and nothing else, so STT
+    // and TTS are injected at parse time (see `defaultProviders`) and the tutor
+    // can still hear and speak. Asserted per MODE so it survives a swap —
+    // declare `stt`/`tts` and the rest still default; 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.mode).toBe("pipeline");
+    for (const stage of ["stt", "llm", "tts"] as const) {
+      expect(config[stage]?.kind, stage).toBe(agentDef[stage]?.kind ?? "assemblyai");
+    }
+  });
+
+  test("the caller is told what to ask, and the greeting survives the conversion", () => {
+    // A voice agent has no buttons, so the opener is the only place a caller
+    // learns that this one wants arithmetic, conversions and dice rather than
+    // conversation. It rides to the browser in `/client-config` beside `name`,
+    // so what has to hold is that there is one and the conversion carries it:
+    // a greeting lost at that boundary is replaced by the framework's generic
+    // opener, which invites the caller to ask for anything at all.
+    expect(agentDef.greeting).toBeTruthy();
+    expect(toAgentConfig(agentDef).greeting).toBe(agentDef.greeting);
+  });
+});

package/dist/templates/night-owl/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 the eval would drive an agent with no `recommend` at all, which is the one
  * failure a green eval must never be able to hide.
  *

package/dist/templates/night-owl/client.tsx

@@ -14,7 +14,13 @@ import "@alexkroman1/aai-ui/styles.css";
  * reconnect is nagging. `useToolCallStart` and `useEvent` are for exactly this —
  * they fire once, carry no history, and drive throwaway `useState`.
  */
-import { Button, client, useAgentState, useEvent, useToolCallStart } from "@alexkroman1/aai-ui";
+import {
+  Button,
+  mountClient,
+  useAgentState,
+  useEvent,
+  useToolCallStart,
+} from "@alexkroman1/aai-ui";
 import { useEffect, useState } from "react";
 import { MOODS, nightProjection } from "./shared.ts";
 
@@ -111,7 +117,7 @@ function RecSidebar() {
   );
 }
 
-client({
+mountClient({
   name: "Night Owl",
   icon: "\u{1F989}",
   subtitle: "A cozy companion for the small hours",

package/dist/templates/personal-finance/agent.test.ts

@@ -0,0 +1,127 @@
+/** The def a DEPLOYED agent runs: authored, plus what `system-prompt.md` says. */
+import agentDef from "virtual:aai/agent";
+import { AgentConfigSchema, toAgentConfig } from "@alexkroman1/aai/manifest";
+import { describe, expect, test } from "vitest";
+
+/**
+ * What a starter's spec may assert.
+ *
+ * `aai init` scaffolds this template verbatim, and `aai build` runs these tests
+ * before it bundles — so an assertion pinning Penny's own identity (her literal
+ * name, her voice, her model, the wording of a house rule) turns a user's first
+ * customization into a build failure in a file they never wrote. Every test
+ * here therefore asserts a property that survives those edits, on the RESOLVED
+ * config rather than on the def's empty fields.
+ *
+ * What is deliberately NOT here: whether Penny actually reaches for `run_code`
+ * instead of dividing in her head, whether she looks a rate up rather than
+ * quoting a remembered one, and whether she keeps the not-financial-advice
+ * caveat. Those are claims about a live model and belong to
+ * `agent.eval.test.ts`, which drives them against one. This tier asserts the
+ * WIRING those runs depend on — a template whose builtins never reached the
+ * config fails an eval as a behaviour problem, in a report nobody reads as
+ * "the tool was not there".
+ */
+describe("personal-finance template", () => {
+  test("config passes manifest validation", () => {
+    // Same conversion `aai build`/`aai deploy` run. It is also what checks the
+    // two builtin NAMES against the SDK's own enum, so a typo in
+    // `builtinTools` fails here rather than shipping an agent whose prompt
+    // commands a tool the platform never resolved.
+    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 the
+    // conversion carries it through — the studio lists a deployed agent by
+    // exactly this string, and renaming her is the first edit this template
+    // invites.
+    expect(agentDef.name).toBeTruthy();
+    expect(toAgentConfig(agentDef).name).toBe(agentDef.name);
+  });
+
+  test("every stage its mode needs is filled, declared or defaulted", () => {
+    // This template declares no provider at all — it is a prompt and two
+    // builtins — so the default all-AssemblyAI cascade is what makes it run
+    // the moment it is deployed. Asserted per MODE so it stays true after a
+    // swap: declare `stt`/`llm`/`tts` and the rest still default; 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();
+    } else if (config.mode === "text") {
+      expect(config.llm?.kind).toBeTruthy();
+    } else {
+      expect(config.mode).toBe("pipeline");
+      expect(config.stt?.kind).toBeTruthy();
+      expect(config.llm?.kind).toBeTruthy();
+      expect(config.tts?.kind).toBeTruthy();
+    }
+  });
+
+  test("both builtins survive into the config a deploy carries", () => {
+    const builtins = toAgentConfig(agentDef).builtinTools ?? [];
+
+    // `run_code` is the arithmetic rule's only mechanism. The prompt forbids
+    // Penny working ANY figure out in her head — a tip, a split, a payment, a
+    // projection — so without the builtin the rule has nothing to point at and
+    // degrades into a model inventing numbers the caller then spends money on.
+    expect(builtins).toContain("run_code");
+
+    // `fetch_json` is the only route to a number that MOVES. A rate or a coin
+    // price the model remembers is months stale and carries no source, and it
+    // arrives in exactly the confident tone a fetched one would — which is why
+    // a finance starter that cannot make a request is worse than one that
+    // declines to answer.
+    expect(builtins).toContain("fetch_json");
+
+    // Asserted on the CONFIG rather than the def because that is what a deploy
+    // ships, and because `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 entry is not a quieter Penny, it is the same Penny with
+    // no way to be right. Adding builtins beside these two is an ordinary edit;
+    // losing one is the regression.
+  });
+
+  test("every builtin the prompt tells Penny to use is one she declares", () => {
+    // The pairing this template is made of: the prose holds the endpoints and
+    // the formulas, each list headed by the tool that consumes it, and
+    // `agent.ts` holds the array that makes those tools exist. The failure 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 dropped from `agent.ts` alone leaves the endpoint list
+    // addressed to nothing — and 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 rather than a catalog restated here: this prompt also
+    // names `vs_currencies`, `include_24hr_change`, `per_person` and
+    // `annual_rate`, so matching every underscored word would redden on a
+    // formula, and a copied list of builtins goes stale the first time the SDK
+    // adds one.
+    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 leave the loop below asserting nothing, and it is also the state
+    // this template lands in when `system-prompt.md` is not applied — the
+    // framework default names no builtin, so "I edited the prompt and nothing
+    // changed" fails here instead of passing quietly with Penny's rules nowhere
+    // in her context.
+    expect(commanded.length).toBeGreaterThan(0);
+    for (const name of commanded) {
+      expect(declared, `the prompt tells Penny to use ${name}`).toContain(name);
+    }
+
+    // The converse is deliberately NOT asserted: declaring a builtin the prompt
+    // never mentions is an ordinary edit, and the model learns about it from its
+    // own tool schema rather than from the prose.
+  });
+});

package/dist/templates/pipeline-simple/agent.test.ts

@@ -1,6 +1,6 @@
 import { agent } from "@alexkroman1/aai";
 import { toAgentConfig } from "@alexkroman1/aai/manifest";
-import { assemblyAIS2s, openaiS2s } from "@alexkroman1/aai/s2s";
+import { assemblyAIS2s, openAIS2s } from "@alexkroman1/aai/s2s";
 import { assemblyAIStt, deepgramStt, elevenLabsStt, sonioxStt } from "@alexkroman1/aai/stt";
 import { ASSEMBLYAI_TTS_VOICES, assemblyAITts, cartesiaTts, rimeTts } from "@alexkroman1/aai/tts";
 import { describe, expect, test } from "vitest";
@@ -99,7 +99,7 @@ describe("swapping any other stage", () => {
   test("S2S: an explicit opt-in, and it REPLACES the pipeline rather than joining it", () => {
     for (const [s2s, kind] of [
       [assemblyAIS2s(), "assemblyai"],
-      [openaiS2s({ voice: "alloy" }), "openai-realtime"],
+      [openAIS2s({ voice: "alloy" }), "openai-realtime"],
     ] as const) {
       const config = toAgentConfig(agent({ name: "Line", s2s }));
       expect(config.s2s?.kind).toBe(kind);

package/dist/templates/pizza-ordering/client.tsx

@@ -1,6 +1,7 @@
+import { formatMoney } from "@alexkroman1/aai/utils";
 import "@alexkroman1/aai-ui/styles.css";
-import { client, useAgentState } from "@alexkroman1/aai-ui";
-import { formatPrice, orderProjection, pizzaPrice } from "./shared.ts";
+import { mountClient, useAgentState } from "@alexkroman1/aai-ui";
+import { orderProjection, pizzaPrice } from "./shared.ts";
 
 function PizzaIcon({ size }: { size: string }) {
   const dim = size === "small" ? 36 : size === "large" ? 52 : 44;
@@ -67,7 +68,7 @@ function OrderSidebar() {
             </p>
           </div>
           <p className="text-sm font-bold whitespace-nowrap text-aai-primary">
-            {formatPrice(pizzaPrice(p))}
+            {formatMoney(pizzaPrice(p))}
           </p>
         </div>
       ))}
@@ -79,7 +80,7 @@ function OrderSidebar() {
   );
 }
 
-client({
+mountClient({
   name: "Pizza Palace",
   sidebar: OrderSidebar,
   theme: {

package/dist/templates/pizza-ordering/shared.ts

@@ -1,4 +1,5 @@
 import { type DeepReadonly, sessionSlot } from "@alexkroman1/aai";
+import { formatMoney } from "@alexkroman1/aai/utils";
 
 export const SIZES = ["small", "medium", "large"] as const;
 export const CRUSTS = ["thin", "regular", "thick", "stuffed"] as const;
@@ -37,19 +38,13 @@ export function calculateTotal(pizzas: readonly ReadonlyPizza[]): number {
   return pizzas.reduce((total, pizza) => total + pizzaPrice(pizza), 0);
 }
 
-/** The one money format. Tool results, the projection, and the sidebar all
- *  show prices through this, so they can never disagree on rounding. */
-export function formatPrice(amount: number): string {
-  return `$${amount.toFixed(2)}`;
-}
-
 /**
  * The menu as prompt prose, generated from `MENU` so the agent can never
  * quote a price the pricing code doesn't charge.
  */
 export function menuText(): string {
   const price = (amount: number, upcharge = false) =>
-    amount === 0 ? "free" : `${upcharge ? "+" : ""}${formatPrice(amount)}`;
+    amount === 0 ? "free" : `${upcharge ? "+" : ""}${formatMoney(amount)}`;
   const list = (items: Record<string, number>, upcharge = false) =>
     Object.entries(items)
       .map(([name, amount]) => `${name.replaceAll("_", " ")} (${price(amount, upcharge)})`)
@@ -169,7 +164,7 @@ export function orderView(order: FrozenOrderState): OrderView {
   const placed = order.placed;
   return {
     pizzas: order.pizzas,
-    total: placed?.total ?? formatPrice(calculateTotal(order.pizzas)),
+    total: placed?.total ?? formatMoney(calculateTotal(order.pizzas)),
     orderPlaced: Boolean(placed),
     ...(placed
       ? { orderNumber: placed.orderNumber, estimatedMinutes: placed.estimatedMinutes }