@alexkroman1/aai-cli 13.2.0 → 14.0.0

package/dist/secret-Cjp912yF.mjs

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+import { a as ok, n as fail, t as CliError } from "./_output-DBP9Op_d.mjs";
+import { n as log, s as unwrapCancel } from "./_ui-DCt4qZrk.mjs";
+import { f as checkedResponse, p as isStringArray } from "./_studio-DnR_BqFp.mjs";
+import { t as secretRequest } from "./_slug-api-CGvc2YSQ.mjs";
+import { isRecord, plural } 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} ${plural(vars.length, "secret")}:`);
+		for (const v of vars) log.message(`  ${v}`);
+	}
+	return ok({ secrets: vars });
+}
+//#endregion
+export { executeSecretDelete, executeSecretList, executeSecretPut, resolveSecretValue };

package/dist/secret.d.ts

@@ -1,25 +1,60 @@
-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>;
-type SecretPutData = {
-    name: 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;
 };
-type SecretDeleteData = {
+/**
+ * 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>;
+/**
+ * Both the put and the delete result — one shape, so one name. They were two
+ * distinct aliases for `{ name: string }`, which implied a difference that does
+ * not exist and left "which alias meant the secret result" to be re-decided.
+ */
+type SecretNameData = {
     name: string;
 };
 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>>;
+export declare function executeSecretPut(cwd: string, name: string, value: string | undefined, server: string | undefined): Promise<CommandResult<SecretNameData>>;
+export declare function executeSecretDelete(cwd: string, name: string, server: string | undefined): Promise<CommandResult<SecretNameData>>;
 export declare function executeSecretList(cwd: string, server: string | undefined): Promise<CommandResult<SecretListData>>;
 export {};

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

@@ -1,17 +1,18 @@
 #!/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-DBP9Op_d.mjs";
+import { n as log, t as fmtUrl } from "./_ui-DCt4qZrk.mjs";
+import { l as formatCappedList } from "./_utils-D5JGcjiW.mjs";
+import { s as updateProjectConfig } from "./_config-DYzC6WMD.mjs";
+import { t as resolveServerEnv } from "./_server-common-vILJp3it.mjs";
+import { o as resolveDeployTarget } from "./_agent-BzUeqOdj.mjs";
+import { layerScaffold } from "./_templates-CK4oKoeX.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-DnR_BqFp.mjs";
 import { existsSync } from "node:fs";
 import path from "node:path";
-import { isRecord, omitUndefined } from "@alexkroman1/aai/utils";
+import { isRecord, omitUndefined, plural } 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`.
@@ -62,7 +63,7 @@ async function notFoundHint(serverUrl, apiKey) {
 	const projects = await listStudioProjects(serverUrl, apiKey).catch(() => null);
 	if (projects === null) return "Run `aai list` to see your projects.";
 	if (projects.length === 0) return "This login has no studio projects at all. If yours are in the studio, the CLI is linked to a different account — run `aai login` again, approve it in a browser signed in to the account that owns the project, then `aai list`.";
-	return `Your projects: ${projects.slice(0, 10).join(", ")}${projects.length > 10 ? `, and ${projects.length - 10} more` : ""}.`;
+	return `Your projects: ${formatCappedList(projects)}.`;
 }
 async function executePull(opts) {
 	const { serverUrl, apiKey } = await resolveDeployTarget(opts.cwd, opts.server);
@@ -159,17 +160,14 @@ async function syncEnvSecrets(cwd, serverUrl, apiKey, project) {
 		method: "PUT",
 		body: env
 	});
-	log.info(`Synced ${names.length} secret${names.length === 1 ? "" : "s"} from .env`);
+	log.info(`Synced ${names.length} ${plural(names.length, "secret")} from .env`);
 	return names;
 }
 async function executePublish(opts) {
-	if (!opts.skipTypecheck) {
-		const { assertTypechecks } = await import("./_typecheck-gate-BXvUNnfs.mjs");
-		await assertTypechecks(opts.cwd);
-	}
+	const { assertTypechecks } = await import("./_typecheck-gate-U3jcil8L.mjs");
+	await assertTypechecks(opts.cwd, { skip: opts.skipTypecheck });
 	const pushed = await pushProject(opts);
 	const { project, serverUrl, apiKey } = pushed;
-	const hadSlug = pushed.slug !== void 0;
 	if (pushed.slug) await syncEnvSecrets(opts.cwd, serverUrl, apiKey, project);
 	log.step(`Publishing ${project} (builds in the project's sandbox)…`);
 	const result = checkedResponse(await publishStudioProject(serverUrl, apiKey, project, { skipTypecheck: opts.skipTypecheck }), (value) => isRecord(value) && typeof value.slug === "string" && typeof value.output === "string", `the publish route at ${serverUrl}`);
@@ -178,7 +176,7 @@ async function executePublish(opts) {
 		serverUrl,
 		slug: result.slug
 	});
