@alexkroman1/aai-cli 8.2.1 → 9.0.0

package/dist/_dev-env.d.ts

@@ -30,7 +30,7 @@ export declare function hostModeEnv(providerEnv: Record<string, string>): Record
  */
 export declare function devBindHost(): string | undefined;
 /**
- * File watching is OPT-IN — `AAI_DEV_WATCH=1` turns it on.
+ * File watching is OPT-IN — `aai dev --watch`, or `AAI_DEV_WATCH=1`.
  *
  * A restart rebuilds the bundle and replaces the server, which drops nothing
  * mid-request but does end in-flight voice sessions. That is the right default
@@ -38,8 +38,21 @@ export declare function devBindHost(): string | undefined;
  * host for twenty minutes: a stray formatter save, a `.env` touch, or a git
  * operation restarts the server underneath the run, and the harness reports it
  * as a provider failure several records deep.
+ *
+ * **The FLAG exists because the variable was undiscoverable**, which made the
+ * default a defect rather than a decision: `aai dev --help` listed nothing about
+ * watching, `AAI_DEV_WATCH` appeared in no document a user reads, and the guide
+ * shipped into every scaffolded project opened with "Iterate in `pnpm dev` —
+ * hot reload". So the promise was false and there was no way to find the switch
+ * that makes it true. The variable stays for a process supervisor, which has an
+ * environment and no argv.
+ *
+ * The flag WINS when passed, in both directions: `--watch` turns it on where the
+ * variable is unset or off, and `--watch=false` turns it off where the variable
+ * says on — an explicit argument that a stale exported variable could override
+ * would be the same discoverability bug wearing the fix's clothes.
  */
-export declare function devWatchEnabled(): boolean;
+export declare function devWatchEnabled(flag?: boolean | undefined): boolean;
 /**
  * The logger the dev server's runtime writes through.
  *

package/dist/{_dev-server-Dt3TCjhj.mjs → _dev-server-BAR8Ya43.mjs}

@@ -4,6 +4,7 @@ import { i as errorCode, o as errorMessage$1 } from "./_utils-B8QmtFhK.mjs";
 import { n as fallbackHtmlPlugin } from "./client-bundler-CWnG42cU.mjs";
 import { t as DEDUPED_PEERS } from "./_vite-env-BNveawd1.mjs";
 import { n as buildWorkflows, t as buildWorker } from "./worker-bundler-CCVEDjm1.mjs";
+import { typecheckProject } from "./typecheck.mjs";
 import { n as ensureApiKey } from "./_config-CmJOFsAP.mjs";
 import { n as createWorkerEvaluator } from "./_bundler-CDuYl5Gb.mjs";
 import { t as resolveServerEnv } from "./_server-common-6e0QI4mq.mjs";
@@ -12,7 +13,7 @@ import path from "node:path";
 import { omitUndefined } from "@alexkroman1/aai/utils";
 import { createCoalescingRunner, sleep } from "@alexkroman1/aai/internal";
 import { agentConfigWarnings } from "@alexkroman1/aai/manifest";
-import { WORKFLOW_API_PREFIX, createRuntime, createServer, requiredProviderEnvVars, withHostCredentialFallback } from "@alexkroman1/aai-runtime";
+import { WORKFLOW_API_PREFIX, createRuntime, createServer, ensureSessionStateSchema, requiredProviderEnvVars, withHostCredentialFallback } from "@alexkroman1/aai-runtime";
 import { configureWorkflowWorld, consoleLogger, createWorkflowSurface, handleWorkflowRequest, publishStepEnv, startWorkflowWorldIfDeclared } from "@alexkroman1/aai-runtime/internal";
 import { defaultClientDir } from "@alexkroman1/aai-ui/client-dir";
 import { watch } from "chokidar";
@@ -42,7 +43,7 @@ function devBindHost() {
 	return host ? host : void 0;
 }
 /**
-* File watching is OPT-IN — `AAI_DEV_WATCH=1` turns it on.
+* File watching is OPT-IN — `aai dev --watch`, or `AAI_DEV_WATCH=1`.
 *
 * A restart rebuilds the bundle and replaces the server, which drops nothing
 * mid-request but does end in-flight voice sessions. That is the right default
@@ -50,8 +51,22 @@ function devBindHost() {
 * host for twenty minutes: a stray formatter save, a `.env` touch, or a git
 * operation restarts the server underneath the run, and the harness reports it
 * as a provider failure several records deep.
+*
+* **The FLAG exists because the variable was undiscoverable**, which made the
+* default a defect rather than a decision: `aai dev --help` listed nothing about
+* watching, `AAI_DEV_WATCH` appeared in no document a user reads, and the guide
+* shipped into every scaffolded project opened with "Iterate in `pnpm dev` —
+* hot reload". So the promise was false and there was no way to find the switch
+* that makes it true. The variable stays for a process supervisor, which has an
+* environment and no argv.
+*
+* The flag WINS when passed, in both directions: `--watch` turns it on where the
+* variable is unset or off, and `--watch=false` turns it off where the variable
+* says on — an explicit argument that a stale exported variable could override
+* would be the same discoverability bug wearing the fix's clothes.
 */
