@alexkroman1/aai-cli 13.2.0 → 13.3.0

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

@@ -103,15 +103,25 @@ const slackInput = (slackWebhookUrl: string) => ({
 
 describe("the declaration", () => {
   test("is a workflow app with one workflow and a static page", () => {
-    expect(agentDef.name).toBe("Podcast Digest");
-    expect(Object.keys(agentDef.workflows ?? {})).toEqual(["dailyDigest"]);
+    // Not the agent's name: renaming it is an invited edit, and pinning the
+    // literal here would fail a build in somebody else's project.
+    expect(agentDef.name).toBeTruthy();
+    // `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("dailyDigest");
     expect(agentDef.workflows?.dailyDigest).toBe(dailyDigest);
   });
 
   test("names the one credential its steps read", () => {
     // A workflow app declares no providers, so nothing else in the config can
     // name this — which is what makes a deploy able to check for it.
-    expect(agentDef.requiredEnv).toEqual(["ASSEMBLYAI_API_KEY"]);
+    // `toContain`, so a step of your own that reads a second credential can be
+    // declared beside this one without failing a test you did not write.
+    expect(agentDef.requiredEnv).toContain("ASSEMBLYAI_API_KEY");
   });
 });
 

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

@@ -17,12 +17,13 @@
  * minutes, this one loses the only Stop button a thirty-digest commitment has,
  * and the run is invisible from then on to everything but `curl`.
  *
- * `key` is the handle that survives and `recover: true` is what reads it back,
- * so a later load lands on the same count, the same newest line, and the same
- * Wake and Cancel buttons bound to the same run.
+ * A correlation KEY is the handle that survives, and `useWorkflowSubmit` looks
+ * that key's newest run up as it mounts, so a later load lands on the same
+ * count, the same newest line, and the same Wake and Cancel buttons bound to
+ * the same run.
  *
- * **The key is `useRunKey({ storage: "local" })`, and this is the one workflow
- * app that passes that option.** Its siblings take the default,
+ * **This is the one workflow app that passes a `key` of its own, and it is
+ * `useRunKey({ storage: "local" })`.** Its siblings let the hook mint one into
  * `sessionStorage`, which dies with the tab and covers exactly the interruption
  * they have — a reload, a same-tab navigation, a crashed tab. A schedule
  * outlives all of that by design: closing the browser on Tuesday and coming
@@ -42,9 +43,9 @@
  *   URL would carry a credential into a lookup token — which is why the
  *   platform stopped writing keys to the operator's log.
  *
- * A real app with accounts passes the account's own id instead, and then the
- * schedule follows the person to a new device — a promise only a login can
- * keep.
+ * A real app with accounts passes the account's own id as `key` instead, and
+ * then the schedule follows the person to a new device — a promise only a login
+ * can keep.
  *
  * ## The form is DECLARED, not written
  *
@@ -135,15 +136,11 @@ export function App() {
   // `run.output` instead of `unknown`. `error` is the agent's own sentence for a
   // rejected input — better copy than anything this page could write, and the
   // reason there is no `try`/`catch` here.
+  // The key REPLACES the tab-scoped one the hook would mint; the lookup that
+  // reads it back on the next load happens either way.
   const { submitForm, run, pending, error, wake, cancel } = useWorkflowSubmit<typeof dailyDigest>(
     WORKFLOW,
-    {
-      // 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,
-    },
+    { key },
   );
 
   return (

package/dist/templates/recap-workflow/agent.test.ts

@@ -116,7 +116,13 @@ function finishedOutput(over: { kept?: boolean; answered?: boolean } = {}) {
 
 describe("the agent declares its workflow", () => {
   test("under the name ctx.workflows.start resolves it by", () => {
-    expect(Object.keys(agentDef.workflows ?? {})).toEqual(["recap"]);
+    // `toContain` rather than an exact key list: a second workflow is an
+    // invited edit and must not redden a test the author did not write. The
+    // NAME is still pinned, deliberately — this key is a STRING to everything
+    // outside this file (the REST route, `ctx.workflows.get`, a schedule), so
+    // renaming it is a runtime 404 rather than a compile error, and nothing
+    // else says so.
+    expect(Object.keys(agentDef.workflows ?? {})).toContain("recap");
     expect(agentDef.workflows?.recap).toBe(recap);
   });
 
@@ -143,14 +149,21 @@ describe("the agent declares its workflow", () => {
   });
 
   test("discovers every tool in tools/, by file name", () => {
-    // Discovered, not declared: every name here is a file in `tools/`.
-    expect(Object.keys(agentDef.tools).sort()).toEqual([
-      "cancel_recap",
-      "keep_transcript",
-      "recap_progress",
-      "recap_status",
-      "request_recap",
-    ]);
+    // Discovered, not declared: every name here is a file in `tools/`. Asserted
+    // with `arrayContaining`, because dropping a file into `tools/` is the
+    // cheapest edit this template invites and an exact list would turn it into
+    // a failing test in somebody else's project. What still fails is a tool
+    // going MISSING — which is what a broken discovery looks like, and it looks
+    // identical to a template that never had tools.
+    expect(Object.keys(agentDef.tools)).toEqual(
+      expect.arrayContaining([
+        "cancel_recap",
+        "keep_transcript",
+        "recap_progress",
+        "recap_status",
+        "request_recap",
+      ]),
+    );
   });
 });
 

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

@@ -46,7 +46,13 @@ describe("the agent declares itself a workflow app", () => {
   test("under the name the page starts a run by", () => {
     // `useWorkflowSubmit("redline")` 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(["redline"]);
+    // `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("redline");
     expect(agentDef.workflows?.redline).toBe(redline);
   });
 

package/dist/templates/redline/client.tsx

@@ -31,11 +31,13 @@
  * in React state — so a refresh lost it while the loop carried on writing,
  * grading and revising without anywhere to report to. On a desk whose whole
  * subject is a loop that runs several long-form model calls, that is the one
- * failure worth two lines of wiring: `key` is the handle that survives a reload
- * and `recover` is what reads it back, so the draft, the critique trail and the
- * Clear button are all there again.
+ * failure the hook now covers on its own: `useWorkflowSubmit` records every run
+ * under a correlation KEY it mints for this page and asks for that key's newest
+ * run as it mounts, so the draft, the critique trail and the Clear button are
+ * all there again with nothing written here.
  *
- * **The key is opaque and lives in `sessionStorage`, and the brief is why.** A
+ * **The key it mints is opaque and lives in `sessionStorage`, and the brief is
+ * why this page wants exactly that one.** A
  * `?key=` parameter in the page's own URL would survive more — a new tab, a
  * bookmark, a link sent to the person who asked for the piece — and that is
  * exactly what it must not do here. There is no per-user filtering behind
@@ -48,7 +50,9 @@
  *
  * Deriving the key from the brief is worse again: two people briefing the same
  * thing would recover each other's runs, and the key would then carry what they
- * typed into a lookup token the platform deliberately stopped logging.
+ * typed into a lookup token the platform deliberately stopped logging. Both are
+ * things a page could still ask for by passing its own `key`, and this one has
+ * no reason to.
  */
 
 import "@alexkroman1/aai-ui/styles.css";
@@ -60,7 +64,6 @@ import {
   page,
   SubmitButton,
   TextAreaField,
-  useRunKey,
   useWorkflowSubmit,
   WORKFLOW_STATUS_LABELS,
   WorkflowFields,
@@ -121,19 +124,13 @@ export function toInput(values: FormValues): WorkflowInputOf<typeof redline> {
 }
 
 function RedlineDesk() {
-  // This tab's handle on its own drafts — opaque, short, and remembered for the
-  // next load, which is what `recover` 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 "writing what you just briefed" from "picking up where
   // you left off" — the hook reports the run, not who asked for it.
   const [startedHere, setStartedHere] = useState(false);
-  const { submit, run, pending, error, reset } = useWorkflowSubmit<typeof redline>(WORKFLOW, {
-    // 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,
-  });
+  // The reload is covered by the hook's own key — see the module doc for why
+  // this desk wants the tab-scoped one it mints rather than a key of its own.
+  const { submit, run, pending, error, reset } = useWorkflowSubmit<typeof redline>(WORKFLOW);
 
   return (
     <main className="mx-auto flex max-w-2xl flex-col gap-8 p-8">

package/dist/templates/research-workflow/agent.test.ts

@@ -106,7 +106,13 @@ function stubWorkflows(runs: WorkflowRunSnapshot[] = []): WorkflowClient {
 
 describe("the agent declares its workflow", () => {
   test("under the name ctx.workflows.start resolves it by", () => {
-    expect(Object.keys(agentDef.workflows ?? {})).toEqual(["research"]);
+    // `toContain` rather than an exact key list: a second workflow is an
+    // invited edit and must not redden a test the author did not write. The
+    // NAME is still pinned, deliberately — this key is a STRING to everything
+    // outside this file (the REST route, `ctx.workflows.get`, a schedule), so
+    // renaming it is a runtime 404 rather than a compile error, and nothing
+    // else says so.
+    expect(Object.keys(agentDef.workflows ?? {})).toContain("research");
     expect(agentDef.workflows?.research).toBe(research);
   });
 

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/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/spoken-summary/agent.test.ts

@@ -55,13 +55,22 @@ describe("the declaration", () => {
   test("is a workflow app with the one workflow the page starts by name", () => {
     // The page calls `api.start("spokenSummary", …)`, so a rename here is a
     // runtime 400 rather than a compile error. This is what pins it.
-    expect(Object.keys(agentDef.workflows ?? {})).toEqual(["spokenSummary"]);
+    // `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("spokenSummary");
+    expect(agentDef.workflows?.spokenSummary).toBe(spokenSummary);
   });
 
-  test("declares no providers and exactly the one credential its steps read", () => {
+  test("declares the credential its steps read, so a deploy checks for it", () => {
     // A workflow app has no session, so nothing else in its config could name
     // one — and one AssemblyAI key covers transcription, the model and the voice.
-    expect(agentDef.requiredEnv).toEqual(["ASSEMBLYAI_API_KEY"]);
+    // `toContain`, so adding a step that reads a second credential and
+    // declaring it here does not fail this test.
+    expect(agentDef.requiredEnv).toContain("ASSEMBLYAI_API_KEY");
   });
 
   test("takes the recording as an UPLOAD, which is what makes the form a file picker", () => {

package/dist/templates/spoken-summary/client.tsx

@@ -37,14 +37,15 @@
  * in React state — so a refresh lost it while the recording carried on being
  * transcribed, summarized and spoken. The bytes were already stored, so the
  * expensive half had happened; what an empty form invites is somebody uploading
- * the recording again and paying for all four legs twice. `key` is the handle
- * that survives a reload, `recover: true` is what reads it back, and the upload
- * half is already the SDK's — picking the same file again sends only the windows
- * that did not land.
+ * the recording again and paying for all four legs twice. Both halves are the
+ * SDK's now and this page writes neither: `useWorkflowSubmit` records the run
+ * under a correlation KEY it keeps for this page and asks for it again on the
+ * next load, and picking the same file again sends only the windows that did
+ * not land.
  *
- * **The key is `useRunKey()`** — opaque, and in `sessionStorage`, which is the
- * same lifetime as that upload recall, so both halves of a reload make the same
- * promise. What that rules out is a `?key=` parameter, and it is worth being
+ * **That key is `useRunKey()`'s** — opaque, and in `sessionStorage`, which is
+ * the same lifetime as the upload recall, so both halves of a reload make the
+ * same promise. What it rules out is a `?key=` parameter, and it is worth being
  * plain about the trade because this template exists to produce something
  * sendable: a summary you can listen to is exactly the sort of thing somebody
  * forwards, and a URL is how people forward things. But there is no per-user
@@ -57,9 +58,9 @@
  * the recording would be worse again: two people summarizing one file would
  * recover each other's runs.
  *
- * A real app with accounts passes the account's own id instead, and then a
- * summary follows the person to another device — a promise only a login can
- * keep.
+ * A real app with accounts passes the account's own id as `key` instead, and
+ * then a summary follows the person to another device — a promise only a login
+ * can keep.
  */
 
 import "@alexkroman1/aai-ui/styles.css";
@@ -74,7 +75,6 @@ import {
   SubmitButton,
   UploadProgressBar,
   useDownloadUrl,
-  useRunKey,
   useWorkflowSubmit,
   WorkflowFields,
   WorkflowProgress,
@@ -128,20 +128,16 @@ function captionsUrl(text: string, durationMs: number): string {
 }
 
 export function App() {
-  // This tab's handle on its own summaries, in the store the upload recall uses
-  // — see the module doc for why a `?key=` is the wrong trade here.
-  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 sent" 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`. Neither half of the recovery is useful
-  // alone: without `key` there is nothing to find the run by, and without
-  // `recover` the key is only ever written.
+  // `run.output` instead of `unknown`. The reload is the hook's own doing — see
+  // the module doc for why the key it mints is the right one for this page.
   const { submitForm, run, pending, upload, pauseUpload, resumeUpload, error } = useWorkflowSubmit<
     typeof spokenSummary
-  >(WORKFLOW, { api, key, recover: true });
+  >(WORKFLOW, { api });
   const output = run?.status === "completed" ? run.output : undefined;
   // `useDownloadUrl` is the SDK's: the byte route takes the agent's bearer, so the
   // bytes have to be FETCHED and handed to the element as an object URL — and the