-	if (!hadSlug) {
+	if (!pushed.slug) {
 		if ((await syncEnvSecrets(opts.cwd, serverUrl, apiKey, result.slug)).length > 0) log.info("They apply on the next `aai publish`.");
 	}
 	const agentUrl = `${serverUrl}/${result.slug}`;

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

@@ -32,7 +32,7 @@
 import { readdir } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { FatalError, RetryableError } from "@alexkroman1/aai/step-errors";
-import { createWorkflowCtx, stubSpeech, WORKFLOW_CTX_NOW } from "@alexkroman1/aai/testing";
+import { createWorkflowContext, stubSpeech, WORKFLOW_CONTEXT_NOW } from "@alexkroman1/aai/testing";
 import {
   installStubGateway,
   installStubReporter,
@@ -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", () => {
@@ -505,7 +516,7 @@ describe("planning where to cut", () => {
   test("the last segment never addresses a byte the file does not have", () => {
     // The twelve-byte bug this API shape exists to prevent: planning from a
     // duration rounded to whole milliseconds put `endByte` at 640,512 for a
-    // 640,500-byte file. `readUpload` clamps a window to the stored size, so
+    // 640,500-byte file. `stepReadUpload` clamps a window to the stored size, so
     // nothing threw — the plan was simply describing audio that does not exist.
     // Found by running the real argv against a real ffmpeg, which is the only
     // place a twelve-byte error was ever going to surface.
@@ -856,14 +867,14 @@ describe("the body's step policy", () => {
    * only reads `ctx.steps` afterwards, so it is built once.
    */
   const walkedCtx = () =>
-    createWorkflowCtx({
+    createWorkflowContext({
       runSteps: false,
       // The body reads the clock at both ends with `ctx.now()`, which the engine
       // journals under `now!0` and `now!1`. A PRODUCER here rather than a fixed
       // number, so the two reaches differ and `elapsedMs` is assertable — based
-      // on `WORKFLOW_CTX_NOW`, the instant the fake otherwise freezes at, rather
+      // on `WORKFLOW_CONTEXT_NOW`, the instant the fake otherwise freezes at, rather
       // than on a second arbitrary epoch nobody can relate to the first.
-      now: clockReads(WORKFLOW_CTX_NOW, WORKFLOW_CTX_NOW + 3000),
+      now: clockReads(WORKFLOW_CONTEXT_NOW, WORKFLOW_CONTEXT_NOW + 3000),
       results: {
         ingestRecording: {
           audio: "upl_pcm",
@@ -926,7 +937,7 @@ describe("the body's step policy", () => {
 /**
  * `auditFlow` on the real replay engine — as far as this tier can take it.
  *
- * The block above drives the body through `createWorkflowCtx` with
+ * The block above drives the body through `createWorkflowContext` with
  * `runSteps: false` and a journaled result per step, which is what makes it
  * affordable: `ingestRecording` shells out to the ffmpeg toolchain, which this
  * tier cannot usefully feed — the `ingestRecording` and `narrate` specs above
@@ -959,6 +970,11 @@ describe("the run is DURABLE, as far as ffmpeg allows", () => {
     });
     installStubReporter();
     vi.stubEnv("ASSEMBLYAI_API_KEY", "test-key");
+    // Neither binary is this block's subject (see its doc), and a real
+    // conversion here would make a developer with ffmpeg installed run a
+    // slower, different test from CI, which has none.
+    vi.stubEnv("AAI_FFMPEG_PATH", "/nonexistent/ffmpeg");
+    vi.stubEnv("AAI_FFPROBE_PATH", "/nonexistent/ffprobe");
   });
 
   test("a FatalError in the first step fails the run on ONE attempt, not six", async () => {

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

@@ -20,7 +20,7 @@
  * - `transcription-workflow` owns the FAN-OUT — why the sync transcription
  *   endpoint's 120-second cap forces one, and how a run survives dying on segment
  *   27 of 60.
- * - `spoken-summary` owns the audio ROUND TRIP — `stepSpeak`, `writeUpload`, and
+ * - `spoken-summary` owns the audio ROUND TRIP — `stepSpeak`, `stepWriteUpload`, and
  *   why a page needs `api.download` rather than a URL.
  *
  * **What this template adds is a decoder**, and everything downstream changes
@@ -153,7 +153,7 @@ export const audit: WorkflowDef<typeof auditInput, CallAudit> = workflow({
   input: auditInput,
   // The one line that makes the form take a file: `<WorkflowFields>` renders a
   // picker for this property, `useWorkflowSubmit` stores the chosen file, and the
-  // ingest step reads it back with `readUpload`.
+  // ingest step reads it back with `stepReadUpload`.
   uploads: ["recording"],
   run: auditFlow,
 });

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.
  *
@@ -75,18 +76,18 @@ import "@alexkroman1/aai-ui/styles.css";
 // already declares.
 import { formatBytes, formatDuration } from "@alexkroman1/aai/utils";
 import {
+  BulletList,
   createWorkflowApi,
+  Facts,
   Form,
-  page,
+  mountPage,
   SubmitButton,
   UploadProgressBar,
   useDownloadUrl,
-  useRunKey,
   useWorkflowSubmit,
   WorkflowFields,
   WorkflowProgress,
 } from "@alexkroman1/aai-ui";
-import { useState } from "react";
 import type { audit } from "./agent.ts";
 
 /**
@@ -130,36 +131,13 @@ function Stat({ label, value }: { label: string; value: string }) {
   );
 }
 
-/** A list that renders nothing rather than an empty box — see `risks` in the schema. */
-function Findings({ title, items }: { title: string; items: string[] }) {
-  if (items.length === 0) return null;
-  return (
-    <section className="flex flex-col gap-1">
-      <h3 className="text-sm font-medium opacity-70">{title}</h3>
-      <ul className="flex list-disc flex-col gap-1 pl-5">
-        {items.map((item) => (
-          <li key={item}>{item}</li>
-        ))}
-      </ul>
-    </section>
-  );
-}
-
 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.
-  const { submitForm, run, pending, upload, pauseUpload, resumeUpload, error } = useWorkflowSubmit<
-    typeof audit
-  >(WORKFLOW, { api, key, recover: true });
+  // `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, startedHere } =
+    useWorkflowSubmit<typeof audit>(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
@@ -176,14 +154,7 @@ export function App() {
         </p>
       </header>
 
-      <Form
-        onSubmit={(values) => {
-          setStartedHere(true);
-          return submitForm(values);
-        }}
-        error={error}
-        className="flex flex-col gap-4"
-      >
+      <Form onSubmit={(values) => submitForm(values)} error={error} className="flex flex-col gap-4">
         {/* Every control, from the workflow's own input schema. See the module doc. */}
         <WorkflowFields workflow={WORKFLOW} />
         <SubmitButton pending={pending} pendingLabel="Auditing…">
@@ -203,20 +174,26 @@ export function App() {
           for `<WorkflowProgress>` to read. */}
       <UploadProgressBar upload={upload} onPause={pauseUpload} onResume={resumeUpload} />
 
-      {/* What the run itself says, from `report()` in the workflow's steps — which
+      {/* What the run itself says, from `stepReport()` in the workflow's steps — which
           for this template is the ffmpeg narration: what the file was, what it
           measured, how many pauses were found. */}
       <WorkflowProgress runId={run?.runId} api={api} />
 
-      {run?.status === "failed" && <p className="text-red-600">That one failed: {run.error}</p>}
+      {/* `role="alert"`, the same contract `<Form>` gives the submit error: this
+          is the outcome the reader waited minutes for. */}
+      {run?.status === "failed" && (
+        <p role="alert" className="text-red-600">
+          That one failed: {run.error}
+        </p>
+      )}
 
       {output !== undefined && (
         <article className="flex flex-col gap-6">
           <div className="flex flex-col gap-1">
             <h2 className="text-xl">{output.headline}</h2>
-            <p className="text-sm opacity-70">
-              {output.source} · {formatDuration(output.durationMs)} · {output.words} words
-            </p>
+            <Facts
+              items={[output.source, formatDuration(output.durationMs), `${output.words} words`]}
+            />
           </div>
 
           {/* What the pipeline did, which is this template's subject. Rendered rather
@@ -234,8 +211,11 @@ export function App() {
             <Stat label="Run time" value={formatDuration(output.elapsedMs)} />
           </dl>
 
-          <Findings title="Risks" items={output.risks} />
-          <Findings title="Actions" items={output.actions} />
+          {/* Either list can come back empty — see `risks` in the schema — and
+              `<BulletList>` renders nothing at all when it does, heading
+              included, rather than a stray heading over an empty box. */}
+          <BulletList title="Risks" items={output.risks} />
+          <BulletList title="Actions" items={output.actions} />
 
           <section className="flex flex-col gap-2">
             <h3 className="text-sm font-medium opacity-70">
@@ -244,7 +224,9 @@ export function App() {
             </h3>
             {audio.pending && <p className="text-sm opacity-70">Fetching the audio…</p>}
             {audio.error !== undefined && (
-              <p className="text-red-600">Could not load the audio: {audio.error}</p>
+              <p role="alert" className="text-red-600">
+                Could not load the audio: {audio.error}
+              </p>
             )}
             {audio.url !== undefined && (
               <>
@@ -254,7 +236,7 @@ export function App() {
                     track would carry. `spoken-summary` serves a one-cue WebVTT
                     data URL instead — worth reading for how, if a real track is
                     what a page needs. */}
-                <audio controls src={audio.url} className="w-full" />
+                <audio aria-label="Audit read aloud" controls src={audio.url} className="w-full" />
                 {/* `download` works on an object URL because the bytes are already in
                     the tab; it is the href that could not carry the agent's bearer,
                     not the attribute. */}
@@ -276,4 +258,4 @@ export function App() {
   );
 }
 
-page({ name: "Call Audit", component: App });
+mountPage({ name: "Call Audit", component: App });