@alexkroman1/aai-cli 13.2.0 → 13.3.0

package/dist/scaffold/.env.example

@@ -4,7 +4,23 @@
 # For production, use `aai secret put <NAME>` to set the same keys on the server.
 # In both cases, access secrets in agent code via ctx.env.MY_KEY.
 #
-# Add any secrets your agent needs below:
+# --- The one key the default voice pipeline needs --------------------------
+#
+# `aai dev` runs speech-to-text, the LLM gateway and text-to-speech on a single
+# AssemblyAI key, so this is the credential a session cannot start without.
+# Any ONE of these is enough, and the first two need no aai account:
+#
+#   1. Paste your key after the `=` below.
+#   2. Or export it in your shell: export ASSEMBLYAI_API_KEY=<your key>
+#   3. Or run `aai login`, and `aai dev` will use your account's key.
+#
+# Get a key at https://www.assemblyai.com/dashboard.
+#
+# Leaving it blank is safe: a declared-but-empty value is dropped rather than
+# handed to a provider, so options 2 and 3 still work with this line as it is.
+ASSEMBLYAI_API_KEY=
+
+# Add any other secrets your agent needs below:
 
 # Required only if your agent enables the `web_search` builtin
 # (free key: https://brave.com/search/api/):

package/dist/scaffold/package.json

@@ -9,14 +9,15 @@
     "prestart": "aai build --skip-tests",
     "start": "node server.mjs",
     "build": "aai build",
