@alexkroman1/aai-cli 13.2.0 → 13.3.0

package/dist/templates/transcription-workflow/agent.test.ts

@@ -143,15 +143,19 @@ function wavFile(
   return head;
 }
 
-describe("the agent declares its three workflows and nothing else", () => {
+describe("the agent declares its three workflows", () => {
   test("under the names the REST route resolves them by", () => {
     // The page starts a run by these strings, so a rename is a runtime 400 rather
     // than a compile error — which is what makes pinning them worth a test.
-    expect(Object.keys(agentDef.workflows ?? {})).toEqual([
-      "transcribe",
-      "transcribeStream",
-      "transcribeBatch",
-    ]);
+    // `arrayContaining` rather than an exact key list: a fourth desk of your own
+    // is an invited edit and must not redden a test you did not write. These
+    // three NAMES stay pinned, deliberately — the page starts a run by each
+    // string, so renaming one is a runtime 400 rather than a compile error, and
+    // this is the only thing that says so. Rename here and in `client.tsx`
+    // together.
+    expect(Object.keys(agentDef.workflows ?? {})).toEqual(
+      expect.arrayContaining(["transcribe", "transcribeStream", "transcribeBatch"]),
+    );
     expect(agentDef.workflows?.transcribe).toBe(transcribe);
     expect(agentDef.workflows?.transcribeStream).toBe(transcribeStream);
     expect(agentDef.workflows?.transcribeBatch).toBe(transcribeBatch);
@@ -168,8 +172,12 @@ describe("the agent declares its three workflows and nothing else", () => {
   });
 
   test("with no tools, because the interface is the page and the API", () => {
-    // The point of the template: a workflow app needs no conversation. A tool
-    // reappearing here would mean the voice path had crept back in.
+    // A PIN, deliberately, and the one assertion in this file you are expected
+    // to edit rather than satisfy. `workflowApp()` declares no session, so a
+    // tool has no conversation to be called from — a name appearing here means
+    // the voice path crept back in and the tool will never run. If you want a
+    // voice agent that STARTS a workflow, `research-workflow` is that template,
+    // and this line is what tells you you are on the wrong one.
     expect(Object.keys(agentDef.tools ?? {})).toEqual([]);
   });
 

package/dist/templates/transcription-workflow/client.tsx

@@ -153,15 +153,17 @@
  * ## A reload keeps two of the three runs, and the third CANNOT be kept
  *
  * The run id lives in React state, so a refresh loses it while the fan-out
- * carries on. `key` is the handle that survives that and `recover: true` is what
- * reads it back — and here it is a decision PER MODE rather than per page:
+ * carries on. A correlation KEY is the handle that survives that, and
+ * `useWorkflowSubmit` keeps one and asks for its newest run on mount — which
+ * here lands differently PER MODE:
  *
  * - **"After it uploads"** and **"Let the provider do it"** recover. Their input
  *   names a recording that is already stored, so a later load adopting the run
  *   is adopting something complete: the transcript arrives, the progress log
  *   replays, and nobody is asked to send a 600 MB file a second time.
  * - **"While it uploads" does not, and the hook REFUSES the option rather than
- *   ignoring it.** That run's input names an upload id this page load minted and
+ *   ignoring it** — `useWorkflowStream` omits `recover` from its options type
+ *   and mints no key. That run's input names an upload id this page load minted and
  *   is still filling, so a later load could only adopt a run waiting for bytes
  *   nobody is sending — and it is worse than useless: `workflows/stream.ts`
  *   fails a run whose upload stops growing (`MAX_IDLE_POLLS`), so the reload
@@ -171,10 +173,11 @@
  * The MODE is remembered too, and that is not decoration: without it a reload
  * opens on the default flow while the recovered run sits behind a radio nobody
  * pressed, so the reader sees an empty form and starts a second run — the exact
- * thing the key exists to prevent. The KEY is `useRunKey()`, which owns the
- * minting, the storage and the argument for the key being opaque rather than a
- * `?key=` parameter; `recover.ts` owns the mode, which is this page's own
- * concept, and the validation on the way back out of storage that turning a
+ * thing the key exists to prevent. The KEY is the hook's own — `use-run-key.ts`
+ * owns the minting, the storage and the argument for it being opaque rather
+ * than a `?key=` parameter, and the two submit hooks here share one because the
+ * slot is keyed by the PAGE; `recover.ts` owns the mode, which is this page's
+ * own concept, and the validation on the way back out of storage that turning a
  * stored string into a workflow name obliges.
  *
  * Two smaller consequences worth knowing. Both recovering hooks look up on
@@ -193,7 +196,6 @@ import {
   page,
   SubmitButton,
   UploadProgressBar,
-  useRunKey,
   useWorkflowRuns,
   useWorkflowStream,
   useWorkflowSubmit,
@@ -268,9 +270,6 @@ function TranscriptionDesk() {
   // piece of state for all three hooks, because it describes the UPLOAD and every
   // mode has one — see the module doc.
   const [parallel, setParallel] = useState(true);
-  // This tab's handle on its own runs — minted once and remembered, which is
-  // what a later load produces to find the run again.
-  const key = useRunKey();
   // Did THIS load press Transcribe? A reload cannot have, and it is the only way
   // the page can tell "working on what you just sent" from "picking up where you
   // left off" — the hooks report the run, not who asked for it.
@@ -279,22 +278,16 @@ function TranscriptionDesk() {
   // and that costs nothing here: none of them does anything until its `submit` is
   // called, and `useWorkflowRun` underneath them holds no id until then either.
   //
-  // `recover` is a constant `true` on the two that take it rather than
-  // `mode === …`: the lookup is a MOUNT-time act, so arming it when a mode is
-  // picked would re-adopt a run the reader had just cleared. The streaming hook
-  // takes neither half — it refuses `recover` by type, and recording a key it
-  // will never read back would be config nothing uses.
+  // The two submit hooks recover unconditionally rather than on `mode === …`:
+  // the lookup is a MOUNT-time act, so arming it when a mode is picked would
+  // re-adopt a run the reader had just cleared. They share ONE key without
+  // saying so — the hook's slot is keyed by the page — and `find` is scoped by
+  // workflow as well as by key, so the two modes recover separate runs. The
+  // streaming hook has neither half: it refuses `recover` by type, and mints no
+  // key it would never read back.
   const streamed = useWorkflowStream<typeof transcribe>(WORKFLOWS.streaming, { parallel });
-  const stored = useWorkflowSubmit<typeof transcribe>(WORKFLOWS.classic, {
-    parallel,
-    key,
-    recover: true,
-  });
-  const batched = useWorkflowSubmit<typeof transcribe>(WORKFLOWS.batch, {
-    parallel,
-    key,
-    recover: true,
-  });
+  const stored = useWorkflowSubmit<typeof transcribe>(WORKFLOWS.classic, { parallel });
+  const batched = useWorkflowSubmit<typeof transcribe>(WORKFLOWS.batch, { parallel });
   // The batch flow uploads the same way the classic one does — the id comes from the
   // store — so it is the SAME hook against a different workflow. Only the streaming
   // mode needs the other one, because only it needs the id before the bytes.

package/dist/test-guenJUxi.mjs

@@ -0,0 +1,255 @@
+#!/usr/bin/env node
+import { a as ok, n as fail } from "./_output-DbJt9gsl.mjs";
+import { n as log, r as notify } from "./_ui-DCt4qZrk.mjs";
+import { i as errorCode, o as errorMessage$1, r as binFromPackageJson } from "./_utils-Dhd058D9.mjs";
+import { createRequire } from "node:module";
+import { existsSync, readdirSync } from "node:fs";
+import path from "node:path";
+import { omitUndefined } from "@alexkroman1/aai/utils";
+import { execaSync } from "execa";
+//#region src/test.ts
+/**
+* `aai test` — run agent tests via vitest.
+*/
+/**
+* Resolve the agent project's own vitest binary so tests run without the
+* npx resolution overhead (and its potential network fetch of vitest).
+*
+* Resolves `vitest/package.json` from the agent directory, derives the bin
+* script, and runs it with the current Node executable. Falls back to
+* `npx vitest` only when no local install is resolvable.
+*/
+function resolveVitestCommand(cwd, resolve = createRequire(path.join(cwd, "package.json")).resolve) {
+	try {
+		const bin = binFromPackageJson(resolve("vitest/package.json"), "vitest");
+		if (bin) return {
+			cmd: process.execPath,
+			args: [bin]
+		};
+	} catch {}
+	return {
+		cmd: "npx",
+		args: ["vitest"]
+	};
+}
+/** The files `aai test` runs, in preference order. */
+const TEST_FILES = ["agent.test.ts", "agent.test.js"];
+/**
+* Run vitest over `candidates` (or, with `all`, the whole project) in the given
+* project directory.
+*
+* Returns the FILES it ran, or `false` if there was nothing to run. Throws on
+* failure.
+*
+* A vitest FILTER, not an include glob: each argument is matched as a substring
+* against the paths vitest's own include globs already found, which is why the
+* candidates are named `*.test.ts` — `agent.test.ts` cannot match
+* `agent.eval.test.ts` and vice versa, so the two commands stay disjoint
+* without either one having to exclude the other's file. That holds for the
+* `all` list too: it is built from {@link projectSpecFiles}, which drops the
+* eval tier by infix.
+*/
+function runVitest(cwd, opts = { candidates: TEST_FILES }) {
+	const files = resolveRunFiles(cwd, opts);
+	if (files.length === 0) return false;
+	const { cmd, args } = resolveVitestCommand(cwd);
+	execaSync(cmd, [
+		...args,
+		"run",
+		"--root",
+		".",
+		...opts.extraArgs ?? [],
+		...files
+	], {
+		cwd,
+		stdio: "inherit",
+		...omitUndefined({ env: opts.env ? {
+			...process.env,
+			...opts.env
+		} : void 0 })
+	});
+	if (opts.announceUnrun !== false) warnUnrunSpecs(cwd, files);
+	return files;
+}
+/** The spec files one {@link runVitest} call points vitest at. */
+function resolveRunFiles(cwd, opts) {
+	if (opts.all) return projectSpecFiles(cwd);
+	const candidate = opts.candidates.find((name) => existsSync(path.join(cwd, name)));
+	return candidate ? [candidate] : [];
+}
+/**
+* Classify a {@link runVitest} failure. execaSync throws an ENOENT-coded
+* error when the binary itself couldn't be spawned (infrastructure problem)
+* and an exit-code error when vitest ran and the tests failed.
+*/
+function classifyVitestError(err, label = "Tests") {
+	if (errorCode(err) === "ENOENT") return {
+		code: "spawn_failed",
+		message: `Could not launch the test runner: ${errorMessage$1(err)} — is the binary on your PATH?`
+	};
+	return {
+		code: "test_failed",
+		message: `${label} failed: ${errorMessage$1(err)}`
+	};
+}
+/** Directories a project's own specs never live in. */
+const UNSCANNED_DIRS = /* @__PURE__ */ new Set([
+	"node_modules",
+	".aai",
+	".git",
+	"dist",
+	".workflow-data"
+]);
+/** What counts as a spec file. */
+const SPEC_FILE_RE = /\.test\.(ts|js|tsx|mts|cts)$/;
+/**
+* Every spec file in the project that belongs to the TEST tier.
+*
+* Eval files are excluded by the `.eval.` INFIX — the tier convention — rather
+* than by a filename list, which is what keeps this module from importing
+* `eval.ts`, which imports this one.
+*/
+function projectSpecFiles(cwd) {
+	const found = [];
+	collectSpecs(cwd, "", found);
+	return found.sort(compareCodeUnits);
+}
+/**
+* Spec files in the project that a run over `ran` did NOT cover.
+*
+* `runVitest` passes the candidate filename as a vitest FILTER, which is what
+* keeps `test` and `eval` disjoint without either excluding the other's file —
+* see its doc. The cost is that every other `*.test.ts` in the project is
+* skipped, and the skip was SILENT: the shipped `retail` template carries seven
+* of them, so `aai test` there ran 1 file / 67 tests, printed "Tests passed",
+* and left 211 of the project's 278 tests unrun with nothing saying so.
+*
+* The narrow default STANDS — which files `aai test` runs is a documented
+* contract (the scaffold guide says "Run agent.test.ts via vitest"), and running
+* a project's other specs by default could reach ones that are slow or want
+* credentials. What does not stand is a GREEN VERDICT over the difference: this
+* set is what {@link executeTest} refuses to call a pass, what it puts in its
+* result for a script to read, and what `--all` opts into running.
+*/
+function unrunSpecFiles(cwd, ran) {
+	const covered = new Set(coveredList(ran));
+	return projectSpecFiles(cwd).filter((rel) => !covered.has(rel));
+}
+/** {@link RanSpecs} as a list, so nothing downstream re-derives the three cases. */
+function coveredList(ran) {
+	if (ran === false) return [];
+	return typeof ran === "string" ? [ran] : ran;
+}
+/** Code-unit comparison — see {@link projectSpecFiles} for why not `localeCompare`. */
+function compareCodeUnits(a, b) {
+	if (a < b) return -1;
+	return a > b ? 1 : 0;
+}
+/** One directory of {@link projectSpecFiles}, recursing into the ones that count. */
+function collectSpecs(dir, prefix, out) {
+	let entries;
+	try {
+		entries = readdirSync(dir, { withFileTypes: true });
+	} catch {
+		return;
+	}
+	for (const e of entries) {
+		const rel = prefix ? `${prefix}/${e.name}` : e.name;
+		if (e.isDirectory()) {
+			if (!(UNSCANNED_DIRS.has(e.name) || e.name.startsWith("."))) collectSpecs(path.join(dir, e.name), rel, out);
+		} else if (SPEC_FILE_RE.test(e.name) && !e.name.includes(".eval.test.")) out.push(rel);
+	}
+}
+/** How many unrun spec names a message prints before it starts counting. */
+const MAX_NAMED_SPECS = 10;
+/** The unrun set as one phrase — capped, because a project may hold hundreds. */
+function formatSpecList(files) {
+	const named = files.slice(0, MAX_NAMED_SPECS).join(", ");
+	const rest = files.length - MAX_NAMED_SPECS;
+	return rest > 0 ? `${named}, and ${rest} more` : named;
+}
+/**
+* The remedy, named the same way wherever the narrowing is reported.
+*
+* The project's own `npm test` comes FIRST because it is the command a
+* scaffolded project already ships (`scaffold/package.json`), so it is the one
+* answer that needs nothing installed or remembered; `--all` is the same thing
+* without leaving the CLI.
+*/
+const WIDEN_HINT = "Run the whole suite with this project's `npm test` (`vitest run --exclude \"**/*.eval.test.*\"`) or `aai test --all`; behaviour evals have their own command (`aai eval`).";
+/**
+* Warn, once, naming the spec files this run did not cover.
+*
+* This is the notice for a caller whose own result says nothing about the
+* narrowing — today that is `aai build`'s pre-build gate, which ran one file
+* out of eight and printed "Build complete". `aai test` does not use it: an
+* incomplete run is a FAILURE there, and the failure's own message is the
+* report.
+*/
+function warnUnrunSpecs(cwd, ran) {
+	const skipped = unrunSpecFiles(cwd, ran);
+	if (skipped.length === 0) return;
+	const ranList = coveredList(ran);
+	const preamble = ranList.length === 0 ? `No agent.test.ts, so vitest ran nothing. ${skipped.length} spec file(s) exist and were NOT run:` : `vitest ran ${ranList.join(", ")} only. ${skipped.length} other spec file(s) were NOT run:`;
+	notify("warn", `${preamble} ${formatSpecList(skipped)}. ${WIDEN_HINT}`);
+}
+/**
+* Execute agent tests and return structured result.
+*
+* **An incomplete run is not a pass.** For as long as this command answered
+* `{"ok":true,"data":{"passed":true}}` with exit 0 over specs it had not run,
+* the scaffold's `"test": "aai test"` was what users wired into CI — so a suite
+* of 25 tests could go red in the editor and green in the pipeline, and adding
+* one tool could break `registry.test.ts` in 17 assertions with `pnpm test` and
+* `pnpm build` both staying green throughout. It is the same defect
+* `defineExec`'s `cwd` policy exists for (a green result for a project that is
+* not there), one directory over, and it gets the same answer: the command
+* fails, names the files, and names the flag that runs them.
+*/
+async function executeTest(cwd, opts = {}) {
+	log.step(opts.all ? "Running project tests" : "Running agent tests");
+	try {
+		const ran = runVitest(cwd, {
+			candidates: TEST_FILES,
+			announceUnrun: false,
+			...omitUndefined({ all: opts.all })
+		});
+		const unrun = unrunSpecFiles(cwd, ran);
+		if (unrun.length > 0) return incomplete(ran, unrun);
+		if (ran === false) {
+			log.info("No test file found. Create agent.test.ts to add tests.");
+			return ok({
+				passed: true,
+				skipped: true,
+				ran: [],
+				unrun: [],
+				complete: true
+			});
+		}
+		log.success(`Tests passed (${ran.length} spec file(s))`);
+		return ok({
+			passed: true,
+			ran,
+			unrun: [],
+			complete: true
+		});
+	} catch (err) {
+		const { code, message } = classifyVitestError(err);
+		return fail(code, message);
+	}
+}
+/**
+* The verdict for a run that left specs uncovered.
+*
+* Both arms fail, and the `ran === false` arm is the one that had misled
+* longest: `aai test` printed "No test file found" while the project's specs sat
+* right there unrun, which reads as "this project has no tests". Measured on a
+* project whose only spec was `tools/echo_back.test.ts` — `{"passed":true,
+* "skipped":true}`, exit 0, and not a word about it.
+*/
+function incomplete(ran, unrun) {
+	const preamble = ran === false ? `\`aai test\` found no agent.test.ts, so it ran nothing, but ${unrun.length} spec file(s) exist` : `\`aai test\` ran ${ran.join(", ")} only — ${unrun.length} other spec file(s) in this project were not run`;
+	return fail("incomplete_run", `${preamble}: ${formatSpecList(unrun)}. An unrun spec is not a passing one, so this is not a green result.`, WIDEN_HINT);
+}
+//#endregion
+export { TEST_FILES, classifyVitestError, executeTest, runVitest };

package/dist/test.d.ts

@@ -2,9 +2,23 @@
  * `aai test` — run agent tests via vitest.
  */
 import { type CommandResult } from "./_output.ts";
+/**
+ * What `aai test` measured, not merely whether it exited 0.
+ *
+ * `passed` alone is what made a narrowed run indistinguishable from a complete
+ * one in a script (`jq -e .data.passed` was true either way), so the set it
+ * covered rides the result: `ran` is what vitest was pointed at, `unrun` is what
+ * it was not, and `complete` is the one field a CI job needs to read.
+ */
 type TestData = {
     passed: boolean;
     skipped?: boolean;
+    /** Spec files this run covered, project-relative, code-unit sorted. */
+    ran: string[];
+    /** Spec files in the project this run did NOT cover — empty when complete. */
+    unrun: string[];
+    /** Whether the run covered every non-eval spec file in the project. */
+    complete: boolean;
 };
 /**
  * Resolve the agent project's own vitest binary so tests run without the
@@ -24,7 +38,7 @@ export declare const TEST_FILES: readonly ["agent.test.ts", "agent.test.js"];
 export type VitestRunOptions = {
     /** File names to look for in the project root, in preference order. */
     readonly candidates: readonly string[];
-    /** Extra vitest CLI arguments, inserted before the file name. */
+    /** Extra vitest CLI arguments, inserted before the file names. */
     readonly extraArgs?: readonly string[];
     /**
      * Variables to add to the child's environment. Absent leaves the child with
@@ -33,20 +47,45 @@ export type VitestRunOptions = {
      * way a session under `aai dev` does.
      */
     readonly env?: Record<string, string>;
+    /**
+     * Run EVERY non-eval spec in the project rather than the first candidate.
+     *
+     * The opt-in half of the narrowing documented on {@link unrunSpecFiles}: the
+     * default stays one file, and this is how a caller says "I want the whole
+     * suite" without the command having to guess. Still a filter list rather than
+     * an include glob, so the eval tier stays disjoint by construction.
+     */
+    readonly all?: boolean;
+    /**
+     * Whether THIS function announces the specs it did not run.
+     *
+     * Default TRUE, and the default is the point: the caller most in need of the
+     * notice is the one that does not know it is narrowing. `aai build` runs this
+     * as its pre-build gate and reports nothing of its own, so a build gated on
+     * one file out of eight said so nowhere. `aai test` and `aai eval` pass
+     * `false` — the first because it reports the same set itself, in its result
+     * as well as its output, and the second because "did not run" is a claim
+     * about the TEST tier and every unit spec in the project would be named
+     * falsely by an eval run.
+     */
+    readonly announceUnrun?: boolean;
 };
 /**
- * Run vitest over one of `candidates` in the given project directory.
+ * Run vitest over `candidates` (or, with `all`, the whole project) in the given
+ * project directory.
  *
- * Returns the FILE it ran, or `false` if none of the candidate files exists.
- * Throws on failure.
+ * Returns the FILES it ran, or `false` if there was nothing to run. Throws on
+ * failure.
  *
- * A vitest FILTER, not an include glob: the argument is matched as a substring
+ * A vitest FILTER, not an include glob: each argument is matched as a substring
  * against the paths vitest's own include globs already found, which is why the
  * candidates are named `*.test.ts` — `agent.test.ts` cannot match
  * `agent.eval.test.ts` and vice versa, so the two commands stay disjoint
- * without either one having to exclude the other's file.
+ * without either one having to exclude the other's file. That holds for the
+ * `all` list too: it is built from {@link projectSpecFiles}, which drops the
+ * eval tier by infix.
  */
-export declare function runVitest(cwd: string, opts?: VitestRunOptions): string | false;
+export declare function runVitest(cwd: string, opts?: VitestRunOptions): string[] | false;
 /**
  * Classify a {@link runVitest} failure. execaSync throws an ENOENT-coded
  * error when the binary itself couldn't be spawned (infrastructure problem)
@@ -59,36 +98,63 @@ label?: string): {
     message: string;
 };
 /**
- * Spec files in the project that `aai test` did NOT run.
+ * Every spec file in the project that belongs to the TEST tier.
  *
- * `runVitest` passes ONE filename as a vitest FILTER, which is what keeps `test`
- * and `eval` disjoint without either excluding the other's file — see its doc.
- * The cost is that every other `*.test.ts` in the project is skipped, and the
- * skip was SILENT: the shipped `retail` template carries seven of them, so
- * `aai test` there ran 1 file / 67 tests, printed "Tests passed", and left
- * 211 of the project's 278 tests unrun with nothing saying so.
+ * Eval files are excluded by the `.eval.` INFIX — the tier convention — rather
+ * than by a filename list, which is what keeps this module from importing
+ * `eval.ts`, which imports this one.
+ */
+export declare function projectSpecFiles(cwd: string): string[];
+/**
+ * Spec files in the project that a run over `ran` did NOT cover.
  *
- * A silent skip is the worst outcome available, so the skip is announced rather
- * than the filter widened: which files `aai test` runs is a documented contract
- * (the scaffold guide says "Run agent.test.ts via vitest"), and running a
- * project's other specs by default could reach ones that are slow or want
- * credentials. Naming them costs nothing and is what a reader needs.
+ * `runVitest` passes the candidate filename as a vitest FILTER, which is what
+ * keeps `test` and `eval` disjoint without either excluding the other's file —
+ * see its doc. The cost is that every other `*.test.ts` in the project is
+ * skipped, and the skip was SILENT: the shipped `retail` template carries seven
+ * of them, so `aai test` there ran 1 file / 67 tests, printed "Tests passed",
+ * and left 211 of the project's 278 tests unrun with nothing saying so.
  *
- * Eval files are excluded because they have their OWN command, named in the
- * message.
+ * The narrow default STANDS — which files `aai test` runs is a documented
+ * contract (the scaffold guide says "Run agent.test.ts via vitest"), and running
+ * a project's other specs by default could reach ones that are slow or want
+ * credentials. What does not stand is a GREEN VERDICT over the difference: this
+ * set is what {@link executeTest} refuses to call a pass, what it puts in its
+ * result for a script to read, and what `--all` opts into running.
+ */
+export declare function unrunSpecFiles(cwd: string, ran: RanSpecs): string[];
+/**
+ * What a caller reports as covered: one filename, a list of them, or `false`
+ * for a run that found nothing to point vitest at.
  */
-export declare function unrunSpecFiles(cwd: string, ran: string): string[];
+export type RanSpecs = string | readonly string[] | false;
 /**
  * Warn, once, naming the spec files this run did not cover.
  *
- * `ran` is `false` when there was no `agent.test.ts` to run, and that case
- * needs the warning MORE rather than less: `aai test` then prints "No test file
- * found" while the project's spec files sit right there unrun, which reads as
- * "this project has no tests". Measured on a project whose only spec was
- * `tools/echo_back.test.ts` — `{"passed":true,"skipped":true}` and not a word
- * about it. It stays silent when there is nothing to name, in both arms.
+ * This is the notice for a caller whose own result says nothing about the
+ * narrowing — today that is `aai build`'s pre-build gate, which ran one file
+ * out of eight and printed "Build complete". `aai test` does not use it: an
+ * incomplete run is a FAILURE there, and the failure's own message is the
+ * report.
+ */
+export declare function warnUnrunSpecs(cwd: string, ran: RanSpecs): void;
+/** What `aai test` was asked to cover. */
+export type TestOptions = {
+    /** Run every non-eval spec in the project rather than `agent.test.ts` alone. */
+    readonly all?: boolean | undefined;
+};
+/**
+ * Execute agent tests and return structured result.
+ *
+ * **An incomplete run is not a pass.** For as long as this command answered
+ * `{"ok":true,"data":{"passed":true}}` with exit 0 over specs it had not run,
+ * the scaffold's `"test": "aai test"` was what users wired into CI — so a suite
+ * of 25 tests could go red in the editor and green in the pipeline, and adding
+ * one tool could break `registry.test.ts` in 17 assertions with `pnpm test` and
+ * `pnpm build` both staying green throughout. It is the same defect
+ * `defineExec`'s `cwd` policy exists for (a green result for a project that is
+ * not there), one directory over, and it gets the same answer: the command
+ * fails, names the files, and names the flag that runs them.
  */
-export declare function warnUnrunSpecs(cwd: string, ran: string | false): void;
-/** Execute agent tests and return structured result. */
-export declare function executeTest(cwd: string): Promise<CommandResult<TestData>>;
+export declare function executeTest(cwd: string, opts?: TestOptions): Promise<CommandResult<TestData>>;
 export {};

package/dist/typecheck.mjs

@@ -1,9 +1,9 @@
 #!/usr/bin/env node
-import { n as binFromManifest, o as errorMessage, u as readPackageJson } from "./_utils-B8QmtFhK.mjs";
+import { n as binFromManifest, o as errorMessage, u as readPackageJson } from "./_utils-Dhd058D9.mjs";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { spawn } from "node:child_process";
-//#region typecheck.ts
+//#region src/typecheck.ts
 /**
 * Project typechecking — `tsc --noEmit` over the project's own tsconfig.
 *

package/dist/worker-bundler.mjs

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
-import { i as errorCode } from "./_utils-B8QmtFhK.mjs";
-import { n as withPreservedNodeEnv } from "./_vite-env-D9Qj6KPX.mjs";
+import { i as errorCode } from "./_utils-Dhd058D9.mjs";
+import { n as withPreservedNodeEnv } from "./_vite-env-kejF0p2L.mjs";
 import path from "node:path";
 import fs from "node:fs/promises";
 import { invariant } from "@alexkroman1/aai/internal";
 import { build } from "vite";
-//#region worker-bundler.ts
+//#region src/worker-bundler.ts
 /**
 * Generated wrapper entry, written under `.aai/` for the duration of the
 * build (the CLI's own scratch dir — dot-paths are ignored by the dev

package/dist/{workflow-BBu5oEDw.mjs → workflow-BZyKLkhV.mjs}

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
-import { a as ok, n as fail, t as CliError } from "./_output-CKkmWs7i.mjs";
-import { n as log } from "./_ui-u7T4YooX.mjs";
-import { i as readProjectConfig } from "./_config-CmJOFsAP.mjs";
-import { n as getServerInfo } from "./_agent-BTwZJu4P.mjs";
+import { a as ok, n as fail, t as CliError } from "./_output-DbJt9gsl.mjs";
+import { n as log } from "./_ui-DCt4qZrk.mjs";
+import { i as readProjectConfig } from "./_config-ZY2euhdh.mjs";
+import { n as getServerInfo } from "./_agent-Clbq3a4h.mjs";
 import { errorMessage, omitUndefined } from "@alexkroman1/aai/utils";
 import { createWorkflowApiClient } from "@alexkroman1/aai/workflow-api";
-//#region workflow.ts
+//#region src/workflow.ts
 /**
 * `aai workflow` — reading and steering a deployed agent's durable runs from a
 * terminal.