@alexkroman1/aai-cli 13.2.0 → 14.0.0

package/dist/templates/retail/pending.test.ts

@@ -1,6 +1,6 @@
 import type { ToolContext } from "@alexkroman1/aai";
 import { isToolFailure } from "@alexkroman1/aai";
-import { createToolContext, ok, okPosition } from "@alexkroman1/aai/testing";
+import { createToolContext, expectDialogOk, expectToolOk } from "@alexkroman1/aai/testing";
 import { describe, expect, test } from "vitest";
 import type { StagedResult } from "./pending.ts";
 import { retailSlot } from "./store.ts";
@@ -17,7 +17,7 @@ import transferToHumanAgents from "./tools/transfer_to_human_agents.ts";
  *  one delivered order (#W4316152), which is every shape these cases need. */
 async function aaravCtx(): Promise<ToolContext> {
   const ctx = createToolContext();
-  ok(await findUserIdByEmail.execute({ email: "aarav.anderson9752@example.com" }, ctx));
+  expectToolOk(await findUserIdByEmail.execute({ email: "aarav.anderson9752@example.com" }, ctx));
   return ctx;
 }
 
@@ -29,7 +29,7 @@ describe("staging", () => {
     const ctx = await aaravCtx();
     const before = structuredClone(retailSlot.get(ctx).store.orders["#W9300146"]);
 
-    const staged = okPosition<StagedResult>(await stageCancel(ctx));
+    const staged = expectDialogOk<StagedResult>(await stageCancel(ctx));
 
     expect(staged.state).toBe("serving.awaitingConfirmation");
     expect(staged.result.staged).toBe("cancel_pending_order");
@@ -43,7 +43,7 @@ describe("staging", () => {
 
   test("the readback names the order, the items, the amount and where the money goes", async () => {
     const ctx = await aaravCtx();
-    const staged = ok<StagedResult>(await stageCancel(ctx));
+    const staged = expectToolOk<StagedResult>(await stageCancel(ctx));
     expect(staged.read_back).toContain("#W9300146");
     expect(staged.read_back).toContain("153.23");
     expect(staged.read_back).toContain("gift_card_7245904");
@@ -52,14 +52,14 @@ describe("staging", () => {
 
   test("the result says out loud that nothing has happened", async () => {
     const ctx = await aaravCtx();
-    const staged = ok<StagedResult>(await stageCancel(ctx));
+    const staged = expectToolOk<StagedResult>(await stageCancel(ctx));
     expect(staged.message).toContain("NOTHING HAS CHANGED YET");
     expect(staged.message).toContain("confirm_change");
   });
 
   test("a second stage is refused, and the refusal names the one already waiting", async () => {
     const ctx = await aaravCtx();
-    ok(await stageCancel(ctx));
+    expectToolOk(await stageCancel(ctx));
 
     // A DIFFERENT change, so this is not a repeat of the first call.
     const second = await modifyUserAddress.execute(
@@ -89,9 +89,9 @@ describe("staging", () => {
 describe("confirming", () => {
   test("confirm_change applies the staged change and returns to helping", async () => {
     const ctx = await aaravCtx();
-    ok(await stageCancel(ctx));
+    expectToolOk(await stageCancel(ctx));
 
-    const done = okPosition<{ confirmed: string; status: string }>(
+    const done = expectDialogOk<{ confirmed: string; status: string }>(
       await confirmChange.execute({}, ctx),
     );
     expect(done.state).toBe("serving.helping");
@@ -114,8 +114,8 @@ describe("confirming", () => {
 
   test("confirming twice is refused — the second call has nothing staged", async () => {
     const ctx = await aaravCtx();
-    ok(await stageCancel(ctx));
-    ok(await confirmChange.execute({}, ctx));
+    expectToolOk(await stageCancel(ctx));
+    expectToolOk(await confirmChange.execute({}, ctx));
 
     const again = await confirmChange.execute({}, ctx);
     expect(isToolFailure(again)).toBe(true);
@@ -130,9 +130,9 @@ describe("confirming", () => {
 describe("cancelling a staged change", () => {
   test("cancel_change drops it, changes nothing, and frees the call", async () => {
     const ctx = await aaravCtx();
-    ok(await stageCancel(ctx));
+    expectToolOk(await stageCancel(ctx));
 
-    const dropped = okPosition<{ dropped: string | null; message: string }>(
+    const dropped = expectDialogOk<{ dropped: string | null; message: string }>(
       await cancelChange.execute({}, ctx),
     );
     expect(dropped.state).toBe("serving.helping");
@@ -144,12 +144,12 @@ describe("cancelling a staged change", () => {
 
   test("a corrected change can be staged straight after", async () => {
     const ctx = await aaravCtx();
-    ok(await stageCancel(ctx));
-    ok(await cancelChange.execute({}, ctx));
+    expectToolOk(await stageCancel(ctx));
+    expectToolOk(await cancelChange.execute({}, ctx));
 
     // The caller changed their mind about which order — the very thing
     // `cancel_change` exists for.
-    const restaged = ok<StagedResult>(
+    const restaged = expectToolOk<StagedResult>(
       await returnDeliveredOrderItems.execute(
         {
           order_id: "#W4316152",
@@ -166,9 +166,9 @@ describe("cancelling a staged change", () => {
 describe("what stays legal while a change waits", () => {
   test("a read is still answerable — 'what was the total again?'", async () => {
     const ctx = await aaravCtx();
-    ok(await stageCancel(ctx));
+    expectToolOk(await stageCancel(ctx));
     // `when: "serving"` matches both children, which is what makes this work.
-    const read = okPosition<{ order_id: string }>(
+    const read = expectDialogOk<{ order_id: string }>(
       await getOrderDetails.execute({ order_id: "#W9300146" }, ctx),
     );
     expect(read.result.order_id).toBe("#W9300146");
@@ -178,9 +178,9 @@ describe("what stays legal while a change waits", () => {
 
   test("a caller can still ask for a human, and everything refuses afterwards", async () => {
     const ctx = await aaravCtx();
-    ok(await stageCancel(ctx));
+    expectToolOk(await stageCancel(ctx));
 
-    const transferred = okPosition(
+    const transferred = expectDialogOk(
       await transferToHumanAgents.execute({ summary: "wants a human" }, ctx),
     );
     // `TRANSFERRED` is declared on the `serving` PARENT, which is what lets it

package/dist/templates/retail/registry.test.ts

@@ -1,21 +1,6 @@
 import { isToolFailure, type ToolContext } from "@alexkroman1/aai";
 import { createToolContext, deployedAgent } from "@alexkroman1/aai/testing";
 import { describe, expect, test } from "vitest";
-import { callFlow, retailSlot } from "./store.ts";
-
-/** Tools that legitimately run before the caller is identified — the six
- *  declaring `when: BEFORE_TRANSFER`. Everything else must refuse. Listed here
- *  so ADDING an unauthenticated tool is a deliberate edit to this file, not a
- *  silent gap. */
-const PUBLIC_TOOLS = new Set([
-  "find_user_id_by_email",
-  "find_user_id_by_name_zip",
-  "get_product_details",
-  "get_item_details",
-  "list_all_product_types",
-  "transfer_to_human_agents",
-]);
-
 /**
  * The def a DEPLOYED agent runs, lowered BY HAND — the one place in the
  * templates that still does.
@@ -27,6 +12,7 @@ const PUBLIC_TOOLS = new Set([
  * whose runner is not vitest, and so cannot register the plugin.
  */
 import authoredAgent from "./agent.ts";
+import { callFlow, gateFor, retailSlot } from "./store.ts";
 import systemPrompt from "./system-prompt.md?raw";
 
 const retailAgent = deployedAgent(authoredAgent, {
@@ -36,6 +22,39 @@ const retailAgent = deployedAgent(authoredAgent, {
 
 const registry = Object.entries(retailAgent.tools);
 
+/**
+ * Whether `name`'s gate admits the pre-identification state — i.e. whether it
+ * is one of the tools that legitimately runs before the caller is identified.
+ *
+ * ASKED OF THE REGISTRY, not read off a list here. This used to be a hardcoded
+ * six-name set, which meant a tool you add is classified by a file you did not
+ * write: declare `when: BEFORE_TRANSFER` on a new catalogue read and the
+ * sweeps below would have demanded it refuse. `retailTool` records every gate
+ * in `TOOL_GATES`, so the honest question is what the tool itself declared.
+ *
+ * `undefined` — a tool built with plain `tool()` rather than `retailTool` — is
+ * neither: it has no gate at all, and the sweeps skip it. That is the same
+ * answer `gateFor` gives the `tool.called` hook, and "a tool this template did
+ * not declare is ignored" below is the assertion for it.
+ */
+const isPublic = (name: string) => gateFor(name)?.includes("identifying") ?? false;
+
+/** Registry entries that went through `retailTool`, so the gate has an opinion. */
+const gatedTools = registry.filter(([name]) => gateFor(name) !== undefined);
+
+/** The tools this template SHIPS that run before identification. A pin on the
+ *  shipped set — one of these quietly losing `BEFORE_TRANSFER` is a policy
+ *  break — and nothing else reads it, so adding a public tool of your own costs
+ *  no edit here. */
+const SHIPPED_PUBLIC_TOOLS = [
+  "find_user_id_by_email",
+  "find_user_id_by_name_zip",
+  "get_product_details",
+  "get_item_details",
+  "list_all_product_types",
+  "transfer_to_human_agents",
+];
+
 // `createToolContext()` rather than a cast: it carries a real slot store (the
 // same storability check and freeze the deployed one applies), and each call is a
 // distinct session, which is what these per-tool cases assume.
@@ -81,9 +100,19 @@ async function bodyReachableCtx(name: string): Promise<ToolContext> {
   return ctx;
 }
 
-/** Minimal args satisfying each tool's schema. Deliberately plausible-shaped
- *  but wrong — these calls are expected to fail; what is asserted is that they
- *  still moved the UI. */
+/**
+ * Minimal args satisfying each tool's schema. Deliberately plausible-shaped but
+ * wrong — these calls are expected to fail; what is asserted is that they still
+ * moved the UI.
+ *
+ * **It is also the list of tools this file sweeps, and the list of tools this
+ * template ships.** It used to be a second copy of a seventeen-name array
+ * asserted with `toEqual`, so adding one tool of your own failed both — the
+ * count and the coverage — before it had run once. One source now: a tool with
+ * an entry here is driven through every sweep below, and every name here must
+ * still be discovered from `tools/`. Add your tool with its arguments and it
+ * joins the sweeps; leave it out and it is simply not covered by them.
+ */
 const SAMPLE_ARGS: Record<string, Record<string, unknown>> = {
   cancel_change: {},
   cancel_pending_order: { order_id: "#W0000000", reason: "no longer needed" },
@@ -137,56 +166,56 @@ const SAMPLE_ARGS: Record<string, Record<string, unknown>> = {
   transfer_to_human_agents: { summary: "test" },
 };
 
+/** The tools with sample args, i.e. the ones every sweep below can drive. */
+const sweepable = registry.filter(([name]) => name in SAMPLE_ARGS);
+
 describe("tool registry", () => {
-  test("registers all seventeen tools", () => {
-    // Fifteen of these are tau2's retail tool set, which this template used to
-    // hold verbatim. `confirm_change` and `cancel_change` are the two it does
-    // not have: tau2's tools apply on their first call, and here nothing does —
-    // see `pending.ts`. Departing from that set is what buys the confirmation
-    // gate, and it is the reason this list is no longer a fidelity claim.
-    expect(registry.map(([name]) => name).sort()).toEqual(
-      [
-        "cancel_change",
-        "cancel_pending_order",
-        "confirm_change",
-        "exchange_delivered_order_items",
-        "find_user_id_by_email",
-        "find_user_id_by_name_zip",
-        "get_item_details",
-        "get_order_details",
-        "get_product_details",
-        "get_user_details",
-        "list_all_product_types",
-        "modify_pending_order_address",
-        "modify_pending_order_items",
-        "modify_pending_order_payment",
-        "modify_user_address",
-        "return_delivered_order_items",
-        "transfer_to_human_agents",
-      ].sort(),
+  test("discovers every tool this template ships", () => {
+    // `arrayContaining` rather than an exact sorted list. Fifteen of these are
+    // tau2's retail tool set, which this template used to hold verbatim;
+    // `confirm_change` and `cancel_change` are the two it does not have, since
+    // tau2's tools apply on their first call and here nothing does (see
+    // `pending.ts`). So the list is not a fidelity claim and never was a
+    // COUNT — what it is worth asserting is that discovery still finds each
+    // one, because a `tools/` glob that resolves nothing looks exactly like a
+    // desk with no tools. Adding a tool of your own passes; losing one of these
+    // fails, naming it.
+    expect(registry.map(([name]) => name)).toEqual(
+      expect.arrayContaining(Object.keys(SAMPLE_ARGS)),
     );
   });
 
-  // Both sweep the registry, so they assert softly: adding a batch of tools
-  // should list every one still missing its entry, not just the first.
-  test("every registered tool has sample args, so the sweeps below cover it", () => {
-    for (const [name] of registry) {
-      expect.soft(SAMPLE_ARGS[name], `add SAMPLE_ARGS["${name}"]`).toBeDefined();
+  // Asserts softly: a batch of renames should list every name that no longer
+  // resolves, not just the first.
+  test("every name in SAMPLE_ARGS resolves to a real tool", () => {
+    for (const name of Object.keys(SAMPLE_ARGS)) {
+      expect.soft(retailAgent.tools[name], `SAMPLE_ARGS["${name}"] names no tool`).toBeDefined();
     }
   });
 
   test("every tool declares a description the model can act on", () => {
     for (const [name, def] of registry) {
+      // Any tool, yours included — the model picks a tool by its description,
+      // so an empty one is invisible to it.
       expect.soft(def.description, name).toBeTruthy();
-      expect.soft(def.description.length, name).toBeGreaterThan(40);
+    }
+    for (const name of Object.keys(SAMPLE_ARGS)) {
+      // The shipped ones additionally carry enough of the policy to be chosen
+      // correctly, which for this desk means more than a label.
+      expect.soft(retailAgent.tools[name]?.description.length, name).toBeGreaterThan(40);
     }
   });
 });
 
 describe("the UI-update invariant", () => {
-  // This is the one that fails if a future tool is built with tool() instead of
+  // Over `sweepable` rather than the whole registry: these two REACH a tool's
+  // body, so they need arguments its schema accepts, and calling a tool of
+  // yours with `{}` would report a crash inside it as a UI regression. Give it
+  // a `SAMPLE_ARGS` entry and it is swept like the rest.
+  //
+  // This is the pair that fails if a future tool is built with tool() instead of
   // retailTool(): it would work, and the sidebar would sit still through it.
-  test.each(registry)("%s increments callSeq and logs activity", async (name, def) => {
+  test.each(sweepable)("%s increments callSeq and logs activity", async (name, def) => {
     // In whichever state lets the body run, so the flow gate is not what these
     // calls are testing: the point is that a tool which reaches its BODY moves
     // the sidebar. A refused call never reaches one — the hook below is what
@@ -200,7 +229,7 @@ describe("the UI-update invariant", () => {
     expect(state.activity.at(-1)?.summary).toBeTruthy();
   });
 
-  test.each(registry)("%s logs its own registry key as its name", async (name, def) => {
+  test.each(sweepable)("%s logs its own registry key as its name", async (name, def) => {
     // Catches a copy-paste where the retailTool `name` and the registry key
     // disagree — the activity feed would then attribute calls to the wrong tool.
     const ctx = await bodyReachableCtx(name);
@@ -229,7 +258,7 @@ describe("the blocked-call hook", () => {
       ctx,
     );
 
-  test.each(registry.filter(([name]) => !PUBLIC_TOOLS.has(name)))(
+  test.each(gatedTools.filter(([name]) => !isPublic(name)))(
     "%s records a blocked line when the model tries it too early",
     (name) => {
       const ctx = makeCtx();
@@ -245,7 +274,7 @@ describe("the blocked-call hook", () => {
     },
   );
 
-  test.each(registry.filter(([name]) => PUBLIC_TOOLS.has(name)))(
+  test.each(gatedTools.filter(([name]) => isPublic(name)))(
     "%s is left to the wrapper, because it is going to run",
     (name) => {
       const ctx = makeCtx();
@@ -280,7 +309,19 @@ describe("the blocked-call hook", () => {
 });
 
 describe("the authentication gate", () => {
-  test.each(registry.filter(([name]) => !PUBLIC_TOOLS.has(name)))(
+  test("the tools that run before identification are still the shipped six", () => {
+    // The one place `SHIPPED_PUBLIC_TOOLS` is read, and the only assertion in
+    // this file about WHICH tools are public. The sweeps below classify by
+    // `isPublic`, i.e. by what each tool declared, so a public tool of your own
+    // needs no edit here — but one of these six quietly losing
+    // `when: BEFORE_TRANSFER` would silently make the desk unreachable before a
+    // caller is identified, and nothing else would say so.
+    expect(registry.map(([name]) => name).filter(isPublic)).toEqual(
+      expect.arrayContaining(SHIPPED_PUBLIC_TOOLS),
+    );
+  });
+
+  test.each(gatedTools.filter(([name]) => !isPublic(name)))(
     "%s refuses before the caller is identified",
     async (name, def) => {
       const result = await def.execute(SAMPLE_ARGS[name] ?? {}, makeCtx());
@@ -297,7 +338,7 @@ describe("the authentication gate", () => {
     },
   );
 
-  test.each(registry.filter(([name]) => PUBLIC_TOOLS.has(name)))(
+  test.each(sweepable.filter(([name]) => isPublic(name)))(
     "%s does not require authentication",
     async (name, def) => {
       const result = await def.execute(SAMPLE_ARGS[name] ?? {}, makeCtx());
@@ -331,7 +372,7 @@ describe("agent config", () => {
 });
 
 describe("the transfer is terminal", () => {
-  test.each(registry)("%s refuses once the call is with a human", async (name, def) => {
+  test.each(gatedTools)("%s refuses once the call is with a human", async (name, def) => {
     const ctx = servingCtx();
     callFlow.send(ctx, { type: "TRANSFERRED" });
 

package/dist/templates/retail/store.test.ts

@@ -1,5 +1,5 @@
 import { isToolFailure, type ToolContext } from "@alexkroman1/aai";
-import { createToolContext, ok, okPosition } from "@alexkroman1/aai/testing";
+import { createToolContext, expectDialogOk, expectToolOk } from "@alexkroman1/aai/testing";
 import { describe, expect, test } from "vitest";
 import { z } from "zod";
 import {
@@ -237,16 +237,16 @@ describe("retailTool", () => {
   test("runs once the flow says serving", async () => {
     const ctx = makeCtx();
     serve(ctx);
-    expect(ok(await gated.execute({}, ctx))).toEqual({ ok: true });
+    expect(expectToolOk(await gated.execute({}, ctx))).toEqual({ ok: true });
   });
 
   test("the result carries the position the call landed in", async () => {
     const ctx = makeCtx();
     serve(ctx);
-    // `okPosition` rather than a cast to `{ instruction?: string }`: it keeps
+    // `expectDialogOk` rather than a cast to `{ instruction?: string }`: it keeps
     // the envelope this test is about, and a refusal fails here naming what the
     // flow said instead of reading `undefined` off a field nobody assigned.
-    const answered = okPosition<{ ok: boolean }>(await gated.execute({}, ctx));
+    const answered = expectDialogOk<{ ok: boolean }>(await gated.execute({}, ctx));
     expect(answered).toMatchObject({ state: "serving.helping", done: false });
     expect(answered.instruction).toMatch(/one identified customer/);
   });
@@ -307,7 +307,7 @@ describe("the call flow", () => {
       summary: () => "ran",
       execute: () => ({ ok: true }),
     });
-    expect(ok(await anywhere.execute({}, ctx))).toEqual({ ok: true });
+    expect(expectToolOk(await anywhere.execute({}, ctx))).toEqual({ ok: true });
 
     const at = callFlow.send(ctx, { type: "TRANSFERRED" });
     expect(at.state).toBe("transferred");

package/dist/templates/retail/swap.ts

@@ -7,6 +7,7 @@
  */
 
 import { isToolFailure, type ToolFailure } from "@alexkroman1/aai";
+import { formatMoney } from "@alexkroman1/aai/utils";
 import { resolveOrder } from "./resolve.ts";
 import type { Order, OrderItem, RetailState, User, Variant } from "./shared.ts";
 import {
@@ -48,7 +49,6 @@ export interface SwapLine {
   fromOptions: Record<string, string>;
   fromPrice: number;
   toItemId: string;
-  toName: string;
   toOptions: Record<string, string>;
   toPrice: number;
 }
@@ -146,9 +146,6 @@ export function toSwapLines(plan: SwapPlan): SwapLine[] {
     fromOptions: { ...pair.item.options },
     fromPrice: pair.item.price,
     toItemId: pair.newVariant.item_id,
-    // Same product by construction — a swap can only reach another option of
-    // it — so the name is the item's own and the OPTIONS are what differ.
-    toName: pair.item.name,
     toOptions: { ...pair.newVariant.options },
     toPrice: pair.newVariant.price,
   }));
@@ -163,7 +160,7 @@ export function assertCanCoverDiff(user: User, methodId: string, diff: number):
   if (isToolFailure(method)) return method;
   if (isGiftCard(method) && method.balance < diff) {
     return {
-      error: `Gift card ${methodId}'s balance ($${method.balance.toFixed(2)}) does not cover the $${diff.toFixed(2)} difference. Ask for another payment method.`,
+      error: `Gift card ${methodId}'s balance (${formatMoney(method.balance)}) does not cover the ${formatMoney(diff)} difference. Ask for another payment method.`,
     };
   }
   return null;
@@ -190,8 +187,8 @@ function describeLine(line: SwapLine): string {
 }
 
 function describeDiff(diff: number, methodId: string): string {
-  if (diff > 0) return `$${diff.toFixed(2)} charged to ${methodId}`;
-  if (diff < 0) return `$${Math.abs(diff).toFixed(2)} refunded to ${methodId}`;
+  if (diff > 0) return `${formatMoney(diff)} charged to ${methodId}`;
+  if (diff < 0) return `${formatMoney(Math.abs(diff))} refunded to ${methodId}`;
   return "no price difference";
 }
 
@@ -275,8 +272,8 @@ export function applyModifyItems(state: RetailState, plan: ModifyItemsPlan) {
     })),
     message:
       plan.diff > 0
-        ? `Done. $${plan.diff.toFixed(2)} was charged to ${plan.paymentMethodId}. This order can no longer be modified or cancelled.`
-        : `Done. $${Math.abs(plan.diff).toFixed(2)} is being refunded to ${plan.paymentMethodId}. This order can no longer be modified or cancelled.`,
+        ? `Done. ${formatMoney(plan.diff)} was charged to ${plan.paymentMethodId}. This order can no longer be modified or cancelled.`
+        : `Done. ${formatMoney(Math.abs(plan.diff))} is being refunded to ${plan.paymentMethodId}. This order can no longer be modified or cancelled.`,
   };
 }
 
@@ -358,7 +355,7 @@ export function applyExchange(state: RetailState, plan: ExchangePlan) {
     })),
     message:
       plan.diff > 0
-        ? `Exchange requested on ${plan.orderId}. $${plan.diff.toFixed(2)} will be charged to ${plan.paymentMethodId}. An email with return instructions is on its way.`
-        : `Exchange requested on ${plan.orderId}. $${Math.abs(plan.diff).toFixed(2)} will be refunded to ${plan.paymentMethodId}. An email with return instructions is on its way.`,
+        ? `Exchange requested on ${plan.orderId}. ${formatMoney(plan.diff)} will be charged to ${plan.paymentMethodId}. An email with return instructions is on its way.`
+        : `Exchange requested on ${plan.orderId}. ${formatMoney(Math.abs(plan.diff))} will be refunded to ${plan.paymentMethodId}. An email with return instructions is on its way.`,
   };
 }

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

@@ -2,17 +2,50 @@ import { toAgentConfig } from "@alexkroman1/aai/manifest";
 import { describe, expect, test } from "vitest";
 import agentDef from "./agent.ts";
 
+/**
+ * What a starter's spec may assert.
+ *
+ * Renaming the agent, giving it a voice, swapping a stage or switching the
+ * whole thing to speech-to-speech are the first edits this template invites —
+ * and `aai build` runs these tests before it bundles, so an assertion that
+ * pins the template's own identity turns the first customization into a build
+ * failure in a file the author never wrote. Every test here therefore asserts
+ * a property that survives those edits, on the RESOLVED config rather than on
+ * the def's empty fields.
+ */
 describe("simple template", () => {
   test("config passes manifest validation", () => {
     // Same conversion `aai build`/`aai deploy` run.
     expect(() => toAgentConfig(agentDef)).not.toThrow();
   });
 
-  test("exports an agent with a name and no explicit providers", () => {
-    // No provider fields declared: the default all-AssemblyAI pipeline is
-    // injected at parse time (see `defaultProviders`).
-    expect(agentDef.name).toBe("Simple Assistant");
-    expect(agentDef.stt).toBeUndefined();
-    expect(agentDef.s2s).toBeUndefined();
+  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("every stage its mode needs is filled, declared or defaulted", () => {
+    // The template's point: with no provider fields declared, the default
+    // all-AssemblyAI cascaded pipeline is injected at parse time (see
+    // `defaultProviders`) — so an agent that declares nothing still runs.
+    // 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();
+    }
   });
 });

package/dist/templates/solo-rpg/agent.eval.test.ts

@@ -33,7 +33,7 @@
  * deployed.
  */
 import agentDef from "virtual:aai/agent";
-import { type EvalTurn, toolResultIn } from "@alexkroman1/aai-runtime/eval";
+import { type EvalTurn, toolResultIn, toolResultsIn } from "@alexkroman1/aai-runtime/eval";
 import { describeEval } from "@alexkroman1/aai-runtime/eval/vitest";
 import { expect } from "vitest";
 import { z } from "zod";
@@ -82,20 +82,6 @@ const Refusal = z.object({ error: z.string() });
 const answerOf = <T>(turn: EvalTurn, name: string, schema: z.ZodType<T>): T =>
   toolResultIn(turn.toolCalls, name, schema);
 
-/**
- * What EVERY call to `name` answered on this turn, in call order.
- *
- * The plural form is for a claim about calls that may legitimately not have
- * happened — a refusal the narrator may have pre-empted by not calling at all.
- * `toolResultIn` over a ONE-CALL list per call: the name is that call's own, so
- * the reader's "no such call" and "two calls" throws are unreachable and what
- * is left is the parse, the schema, and the "never completed" failure.
- */
-const answersOf = <T>(turn: EvalTurn, name: string, schema: z.ZodType<T>): T[] =>
-  turn.toolCalls
-    .filter((c) => c.name === name)
-    .map((call) => toolResultIn([call], call.name, schema));
-
 /**
  * Every field `setup_character` requires, for the SCRIPTED runs.
  *
@@ -267,7 +253,7 @@ describeEval(agentDef, (test) => {
       expect(answerOf(down, "update_state", Settled).state).toBe("gameOver");
 
       const after = await session.say("I refuse to die. Roll to fight on.");
-      const attempts = answersOf(after, "action_roll", Refusal);
+      const attempts = toolResultsIn(after.toolCalls, "action_roll", Refusal);
       // The gate is only OBSERVABLE if something calls the gated tool, and the
       // script is what guarantees that — hence the exact count. `gameOver` was
       // once a flag nothing acted on, so a player with both tracks empty could