-    "test": "aai test",
+    "test": "vitest run --exclude \"**/*.eval.test.*\"",
+    "test:agent": "aai test",
     "eval": "aai eval",
     "publish:agent": "aai publish"
   },
   "dependencies": {
-    "@alexkroman1/aai": "^13.2.0",
-    "@alexkroman1/aai-runtime": "^13.2.0",
-    "@alexkroman1/aai-ui": "^13.2.0",
+    "@alexkroman1/aai": "^13.3.0",
+    "@alexkroman1/aai-runtime": "^13.3.0",
+    "@alexkroman1/aai-ui": "^13.3.0",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "tailwindcss": "^4.0.0",
@@ -24,7 +25,7 @@
     "zod": "^4.5.4"
   },
   "devDependencies": {
-    "@alexkroman1/aai-cli": "^13.2.0",
+    "@alexkroman1/aai-cli": "^13.3.0",
     "@tailwindcss/vite": "^4.3.3",
     "@types/node": "^26.4.1",
     "@types/react": "^19.2.18",

package/dist/secret-V1w7y9-j.mjs

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+import { a as ok, n as fail, t as CliError } from "./_output-DbJt9gsl.mjs";
+import { n as log, s as unwrapCancel } from "./_ui-DCt4qZrk.mjs";
+import { f as checkedResponse, p as isStringArray } from "./_studio-DTi3EdXQ.mjs";
+import { t as secretRequest } from "./_slug-api-DlKpj91X.mjs";
+import { isRecord } from "@alexkroman1/aai/utils";
+import * as p from "@clack/prompts";
+import pTimeout from "p-timeout";
+//#region src/secret.ts
+/**
+* The one `no_input` failure for `secret put`, shared by every path that can
+* reach it — the stdin read that came back empty, the refusal when stdin is a
+* terminal and JSON mode cannot prompt, and the prompt the user dismissed —
+* so the three cannot drift.
+*
+* It is built here rather than kept as a fixed tuple so the hint can name the
+* secret AND both ways of supplying a value: that sentence is the contract,
+* and until this commit it appeared nowhere — not in `--help`, not in the
+* scaffolded README (which said it prompts), and not in the failure itself,
+* which said only "Pipe secret value to stdin".
+*/
+function noInput(name, detail) {
+	return {
+		code: "no_input",
+		message: `No value provided for ${name} (${detail})`,
+		hint: `Pipe the value in — \`printf %s "$VALUE" | aai secret put ${name}\` — or run the command on a terminal to be prompted for it.`
+	};
+}
+/**
+* How long stdin may stay SILENT before `secret put` gives up on it.
+*
+* It bounds only the FIRST byte — a producer that has started is then given
+* as long as it likes, because a secret usually comes out of something slow
+* (`pass show`, `op read`, a KMS call) and cutting it off mid-value would be
+* worse than waiting.
+*
+* What the bound is for is stdin with no producer behind it at all: an
+* inherited-but-idle pipe, which is what an agent harness, a CI step, a
+* supervisor and an editor task all hand a child. Reading to EOF is correct
+* and the EOF was never coming, so the command printed NOTHING and blocked
+* forever — on the only documented way to get a credential into production.
+* A bounded wait that ends in a sentence naming both working forms is the
+* whole difference between "unusable" and "I typed it wrong".
+*/
+const STDIN_FIRST_BYTE_MS = 1e4;
+/**
+* Read stdin to EOF, giving up if nothing arrives at all — `undefined` for
+* that case, distinct from `""` for a producer that sent nothing and closed.
+*
+* Hand-rolled rather than `text(process.stdin)` because the deadline has to
+* apply to the first chunk and NOT to the whole read; `p-timeout`'s
+* `message: false` resolves `undefined` instead of rejecting, so there is no
+* timer to clear and no losing branch to reject late.
+*/
+async function readStdinToEnd(stdin, firstByteMs) {
+	const chunks = [];
+	const firstByte = Promise.withResolvers();
+	const ended = Promise.withResolvers();
+	const onData = (chunk) => {
+		chunks.push(chunk);
+		firstByte.resolve(true);
+	};
+	const onEnd = () => {
+		firstByte.resolve(true);
+		ended.resolve();
+	};
+	const onError = (err) => {
+		firstByte.reject(err);
+		ended.reject(err);
+	};
+	stdin.on("data", onData).once("end", onEnd).once("error", onError);
+	try {
+		if (!await pTimeout(firstByte.promise, {
+			milliseconds: firstByteMs,
+			message: false
+		})) return void 0;
+		await ended.promise;
+		return Buffer.concat(chunks).toString("utf8").trim();
+	} finally {
+		stdin.off("data", onData).off("end", onEnd).off("error", onError);
+		stdin.pause();
+	}
+}
+/**
+* The value for `secret put`, from whichever source is actually available —
+* or `undefined` to mean "prompt", which {@link executeSecretPut} does.
+*
+* Keyed off STDIN, deliberately, and never off the output mode. A stdin read
+* resolves at EOF and a terminal never sends one, so keying the read off
+* `mode === "json"` — which is decided by STDOUT — made `aai secret put NAME`
+* print NOTHING and block forever in every context where stdout is not a
+* terminal but stdin still is: a CI step, `| tee`, an agent harness, an
+* editor task. That is the worst failure a CLI can have on the only
+* documented way to get a credential into production, and it is why each of
+* the three cases below is answered at once:
+*
+* - stdin is a pipe or a file: read it to EOF — the documented contract —
+*   bounded on the FIRST byte so an idle inherited pipe cannot block the
+*   command forever (see {@link STDIN_FIRST_BYTE_MS}). An empty read is
+*   refused rather than sent to the server.
+* - stdin is a terminal, human output: `undefined`, so the executor prompts.
+* - stdin is a terminal, JSON output: refused immediately. JSON mode promises
+*   exactly one result line on stdout and cannot spend it on a prompt — so it
+*   says which two forms do work instead of waiting for an EOF that a person
+*   sitting at a terminal has no reason to send.
+*/
+async function resolveSecretValue(name, mode, io = {}) {
+	if (!(io.stdinIsTTY ?? Boolean(process.stdin.isTTY))) {
+		const firstByteMs = io.firstByteMs ?? STDIN_FIRST_BYTE_MS;
+		const piped = await readStdinToEnd(io.stdin ?? process.stdin, firstByteMs);
+		if (piped) return piped;
+		const { code, message, hint } = noInput(name, piped === void 0 ? `nothing arrived on stdin within ${Math.round(firstByteMs / 1e3)}s` : "stdin was empty");
+		throw new CliError(code, message, hint);
+	}
+	if (mode === "json") {
+		const { code, message, hint } = noInput(name, "stdin is a terminal and --json cannot prompt");
+		throw new CliError(code, message, hint);
+	}
+}
+/**
+* Execute secret put. If `value` is provided, use it directly (the stdin
+* path). If not, prompt for it — masked — which is what
+* {@link resolveSecretValue} returning `undefined` asks for.
+*/
+async function executeSecretPut(cwd, name, value, server) {
+	let secretValue = value;
+	if (!secretValue) {
+		const result = unwrapCancel(await p.password({ message: `Enter value for ${name}` }));
+		if (!result) {
+			const { code, message, hint } = noInput(name, "the prompt came back empty");
+			return fail(code, message, hint);
+		}
+		secretValue = result;
+	}
+	const { target } = await secretRequest(cwd, "", {
+		method: "PUT",
+		body: { [name]: secretValue },
+		action: "secret"
+	}, server);
+	log.success(`Set ${name} for ${target}`);
+	return ok({ name });
+}
+async function executeSecretDelete(cwd, name, server) {
+	const { target } = await secretRequest(cwd, `/${encodeURIComponent(name)}`, {
+		method: "DELETE",
+		action: "secret"
+	}, server);
+	log.success(`Deleted ${name} from ${target}`);
+	return ok({ name });
+}
+async function executeSecretList(cwd, server) {
+	const { data, target } = await secretRequest(cwd, "", { action: "secret" }, server);
+	const { vars } = checkedResponse(data, (value) => isRecord(value) && isStringArray(value.vars), `the secret list for ${target}`);
+	if (vars.length === 0) log.info("No secrets set. Use `aai secret put <name>` to add one.");
+	else {
+		log.message(`${vars.length} secret${vars.length === 1 ? "" : "s"}:`);
+		for (const v of vars) log.message(`  ${v}`);
+	}
+	return ok({ secrets: vars });
+}
+//#endregion
+export { executeSecretDelete, executeSecretList, executeSecretPut, resolveSecretValue };

package/dist/secret.d.ts

@@ -1,11 +1,43 @@
-import { type CommandResult } from "./_output.ts";
+import type { Readable } from "node:stream";
+import { type CommandResult, type OutputMode } from "./_output.ts";
 /**
- * The one `no_input` failure for `secret put`, shared by the JSON-mode stdin
- * path (cli.ts) and the TTY prompt path below so the two can't drift.
+ * The environment {@link resolveSecretValue} branches on, as a seam a spec can
+ * supply — a `Readable` rather than a fake reader function, so a test drives
+ * the real wait (the part that blocked) and needs no cast to stand in for
+ * `process.stdin`.
  */
-export declare const NO_INPUT: readonly ["no_input", "No value provided", "Pipe secret value to stdin"];
-/** Read secret value from stdin (for non-TTY / piped input). */
-export declare function readStdin(): Promise<string>;
+export type SecretValueIo = {
+    /** Defaults to `process.stdin`. */
+    stdin?: Readable | undefined;
+    /** Defaults to whether the real stdin is a terminal. */
+    stdinIsTTY?: boolean | undefined;
+    /** Defaults to {@link STDIN_FIRST_BYTE_MS}. */
+    firstByteMs?: number | undefined;
+};
+/**
+ * The value for `secret put`, from whichever source is actually available —
+ * or `undefined` to mean "prompt", which {@link executeSecretPut} does.
+ *
+ * Keyed off STDIN, deliberately, and never off the output mode. A stdin read
+ * resolves at EOF and a terminal never sends one, so keying the read off
+ * `mode === "json"` — which is decided by STDOUT — made `aai secret put NAME`
+ * print NOTHING and block forever in every context where stdout is not a
+ * terminal but stdin still is: a CI step, `| tee`, an agent harness, an
+ * editor task. That is the worst failure a CLI can have on the only
+ * documented way to get a credential into production, and it is why each of
+ * the three cases below is answered at once:
+ *
+ * - stdin is a pipe or a file: read it to EOF — the documented contract —
+ *   bounded on the FIRST byte so an idle inherited pipe cannot block the
+ *   command forever (see {@link STDIN_FIRST_BYTE_MS}). An empty read is
+ *   refused rather than sent to the server.
+ * - stdin is a terminal, human output: `undefined`, so the executor prompts.
+ * - stdin is a terminal, JSON output: refused immediately. JSON mode promises
+ *   exactly one result line on stdout and cannot spend it on a prompt — so it
+ *   says which two forms do work instead of waiting for an EOF that a person
+ *   sitting at a terminal has no reason to send.
+ */
+export declare function resolveSecretValue(name: string, mode: OutputMode, io?: SecretValueIo): Promise<string | undefined>;
 type SecretPutData = {
     name: string;
 };
@@ -16,8 +48,9 @@ type SecretListData = {
     secrets: string[];
 };
 /**
- * Execute secret put. If `value` is provided, use it directly (non-TTY path).
- * If not provided, prompt interactively (TTY path).
+ * Execute secret put. If `value` is provided, use it directly (the stdin
+ * path). If not, prompt for it — masked — which is what
+ * {@link resolveSecretValue} returning `undefined` asks for.
  */
 export declare function executeSecretPut(cwd: string, name: string, value: string | undefined, server: string | undefined): Promise<CommandResult<SecretPutData>>;
 export declare function executeSecretDelete(cwd: string, name: string, server: string | undefined): Promise<CommandResult<SecretDeleteData>>;

package/dist/{studio-BxAS_FQQ.mjs → studio-BpMCfUNx.mjs}

@@ -1,17 +1,17 @@
 #!/usr/bin/env node
-import { a as ok, t as CliError } from "./_output-CKkmWs7i.mjs";
-import { n as log, t as fmtUrl } from "./_ui-u7T4YooX.mjs";
-import { s as updateProjectConfig } from "./_config-CmJOFsAP.mjs";
-import { t as resolveServerEnv } from "./_server-common-6e0QI4mq.mjs";
-import { a as resolveDeployTarget } from "./_agent-BTwZJu4P.mjs";
-import { layerScaffold } from "./_templates-0Zr2z6yA.mjs";
-import { a as publishStudioProject, c as studioProjectUrl, f as checkedResponse, i as projectNameFromDir, n as fetchStudioProject, o as pushStudioSource, r as listStudioProjects, s as studioProjectApiUrl, t as collectSourceFiles, u as apiRequest } from "./_studio-B1waXMuR.mjs";
+import { a as ok, t as CliError } from "./_output-DbJt9gsl.mjs";
+import { n as log, t as fmtUrl } from "./_ui-DCt4qZrk.mjs";
+import { s as updateProjectConfig } from "./_config-ZY2euhdh.mjs";
+import { t as resolveServerEnv } from "./_server-common-BV4_CrP3.mjs";
+import { a as resolveDeployTarget } from "./_agent-Clbq3a4h.mjs";
+import { layerScaffold } from "./_templates-V4l5sZJy.mjs";
+import { a as publishStudioProject, c as studioProjectUrl, f as checkedResponse, i as projectNameFromDir, n as fetchStudioProject, o as pushStudioSource, r as listStudioProjects, s as studioProjectApiUrl, t as collectSourceFiles, u as apiRequest } from "./_studio-DTi3EdXQ.mjs";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { isRecord, omitUndefined } from "@alexkroman1/aai/utils";
 import { mkdir, readdir, writeFile } from "node:fs/promises";
 import { isPathInside } from "@alexkroman1/aai-runtime/internal";
-//#region studio.ts
+//#region src/studio.ts
 /**
 * The studio-workspace commands: `aai list`, `aai pull`, `aai push`,
 * `aai publish`.
@@ -164,7 +164,7 @@ async function syncEnvSecrets(cwd, serverUrl, apiKey, project) {
 }
 async function executePublish(opts) {
 	if (!opts.skipTypecheck) {
-		const { assertTypechecks } = await import("./_typecheck-gate-BXvUNnfs.mjs");
+		const { assertTypechecks } = await import("./_typecheck-gate-sV4N5F93.mjs");
 		await assertTypechecks(opts.cwd);
 	}
 	const pushed = await pushProject(opts);

package/dist/templates/briefing-desk/agent.test.ts

@@ -63,10 +63,14 @@ function desk(
 
 describe("the desk itself", () => {
   test("has no web tools of its own — everything goes through a subagent", () => {
-    expect(authoredAgent.builtinTools ?? []).toEqual([]);
-    // And the researcher does, which is the split the template exists to show.
+    // Stated as the claim the test's name makes, rather than as "no builtins at
+    // all": giving the desk `run_code` is a reasonable edit, and it does not
+    // put the web in front of the desk.
+    expect(authoredAgent.builtinTools ?? []).not.toContain("web_search");
+    expect(authoredAgent.builtinTools ?? []).not.toContain("visit_webpage");
+    // And the subagents do, which is the split the template exists to show.
     expect(researcher.builtinTools).toContain("web_search");
-    expect(factChecker.builtinTools).toEqual(["web_search"]);
+    expect(factChecker.builtinTools).toContain("web_search");
   });
 
   test("gives the checker a tighter budget than the researcher", () => {

package/dist/templates/call-audit/agent.test.ts

@@ -182,15 +182,26 @@ describe("the declaration", () => {
   test("is a workflow app with the one workflow the page starts by name", () => {
     // The page calls `api.start("audit", …)`, so a rename here is a runtime 400
     // rather than a compile error. This is what pins it.
-    expect(Object.keys(agentDef.workflows ?? {})).toEqual(["audit"]);
+    // `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("audit");
+    expect(agentDef.workflows?.audit).toBe(audit);
   });
 
-  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.
     // Note what is NOT here: ffmpeg. `requiredEnv` checks the environment, and a
     // binary on `PATH` is not an environment variable.
-    expect(agentDef.requiredEnv).toEqual(["ASSEMBLYAI_API_KEY"]);
+    //
+    // `toContain` rather than an exact list: a step of your own that reads a
+    // second credential belongs in `requiredEnv` beside this one, and declaring
+    // it must 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/call-audit/client.tsx

@@ -30,15 +30,16 @@
  * cutting and auditing. On this template that is the most expensive orphaning
  * in `templates/`: the recording is already stored, so the work is paid for, and
  * a page with no handle on it invites somebody to upload a 700 MB call a second
- * time and run the whole pipeline again. `key` is the handle that survives a
- * reload and `recover: true` is what reads it back.
+ * time and run the whole pipeline again. The handle that survives a reload is a
+ * correlation KEY, and this desk passes none: `useWorkflowSubmit` mints one,
+ * records every run under it, and asks for that key's newest run as it mounts.
  *
- * The upload half of a reload is already the SDK's: `useWorkflowSubmit`
- * remembers the id it minted, so picking the same file again sends only the
- * windows that did not land. What it needs from the page is the same LIFETIME
- * on both halves, which is the first reason this desk takes `useRunKey()`'s
- * default — `sessionStorage`, the same store the upload recall uses. A handle
- * that outlived it would promise a return the other half cannot keep.
+ * The upload half of a reload is the same hook's: it remembers the id it
+ * minted, so picking the same file again sends only the windows that did not
+ * land. Both halves therefore have the same LIFETIME — `sessionStorage`, one
+ * store — which is the first reason this desk wants the default rather than a
+ * key of its own. A handle that outlived it would promise a return the other
+ * half cannot keep.
  *
  * ## Why the artifact being shareable does NOT make the key shareable
  *
@@ -61,7 +62,7 @@
  * needs none of it — the page renders the audit and offers `Download audit.mp3`,
  * so a person sends the file and the findings deliberately, to exactly who they
  * meant. A shareable key would trade a deliberate send for an accidental one, on
- * the most sensitive input any template here accepts. It stays in
+ * the most sensitive input any template here accepts. The default key stays in
  * `sessionStorage`, which covers the reload this section is about and dies with
  * the tab.
  *
@@ -81,7 +82,6 @@ import {
   SubmitButton,
   UploadProgressBar,
   useDownloadUrl,
-  useRunKey,
   useWorkflowSubmit,
   WorkflowFields,
   WorkflowProgress,
@@ -146,20 +146,17 @@ function Findings({ title, items }: { title: string; items: string[] }) {
 }
 
 export function App() {
-  // This tab's handle on its own audits, in the store the upload recall uses —
-  // see the module doc for why a `?key=` is the wrong trade on this desk.
-  const key = useRunKey();
   // Did THIS load start the run? A reload cannot have, and that is the only way
   // the page can tell "auditing what you just uploaded" 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 — both halves of it — is the
+  // hook's own doing; see the module doc for why the key it mints is the one
+  // this desk wants.
   const { submitForm, run, pending, upload, pauseUpload, resumeUpload, error } = useWorkflowSubmit<
     typeof audit
-  >(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

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.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.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/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/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");
+    }
   });
 });