@alexkroman1/aai-cli 13.1.0 → 13.3.0

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

@@ -34,7 +34,12 @@ import type { SessionEvent } from "@alexkroman1/aai/protocol";
 // What no eval here can see: anything below the audio boundary. Whether a
 // dispatcher reading a callsign in bursts lands as one turn is a property of
 // endpointing, and these fake speech stages remove it.
-import { type EvalSession, type EvalTurn, lastStateIn } from "@alexkroman1/aai-runtime/eval";
+import {
+  type EvalSession,
+  lastStateIn,
+  toolNames,
+  turnCalling,
+} from "@alexkroman1/aai-runtime/eval";
 import { describeEval } from "@alexkroman1/aai-runtime/eval/vitest";
 import { expect } from "vitest";
 import { z } from "zod";
@@ -100,20 +105,6 @@ const boardEntry = (events: readonly SessionEvent[], id: string) =>
 const refusalAt = (state: string) =>
   new RegExp(`Not available yet: this conversation is at [\\\\"]*${state}`);
 
-/**
- * Drive a whole shift, one dispatcher line at a time, and hand back every turn.
- *
- * The cases below assert about the turn a MECHANISM fired in rather than about
- * turn number two: how many turns a desk takes to get there is the model's
- * business and it varies, and a case pinned to a turn index is a flake with a
- * misleading name.
- */
-async function sayAll(session: EvalSession, lines: readonly string[]): Promise<EvalTurn[]> {
-  const turns: EvalTurn[] = [];
-  for (const line of lines) turns.push(await session.say(line));
-  return turns;
-}
-
 /** Every call to `tool` across the whole shift. */
 const callsTo = (session: EvalSession, tool: string) =>
   session.toolCalls().filter((c) => c.name === tool);
