@alexkroman1/aai-cli 13.3.0 → 15.0.0

package/dist/start.d.ts

@@ -0,0 +1,112 @@
+/**
+ * `aai start` — serve a BUILT agent from a plain Node process.
+ *
+ * The deployment counterpart of `aai dev`: no file watching, no Vite, no
+ * typecheck, no source evaluation. It loads the artifact `aai build` left at
+ * {@link WORKER_ARTIFACT_REL} — the same one `aai publish` uploads and the
+ * managed platform runs — so a self-hosted agent and a deployed one cannot
+ * behave differently.
+ *
+ * ## Why this is a command rather than a file in every project
+ *
+ * It used to be `scaffold/server.mjs`, ~300 lines of boot that `aai init`
+ * copied into every scaffolded project: worker load, env resolution, schema
+ * DDL, client-directory probing, error classification, listen, signal
+ * handlers. Shipping that as source made each of those a fact a USER's
+ * repository asserted, so improving any of them reached only projects
+ * scaffolded afterwards, and an existing project silently kept the old
+ * behaviour with nothing to report the drift.
+ *
+ * Every framework that solved this solved it the same way: the boot belongs to
+ * the framework and the project holds none of it. Next has `next start` and
+ * generates a `server.js` for `output: "standalone"` rather than asking anyone
+ * to write one. Nitro's default production preset is `node-server`, emitted
+ * into the build directory. The custom server is a documented opt-out, not the
+ * default everyone inherits — and here that opt-out is
+ * {@link createProjectServer}, which builds the server and binds nothing.
+ *
+ * ## Why the CLI rather than the runtime
+ *
+ * Booting a project needs three things at once: the runtime, the project's
+ * `.aai/` layout, and the prebuilt browser client. Only this package depends on
+ * all three — `aai-runtime` may not import `@alexkroman1/aai-ui`, and
+ * konsistent's `runtime-package-boundary` carries the install-weight argument
+ * for why that stays true. `client-dir.ts`'s own module doc records that this
+ * composition has always lived in an ENTRY POINT; this is that entry point,
+ * owned by the framework instead of copied into each project.
+ *
+ * The cost, stated because it is real: `npm start` needs `@alexkroman1/aai-cli`
+ * installed, so a production image carries a build toolchain it does not run.
+ * Next makes the same trade — `next` is a `dependency`, not a `devDependency` —
+ * and it is why the scaffold moves this package to `dependencies`.
+ */
+import type { AgentDef } from "@alexkroman1/aai";
+import { type AgentServer } from "@alexkroman1/aai-runtime";
+export { CLIENT_ARTIFACT_REL } from "./_artifacts.ts";
+/** The port `aai start` binds when neither an argument nor `PORT` says otherwise. */
+export declare const DEFAULT_START_PORT = 3000;
+/** Options for {@link createProjectServer} and {@link executeStart}. */
+export interface StartOptions {
+    /** Project root — the directory holding `agent.ts` and `.aai/`. */
+    cwd: string;
+    /** Port to bind. Defaults to `PORT`, then {@link DEFAULT_START_PORT}. */
+    port?: number | undefined;
+    /**
+     * Address to bind. Defaults to `HOST`, then loopback.
+     *
+     * Loopback is deliberate: this server has no request authentication of its
+     * own, so exposing it is an explicit act, and `HOST=0.0.0.0` is how a
+     * container says so. An EMPTY `HOST` means unset, not "every interface".
+     */
+    host?: string | undefined;
+}
+/**
+ * Load the built agent, or fail saying what to run.
+ *
+ * A `file:` URL rather than a relative specifier, because on Windows a bare
+ * POSIX-looking path is not a valid module specifier.
+ */
+export declare function loadBuiltAgent(cwd: string): Promise<AgentDef>;
+/**
+ * Build this project's {@link AgentServer} WITHOUT binding a socket.
+ *
+ * The seam a custom server is written against, and the one a serverless host
+ * needs: Vercel documents `export default <http.Server>` as its Node WebSocket
+ * shape and binds the socket itself, so such a host takes `AgentServer.node`
+ * and never calls `listen()`. `aai build --target vercel` emits an entry that
+ * does exactly this, so nothing host-specific is committed to a project.
+ *
+ * @example
+ * ```ts no-check
+ * // The entry `aai build --target vercel` bundles into
+ * // `.vercel/output/functions/index.func/` — `no-check` because this file
+ * // lives in the USER's project, where `@alexkroman1/aai-cli/start` resolves;
+ * // it cannot resolve from inside this package.
+ * import { createProjectServer } from "@alexkroman1/aai-cli/start";
+ *
+ * const server = (await createProjectServer({ cwd: import.meta.dirname })).node;
+ *
+ * export default function handler(req, res) {
+ *   server.emit("request", req, res);
+ * }
+ * ```
+ */
+export declare function createProjectServer(options: StartOptions): Promise<AgentServer>;
+/** What {@link executeStart} answers, for `--json` and for tests. */
+export interface StartResult {
+    ok: true;
+    data: {
+        name: string;
+        port: number | undefined;
+    };
+}
+/**
+ * Serve the built agent and keep serving it: bind, announce, and shut down
+ * cleanly on a signal.
+ *
+ * The signal listeners are SYNCHRONOUS. An `async` one hands its promise to
+ * `process`, which discards what a listener returns — so a `close()` that
+ * rejected would surface as an unhandled rejection, i.e. a crash with a stack
+ * trace on Ctrl-C, instead of the non-zero exit a failed shutdown should be.
+ */
+export declare function executeStart(options: StartOptions): Promise<StartResult>;

