@alexkroman1/aai-cli 8.2.0 → 9.0.0

package/dist/templates/solo-rpg/shared.ts

@@ -1,5 +1,4 @@
-import { type DeepReadonly, dialog, sessionSlot, type ToolContext } from "@alexkroman1/aai";
-import { z } from "zod";
+import { type DeepReadonly, dialog, sessionSlot } from "@alexkroman1/aai";
 
 // ── Tuning Constants ─────────────────────────────────────────────────────────
 export const MAX_SESSION_LOG = 50;
@@ -390,7 +389,7 @@ export const gameProjection = gameSlot.projection((game) => game);
  * `storyFlow.reset` — and it is what lets `gameOver` be a genuinely `final`
  * state, which is the whole point of having one: `position().done` means the
  * story ended, and XState delivers no events to a done actor, so an `on: {
- * SETUP }` there would have been dead config that looked live. `load_game`
+ * SETUP }` there would have been dead config that looked live. A resumed run
  * resets for the same reason. `SETUP` therefore appears once, on the only state
  * that can be transitioned out of.
  */
@@ -450,65 +449,18 @@ export const storyFlow = dialog("story", storySpec);
  */
 export type FrozenGameState = DeepReadonly<GameState>;
 
-// ── Persistent save slots (ctx.db) ───────────────────────────────────────────
-// save_game / load_game are genuine cross-session persistence, so they use
-// the app's SQL database. Requires storage: `aai storage enable` (or
-// Settings → Database in the studio); under `aai dev`, set DATABASE_URL in .env.
+// ── No cross-session saves, and why ─────────────────────────────────────────
+// `save_game` / `load_game` stood here, keyed by slot name and backed by an
+// `app_state` table through `ctx.db`. Both are gone with `ctx.db` itself: the
+// platform provides tool code no database, and a template cannot reach one — the
+// scaffold ships no Postgres client, and shipped template code cannot import
+// `@alexkroman1/aai-runtime` (templates type-check under the scaffold tsconfig,
+// which that package's source is not clean under).
 //
-// Slots are keyed by name alone — the whole point of a save is loading it in
-// a LATER session, whose sessionId differs, so the key can't embed one. The
-// storage is per app, so every player of one deployment shares the slot
-// namespace; without player identity that is the price of resumability.
-export function saveSlotKey(slot?: string): string {
-  return `save:${slot ?? "autosave"}`;
-}
-
-/** The slot-name grammar, shared by save_game and load_game so a name that
- *  can be saved can always be loaded. */
-export const saveSlotParam = z
-  .string()
-  .regex(/^[A-Za-z0-9_-]{1,32}$/, "letters, digits, dashes, underscores; max 32 chars")
-  .describe("Save slot name, defaults to autosave")
-  .optional();
-
-const ENSURE_APP_STATE = `create table if not exists app_state (
-  key text primary key,
-  value jsonb not null,
-  updated_at timestamptz not null default now()
-)`;
-
-// Memoized per process (each session's tools run in a fresh sandbox, so this
-// is at most one round-trip per session); a failure clears the memo so the
-// next call retries instead of caching the error forever.
-let ensureP: Promise<unknown> | null = null;
-function ensureTable(ctx: ToolContext): Promise<unknown> {
-  ensureP ??= ctx.db.query(ENSURE_APP_STATE).catch((err) => {
-    ensureP = null;
-    throw err;
-  });
-  return ensureP;
-}
-
-/** Read one saved value. jsonb columns come back from the postgres driver
- *  already parsed, so the value needs no JSON.parse here. */
-export async function loadState<T>(ctx: ToolContext, key: string): Promise<T | null> {
-  await ensureTable(ctx);
-  const rows = await ctx.db.query<{ value: T }>("select value from app_state where key = $1", [
-    key,
-  ]);
-  return rows[0]?.value ?? null;
-}
-
-/** Upsert one value. Serialized explicitly and cast with `::jsonb` so the
- *  write is driver-agnostic about object parameters. */
-export async function saveState(ctx: ToolContext, key: string, value: unknown): Promise<void> {
-  await ensureTable(ctx);
-  await ctx.db.query(
-    "insert into app_state (key, value, updated_at) values ($1, $2::jsonb, now()) " +
-      "on conflict (key) do update set value = excluded.value, updated_at = now()",
-    [key, JSON.stringify(value)],
-  );
-}
+// So this adventure is SINGLE-SESSION: everything lives in `sessionSlot`s and
+// ends when the call does. An author who wants saves adds a client of their own
+// (`postgres`, `pg`, a provider SDK) and a `DATABASE_URL` secret — which is the
+// supported pattern, just not one a shipped template can demonstrate.
 
 // ── Helpers ──────────────────────────────────────────────────────────────────
 export function d(sides: number): number {

package/dist/templates/spoken-summary/agent.test.ts

@@ -54,7 +54,6 @@ describe("the declaration", () => {
     // The page calls `api.start("spokenSummary", …)`, so a rename here is a
     // runtime 400 rather than a compile error. This is what pins it.
     expect(Object.keys(agentDef.workflows ?? {})).toEqual(["spokenSummary"]);
-    expect(agentDef.page).toBe("static");
   });
 
   test("declares no providers and exactly the one credential its steps read", () => {

package/dist/templates/spoken-summary/agent.ts

@@ -41,10 +41,11 @@
  *   three services this uses: transcription, the LLM Gateway, and the voice.
  *   `requiredEnv` below is what makes a deploy check for it rather than letting
  *   the first run find out.
- * - **Storage** (`aai storage enable`, Settings → Database in the studio, or
- *   `DATABASE_URL` under `aai dev`). REQUIRED here, and more so than for most
- *   workflow apps: an upload's record is a row, and this app uses uploads at
- *   BOTH ends — the recording coming in and the summary going out.
+ * - **A `DATABASE_URL`** — a secret when deployed, `.env` under `aai dev`, and a
+ *   Postgres you bring since the platform provisions none. REQUIRED here, and
+ *   more so than for most workflow apps: an upload's record is a row, and this
+ *   app uses uploads at BOTH ends — the recording coming in and the summary
+ *   going out.
  *
  * ## The recording is UPLOADED, and the run carries its id
  *

package/dist/templates/spoken-summary/client.tsx

@@ -37,7 +37,6 @@ import "@alexkroman1/aai-ui/styles.css";
 // nothing — and it is what stops this file restating a shape
 // `workflows/summarize.ts` already declares.
 import { formatDuration } from "@alexkroman1/aai/utils";
-import type { WorkflowOutputOf } from "@alexkroman1/aai/workflow-api";
 import {
   createWorkflowApi,
   Form,
@@ -51,9 +50,6 @@ import {
 } from "@alexkroman1/aai-ui";
 import type { spokenSummary } from "./agent.ts";
 
-/** What a completed run reports, derived from the workflow rather than restated. */
-type Summary = WorkflowOutputOf<typeof spokenSummary>;
-
 /**
  * The workflow's name, as a page starts a run by one.
  *
@@ -88,8 +84,9 @@ function captionsUrl(text: string, durationMs: number): string {
 export function App() {
   // The generic is what makes `run.status === "completed"` narrow to a TYPED
   // `run.output` instead of `unknown`.
-  const { submit, run, pending, upload, pauseUpload, resumeUpload, error } =
-    useWorkflowSubmit<Summary>(WORKFLOW, { api });
+  const { submitForm, run, pending, upload, pauseUpload, resumeUpload, error } = useWorkflowSubmit<
+    typeof spokenSummary
+  >(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
@@ -105,7 +102,7 @@ export function App() {
         </p>
       </header>
 
-      <Form onSubmit={submit} error={error} className="flex flex-col gap-4">
+      <Form onSubmit={submitForm} 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="Working…">

package/dist/templates/support-line/agent.eval.test.ts

@@ -1,5 +1,3 @@
-/// <reference types="vite/client" />
-
 // An EVAL: does the line really refuse to say what it cannot ground? Run it
 // with `aai eval`.
 //
@@ -27,20 +25,12 @@
 // product questions from its own knowledge and skips the tools the prompt exists
 // to route it through, so a case run that way measures nothing it claims to.
 
-import { withSystemPrompt } from "@alexkroman1/aai/manifest";
-import { withDiscoveredTools } from "@alexkroman1/aai/testing";
+/** The def a DEPLOYED agent runs — see `agent.test.ts` on why the glob is here. */
+import agentDef from "virtual:aai/agent";
 import { type EvalSession, toolResultIn } from "@alexkroman1/aai-runtime/eval";
 import { describeEval } from "@alexkroman1/aai-runtime/eval/vitest";
 import { expect } from "vitest";
 import { z } from "zod";
-import authoredAgent from "./agent.ts";
-import systemPrompt from "./system-prompt.md?raw";
-
-/** The def a DEPLOYED agent runs — see `agent.test.ts` on why the glob is here. */
-const agentDef = withSystemPrompt(
-  withDiscoveredTools(authoredAgent, import.meta.glob("./tools/*.ts", { eager: true })),
-  systemPrompt,
-);
 
 /**
  * What the BROWSER is sent, as this eval reads it.

package/dist/templates/support-line/agent.test.ts

@@ -1,26 +1,7 @@
-/// <reference types="vite/client" />
-
-import {
-  createToolContext,
-  stubGenerate,
-  toolRunner,
-  withDiscoveredTools,
-} from "@alexkroman1/aai/testing";
+/** The def a DEPLOYED agent runs: authored, plus what `tools/` declares. */
+import agentDef from "virtual:aai/agent";
+import { createToolContext, stubGenerate, toolRunner } from "@alexkroman1/aai/testing";
 import { describe, expect, test } from "vitest";
-import authoredAgent from "./agent.ts";
-
-/**
- * The def a DEPLOYED agent runs: authored, plus what `tools/` declares.
- *
- * The glob is written HERE rather than reached for from a shared helper because
- * this file SHIPS: it is what a scaffolded project runs, so it may not import
- * anything outside its own template, and `import.meta.glob` is expanded against
- * the file containing it either way. This is the pattern a user writes.
- */
-const agentDef = withDiscoveredTools(
-  authoredAgent,
-  import.meta.glob("./tools/*.ts", { eager: true }),
-);
 
 import { MAX_ATTEMPTS, runCorrectiveRag } from "./procedure.ts";
 import {

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

@@ -17,10 +17,10 @@
  *   `aai secret put ASSEMBLYAI_API_KEY` once deployed. `requiredEnv` below is
  *   what makes a deploy check for it rather than letting the first run find out.
  *   A step reads it with `requireStepEnv`; see `@alexkroman1/aai/step`.
- * - **Storage** (`aai storage enable`, Settings → Database in the studio, or
- *   `DATABASE_URL` under `aai dev`). REQUIRED here, unlike most workflow apps:
- *   a run survives without it, but an UPLOAD's record is a row, so the form
- *   below refuses by name until storage is on.
+ * - **A `DATABASE_URL`** — a secret when deployed, `.env` under `aai dev` — and
+ *   the platform provisions none, so it is a Postgres you bring. REQUIRED here,
+ *   unlike most workflow apps: runs are durable on the platform either way, but
+ *   an UPLOAD's record is a row, so the form below refuses by name without one.
  * - **ffmpeg, under `aai dev` only.** A deployed guest's image installs it; on a
  *   laptop it is whatever is on `PATH` (or `AAI_FFMPEG_PATH`). The `transcribe`
  *   flow needs it for anything that is not already a linear-PCM WAV, because the

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

@@ -359,14 +359,14 @@ function TranscriptionDesk() {
   // ALL THREE hooks are called every render, because a hook may not be conditional —
   // 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.
-  const streamed = useWorkflowStream<Transcript>(WORKFLOWS.streaming, { parallel });
-  const stored = useWorkflowSubmit<Transcript>(WORKFLOWS.classic, { parallel });
-  const batched = useWorkflowSubmit<Transcript>(WORKFLOWS.batch, { parallel });
+  const streamed = useWorkflowStream<typeof transcribe>(WORKFLOWS.streaming, { parallel });
+  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.
   const active = mode === "streaming" ? streamed : mode === "batch" ? batched : stored;
-  const { submit, run, upload, pending, error, reset, pauseUpload, resumeUpload } = active;
+  const { submitForm, run, upload, pending, error, reset, pauseUpload, resumeUpload } = active;
   // History is per WORKFLOW, so the list follows the mode: two flows that produce
   // the same output are still two different things to have run, and merging them
   // would put a run under a heading that cannot explain it.
@@ -422,7 +422,7 @@ function TranscriptionDesk() {
       <Form
         onSubmit={(values) => {
           total.start();
-          return submit(values);
+          return submitForm(values);
         }}
         error={error}
       >

package/dist/templates/transcription-workflow/workflows/transcribe.ts

@@ -167,7 +167,16 @@ export const BYTES_IN_FLIGHT = 640 * 1024 * 1024;
  *
  * The table above was measured under the old per-round barrier. Re-measuring it is
  * worth doing before this number moves again: the window makes a wide fan-out
- * cheaper at the tail, which if anything argues for a HIGHER knee.
+ * cheaper at the tail, which if anything argues for a HIGHER knee. *
+ * **What EXECUTES at this width is the world's call, not this number's.**
+ * `mapConcurrent` bounds how many step calls the body has in flight; how many
+ * run at once is the workflow world's worker concurrency, which on the
+ * `DATABASE_URL` path defaults to three — so on a default deployment a width
+ * above three is inert while still costing a queued job per item. That makes
+ * this the FAR SIDE's knee and the width to use once an operator has raised
+ * the ceiling, not a promise about a stock deployment. See "The WINDOW is not
+ * the concurrency" in `@alexkroman1/aai/step`'s `mapConcurrent`; the numbers
+ * above were measured against the endpoint and say nothing about that layer.
  */
 export const MAX_SEGMENT_CONCURRENCY = 32;
 

package/dist/templates/travel-concierge/agent.eval.test.ts

@@ -1,5 +1,3 @@
-/// <reference types="vite/client" />
-
 // An EVAL: does the confirmation gate actually gate? Run it with `aai eval`.
 //
 // `agent.test.ts` drives each tool directly and asserts about the state it
@@ -22,15 +20,6 @@
 // product questions from its own knowledge and skips the tools the prompt exists
 // to route it through, so a case run that way measures nothing it claims to.
 
-import { withSystemPrompt } from "@alexkroman1/aai/manifest";
-import { withDiscoveredTools } from "@alexkroman1/aai/testing";
-import { type EvalSession, type EvalTurn, lastStateIn } from "@alexkroman1/aai-runtime/eval";
-import { describeEval } from "@alexkroman1/aai-runtime/eval/vitest";
-import { expect } from "vitest";
-import { z } from "zod";
-import authoredAgent from "./agent.ts";
-import systemPrompt from "./system-prompt.md?raw";
-
 /**
  * The def a DEPLOYED agent runs: authored, plus what `tools/` declares.
  *
@@ -39,10 +28,11 @@ import systemPrompt from "./system-prompt.md?raw";
  * outside its own template. An eval that forgot it would run an agent with NO
  * tools and read as a model that refuses to act.
  */
-const agentDef = withSystemPrompt(
-  withDiscoveredTools(authoredAgent, import.meta.glob("./tools/*.ts", { eager: true })),
-  systemPrompt,
-);
+import agentDef from "virtual:aai/agent";
+import { type EvalSession, type EvalTurn, lastStateIn } from "@alexkroman1/aai-runtime/eval";
+import { describeEval } from "@alexkroman1/aai-runtime/eval/vitest";
+import { expect } from "vitest";
+import { z } from "zod";
 
 /**
  * What the BROWSER is sent, as this eval reads it.

package/dist/templates/travel-concierge/agent.test.ts

@@ -1,28 +1,8 @@
-/// <reference types="vite/client" />
-
+/** The def a DEPLOYED agent runs: authored, plus what `tools/` declares. */
+import agentDef from "virtual:aai/agent";
 import type { ToolContext } from "@alexkroman1/aai";
-import {
-  createToolContext,
-  ok,
-  okPosition,
-  toolRunner,
-  withDiscoveredTools,
-} from "@alexkroman1/aai/testing";
+import { createToolContext, ok, okPosition, toolRunner } from "@alexkroman1/aai/testing";
 import { describe, expect, test } from "vitest";
-import authoredAgent from "./agent.ts";
-
-/**
- * The def a DEPLOYED agent runs: authored, plus what `tools/` declares.
- *
- * The glob is written HERE rather than reached for from a shared helper because
- * this file SHIPS: it is what a scaffolded project runs, so it may not import
- * anything outside its own template, and `import.meta.glob` is expanded against
- * the file containing it either way. This is the pattern a user writes.
- */
-const agentDef = withDiscoveredTools(
-  authoredAgent,
-  import.meta.glob("./tools/*.ts", { eager: true }),
-);
 
 import {
   activeAssistant,

package/dist/templates/web-researcher/agent.eval.test.ts

@@ -12,13 +12,10 @@
 // `agent.ts` alone would measure Scout with none of its own rules — and its
 // rules are the entire subject of this file. The reasoning is spelled out in
 // `../code-interpreter/agent.eval.test.ts`.
-import { withSystemPrompt } from "@alexkroman1/aai/manifest";
+
+import agentDef from "virtual:aai/agent";
 import { describeEval } from "@alexkroman1/aai-runtime/eval/vitest";
 import { expect } from "vitest";
-import authored from "./agent.ts";
-import systemPrompt from "./system-prompt.md?raw";
-
-const agentDef = withSystemPrompt(authored, systemPrompt);
 
 /**
  * The registrable label of every host this turn's tool results mentioned —

package/dist/test-CvwgeVSQ.mjs

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+import { a as ok, n as fail } from "./_output-CKkmWs7i.mjs";
+import { n as log, r as notify } from "./_ui-u7T4YooX.mjs";
+import { i as errorCode, o as errorMessage$1, r as binFromPackageJson } from "./_utils-B8QmtFhK.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 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 one of `candidates` in the given project directory.
+*
+* Returns the FILE it ran, or `false` if none of the candidate files exists.
+* Throws on failure.
+*
+* A vitest FILTER, not an include glob: the 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.
+*/
+function runVitest(cwd, opts = { candidates: TEST_FILES }) {
+	const testFile = opts.candidates.find((name) => existsSync(path.join(cwd, name)));
+	if (!testFile) return false;
+	const { cmd, args } = resolveVitestCommand(cwd);
+	execaSync(cmd, [
+		...args,
+		"run",
+		"--root",
+		".",
+		...opts.extraArgs ?? [],
+		testFile
+	], {
+		cwd,
+		stdio: "inherit",
+		...omitUndefined({ env: opts.env ? {
+			...process.env,
+			...opts.env
+		} : void 0 })
+	});
+	return testFile;
+}
+/**
+* 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)$/;
+/**
+* Spec files in the project that `aai test` did NOT run.
+*
+* `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.
+*
+* 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.
+*
+* Eval files are excluded because they have their OWN command, named in the
+* message.
+*/
+function unrunSpecFiles(cwd, ran) {
+	const found = [];
+	collectSpecs(cwd, "", ran, found);
+	return found.sort(compareCodeUnits);
+}
+/** Code-unit comparison — see {@link unrunSpecFiles} for why not `localeCompare`. */
+function compareCodeUnits(a, b) {
+	if (a < b) return -1;
+	return a > b ? 1 : 0;
+}
+/** One directory of {@link unrunSpecFiles}, recursing into the ones that count. */
+function collectSpecs(dir, prefix, ran, 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, ran, out);
+		} else if (isUnrunSpec(e.name, rel, ran)) out.push(rel);
+	}
+}
+/** A spec file this run did not cover. The `.eval.` INFIX is the tier convention. */
+function isUnrunSpec(name, rel, ran) {
+	if (!SPEC_FILE_RE.test(name)) return false;
+	return rel !== ran && !name.includes(".eval.test.");
+}
+/**
+* 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.
+*/
+function warnUnrunSpecs(cwd, ran) {
+	const skipped = unrunSpecFiles(cwd, ran === false ? "" : ran);
+	if (skipped.length === 0) return;
+	notify("warn", `${ran === false ? `\`aai test\` found no agent.test.ts, so it ran nothing. ${skipped.length} spec file(s) exist and were NOT run:` : `\`aai test\` ran ${ran} only. ${skipped.length} other spec file(s) were NOT run:`} ${skipped.join(", ")}. Run them with your own vitest (\`npx vitest run\`); behaviour evals have their own command (\`aai eval\`).`);
+}
+/** Execute agent tests and return structured result. */
+async function executeTest(cwd) {
+	log.step("Running agent tests");
+	try {
+		const ran = runVitest(cwd);
+		if (!ran) {
+			log.info("No test file found. Create agent.test.ts to add tests.");
+			warnUnrunSpecs(cwd, ran);
+			return ok({
+				passed: true,
+				skipped: true
+			});
+		}
+		log.success("Tests passed");
+		warnUnrunSpecs(cwd, ran);
+		return ok({ passed: true });
+	} catch (err) {
+		const { code, message } = classifyVitestError(err);
+		return fail(code, message);
+	}
+}
+//#endregion
+export { classifyVitestError, executeTest, runVitest };

