@alexkroman1/aai-cli 13.2.0 → 14.0.0

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.
  *

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

@@ -57,10 +57,14 @@ describe("health-assistant template", () => {
   test("both tools are discovered from tools/", () => {
     // `agent()` takes no `tools` field: a file in `tools/` IS the tool. A
     // template whose tools are never resolved ships a model with none.
-    expect(Object.keys(agentDef.tools ?? {}).sort()).toEqual([
-      "check_drug_interaction",
-      "medication_lookup",
-    ]);
+    // `arrayContaining` rather than an exact list: a tool you add is the edit
+    // this template invites, and it must not redden a test you did not write.
+    // Losing one of these two still fails, which is the regression worth
+    // catching — discovery silently finding nothing looks exactly like a
+    // template with no tools.
+    expect(Object.keys(agentDef.tools ?? {})).toEqual(
+      expect.arrayContaining(["check_drug_interaction", "medication_lookup"]),
+    );
   });
 });
 

package/dist/templates/infocom-adventure/client.tsx

@@ -1,10 +1,11 @@
 import "@alexkroman1/aai-ui/styles.css";
-import type { AgentState, Session } from "@alexkroman1/aai-ui";
+import type { AgentState } from "@alexkroman1/aai-ui";
 import {
   AutoScroll,
-  client,
+  mountClient,
   useConversation,
-  useSession,
+  useSessionActions,
+  useSessionError,
   useSessionSelector,
   useTheme,
 } from "@alexkroman1/aai-ui";
@@ -98,7 +99,7 @@ function Transcript() {
   // The one theme read left in this file, and the case `useTheme()` is still
   // for: `scrollbar-color` takes TWO values and has no utility class, so it has
   // to be a style — and reading it off the theme beats re-pinning the two hex
-  // codes the `client({ theme })` block below already declares.
+  // codes the `mountClient({ theme })` block below already declares.
   const theme = useTheme();
 
   return (
@@ -146,8 +147,16 @@ function Transcript() {
           {transcript.text}
         </div>
       )}
+      {/* Same contract as the shipped `MessageList`'s indicator: the blinking
+          block is the only sign the parser is working, and to a screen reader it
+          is one unpronounceable glyph. */}
       {thinking && (
-        <div className="animate-pulse" style={{ color: GREEN_DIM }}>
+        <div
+          role="status"
+          aria-label="The parser is thinking"
+          className="animate-pulse"
+          style={{ color: GREEN_DIM }}
+        >
           &#9612;
         </div>
       )}
@@ -155,12 +164,18 @@ function Transcript() {
   );
 }
 
+/** Module scope, so the selector has a STABLE identity: an inline arrow makes
+ *  `useSyncExternalStoreWithSelector` rebuild its selection memo every render,
+ *  and this runs on every snapshot push — each STT partial and streaming
+ *  delta. Counting with `reduce` rather than `filter().length` for the same
+ *  reason: the array copy is thrown away, and it grows for the whole adventure. */
+const userTurns = (snapshot: { messages: { role: string }[] }): number =>
+  snapshot.messages.reduce((n, message) => (message.role === "user" ? n + 1 : n), 0);
+
 /** The turn counter — a NUMBER out of the selector, so a new message array with
  *  the same user-message count re-renders nothing. */
 function TurnCount() {
-  const turns = useSessionSelector(
-    (snapshot) => snapshot.messages.filter((message) => message.role === "user").length,
-  );
+  const turns = useSessionSelector(userTurns);
   return <span>Turns: {turns}</span>;
 }
 
