@alexkroman1/aai-cli 13.1.0 → 13.3.0

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

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

package/dist/templates/pizza-ordering/agent.eval.test.ts

@@ -13,7 +13,7 @@ import type { SessionEvent } from "@alexkroman1/aai/protocol";
 // SCRIPTED model (its `stubReply`), which still boots this agent, still
 // resolves `tools/`, and still executes the tool a script names — so a stub run
 // proves the wiring and proves nothing about what the agent chose.
-import { lastStateIn, toolResultIn } from "@alexkroman1/aai-runtime/eval";
+import { lastStateIn, statesIn, toolNames, toolResultIn } from "@alexkroman1/aai-runtime/eval";
 import { describeEval } from "@alexkroman1/aai-runtime/eval/vitest";
 import { expect } from "vitest";
 import { z } from "zod";
@@ -44,9 +44,14 @@ const ProjectedOrder = z.object({
  */
 const lastPushedView = (events: readonly SessionEvent[]) => lastStateIn(events, ProjectedOrder);
 
-/** Every cart the session pushed, in stream order. */
-const pushedViews = (events: readonly SessionEvent[]) =>
-  events.flatMap((e) => (e.type === "state.updated" ? [ProjectedOrder.parse(e.state)] : []));
+/**
+ * Every cart the session pushed, in stream order — `statesIn` is `lastStateIn`'s
+ * plural half, and takes the schema for the same reason.
+ *
+ * The SEQUENCE is the stronger claim: not "the cart is not placed now" but "no
+ * frame the customer ever saw showed it placed".
+ */
+const pushedViews = (events: readonly SessionEvent[]) => statesIn(events, ProjectedOrder);
 
 describeEval(agentDef, (test) => {
   test(
@@ -58,7 +63,7 @@ describeEval(agentDef, (test) => {
 
       // One tool, and the right one: quoting a price without adding the pizza,
       // or adding it twice, are both real findings.
-      expect(turn.toolCalls.map((c) => c.name)).toEqual(["add_pizza"]);
+      expect(toolNames(turn.toolCalls)).toEqual(["add_pizza"]);
       const call = turn.toolCalls[0]!;
       const args = call.args as { size: string; crust: string; toppings: string[] };
       expect(args.size).toBe("large");
@@ -106,7 +111,7 @@ describeEval(agentDef, (test) => {
       // turn leaves the model with nothing to address.
       const turn = await session.say("Actually, make that a large.");
 
-      expect(turn.toolCalls.map((c) => c.name)).toEqual(["update_pizza"]);
+      expect(toolNames(turn.toolCalls)).toEqual(["update_pizza"]);
       const call = turn.toolCalls[0]!;
       expect(call.args).toMatchObject({ pizza_id: 1, size: "large" });
 

package/dist/templates/plan-and-execute/agent.eval.test.ts

@@ -24,7 +24,13 @@
 
 /** The def a DEPLOYED agent runs — see `agent.test.ts` on why the glob is here. */
 import agentDef from "virtual:aai/agent";
-import { type EvalSession, lastStateIn } from "@alexkroman1/aai-runtime/eval";
+import {
+  describeToolCalls,
+  describeTurn,
+  type EvalSession,
+  lastStateIn,
+  toolNames,
+} from "@alexkroman1/aai-runtime/eval";
 import { describeEval } from "@alexkroman1/aai-runtime/eval/vitest";
 import { expect } from "vitest";
 import { z } from "zod";
@@ -57,8 +63,6 @@ const ProjectedPlan = z.object({
  */
 const planState = (session: EvalSession) => lastStateIn(session.events(), ProjectedPlan);
 
-const named = (calls: readonly { name: string }[]): string[] => calls.map((call) => call.name);
-
 describeEval(agentDef, (test) => {
   test(
     "the stage the desk reports is the flow's, not a guess at the plan",
@@ -122,7 +126,10 @@ describeEval(agentDef, (test) => {
         "I want to work out whether it is cheaper to take the train or fly from London to Edinburgh next month.",
       );
       const started = session.toolCalls().find((call) => call.name === "start_plan");
-      expect(started, `tools called: ${named(session.toolCalls()).join(", ")}`).toBeDefined();
+      // The whole SESSION's calls, not one turn's: the plan may be started on
+      // either utterance, and "expected undefined to be defined" says nothing
+      // about a desk that talked instead. `describeToolCalls` is that sentence.
+      expect(started, describeToolCalls(session.toolCalls())).toBeDefined();
       const planned = planState(session);
       // The tool's own result rides in the message: a planner that FAILED (a
       // gateway error, a schema the provider would not honour) writes nothing,
@@ -131,8 +138,8 @@ describeEval(agentDef, (test) => {
       expect(planned?.plan.length ?? 0).toBeGreaterThan(0);
 
       const worked = await session.say("Yes, go ahead and start on it.");
-      const calls = named(worked.toolCalls).filter((name) => name === "work_next_step").length;
-      expect(calls, `tools called: [${named(worked.toolCalls).join(", ")}]`).toBeGreaterThan(0);
+      const calls = toolNames(worked.toolCalls).filter((name) => name === "work_next_step").length;
+      expect(calls, describeTurn(worked)).toBeGreaterThan(0);
 
       const after = planState(session);
       const done = after?.done ?? [];
@@ -180,7 +187,7 @@ describeEval(agentDef, (test) => {
       const revised = turn.toolCalls.find((call) => call.name === "revise_plan");
       expect(
         revised,
-        `tools called: ${named(turn.toolCalls).join(", ")} — the caller changed the objective, ` +
+        `${describeTurn(turn)} — the caller changed the objective, ` +
           "so this is `revise_plan`, not a plan rewritten by hand",
       ).toBeDefined();
       expect(revised?.args.instruction).toBeTruthy();

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.eval.test.ts

@@ -62,8 +62,15 @@
  * this file SHIPS — see `agent.test.ts`.
  */
 import agentDef from "virtual:aai/agent";
+import { stubGatewayRoute } from "@alexkroman1/aai/testing";
 import { installStubStepFetch } from "@alexkroman1/aai/testing/vitest";
-import type { EvalToolCall, EvalWorkflows } from "@alexkroman1/aai-runtime/eval";
+import {
+  describeToolCalls,
+  type EvalToolCall,
+  type EvalWorkflows,
+  toolResultIn,
+  toolResultsIn,
+} from "@alexkroman1/aai-runtime/eval";
 import { describeEval } from "@alexkroman1/aai-runtime/eval/vitest";
 import { expect } from "vitest";
 import { z } from "zod";
@@ -116,17 +123,24 @@ type ScriptedProvider = {
  * rather than answering an empty 200: a step calling something nobody expected
  * is a finding, where an empty body reads as a provider that said nothing.
  *
+ * The model leg is `stubGatewayRoute`'s, first, because it is the one leg whose
+ * shape this file cannot check: the completion envelope is a WIRE shape, so a
+ * field typed one off does not fail — `stepGenerate` reads no content, reports
+ * an empty completion, and the case blames the recap. The reader routes off the
+ * SDK's own completions PATH and answers `undefined` for everything else, which
+ * is what lets it sit in front of the three batch legs below it.
+ *
  * `hold` keeps the FIRST poll pending, and it is the only way to observe a run
  * that is still going: a durable `sleep` is skipped here, so an unheld run
  * burns its whole poll loop in milliseconds.
  */
 function stubProvider(options: { hold?: boolean; ending?: Ending } = {}): ScriptedProvider {
   const gate = Promise.withResolvers<void>();
+  const model = stubGatewayRoute(RECAP_JSON);
   let polls = 0;
   const stub = installStubStepFetch(async (request) => {
-    if (request.url.includes("/chat/completions")) {
-      return { body: { choices: [{ message: { content: RECAP_JSON } }] } };
-    }
+    const recapped = model.route(request);
+    if (recapped) return recapped;
     if (request.method === "POST") return { body: { id: TRANSCRIPT_ID, status: "queued" } };
     // The compensation. A real DELETE removes the transcript from the account,
     // which is what makes "a failed run leaves nothing behind" a claim rather
@@ -158,21 +172,32 @@ const Cancelled = z.object({ cancelled: z.boolean(), note: z.string() });
  *
  * Parsed rather than regexed: a tool result reaches the event stream as a
  * serialized string, and a shape that stopped matching should fail HERE naming
- * the field instead of handing the next assertion `undefined`.
+ * the field instead of handing the next assertion `undefined`. That is
+ * `toolResultsIn`'s job, and the half it does better than the filter-and-map
+ * this was: a call with no result THROWS naming its position, where
+ * `one.result !== undefined` dropped it — so a tool that was called and never
+ * returned left a shorter list and a case that read the calls it did get.
  */
-function recapStarts(calls: readonly EvalToolCall[]): z.infer<typeof RecapStart>[] {
-  return calls
-    .filter((one) => one.name === "request_recap" && one.result !== undefined)
-    .map((one) => RecapStart.parse(JSON.parse(String(one.result))));
+function recapStarts(calls: readonly EvalToolCall[]): readonly z.infer<typeof RecapStart>[] {
+  return toolResultsIn(calls, "request_recap", RecapStart);
 }
 
-/** The run id the first `request_recap` of this turn reported. */
+/**
+ * The run id the FIRST `request_recap` of this turn reported.
+ *
+ * `recapStarts` rather than `toolResultIn`: a turn is allowed more than one call
+ * here — the case below says so in as many words, a desk that asks twice being
+ * the model's business — and the singular reader refuses a second one on
+ * purpose. What is asserted about the extras is that each was REFUSED with the
+ * run this found.
+ */
 function startedRunId(calls: readonly EvalToolCall[]): string {
   const [first] = recapStarts(calls);
   if (first === undefined) {
-    throw new Error(
-      `the desk called no request_recap: ${calls.map((one) => one.name).join(", ") || "(no tools)"}`,
-    );
+    // `describeToolCalls` is the harness's own sentence for this — including
+    // "called no tools", which is the answer a desk that asked a question
+    // instead of acting gives and the one an empty list reads as truncation.
+    throw new Error(`no request_recap in this turn: ${describeToolCalls(calls)}`);
   }
   return first.runId;
 }
@@ -207,14 +232,19 @@ const START_TURN = [
  * Not tidiness: the scripted provider is unpublished when the test that
  * installed it finishes, so a body still mid-flight would make its next request
  * against whatever the next case publishes — or against the real provider, with
- * a real key. A run drained here COMPLETES rather than failing, and the last
- * thing it does on the way is delete its own transcript: the retention gate's
- * window closes with nobody having answered, which is the safe default. See the
- * header, and the case that pins it.
+ * a real key. `close()` says so on stderr (`EvalRunAbandoned`) when a case
+ * forgets, which is a report rather than a fix — the wait is `settleAll`'s and
+ * the RELEASE is this template's, because what holds the run in flight is this
+ * file's own gate and nothing in the harness can open one.
+ *
+ * A run drained here COMPLETES rather than failing, and the last thing it does
+ * on the way is delete its own transcript: the retention gate's window closes
+ * with nobody having answered, which is the safe default. See the header, and
+ * the case that pins it.
  */
 async function drain(workflows: EvalWorkflows | undefined, provider: ScriptedProvider) {
   provider.release();
-  for (const run of await (workflows?.runs() ?? [])) await workflows?.settle(run.runId, recap);
+  await workflows?.settleAll();
 }
 
 describeEval(
@@ -328,8 +358,7 @@ describeEval(
         const runId = startedRunId(started.toolCalls);
         const turn = await session.say("Forget it — cancel that, please.");
 
-        const cancel = turn.toolCalls.find((one) => one.name === "cancel_recap");
-        const answer = Cancelled.parse(JSON.parse(String(cancel?.result)));
+        const answer = toolResultIn(turn.toolCalls, "cancel_recap", Cancelled);
         expect(answer.cancelled).toBe(true);
         // The sentence is a documented promise of this template, not a
         // decoration: cancellation is NOT cooperative here, so the transcript

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.eval.test.ts

@@ -29,6 +29,7 @@
 // journal, no replay, and no per-step retry, so a rate-limited live run FAILS
 // where a deployed one would have ridden it out. The tier that really resumes a
 // run is `aai-cli`'s `dev-workflow.scenario.test.ts`.
+import { stubGatewayRoute } from "@alexkroman1/aai/testing";
 import { installStubStepFetch } from "@alexkroman1/aai/testing/vitest";
 import { describeWorkflowEval } from "@alexkroman1/aai-runtime/eval/vitest";
 import { expect } from "vitest";
@@ -52,32 +53,36 @@ const critique = (verdict: "ship" | "revise", score = 8): string =>
     notes: verdict === "ship" ? [] : ["Say what happens to the handover", "Name the start date"],
   });
 
-/** One gateway reply, in the envelope `stepGenerate` reads. */
-const reply = (content: string) => ({ body: { choices: [{ message: { content } }] } });
-
 /**
  * Answer the gateway with `contents`, in order, and record what each stage asked.
  *
- * The last reply repeats, matching `stubGateway`'s convention — a loop cannot
- * know how many calls it will make, and a script that ran out mid-loop would
- * fail on the script rather than on the code. `installStubStepFetch` rather than
- * `installStubGateway`: `stepGenerate` goes through the published `stepFetch`
- * slot, and a published slot BEATS a stubbed global, so stubbing the global here
- * would test a path production does not take.
+ * `stubGatewayRoute` owns both halves this file used to hand-write. The
+ * ENVELOPE, because it is a WIRE shape and a field typed one off does not fail —
+ * `stepGenerate` reads no content, reports an empty completion, and the case
+ * blames the loop. And the CURSOR: the last reply repeats, because a loop cannot
+ * know how many calls it will make, so a script that said one thing forever
+ * could only ever drive it into its budget and one that ran out mid-loop would
+ * fail on the script rather than on the code. Both of those are now the SDK's
+ * one copy rather than this file's second.
+ *
+ * `installStubStepFetch` rather than `installStubGateway`: `stepGenerate` goes
+ * through the published `stepFetch` slot, and a published slot BEATS a stubbed
+ * global, so stubbing the global here would test a path production does not
+ * take. Anything that is not a completion request THROWS — every step in this
+ * body is a model call, so a request the route does not recognise is a finding,
+ * and answering it with a reply anyway is how a stage that started dialling
+ * something else would pass.
  */
 function scriptGateway(contents: readonly string[]) {
-  let next = 0;
-  const fetched = installStubStepFetch(() => {
-    const content = contents.at(Math.min(next, contents.length - 1)) ?? "";
-    next += 1;
-    return reply(content);
+  const model = stubGatewayRoute(contents);
+  installStubStepFetch((request) => {
+    const answered = model.route(request);
+    if (answered === undefined) {
+      throw new Error(`unexpected step request in an eval: ${request.method} ${request.url}`);
+    }
+    return answered;
   });
-  return fetched;
-}
-
-/** Every prompt the gateway was sent, in call order. */
-function promptsOf(fetched: ReturnType<typeof scriptGateway>): string[] {
-  return fetched.calls.map((call) => String(call.body ?? ""));
+  return model;
 }
 
 describeWorkflowEval(agentDef, (test) => {
@@ -140,7 +145,7 @@ describeWorkflowEval(agentDef, (test) => {
     // running, and asking it and then accepting whatever it says is not evidence
     // about the budget. What this pins is the loop's arithmetic — the half a
     // live case cannot reach.
-    const fetched = scriptGateway([
+    const model = scriptGateway([
       DRAFT,
       critique("revise", 4),
       `${DRAFT} It starts on the first Monday of the month.`,
@@ -170,12 +175,15 @@ describeWorkflowEval(agentDef, (test) => {
     ).toBe(true);
     // One draft plus a critique-and-revise pair per round. A loop that critiqued
     // twice, or revised the round it shipped, changes this number.
-    expect(fetched.calls).toHaveLength(1 + 2 * MAX_ROUNDS);
+    expect(model.calls).toHaveLength(1 + 2 * MAX_ROUNDS);
 
     // `briefBlock` is what keeps the three stages from drifting apart, and this is
     // the assertion behind that claim: the writer, the critic AND the reviser were
-    // all shown the same brief and the same must-cover point.
-    const prompts = promptsOf(fetched);
+    // all shown the same brief and the same must-cover point. Read off the
+    // recorded `prompt` — the USER message — rather than off the raw request
+    // body, which is the whole serialized request and would let a `model` id or a
+    // `temperature` satisfy one of these `toContain`s.
+    const prompts = model.calls.map((call) => call.prompt);
     expect(prompts).toHaveLength(1 + 2 * MAX_ROUNDS);
     for (const prompt of prompts) {
       expect(prompt).toContain("quokka");

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">