@alexkroman1/aai-cli 13.1.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.1.0",
-    "@alexkroman1/aai-runtime": "^13.1.0",
-    "@alexkroman1/aai-ui": "^13.1.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.1.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.eval.test.ts

@@ -52,6 +52,7 @@
 // the tier that really resumes a run.
 import { spawnSync } from "node:child_process";
 import { encodeWav } from "@alexkroman1/aai/step";
+import { stubGatewayRoute } from "@alexkroman1/aai/testing";
 import { installStubTranscribe, installStubUploads } from "@alexkroman1/aai/testing/vitest";
 import { describeWorkflowEval } from "@alexkroman1/aai-runtime/eval/vitest";
 import { describe, expect, test } from "vitest";
@@ -211,19 +212,21 @@ function publish(bytes: Uint8Array, name: string, type: string) {
  * Answer the sync transcription endpoint and the model in memory.
  *
  * ONE fake, because publishing a `stepFetch` REPLACES — a flow that transcribes
- * AND calls a model cannot install two, which is what `otherwise` is for. The
- * transcription half is the SDK's own fake rather than this file's hand-typed
- * wire: it routes off the SDK's endpoint constants, so a case cannot pass
- * because the fake and the step agree on a typo.
+ * AND calls a model cannot install two, which is what `otherwise` is for. BOTH
+ * halves are the SDK's own fakes rather than this file's hand-typed wire, and
+ * for the same reason: each routes off the SDK's own endpoint constant, so a
+ * case cannot pass because the fake and the step agree on a typo. The gateway
+ * envelope is the half where that matters most — it is a WIRE shape, so getting
+ * a field wrong does not fail: `stepGenerate` reads no content, reports an empty
+ * completion, and the case blames the desk.
+ *
+ * `route` answers `undefined` for anything that is not a completion request, so
+ * it drops straight into `otherwise` and the transcription legs still reach the
+ * fake below it.
  */
 function scriptProvider(text: readonly string[]) {
-  return installStubTranscribe({
-    text,
-    otherwise: (request) =>
-      request.url.includes("/chat/completions")
-        ? { body: { choices: [{ message: { content: JSON.stringify(REPLY) } }] } }
-        : undefined,
-  });
+  const model = stubGatewayRoute(JSON.stringify(REPLY));
+  return installStubTranscribe({ text, otherwise: (request) => model.route(request) });
 }
 
 describeWorkflowEvalWithFfmpeg(

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", () => {
@@ -928,9 +939,21 @@ describe("the body's step policy", () => {
  *
  * The block above drives the body through `createWorkflowCtx` with
  * `runSteps: false` and a journaled result per step, which is what makes it
- * affordable: `ingestRecording` runs ffmpeg, and this repo's test environment
- * has none — the `ingestRecording` and `narrate` specs above assert the
- * `FatalError` that produces, unconditionally.
+ * affordable: `ingestRecording` shells out to the ffmpeg toolchain, which this
+ * tier cannot usefully feed — the `ingestRecording` and `narrate` specs above
+ * assert the `FatalError` that produces, unconditionally.
+ *
+ * **The run fails here whether or not ffmpeg is installed, and the two failures
+ * do not say the same thing** — which is what the assertion below has to be
+ * written against. With no binary on `PATH` the step reports the missing
+ * toolchain as an instruction (the template's own doc promises that rather than
+ * `spawn ffmpeg ENOENT`); WITH one, the step gets a step further and `ffprobe`
+ * rejects the 2 KB stub above with `ffprobe exited with code 1`. This docblock
+ * used to state "this repo's test environment has none" as a premise, and the
+ * spec below matched `/ffmpeg/i` on the strength of it — so the test passed only
+ * on a machine where ffmpeg was ABSENT, and a developer with Homebrew's ffmpeg
+ * saw a red suite on a clean checkout of `main`. CI has no ffmpeg, so nothing
+ * caught it.
  *
  * So a whole run of this desk is not reachable here and this file does not
  * pretend otherwise; `aai-cli`'s `dev-workflow.scenario.test.ts` is the tier
@@ -953,7 +976,11 @@ describe("the run is DURABLE, as far as ffmpeg allows", () => {
     const run = await runWorkflow(audit, { recording: UPLOAD_ID }, { name: "audit" });
 
     expect(run.status).toBe("failed");
-    expect(run.error).toMatch(/ffmpeg/i);
+    // Either member of the toolchain, for the reason this block's doc gives: the
+    // step names `ffmpeg` when the binary is missing and `ffprobe` when it is
+    // present, and this spec is about neither. What it is about is the two
+    // assertions below — the ENGINE honouring `FatalError`.
+    expect(run.error).toMatch(/ff(mpeg|probe)/i);
     const ingest = run.steps.find((step) => step.name === "ingestRecording");
     // The whole point of `FatalError`: `maxAttempts: 6` is the budget this call
     // site asks for, and a failure that cannot change must not spend it. A step

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/call-audit/workflows/ingest.ts

@@ -143,7 +143,16 @@ export async function ingestRecording(uploadId: string): Promise<Ingested> {
       const normalized = join(dir, "audio.pcm");
       const silenceLog = join(dir, "silence.txt");
 
-      await readUploadToFile(uploadId, source, { size: stored.size });
+      // NO `size`, though `stored.size` is right there — and that is the whole
+      // difference between this copy being one window at a time and being
+      // `STEP_FILE_READ_CONCURRENCY` of them. Passing `size` means "I am judging
+      // completeness myself", which is what a body polling a still-arriving
+      // upload needs and is the opposite of what happened above: this step has
+      // already called `requireCompleteUpload`, so the file IS whole and the
+      // windows may land in any order. Omitting it lets `readUploadToFile`
+      // establish that for itself and fan out. The cost is one metadata round
+      // trip, against the dozens of window reads it overlaps.
+      await readUploadToFile(uploadId, source);
 
       // What it WAS, for the progress log and the page. Worth one ffprobe: "41
       // minutes of aac" explains the shape of the run, where "the recording" leaves

package/dist/templates/code-interpreter/agent.eval.test.ts

@@ -24,27 +24,37 @@
 // Coda reached for code, and what the code came back with.
 
 import agentDef from "virtual:aai/agent";
-import { createVmRunCode, toolResultsIn } from "@alexkroman1/aai-runtime/eval";
+import {
+  createVmRunCode,
+  type EvalTurn,
+  toolArgsIn,
+  toolNames,
+  toolResultsIn,
+} from "@alexkroman1/aai-runtime/eval";
 import { describeEval } from "@alexkroman1/aai-runtime/eval/vitest";
 import { expect } from "vitest";
+import { z } from "zod";
 
-/** The code every `run_code` call in this turn carried, joined. */
-const codeIn = (turn: { toolCalls: readonly { name: string; args: Record<string, unknown> }[] }) =>
-  turn.toolCalls
-    .filter((c) => c.name === "run_code")
-    .map((c) => String(c.args.code ?? ""))
+/**
+ * The code every `run_code` call in this turn carried, joined.
+ *
+ * Read through `toolArgsIn` WITH a schema, which is what that reader takes one
+ * for: `args` is `Record<string, unknown>` on the wire — the model wrote it and
+ * nothing validated it — so the `String(c.args.code ?? "")` this replaced turned
+ * an argument Coda renamed, or never sent, into `""`, and every claim below about
+ * the code she wrote would have been a claim about an empty string. A `code`
+ * that stops arriving FAILS here, naming the field.
+ */
+const RunCodeArgs = z.object({ code: z.string() });
+const codeIn = (turn: EvalTurn) =>
+  toolArgsIn(turn.toolCalls, "run_code", RunCodeArgs)
+    .map((args) => args.code)
     .join("\n");
 
 /**
- * A `run_code` executor, so these cases can assert the ANSWER.
- *
- * The builtin refuses without one — the Modal container is the security
- * boundary, and off-platform there is none — so a case could assert the CALL and
- * the code it carried, and never what the code came back with.
- * `createVmRunCode()` is a `node:vm` context with a capturing `console.log`,
- * which is enough here: what runs is arithmetic, not a program. It is NOT a
- * sandbox and does not pretend to be one; a deployed agent still gets the
- * refusal.
+ * A `run_code` executor, so these cases can assert the ANSWER and not merely the
+ * call — `createVmRunCode`'s own doc carries why the builtin refuses without one
+ * and why a `node:vm` context is the right thing to hand it here.
  */
 const runCode = createVmRunCode();
 
@@ -59,7 +69,7 @@ describeEval(
         // The template's CRITICAL RULE, and the whole reason it declares
         // run_code: a model that answers this one directly has regressed, and it
         // is the easiest question in the file to answer wrongly with confidence.
-        expect(turn.toolCalls.map((c) => c.name)).toContain("run_code");
+        expect(toolNames(turn.toolCalls)).toContain("run_code");
         const code = codeIn(turn);
         expect(code).toContain("127");
         expect(code).toContain("849");
@@ -90,7 +100,7 @@ describeEval(
         // The prompt lists this exact question under "you MUST use code for".
         // It is the case a narrower reading of the rule ("code is for maths")
         // silently drops.
-        expect(turn.toolCalls.map((c) => c.name)).toContain("run_code");
+        expect(toolNames(turn.toolCalls)).toContain("run_code");
         expect(codeIn(turn)).toMatch(/Date|2000/);
         // The code RAN rather than being refused — but the ANSWER is
         // deliberately not asserted here, and the reason is worth knowing before