package/dist/test.d.ts

@@ -37,7 +37,7 @@ export type VitestRunOptions = {
 /**
  * Run vitest over one of `candidates` in the given project directory.
  *
- * Returns `true` if it ran, `false` if none of the candidate files exists.
+ * Returns the FILE it ran, or `false` if none of the candidate files exists.
  * Throws on failure.
  *
  * A vitest FILTER, not an include glob: the argument is matched as a substring
@@ -46,7 +46,7 @@ export type VitestRunOptions = {
  * `agent.eval.test.ts` and vice versa, so the two commands stay disjoint
  * without either one having to exclude the other's file.
  */
-export declare function runVitest(cwd: string, opts?: VitestRunOptions): boolean;
+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)
@@ -58,6 +58,37 @@ label?: string): {
     code: "spawn_failed" | "test_failed";
     message: string;
 };
+/**
+ * Spec files in the project that `aai test` did NOT run.
+ *
+ * `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.
+ *
+ * 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.
+ *
+ * Eval files are excluded because they have their OWN command, named in the
+ * message.
+ */
+export declare function unrunSpecFiles(cwd: string, ran: string): string[];
+/**
+ * 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.
+ */
+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 {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexkroman1/aai-cli",
-  "version": "8.2.0",
+  "version": "9.0.0",
   "type": "module",
   "bin": {
     "aai": "bin.mjs"
@@ -44,9 +44,9 @@
     "p-timeout": "^7.0.1",
     "vite": "^8.2.1",
     "zod": "^4.4.3",
-    "@alexkroman1/aai-ui": "8.2.0",
-    "@alexkroman1/aai": "8.2.0",
-    "@alexkroman1/aai-runtime": "8.2.0"
+    "@alexkroman1/aai": "9.0.0",
+    "@alexkroman1/aai-runtime": "9.0.0",
+    "@alexkroman1/aai-ui": "9.0.0"
   },
   "devDependencies": {
     "playwright": "^1.62.1",