@@ -207,7 +222,7 @@ function StatusDot() {
  * never told an unannounced one appeared.
  */
 function ErrorBanner() {
-  const error = useSessionSelector((snapshot) => snapshot.error);
+  const error = useSessionError();
   if (!error) return null;
   return (
     <div
@@ -215,33 +230,22 @@ function ErrorBanner() {
       className="px-5 py-2 text-xs"
       style={{ background: "#3a0000", color: "#ff4141" }}
     >
-      ERROR: {error.message}
+      ERROR: {error.message} ({error.code})
     </div>
   );
 }
 
-/**
- * Start a fresh conversation without leaving the game screen.
+/*
+ * Pause/resume, new game and hang-up.
  *
- * 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 game's world would come back with the next tool call. `end()` drops the
- * resume identity, so the redial is a brand-new session (fresh world, opening
- * scene included), and `start()` puts the player straight into it rather than
- * back at the title screen.
+ * `useSessionActions()` is the narrow way `<Controls>` reaches the methods, and
+ * it is published now — so this row takes the three it presses and one
+ * selector for the flag it reads, instead of a whole-snapshot `useSession()`
+ * that re-rendered the footer on every partial transcript.
  */
-function newConversation(session: Session): void {
-  session.end();
-  session.start();
-}
-
-/** Pause/resume, new game and hang-up. The only place a whole-session
- *  subscription is still needed: the ACTIONS live on `useSession()`, and
- *  `useSessionCore` — the narrow way `<Controls>` reaches them — is not on the
- *  public surface. */
 function Footer() {
-  const session = useSession();
+  const { toggle, restart, end } = useSessionActions();
+  const running = useSessionSelector((snapshot) => snapshot.running);
   return (
     <div
       className="flex items-center justify-between px-5 py-2 shrink-0 gap-3"
@@ -253,9 +257,9 @@ function Footer() {
           type="button"
           className="px-4 py-1 bg-transparent cursor-pointer uppercase tracking-wider font-mono text-[11px]"
           style={{ color: GREEN_DIM, border: `1px solid ${GREEN_DARK}` }}
-          onClick={session.toggle}
+          onClick={toggle}
         >
-          {session.running ? "[P]ause" : "[R]esume"}
+          {running ? "[P]ause" : "[R]esume"}
         </button>
         {/* The one-click new conversation the default shell's `<Controls>`
             gives every other template — a custom `component:` renders no
@@ -266,7 +270,7 @@ function Footer() {
           type="button"
           className="px-4 py-1 bg-transparent cursor-pointer uppercase tracking-wider font-mono text-[11px]"
           style={{ color: GREEN_DIM, border: `1px solid ${GREEN_DARK}` }}
-          onClick={() => newConversation(session)}
+          onClick={restart}
         >
           [N]ew Game
         </button>
@@ -276,7 +280,7 @@ function Footer() {
           type="button"
           className="px-4 py-1 bg-transparent cursor-pointer uppercase tracking-wider font-mono text-[11px]"
           style={{ color: GREEN_DIM, border: `1px solid ${GREEN_DARK}` }}
-          onClick={() => session.end()}
+          onClick={() => end()}
         >
           [Q]uit
         </button>
@@ -315,7 +319,7 @@ function Crt({ children }: { children: ReactNode }) {
 }
 
 function TitleScreen() {
-  const session = useSession();
+  const { start } = useSessionActions();
   return (
     <Crt>
       <div
@@ -345,7 +349,7 @@ function TitleScreen() {
             border: `1px solid ${GREEN}`,
             animation: "ic-pulse 2s ease-in-out infinite",
           }}
-          onClick={session.start}
+          onClick={start}
         >
           Begin Adventure
         </button>
@@ -381,7 +385,7 @@ function InfocomAdventure() {
   );
 }
 
-client({
+mountClient({
   component: InfocomAdventure,
   theme: {
     bg: CRT_BG,

package/dist/templates/link-digest/agent.test.ts

@@ -26,7 +26,7 @@
  */
 
 import {
-  createWorkflowCtx,
+  createWorkflowContext,
   schemaInputIssues,
   stubGatewayRoute,
   stubStepInfo,
@@ -51,7 +51,13 @@ describe("the agent declares itself a workflow app", () => {
   test("under the name the page starts a run by", () => {
     // `api.start("digest", …)` in client.tsx names this key. Nothing else
     // records it, so a rename here is a 400 there rather than a compile error.
-    expect(Object.keys(agentDef.workflows ?? {})).toEqual(["digest"]);
+    // `toContain` rather than an exact key list: adding a second workflow is an
+    // invited edit and must not redden a test the author did not write. The
+    // NAME is still pinned, deliberately — the page starts a run by this
+    // string, so renaming the key is a runtime 400 rather than a compile
+    // error, and this pin is the only thing that says so. Rename it here and
+    // in `client.tsx` together.
+    expect(Object.keys(agentDef.workflows ?? {})).toContain("digest");
     expect(agentDef.workflows?.digest).toBe(digest);
   });
 });
@@ -164,7 +170,7 @@ describe("fetchArticle", () => {
   });
 
   test("fails FATALLY on a 404 and plainly on a 503", async () => {
-    // `stepFetchOk` builds the message, so it is the SDK's one spelling for a
+    // `stepFetchOrFail` builds the message, so it is the SDK's one spelling for a
     // bad response — the REQUEST, the status, and a preview of any body.
     stubPage("", 404);
     await expect(fetchArticle("https://example.com/gone")).rejects.toThrow(
@@ -258,7 +264,7 @@ describe("summarize", () => {
     // which is the only place the policy is observable at all. `runSteps: false`
     // because the subject is the declared policy rather than the work: the steps
     // would otherwise need a page and a model.
-    const ctx = createWorkflowCtx({ runSteps: false });
+    const ctx = createWorkflowContext({ runSteps: false });
     await digestFlow({ url: "https://example.com/a" }, ctx);
 
     const summarizeStep = ctx.steps.find((step) => step.name === "summarize");

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

@@ -13,8 +13,8 @@
  * the entire product, and the declaration says so:
  *
  * - `workflowApp()` is `agent({ …, page: "static" })` with the discriminant
- *   already set. The declaration is not decoration: `createServer` declines
- *   `/websocket` with a reason (so a page mounted with `client()` by mistake
+ *   already set. The declaration is not decoration: `createRuntimeServer` declines
+ *   `/websocket` with a reason (so a page mounted with `mountClient()` by mistake
  *   fails the same way in `aai dev` and in production rather than only after a
  *   deploy) and telephony defaults off.
  * - There is no `stt`/`llm`/`tts`, no `tools` and no `systemPrompt` — and they

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.
@@ -19,16 +19,18 @@
  * page used to promise "the run continues without it" and then had no way back
  * to the run it was promising about.
  *
- * `key` is the handle that survives, and `recover` is what reads it back. Two
- * lines of wiring, one decision:
+ * A correlation KEY is the handle that survives, and this page writes none of
+ * it: `useWorkflowSubmit` mints an opaque per-page key into `sessionStorage`,
+ * records every run under it, and asks `find("digest", key)` as it mounts —
+ * so a reload lands back on the same headline, the same progress log and the
+ * same buttons. Six templates used to write those two options each, which is
+ * what made it the default.
  *
- * - **The key is OPAQUE and lives in `sessionStorage`.** It names nothing about
- *   the person or the link — `useRunKey()` is the SDK's, and its module argues
- *   what that rules out (a key derived from the URL being digested, a `?key=`
- *   parameter) and why. Six templates had written those twenty lines each.
- * - **`recover: true`** makes the hook ask `find("digest", key)` as it mounts
- *   and follow whatever run comes back, so a reload lands back on the same
- *   headline, the same progress log and the same buttons.
+ * What the page can still say is which key: `useRunKey({ storage: "local" })`
+ * for a run meant to outlive the tab (`podcast-digest`), an ACCOUNT's own id
+ * for an app with logins, `recover: false` for a form that must always open
+ * empty. `use-run-key.ts` argues what a key may not be — derived from the URL
+ * being digested, or carried in a `?key=` parameter.
  *
  * Deployed, this needs the correlation-key index, which is a `DATABASE_URL`
  * away — `agent.ts` says what happens without one (the runs are still durable;
@@ -47,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.
@@ -55,14 +57,14 @@
  * Progress also REPLAYS — chunks are retained with the run — so a reload mid-run
  * catches up rather than starting from whatever arrives next. That only pays off
  * because the reload can name its run again: `<WorkflowProgress runId>` is handed
- * `run?.runId`, so before `recover` a refresh replayed a log for nobody.
+ * `run?.runId`, so before the recovery a refresh replayed a log for nobody.
  * `lines={1}` is
  * 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.
  */
 
-import { page, useRunKey, useWorkflowSubmit, WorkflowProgress } from "@alexkroman1/aai-ui";
+import { BulletList, mountPage, 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,32 +92,22 @@ function pendingNote(startedHere: boolean, found: boolean): string {
 
 export function App() {
   const [url, setUrl] = useState("");
-  // This tab's handle on its own runs — minted once and remembered, which is
-  // what a later load produces to find the run again.
-  const key = useRunKey();
-  // 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);
   // 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
   // `wake` is bound to whatever run the hook is following — the whole reason this
   // page no longer holds a `createWorkflowApi()` of its own.
-  const { submit, run, pending, error, wake } = useWorkflowSubmit<typeof digest>("digest", {
-    // Recorded with the run, and read back on the next load. Neither half is
-    // useful alone: without the key there is nothing to find the run by, and
-    // without `recover` the key is only ever written.
-    key,
-    recover: true,
-  });
+  // 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, 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 });
   };
 
@@ -129,6 +121,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
@@ -143,7 +140,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,
@@ -172,16 +175,19 @@ export function App() {
         </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>
         </article>
       )}
@@ -189,4 +195,4 @@ export function App() {
   );
 }
 
-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/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/agent.test.ts

@@ -32,7 +32,12 @@ describe("night-owl template", () => {
   });
 
   test("recommend is discovered from tools/", () => {
-    expect(Object.keys(agentDef.tools ?? {})).toEqual(["recommend"]);
+    // `toContain` rather than an exact list: a file in `tools/` IS a tool, so
+    // adding one is the edit this template most invites, and an exact list
+    // would make that edit fail a test the author never wrote. What has to hold
+    // is that discovery ran at all — a template whose `tools/` is never
+    // resolved ships a model with no tools.
+    expect(Object.keys(agentDef.tools ?? {})).toContain("recommend");
   });
 
   test("the projection an untouched session pushes is an empty log", () => {

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/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";
@@ -13,25 +13,42 @@ describe("pipeline-simple template", () => {
     expect(() => toAgentConfig(agentDef)).not.toThrow();
   });
 
-  test("declares only the LLM stage on the def", () => {
-    // The template's point: swap one stage, leave the rest unset. The
-    // unset stages are filled with the AssemblyAI defaults at parse time.
-    expect(agentDef.name).toBe("pipeline-simple");
-    expect(agentDef.llm).toBeDefined();
-    expect(agentDef.stt).toBeUndefined();
-    expect(agentDef.tts).toBeUndefined();
+  test("exports an agent the platform can name", () => {
+    // Not the literal. `aai init <project>` scaffolds this file verbatim, so a
+    // pinned name is a test about the TEMPLATE inside somebody else's project —
+    // and renaming the agent is the first thing they will do. What has to hold
+    // is that there is a name and the conversion carries it through.
+    expect(agentDef.name).toBeTruthy();
+    expect(toAgentConfig(agentDef).name).toBe(agentDef.name);
   });
 
-  test("LLM descriptor is Anthropic", () => {
-    expect(agentDef.llm?.kind).toBe("anthropic");
+  test("declares at least one stage itself, which is what makes it a pipeline", () => {
+    // WHICH stage is deliberately not asserted: `agent.ts` invites you to move
+    // the declaration ("Declare only the stage you want elsewhere"), so naming
+    // one here would redden on the edit the comment above it asks for.
+    const declared = (["stt", "llm", "tts"] as const).filter(
+      (stage) => agentDef[stage] !== undefined,
+    );
+    expect(declared.length).toBeGreaterThan(0);
   });
 
-  test("unset stages fill to AssemblyAI in the deployable config", () => {
+  test("a stage you declare survives, and every stage you leave unset defaults", () => {
+    // The template's whole subject, stated so it survives a swap: the config a
+    // deploy carries agrees with the def wherever the def has an opinion, and
+    // fills the AssemblyAI default wherever it does not.
     const config = toAgentConfig(agentDef);
-    expect(config.mode).toBe("pipeline");
-    expect(config.stt?.kind).toBe("assemblyai");
-    expect(config.tts?.kind).toBe("assemblyai");
-    expect(config.llm?.kind).toBe("anthropic");
+    if (config.mode !== "pipeline") {
+      // Switched the def to `s2s`? Then there is no cascade to fill — S2S
+      // REPLACES the pipeline rather than joining it, which the last describe
+      // below is the worked example for.
+      expect(config.mode).toBe("s2s");
+      expect(config.stt).toBeUndefined();
+      expect(config.tts).toBeUndefined();
+      return;
+    }
+    for (const stage of ["stt", "llm", "tts"] as const) {
+      expect(config[stage]?.kind, stage).toBe(agentDef[stage]?.kind ?? "assemblyai");
+    }
   });
 });
 
@@ -82,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);