package/dist/start.mjs

@@ -0,0 +1,156 @@
+#!/usr/bin/env node
+import { n as log } from "./_ui-DCt4qZrk.mjs";
+import { n as WORKER_ARTIFACT_REL, t as CLIENT_ARTIFACT_REL } from "./_artifacts-BJOYGQPp.mjs";
+import { n as resolveServerEnv, t as DEPLOY_ENV_FILES } from "./_server-common-De0haHr9.mjs";
+import { existsSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { createAgentServer, ensureSessionStateSchema, ensureWorkflowJournalSchema, withHostCredentialFallback } from "@alexkroman1/aai-runtime";
+import { defaultClientDir } from "@alexkroman1/aai-ui/client-dir";
+//#region src/start.ts
+/**
+* `aai start` — serve a BUILT agent from a plain Node process.
+*
+* The deployment counterpart of `aai dev`: no file watching, no Vite, no
+* typecheck, no source evaluation. It loads the artifact `aai build` left at
+* {@link WORKER_ARTIFACT_REL} — the same one `aai publish` uploads and the
+* managed platform runs — so a self-hosted agent and a deployed one cannot
+* behave differently.
+*
+* ## Why this is a command rather than a file in every project
+*
+* It used to be `scaffold/server.mjs`, ~300 lines of boot that `aai init`
+* copied into every scaffolded project: worker load, env resolution, schema
+* DDL, client-directory probing, error classification, listen, signal
+* handlers. Shipping that as source made each of those a fact a USER's
+* repository asserted, so improving any of them reached only projects
+* scaffolded afterwards, and an existing project silently kept the old
+* behaviour with nothing to report the drift.
+*
+* Every framework that solved this solved it the same way: the boot belongs to
+* the framework and the project holds none of it. Next has `next start` and
+* generates a `server.js` for `output: "standalone"` rather than asking anyone
+* to write one. Nitro's default production preset is `node-server`, emitted
+* into the build directory. The custom server is a documented opt-out, not the
+* default everyone inherits — and here that opt-out is
+* {@link createProjectServer}, which builds the server and binds nothing.
+*
+* ## Why the CLI rather than the runtime
+*
+* Booting a project needs three things at once: the runtime, the project's
+* `.aai/` layout, and the prebuilt browser client. Only this package depends on
+* all three — `aai-runtime` may not import `@alexkroman1/aai-ui`, and
+* konsistent's `runtime-package-boundary` carries the install-weight argument
+* for why that stays true. `client-dir.ts`'s own module doc records that this
+* composition has always lived in an ENTRY POINT; this is that entry point,
+* owned by the framework instead of copied into each project.
+*
+* The cost, stated because it is real: `npm start` needs `@alexkroman1/aai-cli`
+* installed, so a production image carries a build toolchain it does not run.
+* Next makes the same trade — `next` is a `dependency`, not a `devDependency` —
+* and it is why the scaffold moves this package to `dependencies`.
+*/
+/** The port `aai start` binds when neither an argument nor `PORT` says otherwise. */
+const DEFAULT_START_PORT = 3e3;
+/**
+* Load the built agent, or fail saying what to run.
+*
+* A `file:` URL rather than a relative specifier, because on Windows a bare
+* POSIX-looking path is not a valid module specifier.
+*/
+async function loadBuiltAgent(cwd) {
+	const workerPath = path.join(cwd, WORKER_ARTIFACT_REL);
+	if (!existsSync(workerPath)) throw new Error(`No built agent at ${WORKER_ARTIFACT_REL}. Run \`aai build\` first — the scaffold's \`prestart\` script normally does it for you.`);
+	return (await import(pathToFileURL(workerPath).href)).default;
+}
+/**
+* Static assets to serve at `/`: this project's own built UI when it has one,
+* otherwise the prebuilt default client that ships inside `@alexkroman1/aai-ui`.
+*
+* A `client.tsx` that has not been BUILT is worth saying out loud — the server
+* would otherwise serve the default UI and look like it had ignored the file.
+*/
+function resolveClientDir(cwd) {
+	const built = path.join(cwd, CLIENT_ARTIFACT_REL);
+	if (existsSync(path.join(built, "index.html"))) return built;
+	if (existsSync(path.join(cwd, "client.tsx"))) log.warn("client.tsx is not built — serving the default UI. Run `aai build` first.");
+	return defaultClientDir();
+}
+/**
+* Build this project's {@link AgentServer} WITHOUT binding a socket.
+*
+* The seam a custom server is written against, and the one a serverless host
+* needs: Vercel documents `export default <http.Server>` as its Node WebSocket
+* shape and binds the socket itself, so such a host takes `AgentServer.node`
+* and never calls `listen()`. `aai build --target vercel` emits an entry that
+* does exactly this, so nothing host-specific is committed to a project.
+*
+* @example
+* ```ts no-check
+* // The entry `aai build --target vercel` bundles into
+* // `.vercel/output/functions/index.func/` — `no-check` because this file
+* // lives in the USER's project, where `@alexkroman1/aai-cli/start` resolves;
+* // it cannot resolve from inside this package.
+* import { createProjectServer } from "@alexkroman1/aai-cli/start";
+*
+* const server = (await createProjectServer({ cwd: import.meta.dirname })).node;
+*
+* export default function handler(req, res) {
+*   server.emit("request", req, res);
+* }
+* ```
+*/
+async function createProjectServer(options) {
+	const { cwd } = options;
+	const agent = await loadBuiltAgent(cwd);
+	const env = await resolveServerEnv(cwd, void 0, DEPLOY_ENV_FILES);
+	if (env.DATABASE_URL) {
+		await ensureSessionStateSchema({
+			url: env.DATABASE_URL,
+			logger: console
+		});
+		await ensureWorkflowJournalSchema({
+			url: env.DATABASE_URL,
+			logger: console
+		});
+	} else log.warn("No DATABASE_URL: session state and durable runs live in THIS process's memory.\nOne replica is fine. Behind a load balancer, enable sticky sessions so a reconnect (the client re-dials with ?sessionId=) reaches the same process — or set DATABASE_URL and let every replica share the state.");
+	return createAgentServer({
+		agent,
+		env,
+		providerEnv: withHostCredentialFallback(env),
+		clientDir: resolveClientDir(cwd),
+		...process.env.PUBLIC_URL?.trim() ? { publicUrl: process.env.PUBLIC_URL.trim() } : {}
+	});
+}
+/**
+* Serve the built agent and keep serving it: bind, announce, and shut down
+* cleanly on a signal.
+*
+* The signal listeners are SYNCHRONOUS. An `async` one hands its promise to
+* `process`, which discards what a listener returns — so a `close()` that
+* rejected would surface as an unhandled rejection, i.e. a crash with a stack
+* trace on Ctrl-C, instead of the non-zero exit a failed shutdown should be.
+*/
+async function executeStart(options) {
+	const agent = await loadBuiltAgent(options.cwd);
+	const server = await createProjectServer(options);
+	const port = options.port ?? Number(process.env.PORT ?? 3e3);
+	const host = options.host ?? (process.env.HOST?.trim() || void 0);
+	await server.listen(port, host);
+	log.info(`${agent.name} listening on http://${host ?? "127.0.0.1"}:${server.port}`);
+	for (const signal of ["SIGINT", "SIGTERM"]) process.once(signal, () => {
+		server.close().then(() => process.exit(0), (error) => {
+			log.error(`shutdown failed: ${error instanceof Error ? error.message : String(error)}`);
+			process.exit(1);
+		});
+	});
+	return {
+		ok: true,
+		data: {
+			name: agent.name,
+			port: server.port
+		}
+	};
+}
+//#endregion
+export { CLIENT_ARTIFACT_REL, DEFAULT_START_PORT, createProjectServer, executeStart, loadBuiltAgent };

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

@@ -1,14 +1,15 @@
 #!/usr/bin/env node
-import { a as ok, t as CliError } from "./_output-DbJt9gsl.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 { 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 { l as formatCappedList } from "./_utils-D5JGcjiW.mjs";
+import { s as updateProjectConfig } from "./_config-DYzC6WMD.mjs";
+import { n as resolveServerEnv } from "./_server-common-De0haHr9.mjs";
+import { o as resolveDeployTarget } from "./_agent-BzUeqOdj.mjs";
+import { layerScaffold } from "./_templates-CIlJ3Vay.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 src/studio.ts
@@ -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-sV4N5F93.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.eval.test.ts

@@ -0,0 +1,156 @@
+// An EVAL: does the desk really DELEGATE, or does it brief you from memory?
+//
+// `agent.test.ts` settles what each tool does once it has been called — it
+// hands `researchAngle` a `stubDelegate` and asserts on the board. What it
+// cannot settle is the two things this template exists to demonstrate: that the
+// MODEL turns "tell me about home battery prices" into ONE `research_topic`
+// call carrying several angles rather than one call per angle, and that nothing
+// the caller hears came from a web tool the DESK holds — because it holds none.
+//
+// Run it with `aai eval`. Without a provider key every case runs against a
+// SCRIPTED model (its `stubReply`), which proves the wiring and nothing about
+// the choice — so the two claims above are `{ live: true }` and the recap case,
+// whose whole point is that it spends no model at all, is not.
+
+/**
+ * The def a DEPLOYED agent runs: authored, plus what `tools/` declares, plus
+ * its PROMPT.
+ *
+ * Taken from `virtual:aai/agent` rather than a hand-written glob: the plugin
+ * expands it against THIS file's own directory, so the spec needs no glob and
+ * no shared helper — which matters because this file SHIPS, and a scaffolded
+ * project has no repo helper to import. `agent.ts` here is three fields, so an
+ * eval driving it alone would measure an agent with no tools and the FRAMEWORK
+ * DEFAULT prompt — i.e. a desk that has never heard of a researcher, on which
+ * every claim below would pass or fail for the wrong reason. The reasoning is
+ * spelled out in `../code-interpreter/agent.eval.test.ts`.
+ */
+import agentDef from "virtual:aai/agent";
+import { describeTurn, toolNames, toolResultIn } from "@alexkroman1/aai-runtime/eval";
+import { describeEval } from "@alexkroman1/aai-runtime/eval/vitest";
+import { expect } from "vitest";
+import { z } from "zod";
+import { MAX_ANGLES } from "./shared.ts";
+
+/**
+ * Every tool the desk declares — the two that reach the outside world through a
+ * subagent, and the recap that reaches nothing.
+ *
+ * Named here because the isolation claim is stated as a NEGATIVE — no
+ * `web_search`, no `visit_webpage` — and a negative over a hand-typed list is
+ * the assertion that goes quietly true when a tool is renamed. Every call the
+ * desk makes must be one of these three names.
+ */
+const DESK_TOOLS: readonly string[] = ["research_topic", "verify_claim", "briefing_so_far"];
+
+/**
+ * What `research_topic` answers with, as a schema rather than a cast.
+ *
+ * `toolResultIn` takes one for the reason `night-owl`'s spec records: a result
+ * that stopped carrying `findings` FAILS here naming the field, where a cast
+ * hands the assertions `undefined` and fails a line later on something
+ * unrelated.
+ */
+const BriefingResult = z.object({
+  topic: z.string(),
+  findings: z.array(z.object({ angle: z.string(), summary: z.string() })),
+  failed: z.array(z.object({ angle: z.string() })),
+});
+
+/** What `briefing_so_far` answers with on an EMPTY board. */
+const EmptyRecap = z.object({
+  topic: z.null(),
+  findings: z.array(z.unknown()).length(0),
+  message: z.string(),
+});
+
+/** What `verify_claim` answers with. */
+const Verdict = z.object({ claim: z.string(), verdict: z.string() });
+
+describeEval(agentDef, (test) => {
+  test(
+    "a recap on an empty board costs no researcher",
+    async ({ session }) => {
+      const turn = await session.say("What have you got for me so far?");
+
+      // The one tool here that spends no model at all, and the case that can
+      // therefore run against a script: the desk answers the recap out of its
+      // own slot. A desk that reached for `research_topic` to find out what it
+      // already knows is the regression — it bills the caller for four
+      // researchers to answer "nothing yet".
+      expect(toolNames(turn.toolCalls), describeTurn(turn)).toEqual(["briefing_so_far"]);
+      // And the slot really resolved: an empty board reports itself as empty
+      // rather than throwing or answering with a half-built shape.
+      expect(toolResultIn(turn.toolCalls, "briefing_so_far", EmptyRecap).topic).toBeNull();
+    },
+    {
+      stubReply: [
+        { tool: "briefing_so_far", args: {} },
+        "Nothing yet — tell me a subject and I'll put some researchers on it.",
+      ],
+    },
+  );
+
+  test(
+    "fans one subject out across angles in a SINGLE call",
+    async ({ session }) => {
+      const turn = await session.say("What's going on with home battery prices?");
+
+      // One call carrying several angles, never one call per angle. That is the
+      // whole economic claim of the template — the angles run in parallel, so
+      // the caller waits for the slowest rather than the sum — and a desk that
+      // called the tool three times in a row would satisfy any assertion that
+      // merely counted angles.
+      const calls = turn.toolCalls.filter((call) => call.name === "research_topic");
+      expect(calls, describeTurn(turn)).toHaveLength(1);
+      const angles = z.array(z.string()).parse(calls[0]?.args.angles);
+      expect(angles.length).toBeGreaterThan(1);
+      expect(angles.length).toBeLessThanOrEqual(MAX_ANGLES);
+      // Each angle stands on its own — the prompt's rule, and the one a
+      // researcher cannot recover from, having heard none of this call. A bare
+      // "the same for Europe" is a handful of characters; a self-contained
+      // question is a sentence.
+      for (const angle of angles) expect(angle.length).toBeGreaterThan(15);
+
+      // What came back is what the researchers concluded, not what the desk
+      // believes: every finding carries prose, and the board holds the topic.
+      const result = toolResultIn(turn.toolCalls, "research_topic", BriefingResult);
+      expect(result.findings).not.toEqual([]);
+      for (const finding of result.findings) expect(finding.summary.length).toBeGreaterThan(40);
+
+      // The isolation claim, and the reason this template is not
+      // `web-researcher`: the desk has NO web tools, so anything it says about
+      // the world crossed back out of a subagent. A `web_search` in this list
+      // would mean the builtins had leaked onto the parent.
+      expect(toolNames(turn.toolCalls).filter((name) => !DESK_TOOLS.includes(name))).toEqual([]);
+      expect(turn.text).not.toBe("");
+    },
+    // Live only: a script cannot choose the angles, and choosing them is the
+    // measurement. It also cannot run a subagent — the researcher resolves a
+    // model of its own from `shared.ts`, which the turn's stub never covers.
+    { live: true },
+  );
+
+  test(
+    "checks a claim the caller pushes back on instead of defending it",
+    async ({ session }) => {
+      const turn = await session.say(
+        "Someone told me home batteries pay for themselves in two years. " +
+          "Is that right? Check it for me.",
+      );
+
+      // `verify_claim` is the cheaper subagent on the narrower surface, and
+      // reaching for it rather than answering is the prompt's rule that a live
+      // model actually has to keep. The claim it forwards must be the sentence
+      // it was given, not a keyword — a fact-checker handed "batteries" answers
+      // confidently about nothing.
+      const calls = turn.toolCalls.filter((call) => call.name === "verify_claim");
+      expect(calls, describeTurn(turn)).toHaveLength(1);
+      const verdict = toolResultIn(turn.toolCalls, "verify_claim", Verdict);
+      expect(verdict.claim.split(/\s+/).length).toBeGreaterThan(3);
+      expect(verdict.verdict).not.toBe("");
+      expect(toolNames(turn.toolCalls).filter((name) => !DESK_TOOLS.includes(name))).toEqual([]);
+    },
+    { live: true },
+  );
+});

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,
@@ -516,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.
@@ -867,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",
@@ -937,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
@@ -970,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,
 });