@@ -200,12 +191,15 @@ describeEval(dispatchAgent, (test) => {
   test(
     "rolls units on a logged incident and follows them to monitoring",
     async ({ session }) => {
-      const turns = await sayAll(session, [THE_CALL, "Dispatch the recommended units now."]);
+      const turns = await session.sayAll([THE_CALL, "Dispatch the recommended units now."]);
 
-      const dispatching = turns.find((t) =>
-        t.toolCalls.some((c) => c.name === "resources_dispatch"),
-      );
-      const rolled = dispatching?.toolCalls.find((c) => c.name === "resources_dispatch");
+      // The turn the dispatch fired in, whichever one that turned out to be:
+      // how many turns a desk spends getting there is the model's business, so
+      // a case pinned to turn two is a flake with a misleading name. A shift
+      // that never dispatched at all fails HERE, with every turn's tool list in
+      // the message, rather than as an `undefined` three assertions later.
+      const dispatching = turnCalling(turns, "resources_dispatch");
+      const rolled = dispatching.toolCalls.find((c) => c.name === "resources_dispatch");
       // Units really assigned — `dispatched` is empty when every requested
       // callsign was busy, which is the case the fourth test owns.
       expect(rolled?.result).toMatch(/"dispatched":\[\{/);
@@ -215,7 +209,7 @@ describeEval(dispatchAgent, (test) => {
       // The board agrees: the incident is dispatched, not merely triaged.
       expect(boardEntry(session.events(), FIRST_INCIDENT)?.status).toBe("dispatched");
       // And the order is the one the desk's flow requires: log, then dispatch.
-      const names = session.toolCalls().map((c) => c.name);
+      const names = toolNames(session.toolCalls());
       expect(names.indexOf("resources_dispatch")).toBeGreaterThan(names.indexOf("incident_create"));
     },
     {
@@ -230,7 +224,7 @@ describeEval(dispatchAgent, (test) => {
   test(
     "closing an incident releases the units that were on it",
     async ({ session }) => {
-      await sayAll(session, [
+      await session.sayAll([
         THE_CALL,
         "Dispatch the recommended units, emergency priority.",
         "Units report the patient is transported and they're clear. Close it out.",
@@ -252,7 +246,7 @@ describeEval(dispatchAgent, (test) => {
       // The board agrees, which is the half a browser would show.
       expect(boardEntry(session.events(), FIRST_INCIDENT)?.status).toBe("resolved");
       // And the shift ran in the order the flow requires.
-      const names = session.toolCalls().map((c) => c.name);
+      const names = toolNames(session.toolCalls());
       expect(names.indexOf("incident_create")).toBeGreaterThanOrEqual(0);
       expect(names.indexOf("resources_dispatch")).toBeGreaterThan(names.indexOf("incident_create"));
       expect(names.lastIndexOf("incident_update_status")).toBeGreaterThan(
@@ -279,7 +273,7 @@ describeEval(dispatchAgent, (test) => {
   test(
     "a unit already rolling is not sent to a second call",
     async ({ session }) => {
-      await sayAll(session, [
+      await session.sayAll([
         THE_CALL,
         "Send Medic-1 to Oak Street.",
         "New call: 12 Pine Lane, chest pains. Log it.",

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

@@ -25,7 +25,7 @@
  * tool-choice claim below then passes or fails for the wrong reason.
  */
 import agentDef from "virtual:aai/agent";
-import { toolResultIn } from "@alexkroman1/aai-runtime/eval";
+import { toolNames, toolResultIn } from "@alexkroman1/aai-runtime/eval";
 import { describeEval } from "@alexkroman1/aai-runtime/eval/vitest";
 import { expect } from "vitest";
 import { z } from "zod";
@@ -57,7 +57,7 @@ describeEval(agentDef, (test) => {
       // about voice frameworks in general.
       const turn = await session.say("Can your agents make HTTP requests?");
 
-      expect(turn.toolCalls.map((c) => c.name)).toEqual(["search_knowledge"]);
+      expect(toolNames(turn.toolCalls)).toEqual(["search_knowledge"]);
       const call = turn.toolCalls[0]!;
       expect(typeof (call.args as { query?: unknown }).query).toBe("string");
       // The right entry, out of four: the one this question is really about.
@@ -81,7 +81,7 @@ describeEval(agentDef, (test) => {
     async ({ session }) => {
       const turn = await session.say("What topics can you help me with?");
 
-      expect(turn.toolCalls.map((c) => c.name)).toEqual(["list_topics"]);
+      expect(toolNames(turn.toolCalls)).toEqual(["list_topics"]);
       // Every question in `knowledge.json` and nothing else — the check that
       // catches an index built from a stale copy of the asset.
       expect(toolResultIn(turn.toolCalls, "list_topics", z.array(z.string()))).toEqual(

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

@@ -30,7 +30,13 @@ describe("embedded-assets template", () => {
     // `agent()` takes no `tools` field: a file in `tools/` IS the tool, and
     // nothing imports it. Discovery is what puts it in front of the model, so a
     // template whose tools are never resolved ships a model with no tools.
-    expect(Object.keys(agentDef.tools ?? {}).sort()).toEqual(["list_topics", "search_knowledge"]);
+    // `arrayContaining` rather than an exact list: adding a file to `tools/` is
+    // the edit this template most invites, and an exact list would redden on
+    // it. Losing one of these two is still a failure — that is the half worth
+    // asserting.
+    expect(Object.keys(agentDef.tools ?? {})).toEqual(
+      expect.arrayContaining(["list_topics", "search_knowledge"]),
+    );
   });
 });
 

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

@@ -34,14 +34,36 @@
  * tool-choice claim below then passes or fails for the wrong reason.
  */
 import agentDef from "virtual:aai/agent";
-import { toolResultIn } from "@alexkroman1/aai-runtime/eval";
+import {
+  describeTurn,
+  type EvalToolCall,
+  toolArgsIn,
+  toolResultIn,
+} from "@alexkroman1/aai-runtime/eval";
 import { describeEval } from "@alexkroman1/aai-runtime/eval/vitest";
 import { expect } from "vitest";
 import { z } from "zod";
 
-/** The drugs an interaction check was actually asked about, lowercased. */
-const drugsIn = (args: Record<string, unknown>): string[] =>
-  ((args.drugs as string[] | undefined) ?? []).map((d) => d.trim().toLowerCase());
+/**
+ * Every drug this scope's interaction checks were actually asked about,
+ * lowercased.
+ *
+ * Read through `toolArgsIn` WITH a schema, which is what that reader takes one
+ * for: `args` is `Record<string, unknown>` on the wire — the model wrote it and
+ * nothing validated it — so the `args.drugs as string[] ?? []` this replaced
+ * turned a `drugs` the desk renamed, or never sent, into an empty list, and the
+ * two claims below would have been claims about nothing. A `drugs` that stops
+ * arriving FAILS here, naming the field.
+ *
+ * ZERO checks answers `[]` rather than throwing, which is what keeps the
+ * dangerous case assertable: a desk that answered an interaction question
+ * without asking a single label reaches the assertions with nothing in hand.
+ */
+const InteractionArgs = z.object({ drugs: z.array(z.string()) });
+const drugsAsked = (calls: readonly EvalToolCall[]): string[] =>
+  toolArgsIn(calls, "check_drug_interaction", InteractionArgs).flatMap((args) =>
+    args.drugs.map((drug) => drug.trim().toLowerCase()),
+  );
 
 /**
  * A refusal from `check_drug_interaction`, as the model saw it.
@@ -60,12 +82,15 @@ describeEval(agentDef, (test) => {
       const turn = await session.say("Can I take ibuprofen and warfarin together?");
 
       // It may look each drug up as well — that is fine and often useful. What
-      // it may not do is answer this question without asking the labels.
-      const checks = turn.toolCalls.filter((c) => c.name === "check_drug_interaction");
-      expect(checks).not.toEqual([]);
-      const asked = checks.flatMap((c) => drugsIn(c.args));
-      expect(asked).toContain("ibuprofen");
-      expect(asked).toContain("warfarin");
+      // it may not do is answer this question without asking the labels — and a
+      // desk that asked nothing arrives here with an empty list, so these two
+      // lines carry the never-checked finding as well as the wrong-drugs one.
+      // `describeTurn` is what tells them apart in the failure: "expected [] to
+      // contain 'ibuprofen'" does not say whether the desk called something
+      // else, called nothing, or was cut off mid-reply.
+      const asked = drugsAsked(turn.toolCalls);
+      expect(asked, describeTurn(turn)).toContain("ibuprofen");
+      expect(asked, describeTurn(turn)).toContain("warfarin");
 
       // The rule at the top of its prompt: it is not a doctor. An interaction
       // answer that does not end at a professional is the failure that makes
@@ -90,11 +115,9 @@ describeEval(agentDef, (test) => {
       // drug alone and report nothing.
       const turn = await session.say("Is it okay if I add ibuprofen for a headache?");
 
-      const checks = turn.toolCalls.filter((c) => c.name === "check_drug_interaction");
-      expect(checks).not.toEqual([]);
-      const asked = checks.flatMap((c) => drugsIn(c.args));
-      expect(asked).toContain("warfarin");
-      expect(asked).toContain("ibuprofen");
+      const asked = drugsAsked(turn.toolCalls);
+      expect(asked, describeTurn(turn)).toContain("warfarin");
+      expect(asked, describeTurn(turn)).toContain("ibuprofen");
     },
     {
       stubReply: [

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/link-digest/agent.eval.test.ts

@@ -26,15 +26,13 @@
 
 import { createServer, type Server } from "node:http";
 import type { AddressInfo } from "node:net";
+import { stubGatewayRoute } from "@alexkroman1/aai/testing";
 import { installStubStepFetch } from "@alexkroman1/aai/testing/vitest";
 import { describeWorkflowEval } from "@alexkroman1/aai-runtime/eval/vitest";
 import { expect, onTestFinished } from "vitest";
 import agentDef, { digest } from "./agent.ts";
 import { SETTLE_MS } from "./workflows/digest.ts";
 
-/** The gateway leg, so one handler can route the page and the model apart. */
-const isModelCall = (url: string): boolean => url.includes("/chat/completions");
-
 /**
  * A page with an ANSWER in it, so "did it summarize what it fetched" is a
  * question with a right answer rather than a vibe.
@@ -107,15 +105,25 @@ async function servePage(html: string): Promise<string> {
  *
  * ONE handler, because publishing a `stepFetch` REPLACES — a flow that fetches a
  * page and calls a model cannot install two fakes, so it routes by URL. The
- * recorded calls are what makes the prompt assertable, which is the only way to
- * check what the model was SHOWN rather than what it said.
+ * routing is `stubGatewayRoute`'s rather than this file's: it answers the
+ * completion request and `undefined` for everything else, which is what makes
+ * the page the `??` arm — and it routes off the SDK's own completions PATH, so a
+ * case cannot pass because the fake and the step agree on a typo. That matters
+ * more here than it looks: the envelope is a WIRE shape, so a field typed one
+ * off does not fail — `stepGenerate` reads no content and reports an empty
+ * completion, and the case blames the digest.
+ *
+ * The recorded calls are what makes the prompt assertable, which is the only way
+ * to check what the model was SHOWN rather than what it said — and they come
+ * back DECODED, so the last case reads `prompt` rather than the raw request
+ * body, which is the whole serialized request.
  */
 function scriptBothLegs(html: string, reply = SCRIPTED_DIGEST) {
-  return installStubStepFetch((request) =>
-    isModelCall(request.url)
-      ? { body: { choices: [{ message: { content: reply } }] } }
-      : { body: html, headers: { "Content-Type": "text/html" } },
+  const model = stubGatewayRoute(reply);
+  installStubStepFetch(
+    (request) => model.route(request) ?? { body: html, headers: { "Content-Type": "text/html" } },
   );
+  return model;
 }
 
 describeWorkflowEval(agentDef, (test) => {
@@ -180,18 +188,19 @@ describeWorkflowEval(agentDef, (test) => {
       "</body>",
       `<p>${"padding sentence about otters. ".repeat(2000)}</p></body>`,
     );
-    const legs = scriptBothLegs(oversized);
+    const model = scriptBothLegs(oversized);
 
     const run = await app.run(digest, { url: "https://example.test/otters" });
     expect(run.status).toBe("completed");
 
-    const prompt = String(legs.calls.find((call) => isModelCall(call.url))?.body ?? "");
-    expect(prompt).toContain("Sea otters are one of the few mammals that use tools");
+    const asked = model.calls[0];
+    if (asked === undefined) expect.fail("the run must have shown the article to the model");
+    expect(asked.prompt).toContain("Sea otters are one of the few mammals that use tools");
     // Neither the script's instruction nor the stylesheet reached the prompt.
-    expect(prompt).not.toContain(SMUGGLED);
-    expect(prompt).not.toContain("rebeccapurple");
+    expect(asked.prompt).not.toContain(SMUGGLED);
+    expect(asked.prompt).not.toContain("rebeccapurple");
     // And the text was CAPPED on the way across the queue. 24k characters plus
     // the prompt's own framing, well under the ~60k this page would otherwise be.
-    expect(prompt.length).toBeLessThan(30_000);
+    expect(asked.prompt.length).toBeLessThan(30_000);
   });
 });

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

@@ -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);
   });
 });

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

@@ -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;
@@ -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 { page, 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,9 +92,6 @@ 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.
@@ -102,13 +101,10 @@ export function App() {
   // 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 } = 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

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

@@ -14,27 +14,38 @@
 // back with as well as the code the tutor wrote.
 
 import agentDef from "virtual:aai/agent";
-import { createVmRunCode, toolResultsIn } from "@alexkroman1/aai-runtime/eval";
+import {
+  createVmRunCode,
+  type EvalTurn,
+  toolArgsIn,
+  toolNames,
+  toolResultsIn,
+} from "@alexkroman1/aai-runtime/eval";
 import { describeEval } from "@alexkroman1/aai-runtime/eval/vitest";
 import { expect } from "vitest";
+import { z } from "zod";
 
-/** The code every `run_code` call in this turn carried, joined. */
-const codeIn = (turn: { toolCalls: readonly { name: string; args: Record<string, unknown> }[] }) =>
-  turn.toolCalls
-    .filter((c) => c.name === "run_code")
-    .map((c) => String(c.args.code ?? ""))
+/**
+ * The code every `run_code` call in this turn carried, joined.
+ *
+ * Read through `toolArgsIn` WITH a schema, which is what that reader takes one
+ * for: `args` is `Record<string, unknown>` on the wire — the tutor wrote it and
+ * nothing validated it — so the `String(c.args.code ?? "")` this replaced turned
+ * an argument the model renamed, or never sent, into `""`. The claims below are
+ * about the recipe the tutor wrote, and against `""` every one of them would
+ * have been a claim about nothing. A `code` that stops arriving FAILS here,
+ * naming the field.
+ */
+const RunCodeArgs = z.object({ code: z.string() });
+const codeIn = (turn: EvalTurn) =>
+  toolArgsIn(turn.toolCalls, "run_code", RunCodeArgs)
+    .map((args) => args.code)
     .join("\n");
 
 /**
- * A `run_code` executor, so these cases can assert the ANSWER.
- *
- * The builtin refuses without one — the Modal container is the security
- * boundary, and off-platform there is none — so a case could assert the CALL and
- * the code it carried, and never what the code came back with.
- * `createVmRunCode()` is a `node:vm` context with a capturing `console.log`,
- * which is enough here: what runs is arithmetic, not a program. It is NOT a
- * sandbox and does not pretend to be one; a deployed agent still gets the
- * refusal.
+ * A `run_code` executor, so these cases can assert the answer the tutor's code
+ * came back with and not merely the code — `createVmRunCode`'s own doc carries
+ * why the builtin refuses without one.
  */
 const runCode = createVmRunCode();
 
@@ -49,7 +60,7 @@ describeEval(
         // The prompt hands the tutor the factors; the finding it guards against
         // is a tutor that recites a remembered figure instead. A factor in the
         // code is the evidence that the conversion was computed, not recalled.
-        expect(turn.toolCalls.map((c) => c.name)).toContain("run_code");
+        expect(toolNames(turn.toolCalls)).toContain("run_code");
         const code = codeIn(turn);
         expect(code).toContain("5");
         expect(code).toMatch(/1\.60|1\.61|0\.621|8\.04/);
@@ -69,7 +80,7 @@ describeEval(
         // A model asked for dice will happily make three numbers up, and the
         // reply is indistinguishable from a real roll. `Math.random` in the code
         // is the only thing that tells them apart.
-        expect(turn.toolCalls.map((c) => c.name)).toContain("run_code");
+        expect(toolNames(turn.toolCalls)).toContain("run_code");
         const code = codeIn(turn);
         expect(code).toMatch(/Math\.random/);
         expect(code).toContain("20");

package/dist/templates/night-owl/agent.eval.test.ts

@@ -29,7 +29,10 @@ import type { SessionEvent } from "@alexkroman1/aai/protocol";
 import {
   createVmRunCode,
   customEventsIn,
+  describeTurn,
   lastStateIn,
+  toolArgsIn,
+  toolNames,
   toolResultIn,
 } from "@alexkroman1/aai-runtime/eval";
 import { describeEval } from "@alexkroman1/aai-runtime/eval/vitest";
@@ -66,17 +69,23 @@ const pushedRecs = (events: readonly SessionEvent[]) =>
 const nudges = (events: readonly SessionEvent[]) => customEventsIn(events, "wind_down");
 
 /**
- * A `run_code` executor, so the sleep-cycle case can assert the ANSWER.
- *
- * The builtin refuses without one — the Modal container is the security
- * boundary, and off-platform there is none — which left this template's
- * headline feature assertable as a CALL and never as a number. A `node:vm`
- * context with a capturing `console.log` is what a developer would reach for on
- * their own machine, and `createVmRunCode()` is exactly that: the code under
- * test is arithmetic the model wrote, not a program.
+ * A `run_code` executor, so the sleep-cycle case can assert the bedtime NUMBER
+ * and not merely the call — this template's headline feature is the arithmetic.
+ * `createVmRunCode`'s own doc carries why the builtin refuses without one.
  */
 const runCode = createVmRunCode();
 
+/**
+ * The `code` argument a `run_code` call carries.
+ *
+ * The schema is what `toolArgsIn` takes one for: `args` is
+ * `Record<string, unknown>` on the wire — the model wrote it and nothing
+ * validated it — so the `String(c.args.code ?? "")` this replaced turned an
+ * argument the companion renamed, or never sent, into `""`, and the two
+ * constants asserted below would have been looked for in nothing at all.
+ */
+const RunCodeArgs = z.object({ code: z.string() });
+
 /** Two-digit, for the clock arithmetic below. */
 const pad = (n: number): string => String(n).padStart(2, "0");
 
@@ -113,7 +122,7 @@ describeEval(
 
         // "to watch" is the category and "cozy" is the mood; the shelf is the
         // tool's, so answering from the model's own taste is the regression.
-        expect(turn.toolCalls.map((c) => c.name)).toEqual(["recommend"]);
+        expect(toolNames(turn.toolCalls)).toEqual(["recommend"]);
         const call = turn.toolCalls[0]!;
         expect(call.args).toEqual({ category: "movie", mood: "cozy" });
 
@@ -139,7 +148,7 @@ describeEval(
         await session.say("I want something cozy to watch tonight.");
         const turn = await session.say("Now give me something spooky to read.");
 
-        expect(turn.toolCalls.map((c) => c.name)).toEqual(["recommend"]);
+        expect(toolNames(turn.toolCalls)).toEqual(["recommend"]);
         expect(turn.toolCalls[0]!.args).toEqual({ category: "book", mood: "spooky" });
 
         // The slot survived the turn boundary: the frame the page renders after
@@ -197,15 +206,21 @@ describeEval(
           "I need to be up at 7 in the morning. When should I fall asleep?",
         );
 
+        // The CALLS, not their arguments: what this asserts is that the companion
+        // reached for code at all, and the results are read off the same list
+        // below. `toolArgsIn` answers the other half, the code it submitted.
         const ran = turn.toolCalls.filter((c) => c.name === "run_code");
-        expect(
-          ran,
-          `tools called: [${turn.toolCalls.map((c) => c.name).join(", ")}]; said: ${turn.text}`,
-        ).not.toEqual([]);
+        // `describeTurn` is the message: "expected [] not to equal []" says
+        // nothing about a companion that talked its way through the sum
+        // instead, and it names a cancelled reply, which is the usual reason a
+        // turn reached for nothing at all.
+        expect(ran, describeTurn(turn)).not.toEqual([]);
         // The recipe is the prompt's, and it is two constants: a 90-minute cycle
         // plus the 15 minutes it takes to fall asleep. Arithmetic done in the
         // model's head has neither of them anywhere in the code.
-        const code = ran.map((c) => String(c.args.code ?? "")).join("\n");
+        const code = toolArgsIn(turn.toolCalls, "run_code", RunCodeArgs)
+          .map((args) => args.code)
+          .join("\n");
         expect(code).toContain("90");
         expect(code).toContain("15");
 

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/personal-finance/agent.eval.test.ts

@@ -16,33 +16,43 @@
 // live rates API.
 
 import agentDef from "virtual:aai/agent";
-import { createVmRunCode, toolResultsIn } from "@alexkroman1/aai-runtime/eval";
+import {
+  createVmRunCode,
+  type EvalTurn,
+  toolArgsIn,
+  toolResultsIn,
+} from "@alexkroman1/aai-runtime/eval";
 import { describeEval } from "@alexkroman1/aai-runtime/eval/vitest";
 import { expect } from "vitest";
+import { z } from "zod";
 
-type Turn = { toolCalls: readonly { name: string; args: Record<string, unknown> }[] };
+/**
+ * The arguments Penny's two builtins carry, as the wire has them.
+ *
+ * Schemas rather than `String(args.code ?? "")`, which is what `toolArgsIn`
+ * takes one for: `args` is `Record<string, unknown>` — the model wrote it and
+ * nothing validated it — so an argument Penny renamed, or never sent, used to
+ * read as `""`, and the claims below about the code she submitted and the URL
+ * she asked for would have been claims about an empty string. An argument that
+ * stops arriving FAILS here, naming the field.
+ */
+const RunCodeArgs = z.object({ code: z.string() });
+const FetchJsonArgs = z.object({ url: z.string() });
 
 /** The code every `run_code` call in this turn carried, joined. */
-const codeIn = (turn: Turn) =>
-  turn.toolCalls
-    .filter((c) => c.name === "run_code")
-    .map((c) => String(c.args.code ?? ""))
+const codeIn = (turn: EvalTurn) =>
+  toolArgsIn(turn.toolCalls, "run_code", RunCodeArgs)
+    .map((args) => args.code)
     .join("\n");
 
 /** Every URL this turn's `fetch_json` calls asked for. */
-const fetchedUrls = (turn: Turn) =>
-  turn.toolCalls.filter((c) => c.name === "fetch_json").map((c) => String(c.args.url ?? ""));
+const fetchedUrls = (turn: EvalTurn) =>
+  toolArgsIn(turn.toolCalls, "fetch_json", FetchJsonArgs).map((args) => args.url);
 
 /**
- * A `run_code` executor, so these cases can assert the ANSWER.
- *
- * The builtin refuses without one — the Modal container is the security
- * boundary, and off-platform there is none — so a case could assert the CALL and
- * the code it carried, and never what the code came back with.
- * `createVmRunCode()` is a `node:vm` context with a capturing `console.log`,
- * which is enough here: what runs is arithmetic, not a program. It is NOT a
- * sandbox and does not pretend to be one; a deployed agent still gets the
- * refusal.
+ * A `run_code` executor, so the arithmetic cases can assert the ANSWER and not
+ * merely the call — `createVmRunCode`'s own doc carries why the builtin refuses
+ * without one. `fetch_json` needs nothing of the sort: it makes a real request.
  */
 const runCode = createVmRunCode();