-function devWatchEnabled() {
+function devWatchEnabled(flag) {
+	if (flag !== void 0) return flag;
 	return /^(1|true|yes|on)$/i.test(process.env.AAI_DEV_WATCH?.trim() ?? "");
 }
 /**
@@ -215,6 +230,149 @@ function createRestartSupervisor(ops) {
 	};
 }
 //#endregion
+//#region _dev-typecheck.ts
+/**
+* The background typecheck under `aai dev`.
+*
+* `assertTypechecks` is wired into `build`, `deploy` and `studio` — and not
+* into `dev`, the loop an author actually lives in. That made the whole
+* compile-message system in `agent-params.ts` (five families of hand-written
+* diagnostic sentences, the most careful work in the SDK) conditional on the
+* author having an editor open on the right file. Demonstrated: a project whose
+* `agent.ts` fails `tsc --noEmit` starts cleanly under `aai dev` and serves,
+* and the typo is found later by `aai build` — or by a caller.
+*
+* Three properties, and each is the reason this is not just a call to
+* `assertTypechecks`:
+*
+* - **It never blocks and never fails the server.** `aai dev` must start with a
+*   type error in an unrelated file; refusing to serve would be a worse tool
+*   than one that says nothing. The report is a `notify`, not a throw.
+* - **It coalesces.** A save touches several files and the watcher debounces to
+*   a restart; without coalescing a burst spawns a `tsc` per restart, and `tsc`
+*   on a real project is seconds. A request during a run schedules exactly one
+*   more, which is `createCoalescingRunner`'s contract.
+* - **It is quiet when clean.** A dev server that prints "types OK" on every
+*   save trains the author to stop reading it, which is how the failure this
+*   exists to surface gets missed again.
+*/
+/**
+* A coalescing background typechecker for the project at `cwd`.
+*
+* `report` is injected so the dev-server specs can read what an author would
+* have seen without capturing stdout — the same seam every other reporter in
+* this package takes.
+*/
+function createDevTypecheck(cwd, report = notify) {
+	const runner = createCoalescingRunner(async () => {
+		const result = await typecheckProject(cwd);
+		if (result.ok) return;
+		report("warn", `Type errors — \`aai dev\` keeps serving, but \`aai build\` will refuse:\n${result.output}`);
+	});
+	return { request() {
+		runner.trigger().catch((err) => {
+			report("error", `Background typecheck failed to run: ${String(err)}`);
+		});
+	} };
+}
+//#endregion
+//#region _dev-vite-config.ts
+/**
+* The Vite dev server's config for a project with a `client.tsx`.
+*
+* Its own module because it is the whole agent API as the BROWSER can see it —
+* a table worth reading without the 400 lines of watcher, restart and env
+* plumbing that surround it in `_dev-server.ts`, which is also what pushed that
+* file past the length cap.
+*/
+/**
+* Vite dev-server config for the client SPA. Extracted so the proxy wiring
+* is unit-testable: `/websocket` MUST proxy with `ws: true` or `aai dev`
+* with a `client.tsx` serves a page whose WebSocket never connects.
+*
+* **This table is the whole agent API as the browser can see it**, which is
+* the thing to hold in mind before adding a route to `createServer`. Vite owns
+* the port the user is told to open and answers everything not listed here
+* itself — with a bare 404 carrying none of the agent server's headers, so the
+* failure looks like a missing route rather than a missing proxy entry.
+*
+* `/workflows` is why that matters beyond voice. A WORKFLOW APP
+* (`workflowApp()`) has no session and no socket: `page()` mounts a
+* form and every single thing it does — listing workflows, starting a run,
+* polling it, streaming its events — is a same-origin `fetch` under that
+* prefix. Unproxied, the two workflow-app templates were dead on arrival under
+* `aai dev` (`404 POST /workflows/runs` the instant the form is submitted)
+* while the backend served the API correctly one port over. A string key
+* prefix-matches, so this one entry covers `/runs`, `/runs/:id` and the
+* `/runs/:id/events` SSE stream.
+*
+* `strictPort` because the reported URL is `http://localhost:<port>` —
+* without it, Vite silently binds port+N when the port is busy and the
+* printed/JSON-returned URL points at whatever else was listening.
+*
+* `AAI_DEV_HOST` reaches BOTH servers. Binding only the backend left Vite —
+* the port the user is told to open — on loopback, i.e. failing exactly the
+* case that variable exists for (`aai dev` in a container, reached from the host).
+*
+* ## The target is an IP LITERAL, and that is a fix rather than a style choice
+*
+* `127.0.0.1`, never `localhost`. Vite opens a FRESH upstream connection for
+* every WebSocket upgrade — an HTTP request reuses a pooled keep-alive socket and
+* so resolves rarely — which means a hostname here is one `getaddrinfo` per
+* session handshake. That lookup runs on libuv's threadpool (four threads,
+* shared with every other fs and DNS call in a process that is ALSO serving the
+* agent), and under load it intermittently stalls for almost exactly two
+* seconds.
+*
+* Measured on the `retail` template, session handshakes to `session.configured`:
+*
+* | Target | conc | rps | p50 | p99 |
+* | --- | --- | --- | --- | --- |
+* | `localhost` | 1 | 12-18 | 8-11 ms | 2.0 s |
+* | `localhost` | 10 | 0.6 | 16.7 s | 16.7 s |
+* | `127.0.0.1` | 1 | 89-207 | 4-9 ms | 23-49 ms |
+* | `127.0.0.1` | 20 | 260 | 73 ms | 166 ms |
+*
+* The `localhost` row is not a slow proxy, it is a queue: one handshake in thirty
+* stalls two seconds on its own, and at concurrency 10 the stalls pile onto four
+* threads until a sustained burst left the proxy refusing upgrades entirely until
+* the dev server was restarted. With the literal it recovers from a burst and
+* sits within ~1.5x of the backend port.
+*
+* Localized by timing the phases separately — TCP connect and the first frame
+* were always fast, the 101 was not — and then by comparing the instant the
+* client sent its upgrade against the backend's own log line for it: 23.808 out,
+* 25.796 in, answered in 5 ms. The two seconds were spent before Vite dialled,
+* which is what pointed at resolution rather than at either server.
+*
+* Not a behaviour change: `localhost` resolved to loopback anyway, so this
+* removes the lookup and nothing else. An `AAI_DEV_HOST` that binds the backend
+* to ONE non-loopback interface was unreachable through the proxy before this and
+* still is.
+*/
+function viteDevConfig(cwd, vitePort, backendPort) {
+	const target = `http://127.0.0.1:${backendPort}`;
+	return {
+		root: cwd,
+		plugins: [fallbackHtmlPlugin(cwd)],
+		resolve: { dedupe: DEDUPED_PEERS },
+		server: {
+			port: vitePort,
+			strictPort: true,
+			...omitUndefined({ host: devBindHost() }),
+			proxy: {
+				"/health": target,
+				"/client-config": target,
+				"/websocket": {
+					target,
+					ws: true
+				},
+				[WORKFLOW_API_PREFIX]: target
+			}
+		}
+	};
+}
+//#endregion
 //#region _dev-server.ts
 /**
 * Dev server for directory-based agents.
@@ -332,57 +490,6 @@ function watchDirectory(dir, onChange) {
 	return watcher;
 }
 /**
-* Vite dev-server config for the client SPA. Extracted so the proxy wiring
-* is unit-testable: `/websocket` MUST proxy with `ws: true` or `aai dev`
-* with a `client.tsx` serves a page whose WebSocket never connects.
-*
-* **This table is the whole agent API as the browser can see it**, which is
-* the thing to hold in mind before adding a route to `createServer`. Vite owns
-* the port the user is told to open and answers everything not listed here
-* itself — with a bare 404 carrying none of the agent server's headers, so the
-* failure looks like a missing route rather than a missing proxy entry.
-*
-* `/workflows` is why that matters beyond voice. A WORKFLOW APP
-* (`workflowApp()`) has no session and no socket: `page()` mounts a
-* form and every single thing it does — listing workflows, starting a run,
-* polling it, streaming its events — is a same-origin `fetch` under that
-* prefix. Unproxied, the two workflow-app templates were dead on arrival under
-* `aai dev` (`404 POST /workflows/runs` the instant the form is submitted)
-* while the backend served the API correctly one port over. A string key
-* prefix-matches, so this one entry covers `/runs`, `/runs/:id` and the
-* `/runs/:id/events` SSE stream.
-*
-* `strictPort` because the reported URL is `http://localhost:<port>` —
-* without it, Vite silently binds port+N when the port is busy and the
-* printed/JSON-returned URL points at whatever else was listening.
-*
-* `AAI_DEV_HOST` reaches BOTH servers. Binding only the backend left Vite —
-* the port the user is told to open — on loopback, i.e. failing exactly the
-* case that variable exists for (`aai dev` in a container, reached from the host).
-*/
-function viteDevConfig(cwd, vitePort, backendPort) {
-	const target = `http://localhost:${backendPort}`;
-	return {
-		root: cwd,
-		plugins: [fallbackHtmlPlugin(cwd)],
-		resolve: { dedupe: DEDUPED_PEERS },
-		server: {
-			port: vitePort,
-			strictPort: true,
-			...omitUndefined({ host: devBindHost() }),
-			proxy: {
-				"/health": target,
-				"/client-config": target,
-				"/websocket": {
-					target,
-					ws: true
-				},
-				[WORKFLOW_API_PREFIX]: target
-			}
-		}
-	};
-}
-/**
 * Start the dev server for a directory-based agent.
 *
 * Returns a cleanup function to shut down the server and watchers.
@@ -396,11 +503,26 @@ async function startDevServer(opts) {
 	const evaluateWorker = createWorkerEvaluator();
 	const devLogger = createDevLogger(outputSilenced());
 	let workflowWorldStarted = false;
+	/**
+	* Whether the session-state tables have been ensured this process.
+	*
+	* Once, like the workflow world above and for the same reason: a rebuild
+	* replaces the routes, not the storage behind them, and re-running the DDL on
+	* every file save would be two round trips per keystroke burst.
+	*/
+	let sessionSchemaEnsured = false;
 	/** Full build sequence, shared by initial startup and every restart. */
 	async function buildServer() {
 		const worker = await loadWorker(cwd, evaluateWorker);
 		const agentDef = worker.agent;
 		const env = await resolveAgentEnv(cwd, agentDef);
+		if (env.DATABASE_URL && !sessionSchemaEnsured) {
+			sessionSchemaEnsured = true;
+			await ensureSessionStateSchema({
+				url: env.DATABASE_URL,
+				logger: devLogger
+			});
+		}
 		const world = configureWorkflowWorld({
 			databaseUrl: env.DATABASE_URL,
 			port: backendPort,
@@ -442,7 +564,12 @@ async function startDevServer(opts) {
 			await viteServer?.close().catch(() => void 0);
 		}
 	});
-	watcher = devWatchEnabled() ? watchDirectory(cwd, supervisor.request) : void 0;
+	const devTypecheck = createDevTypecheck(cwd);
+	devTypecheck.request();
+	watcher = devWatchEnabled(opts.watch) ? watchDirectory(cwd, () => {
+		devTypecheck.request();
+		supervisor.request();
+	}) : void 0;
 	let boundServer;
 	try {
 		const initialServer = await buildServer();

package/dist/_dev-server.d.ts

@@ -63,37 +63,12 @@ export declare function watchDirectory(dir: string, onChange: () => void): FSWat
 export type DevServerOptions = {
     cwd: string;
     port: number;
+    /**
+     * Restart on a file change. Omitted, `AAI_DEV_WATCH` decides — see
+     * {@link devWatchEnabled} for why watching is opt-in at all.
+     */
+    watch?: boolean | undefined;
 };
-/**
- * Vite dev-server config for the client SPA. Extracted so the proxy wiring
- * is unit-testable: `/websocket` MUST proxy with `ws: true` or `aai dev`
- * with a `client.tsx` serves a page whose WebSocket never connects.
- *
- * **This table is the whole agent API as the browser can see it**, which is
- * the thing to hold in mind before adding a route to `createServer`. Vite owns
- * the port the user is told to open and answers everything not listed here
- * itself — with a bare 404 carrying none of the agent server's headers, so the
- * failure looks like a missing route rather than a missing proxy entry.
- *
- * `/workflows` is why that matters beyond voice. A WORKFLOW APP
- * (`workflowApp()`) has no session and no socket: `page()` mounts a
- * form and every single thing it does — listing workflows, starting a run,
- * polling it, streaming its events — is a same-origin `fetch` under that
- * prefix. Unproxied, the two workflow-app templates were dead on arrival under
- * `aai dev` (`404 POST /workflows/runs` the instant the form is submitted)
- * while the backend served the API correctly one port over. A string key
- * prefix-matches, so this one entry covers `/runs`, `/runs/:id` and the
- * `/runs/:id/events` SSE stream.
- *
- * `strictPort` because the reported URL is `http://localhost:<port>` —
- * without it, Vite silently binds port+N when the port is busy and the
- * printed/JSON-returned URL points at whatever else was listening.
- *
- * `AAI_DEV_HOST` reaches BOTH servers. Binding only the backend left Vite —
- * the port the user is told to open — on loopback, i.e. failing exactly the
- * case that variable exists for (`aai dev` in a container, reached from the host).
- */
-export declare function viteDevConfig(cwd: string, vitePort: number, backendPort: number): import("vite").InlineConfig;
 /**
  * Start the dev server for a directory-based agent.
  *

package/dist/_dev-typecheck.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The background typecheck under `aai dev`.
+ *
+ * `assertTypechecks` is wired into `build`, `deploy` and `studio` — and not
+ * into `dev`, the loop an author actually lives in. That made the whole
+ * compile-message system in `agent-params.ts` (five families of hand-written
+ * diagnostic sentences, the most careful work in the SDK) conditional on the
+ * author having an editor open on the right file. Demonstrated: a project whose
+ * `agent.ts` fails `tsc --noEmit` starts cleanly under `aai dev` and serves,
+ * and the typo is found later by `aai build` — or by a caller.
+ *
+ * Three properties, and each is the reason this is not just a call to
+ * `assertTypechecks`:
+ *
+ * - **It never blocks and never fails the server.** `aai dev` must start with a
+ *   type error in an unrelated file; refusing to serve would be a worse tool
+ *   than one that says nothing. The report is a `notify`, not a throw.
+ * - **It coalesces.** A save touches several files and the watcher debounces to
+ *   a restart; without coalescing a burst spawns a `tsc` per restart, and `tsc`
+ *   on a real project is seconds. A request during a run schedules exactly one
+ *   more, which is `createCoalescingRunner`'s contract.
+ * - **It is quiet when clean.** A dev server that prints "types OK" on every
+ *   save trains the author to stop reading it, which is how the failure this
+ *   exists to surface gets missed again.
+ */
+/** What {@link createDevTypecheck} hands back: fire-and-forget, already coalesced. */
+export type DevTypecheck = {
+    /** Schedule a run. Returns immediately; never rejects. */
+    request(): void;
+};
+/**
+ * A coalescing background typechecker for the project at `cwd`.
+ *
+ * `report` is injected so the dev-server specs can read what an author would
+ * have seen without capturing stdout — the same seam every other reporter in
+ * this package takes.
+ */
+export declare function createDevTypecheck(cwd: string, report?: (level: "warn" | "error", message: string) => void): DevTypecheck;

package/dist/_dev-vite-config.d.ts

@@ -0,0 +1,74 @@
+/**
+ * The Vite dev server's config for a project with a `client.tsx`.
+ *
+ * Its own module because it is the whole agent API as the BROWSER can see it —
+ * a table worth reading without the 400 lines of watcher, restart and env
+ * plumbing that surround it in `_dev-server.ts`, which is also what pushed that
+ * file past the length cap.
+ */
+/**
+ * Vite dev-server config for the client SPA. Extracted so the proxy wiring
+ * is unit-testable: `/websocket` MUST proxy with `ws: true` or `aai dev`
+ * with a `client.tsx` serves a page whose WebSocket never connects.
+ *
+ * **This table is the whole agent API as the browser can see it**, which is
+ * the thing to hold in mind before adding a route to `createServer`. Vite owns
+ * the port the user is told to open and answers everything not listed here
+ * itself — with a bare 404 carrying none of the agent server's headers, so the
+ * failure looks like a missing route rather than a missing proxy entry.
+ *
+ * `/workflows` is why that matters beyond voice. A WORKFLOW APP
+ * (`workflowApp()`) has no session and no socket: `page()` mounts a
+ * form and every single thing it does — listing workflows, starting a run,
+ * polling it, streaming its events — is a same-origin `fetch` under that
+ * prefix. Unproxied, the two workflow-app templates were dead on arrival under
+ * `aai dev` (`404 POST /workflows/runs` the instant the form is submitted)
+ * while the backend served the API correctly one port over. A string key
+ * prefix-matches, so this one entry covers `/runs`, `/runs/:id` and the
+ * `/runs/:id/events` SSE stream.
+ *
+ * `strictPort` because the reported URL is `http://localhost:<port>` —
+ * without it, Vite silently binds port+N when the port is busy and the
+ * printed/JSON-returned URL points at whatever else was listening.
+ *
+ * `AAI_DEV_HOST` reaches BOTH servers. Binding only the backend left Vite —
+ * the port the user is told to open — on loopback, i.e. failing exactly the
+ * case that variable exists for (`aai dev` in a container, reached from the host).
+ *
+ * ## The target is an IP LITERAL, and that is a fix rather than a style choice
+ *
+ * `127.0.0.1`, never `localhost`. Vite opens a FRESH upstream connection for
+ * every WebSocket upgrade — an HTTP request reuses a pooled keep-alive socket and
+ * so resolves rarely — which means a hostname here is one `getaddrinfo` per
+ * session handshake. That lookup runs on libuv's threadpool (four threads,
+ * shared with every other fs and DNS call in a process that is ALSO serving the
+ * agent), and under load it intermittently stalls for almost exactly two
+ * seconds.
+ *
+ * Measured on the `retail` template, session handshakes to `session.configured`:
+ *
+ * | Target | conc | rps | p50 | p99 |
+ * | --- | --- | --- | --- | --- |
+ * | `localhost` | 1 | 12-18 | 8-11 ms | 2.0 s |
+ * | `localhost` | 10 | 0.6 | 16.7 s | 16.7 s |
+ * | `127.0.0.1` | 1 | 89-207 | 4-9 ms | 23-49 ms |
+ * | `127.0.0.1` | 20 | 260 | 73 ms | 166 ms |
+ *
+ * The `localhost` row is not a slow proxy, it is a queue: one handshake in thirty
+ * stalls two seconds on its own, and at concurrency 10 the stalls pile onto four
+ * threads until a sustained burst left the proxy refusing upgrades entirely until
+ * the dev server was restarted. With the literal it recovers from a burst and
+ * sits within ~1.5x of the backend port.
+ *
+ * Localized by timing the phases separately — TCP connect and the first frame
+ * were always fast, the 101 was not — and then by comparing the instant the
+ * client sent its upgrade against the backend's own log line for it: 23.808 out,
+ * 25.796 in, answered in 5 ms. The two seconds were spent before Vite dialled,
+ * which is what pointed at resolution rather than at either server.
+ *
+ * Not a behaviour change: `localhost` resolved to loopback anyway, so this
+ * removes the lookup and nothing else. An `AAI_DEV_HOST` that binds the backend
+ * to ONE non-loopback interface was unreachable through the proxy before this and
+ * still is.
+ */
+export declare function viteDevConfig(cwd: string, vitePort: number, backendPort: number): import("vite").InlineConfig;

package/dist/_e2e-test-utils.d.ts

@@ -3,13 +3,25 @@
  * registry setup, dependency installation, and process/server utilities.
  * Each e2e suite performs its own setup/teardown using these helpers.
  */
-import type { ChildProcess } from "node:child_process";
+import { type ChildProcess } from "node:child_process";
 import type { MockRegistry } from "./_mock-registry.ts";
 export declare const dir: string;
 export declare const packagesDir: string;
 export declare const pm: "pnpm" | "npm" | "yarn";
 export declare function aaiEnv(): NodeJS.ProcessEnv;
 export declare function aai(aaiBin: string, args: string[], cwd: string, timeoutMs?: number): void;
+/**
+ * {@link aai}, but CAPTURING — for the cases whose subject is what the CLI
+ * SAID rather than that it exited 0.
+ *
+ * Separate rather than a flag, because `stdio: "inherit"` is load-bearing for
+ * every other call: an e2e failure's only diagnosis trail is the child's output
+ * in the run log, and capturing it by default would take that away.
+ */
+export declare function aaiOutput(aaiBin: string, args: string[], cwd: string, timeoutMs?: number): {
+    stdout: string;
+    stderr: string;
+};
 /**
  * Build the CLI and return the path to the built binary.
  *
@@ -39,6 +51,26 @@ export declare function startRegistry(): Promise<MockRegistry>;
 export declare function waitForHealth(url: string, child?: ChildProcess, timeoutMs?: number): Promise<void>;
 /** Wait for a child process to exit (for clean teardown). */
 export declare function waitForExit(child: ChildProcess, timeoutMs?: number): Promise<void>;
+/**
+ * Run a scaffolded project the way a self-hoster does — `npm start`, which runs
+ * the project's own `prestart` (`aai build`) and then `server.mjs`.
+ *
+ * Extracted because there are two legs now and the spawn is the fiddly half: the
+ * port has to be read off stdout, and every way this can fail — a build error, a
+ * missing artifact, a throwing agent — reports on STDERR, so both streams are
+ * buffered and both go into the failure. Discarding stderr leaves a bare
+ * "exited with code 1" naming none of them, which cost a full diagnosis cycle
+ * once already.
+ *
+ * `PORT=0` lets the OS assign one: this suite runs servers concurrently and a
+ * fixed port is an EADDRINUSE flake waiting to happen.
+ */
+export declare function startSelfHostedServer(projectDir: string, extraEnv?: NodeJS.ProcessEnv): Promise<{
+    url: string;
+    port: number;
+    stop: () => Promise<void>;
+    output: () => string;
+}>;
 /**
  * Whether a failed install may be excused as the mock registry's npmjs
  * passthrough failing rather than as a real dependency-resolution break.