@alexkroman1/aai-cli 13.3.0 → 15.0.0

package/dist/_vercel-output.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Assemble a PREBUILT Vercel deployment — `.vercel/output/` — from what
+ * `aai build` just produced.
+ *
+ * The argument for the Build Output API over an `api/` entry is in
+ * `_build-target.ts` at {@link VERCEL_OUTPUT_DIR}; what this module adds is the
+ * consequence of it. A `.func` directory is a directory WE fill, so every file
+ * the server reads at runtime is present because it was copied in, and nothing
+ * depends on a static tracer following a path it structurally cannot:
+ *
+ * - **`.aai/worker.mjs`** is loaded through `import(pathToFileURL(...))`
+ *   (`start.ts`), which `@vercel/nft` cannot resolve. Under the `api/` shape
+ *   the build was green and the function 500'd on its first request with
+ *   "No built agent at .aai/worker.mjs".
+ * - **`.env.example`** is not documentation here. `resolveServerEnv` treats it
+ *   as the DECLARATION of which variables become `ctx.env` (see
+ *   `DEPLOY_ENV_FILES`), so a function without it hands every tool an empty
+ *   env while the Vercel project has the values set — a failure that looks
+ *   like a credential problem and is a packaging one.
+ * - **The client** is copied to `static/`, where the CDN serves it, and also
+ *   beside the worker, so `resolveClientDir` finds a real directory rather
+ *   than reaching into a `node_modules` that the bundle replaced.
+ *
+ * The entry is BUNDLED rather than shipped with a `node_modules`. Same call as
+ * the worker (`ssr: { noExternal: true }`, `root: cwd`), so it resolves the
+ * project's own installed SDK and pulls the runtime, `ws` and `pg` in with it
+ * — which is already the arrangement a deployed worker runs under, and it is
+ * what makes the function independent of whether the host's install left a
+ * usable, hoisted `node_modules` behind.
+ */
+/** Options for {@link emitVercelOutput}. */
+export interface EmitVercelOutputOptions {
+    /**
+     * Produce the function's `index.mjs`. Defaults to {@link bundleEntry}.
+     *
+     * Injectable so the ASSEMBLY — which file lands where, and which does not —
+     * can be asserted without a ~15s rolldown pass over the whole runtime. The
+     * bundle has its own contract and its own (scenario-tier) test; what this
+     * seam separates is a question about a directory from a question about a
+     * bundler.
+     */
+    bundle?: (cwd: string) => Promise<string>;
+}
+/**
+ * Write `.vercel/output/` for this project.
+ *
+ * The directory is REMOVED first. It is not addressed by content, so a
+ * function or a static asset left by an earlier build with a different shape
+ * would be deployed alongside this one — and `vercel deploy --prebuilt`
+ * uploads whatever is there.
+ */
+export declare function emitVercelOutput(cwd: string, options?: EmitVercelOutputOptions): Promise<void>;
+/**
+ * Bundle {@link VERCEL_ENTRY_SOURCE} and everything it imports into one ESM
+ * file.
+ *
+ * The entry is written INTO the project rather than a temp directory, because
+ * that is what makes `@alexkroman1/aai-cli/start` resolve against the user's
+ * install — the deployed server is then the version their lockfile pins, which
+ * is the same guarantee `aai publish` gives. Removed in a `finally`: a build
+ * that throws must not leave a file that looks authored.
+ */
+export declare function bundleEntry(cwd: string): Promise<string>;

package/dist/{_workflow-determinism-C9l8uC2R.mjs → _workflow-determinism-CvpqMpdh.mjs}

@@ -24,12 +24,12 @@ import { readFile, readdir } from "node:fs/promises";
 * compiling every fence in this repo's shipped docs:
 *
 * ```ts
-* import type { WorkflowCtx } from "@alexkroman1/aai";
+* import type { WorkflowContext } from "@alexkroman1/aai";
 *
 * declare const charge: () => Promise<string>;
 *
-* export async function body(ctx: WorkflowCtx, coin: string): Promise<void> {
-*   // No error. The banned shape, against the real `WorkflowCtx`.
+* export async function body(ctx: WorkflowContext, coin: string): Promise<void> {
+*   // No error. The banned shape, against the real `WorkflowContext`.
 *   await ctx.step(`charge-${coin}`, charge);
 * }
 * ```
@@ -81,19 +81,6 @@ import { readFile, readdir } from "node:fs/promises";
 * @module
 */
 /**
-* The three `ctx` methods whose first argument is a journal identity.
-*
-* All three key a journal row by it — `name#occurrence` for a step,
-* `sleep!<label>#<n>` and `hook!<token>#<n>` for the waits — so a computed one
-* mints a row no earlier walk reached in exactly the same way. Kept as a list
-* so the message can name the method that was called.
-*/
-const IDENTITY_METHODS = [
-	"step",
-	"sleep",
-	"waitFor"
-];
-/**
 * A `ctx.<method>(` immediately followed by a BACKTICK.
 *
 * The whole check, and its narrowness is the point. A quoted literal is
@@ -104,8 +91,17 @@ const IDENTITY_METHODS = [
 * The receiver is not pinned to `ctx` — a body may destructure or rename it —
 * and a `.step(` on anything else taking a template-literal first argument is
 * not a shape worth excluding.
+*
+* Shared rather than built per call, which is safe ONLY because the single
+* reader is `matchAll`: that method species-constructs its own clone and never
+* advances this object's `lastIndex`. A `.exec` or `.test` added against a `/g`
+* regex would carry state between lines — build a fresh one there.
 */
-const identityPattern = () => new RegExp(`\\.(${IDENTITY_METHODS.join("|")})\\(\``, "g");
+const IDENTITY_PATTERN = new RegExp(`\\.(${[
+	"step",
+	"sleep",
+	"waitFor"
+].join("|")})\\(\``, "g");
 /** Whether a template literal actually INTERPOLATES, or is merely quoted oddly. */
 const INTERPOLATES = /\$\{/;
 /**
@@ -132,7 +128,7 @@ function findComputedIdentities(source, file) {
 	const findings = [];
 	for (const [n, line] of source.split("\n").entries()) {
 		if (isCommentOnly(line)) continue;
-		for (const match of line.matchAll(identityPattern())) {
+		for (const match of line.matchAll(IDENTITY_PATTERN)) {
 			const method = match[1];
 			if (method === void 0) continue;
 			if (!INTERPOLATES.test(line.slice((match.index ?? 0) + match[0].length))) continue;
@@ -169,17 +165,13 @@ async function workflowFiles(cwd) {
 * warning pass beside a typecheck that has already run on the same tree.
 */
 async function scanWorkflowDeterminism(cwd) {
-	const findings = [];
-	for (const rel of await workflowFiles(cwd)) {
-		let source;
+	return (await Promise.all((await workflowFiles(cwd)).map(async (rel) => {
 		try {
-			source = await readFile(path.join(cwd, rel), "utf-8");
+			return findComputedIdentities(await readFile(path.join(cwd, rel), "utf-8"), rel);
 		} catch {
-			continue;
+			return [];
 		}
-		findings.push(...findComputedIdentities(source, rel));
-	}
-	return findings;
+	}))).flat();
 }
 /**
 * The remedy, once, however many findings there are.

package/dist/_workflow-determinism.d.ts

@@ -20,12 +20,12 @@
  * compiling every fence in this repo's shipped docs:
  *
  * ```ts
- * import type { WorkflowCtx } from "@alexkroman1/aai";
+ * import type { WorkflowContext } from "@alexkroman1/aai";
  *
  * declare const charge: () => Promise<string>;
  *
- * export async function body(ctx: WorkflowCtx, coin: string): Promise<void> {
- *   // No error. The banned shape, against the real `WorkflowCtx`.
+ * export async function body(ctx: WorkflowContext, coin: string): Promise<void> {
+ *   // No error. The banned shape, against the real `WorkflowContext`.
  *   await ctx.step(`charge-${coin}`, charge);
  * }
  * ```

package/dist/build-BhEaxBPu.mjs

@@ -0,0 +1,481 @@
+#!/usr/bin/env node
+import { a as ok, t as CliError } from "./_output-DBP9Op_d.mjs";
+import { n as log, r as notify } from "./_ui-DCt4qZrk.mjs";
+import { n as withPreservedNodeEnv } from "./_vite-env-kejF0p2L.mjs";
+import { n as WORKER_ARTIFACT_REL, t as CLIENT_ARTIFACT_REL } from "./_artifacts-BJOYGQPp.mjs";
+import { r as evalWorkerBundle, t as buildAgentBundle } from "./_bundler-DM0d0M7m.mjs";
+import { assertTypechecks } from "./_typecheck-gate-U3jcil8L.mjs";
+import { n as scanWorkflowDeterminism, t as determinismWarnings } from "./_workflow-determinism-CvpqMpdh.mjs";
+import { TEST_FILES, classifyVitestError, runVitest } from "./test-D032V2cA.mjs";
+import path from "node:path";
+import fs from "node:fs/promises";
+import { invariant } from "@alexkroman1/aai/internal";
+import { build } from "vite";
+import { defaultClientDir } from "@alexkroman1/aai-ui/client-dir";
+import { agentConfigWarnings } from "@alexkroman1/aai/manifest";
+import { DEFAULT_SYSTEM_PROMPT } from "@alexkroman1/aai";
+//#region src/_build-target.ts
+/**
+* Deployment TARGETS — what `aai build` emits beside the worker so a host can
+* run this project without the project holding anything host-specific.
+*
+* ## Why a target rather than a file in the scaffold
+*
+* Every host wants a different entry shape: Vercel wants a module whose default
+* export is an `http.Server` it binds itself, a container wants a long-lived
+* process, another platform wants something else again. Committing one of those
+* to the scaffold makes every project assert a fact that is load-bearing on
+* exactly one host — the same objection that removed `server.mjs`.
+*
+* Nitro is the worked precedent: one codebase, a preset per provider, and the
+* preset EMITS the host's expected shape into the build directory. `node-server`
+* is its default and Vercel/Netlify/Cloudflare are detected from the CI
+* environment with no configuration. Next does the same narrower thing with
+* `output: "standalone"` — it generates a `server.js` rather than asking anyone
+* to write one. Either way the user's repository contains no host file, which is
+* the property to preserve here.
+*
+* ## Auto-detection, and why it is safe
+*
+* A target is chosen with `--target`, or detected from the environment when the
+* flag is absent. Detection reads the variables the hosts set on their own build
+* containers ({@link TARGET_ENV_MARKERS}), so it only ever fires where the build
+* is genuinely running on that host — a laptop sets none of them and gets
+* {@link DEFAULT_BUILD_TARGET}, which emits nothing extra and is what every
+* existing project already does.
+*/
+/** The targets `aai build --target` accepts. */
+const BUILD_TARGETS = ["node", "vercel"];
+/**
+* What a build with no `--target` and no host environment produces: the worker
+* and the client, and nothing else.
+*
+* `node` rather than a `"none"` sentinel because it NAMES the deployment it
+* serves — a long-lived process running `aai start` — which is what every
+* container platform wants and what the scaffold's own `start` script runs.
+*/
+const DEFAULT_BUILD_TARGET = "node";
+/**
+* The environment variable each host sets on its own build container.
+*
+* `VERCEL` is set for every Vercel build and deployment. Detection is per host
+* rather than a single "am I in CI" test, because a GitHub Action building a
+* container image is CI too and wants the default.
+*/
+const TARGET_ENV_MARKERS = { VERCEL: "vercel" };
+function isBuildTarget(value) {
+	return BUILD_TARGETS.includes(value);
+}
+/**
+* Resolve the target for this build: an explicit flag wins, then the
+* environment, then {@link DEFAULT_BUILD_TARGET}.
+*
+* An unrecognised `--target` is REFUSED naming what is accepted, rather than
+* falling back to the default — a typo'd target that silently built the default
+* would deploy a project missing the entry its host needs, and the failure would
+* arrive as a 404 from the platform rather than as an error from the build.
+*/
+function resolveBuildTarget(explicit, env = process.env) {
+	if (explicit !== void 0) {
+		if (!isBuildTarget(explicit)) throw new Error(`Unknown build target "${explicit}". Accepted: ${BUILD_TARGETS.join(", ")}.`);
+		return explicit;
+	}
+	for (const [marker, target] of Object.entries(TARGET_ENV_MARKERS)) if (env[marker]) return target;
+	return DEFAULT_BUILD_TARGET;
+}
+/**
+* Where a PREBUILT Vercel deployment lives, relative to the project root.
+*
+* The Build Output API rather than an `api/` entry plus a `vercel.json`, and
+* the reason is ORDERING. Vercel reads `vercel.json` and decides what to build
+* BEFORE it runs the build command, so a `vercel.json` that the build WRITES
+* configures the NEXT deployment and not this one — a clean clone deploys with
+* no rewrite and no function at all. The `api/` shape only ever appeared to
+* work because a previous local `aai build --target vercel` had left both
+* files in the working tree, which is a property of one laptop rather than of
+* the repository. `.vercel/output/` is read AFTER the build command; it is the
+* only place a build can describe its own deployment.
+*
+* Two more things fall out of owning the directory, both of which the `api/`
+* shape got wrong and could not fix. The function bundle is ASSEMBLED here
+* rather than traced, so `.aai/worker.mjs` — loaded through a dynamic
+* `import(pathToFileURL(...))` that no static tracer can follow — and
+* `.env.example` — the file that DECLARES which variables become `ctx.env` —
+* are present because they were copied in. And the built client is served by
+* the CDN out of `static/` instead of through the function.
+*
+* Nitro's vercel preset is the worked precedent and lands in exactly here:
+* `output.dir = {{rootDir}}/.vercel/output`, `serverDir` a `.func` under it.
+*
+* @see https://vercel.com/docs/build-output-api/v3
+*/
+const VERCEL_OUTPUT_DIR = path.join(".vercel", "output");
+/**
+* The one function every request that is not a static file reaches.
+*
+* The Build Output API derives a function's ROUTE from its path, so the
+* directory name IS a URL and must not collide with one the static output
+* claims. **`index.func` collides**, which a deployment is the only way to
+* find out: it is served at `/index`, and Vercel's directory index resolves
+* `/` to the extensionless `/index` — so the function won `/`, every other
+* asset came off the CDN correctly, and the home page 500'd on a deployment
+* whose static output was perfect. Measured on a real preview:
+* `/favicon.ico`, `/index.html` and both hashed `/assets/*` returned 200
+* while `/` and `/index` did not.
+*
+* `__server` is Nitro's answer to the same problem (`__server.func`) and the
+* reason is this one: a double-underscore prefix is not a path any bundler
+* emits, so no static file can ever take the name.
+*/
+const VERCEL_FUNCTION_DIR = path.join(VERCEL_OUTPUT_DIR, "functions", "__server.func");
+/**
+* The route {@link VERCEL_FUNCTION_DIR} is served at — its directory name
+* without `.func`, which is how the Build Output API names a function.
+*/
+const VERCEL_FUNCTION_ROUTE = "/__server";
+/** Static assets the Vercel CDN serves directly, never reaching the function. */
+const VERCEL_STATIC_DIR = path.join(VERCEL_OUTPUT_DIR, "static");
+/**
+* Node versions Vercel offers. A build on anything newer picks the newest of
+* these rather than naming a runtime the platform will reject.
+*
+* @see https://vercel.com/docs/functions/runtimes/node-js/node-js-versions
+*/
+const SUPPORTED_NODE_MAJORS = [
+	20,
+	22,
+	24
+];
+/** `nodejs<major>.x` for the Node running this build, clamped to what Vercel offers. */
+function vercelNodeRuntime(version = process.versions.node) {
+	const major = Number.parseInt(version.split(".")[0] ?? "", 10);
+	return `nodejs${Number.isNaN(major) ? 22 : SUPPORTED_NODE_MAJORS.findLast((v) => v <= major) ?? SUPPORTED_NODE_MAJORS[0]}.x`;
+}
+/**
+* The Vercel function entry, emitted into {@link VERCEL_FUNCTION_DIR}.
+*
+* ## Why a `(req, res)` handler and not `export default server`
+*
+* `export default <http.Server>` is what Vercel's own `@vercel/node` BUILDER
+* accepts, and it is the shape the previous `api/index.mjs` used. The Build
+* Output API has no builder in the path: `launcherType: "Nodejs"` invokes the
+* module's default export as a request handler, so the server never gets
+* bound and there is nothing to raise an `upgrade` event on it.
+*
+* ## How a WebSocket survives that
+*
+* Vercel hands a Node function the raw upgrade through its PER-REQUEST
+* context — `globalThis[Symbol.for("@vercel/request-context")].get()
+* .upgradeWebSocket()` returns the `{ req, socket, head }` triple — rather
+* than as an event. Nitro reaches it through `crossws/adapters/vercel`; here
+* the adapter is three lines, because {@link AgentServer.node} is a real
+* `http.Server` that already has both an `upgrade` and a `request` listener
+* registered. Re-emitting onto it is the whole translation, and it means the
+* deployed path through `server.ts` is the same one `aai dev` and `aai start`
+* take — no second WebSocket entry point to keep in step.
+*
+* The `204` afterwards is what the launcher needs to consider the invocation
+* finished; the socket the agent is now talking on is not this `res`.
+*
+* ## `import.meta.dirname`, not `process.cwd()`
+*
+* The function's working directory belongs to the platform, but `.aai/` and
+* `.env.example` were copied in BESIDE this file. Resolving from the module
+* keeps that a fact about the bundle rather than about how Vercel happens to
+* invoke it.
+*/
+const VERCEL_ENTRY_SOURCE = `// Generated by \`aai build --target vercel\` — do not edit, and do not commit.
+// Vercel invokes this handler per request and delivers a WebSocket upgrade
+// through its request context. See @alexkroman1/aai-cli/start.
+import { createProjectServer } from "@alexkroman1/aai-cli/start";
+
+const server = (await createProjectServer({ cwd: import.meta.dirname })).node;
+
+const REQUEST_CONTEXT = Symbol.for("@vercel/request-context");
+
+export default function handler(req, res) {
+  if (req.method === "GET" && req.headers.upgrade?.toLowerCase() === "websocket") {
+    const upgrade = globalThis[REQUEST_CONTEXT]?.get?.()?.upgradeWebSocket?.();
+    if (upgrade) {
+      server.emit("upgrade", upgrade.req, upgrade.socket, upgrade.head);
+      if (!res.headersSent && !res.writableEnded) {
+        res.statusCode = 204;
+        res.end();
+      }
+      return;
+    }
+  }
+  server.emit("request", req, res);
+}
+`;
+/**
+* `.vc-config.json` — how the platform runs {@link VERCEL_ENTRY_SOURCE}.
+*
+* `supportsResponseStreaming` is not optional here: an agent streams TTS audio
+* and SSE workflow events, and without it the platform buffers a response to
+* completion, which for a stream that ends when the call does means it never
+* arrives. `shouldAddHelpers` stays off — the entry speaks `node:http`, and
+* the helpers exist to bolt Express-shaped sugar onto a handler that does not.
+*/
+function vercelFunctionConfigSource(runtime = vercelNodeRuntime()) {
+	return `${JSON.stringify({
+		runtime,
+		handler: "index.mjs",
+		launcherType: "Nodejs",
+		shouldAddHelpers: false,
+		supportsResponseStreaming: true
+	}, null, 2)}\n`;
+}
+/**
+* `config.json` — the routing table, and the reason static assets stop paying
+* for a function invocation.
+*
+* `{ "handle": "filesystem" }` serves anything present in
+* {@link VERCEL_STATIC_DIR} from the CDN and only then falls through, so the
+* client bundle, its assets and the worklets are edge-served while
+* `/client-config`, `/websocket`, `/workflows/*` and the webhook route reach
+* the agent. The `api/` shape routed EVERY request through the function, which
+* this file's earlier revision noted as deliberate and "not what makes a
+* deployment work or not" — true of correctness, false of cost, and free here
+* because the Build Output API already separates the two directories.
+*/
+const VERCEL_BUILD_CONFIG_SOURCE = `${JSON.stringify({
+	version: 3,
+	routes: [{ handle: "filesystem" }, {
+		src: "/(.*)",
+		dest: VERCEL_FUNCTION_ROUTE
+	}]
+}, null, 2)}\n`;
+//#endregion
+//#region src/_vercel-output.ts
+/**
+* Assemble a PREBUILT Vercel deployment — `.vercel/output/` — from what
+* `aai build` just produced.
+*
+* The argument for the Build Output API over an `api/` entry is in
+* `_build-target.ts` at {@link VERCEL_OUTPUT_DIR}; what this module adds is the
+* consequence of it. A `.func` directory is a directory WE fill, so every file
+* the server reads at runtime is present because it was copied in, and nothing
+* depends on a static tracer following a path it structurally cannot:
+*
+* - **`.aai/worker.mjs`** is loaded through `import(pathToFileURL(...))`
+*   (`start.ts`), which `@vercel/nft` cannot resolve. Under the `api/` shape
+*   the build was green and the function 500'd on its first request with
+*   "No built agent at .aai/worker.mjs".
+* - **`.env.example`** is not documentation here. `resolveServerEnv` treats it
+*   as the DECLARATION of which variables become `ctx.env` (see
+*   `DEPLOY_ENV_FILES`), so a function without it hands every tool an empty
+*   env while the Vercel project has the values set — a failure that looks
+*   like a credential problem and is a packaging one.
+* - **The client** is copied to `static/`, where the CDN serves it, and also
+*   beside the worker, so `resolveClientDir` finds a real directory rather
+*   than reaching into a `node_modules` that the bundle replaced.
+*
+* The entry is BUNDLED rather than shipped with a `node_modules`. Same call as
+* the worker (`ssr: { noExternal: true }`, `root: cwd`), so it resolves the
+* project's own installed SDK and pulls the runtime, `ws` and `pg` in with it
+* — which is already the arrangement a deployed worker runs under, and it is
+* what makes the function independent of whether the host's install left a
+* usable, hoisted `node_modules` behind.
+*/
+/**
+* Files copied verbatim into the function, each one read at RUNTIME by a path
+* no bundler can see. A missing one is skipped rather than fatal.
+*
+* **`.env` is deliberately NOT here.** `resolveServerEnv` reads
+* {@link DEPLOY_ENV_FILES} — `.env.example` then `.env` — but only the first is
+* a DECLARATION; the second holds a developer's own keys, and copying it would
+* bake them into a deployment artifact and let them silently win over the
+* values set in the Vercel project. Declarations ship, values come from the
+* platform environment. Verified by building the `simple` template: a local
+* `.env` with live credentials landed in the function until this list dropped
+* it.
+*/
+const RUNTIME_FILES = [WORKER_ARTIFACT_REL, ".env.example"];
+/**
+* Write `.vercel/output/` for this project.
+*
+* The directory is REMOVED first. It is not addressed by content, so a
+* function or a static asset left by an earlier build with a different shape
+* would be deployed alongside this one — and `vercel deploy --prebuilt`
+* uploads whatever is there.
+*/
+async function emitVercelOutput(cwd, options = {}) {
+	const outputDir = path.join(cwd, VERCEL_OUTPUT_DIR);
+	const functionDir = path.join(cwd, VERCEL_FUNCTION_DIR);
+	const staticDir = path.join(cwd, VERCEL_STATIC_DIR);
+	await fs.rm(outputDir, {
+		recursive: true,
+		force: true
+	});
+	await fs.mkdir(functionDir, { recursive: true });
+	await fs.writeFile(path.join(outputDir, "config.json"), VERCEL_BUILD_CONFIG_SOURCE, "utf-8");
+	await fs.writeFile(path.join(functionDir, ".vc-config.json"), vercelFunctionConfigSource(), "utf-8");
+	const bundle = options.bundle ?? bundleEntry;
+	await fs.writeFile(path.join(functionDir, "index.mjs"), await bundle(cwd), "utf-8");
+	for (const rel of RUNTIME_FILES) {
+		const from = path.join(cwd, rel);
+		if (!await exists(from)) continue;
+		const to = path.join(functionDir, rel);
+		await fs.mkdir(path.dirname(to), { recursive: true });
+		await fs.copyFile(from, to);
+	}
+	const clientSource = await exists(path.join(cwd, CLIENT_ARTIFACT_REL, "index.html")) ? path.join(cwd, CLIENT_ARTIFACT_REL) : defaultClientDir();
+	await fs.cp(clientSource, staticDir, { recursive: true });
+	await fs.cp(clientSource, path.join(functionDir, CLIENT_ARTIFACT_REL), { recursive: true });
+}
+/**
+* Bundle {@link VERCEL_ENTRY_SOURCE} and everything it imports into one ESM
+* file.
+*
+* The entry is written INTO the project rather than a temp directory, because
+* that is what makes `@alexkroman1/aai-cli/start` resolve against the user's
+* install — the deployed server is then the version their lockfile pins, which
+* is the same guarantee `aai publish` gives. Removed in a `finally`: a build
+* that throws must not leave a file that looks authored.
+*/
+async function bundleEntry(cwd) {
+	const entryPath = path.join(cwd, ".aai", "vercel-entry.mjs");
+	await fs.mkdir(path.dirname(entryPath), { recursive: true });
+	await fs.writeFile(entryPath, VERCEL_ENTRY_SOURCE, "utf-8");
+	let result;
+	try {
+		result = await withPreservedNodeEnv(() => build({
+			root: cwd,
+			logLevel: "silent",
+			configFile: false,
+			ssr: { noExternal: true },
+			build: {
+				ssr: true,
+				lib: {
+					entry: entryPath,
+					formats: ["es"],
+					fileName: "index"
+				},
+				target: "node20",
+				minify: false,
+				write: false,
+				rollupOptions: { output: {
+					entryFileNames: "[name].mjs",
+					codeSplitting: false
+				} }
+			}
+		}));
+	} finally {
+		await fs.rm(entryPath, { force: true }).catch(() => void 0);
+	}
+	const output = Array.isArray(result) ? result[0] : result;
+	invariant(output !== void 0, "vercel.entry.output");
+	const chunk = output.output.find((o) => o.type === "chunk" && o.isEntry);
+	invariant(chunk !== void 0, "vercel.entry.chunk", () => ({ kinds: output.output.map((o) => o.type) }));
+	return chunk.code;
+}
+async function exists(target) {
+	return await fs.stat(target).then(() => true, () => false);
+}
+//#endregion
+//#region src/build.ts
+/**
+* `aai build` — bundle the agent without deploying, behind the same gates
+* deploy runs (tests, then typecheck), so the command previews the deploy
+* artifact and its failures alike.
+*
+* It also LEAVES that artifact on disk, at {@link WORKER_ARTIFACT_REL}, which is
+* what makes self-hosting work: `aai start` loads the built worker rather than
+* `agent.ts`, because a tool is discovered by the bundler enumerating `tools/`
+* and no un-bundled loader can see that directory. See `start.ts` and
+* "Self-hosting is the scaffold's default" in `packages/aai-cli/CLAUDE.md`.
+*
+* `--target` decides what else it emits — see `_build-target.ts`.
+*/
+/**
+* The prose slot, named by convention. Mirrors `worker-bundler.ts`'s constant of
+* the same name — the two cannot share one without an import cycle
+* (`build.ts` → `_bundler.ts` → `worker-bundler.ts`), so `_build.test.ts` pins
+* the pair end to end instead: a build whose prompt really came from the file
+* has to report the file.
+*/
+const SYSTEM_PROMPT_FILE = "system-prompt.md";
+/** What {@link systemPromptSource} reports when nothing declared a prompt. */
+const FRAMEWORK_DEFAULT_PROMPT_SOURCE = "the framework default (DEFAULT_SYSTEM_PROMPT)";
+/**
+* Which of the three possible authors of this agent's system prompt actually
+* wrote the one in the bundle.
+*
+* `aai build` reported `name` and `workerBytes` and nothing about the prompt,
+* and the prompt is the one field that can change COMPLETELY without any
+* config changing: deleting `system-prompt.md` swaps in
+* `DEFAULT_SYSTEM_PROMPT` — a total personality change — with exit 0 and no
+* line anywhere. `withSystemPrompt` refuses the case where a file exists and
+* nothing reads it; it cannot refuse a file that is simply GONE, because that
+* is what an agent with no file legitimately looks like. So this is a report
+* rather than a check.
+*
+* Decided by comparing VALUES against the built agent's resolved prompt, which
+* is the same method `withSystemPrompt` uses and for the same reason — the
+* alternative asks the bundler's module graph a question, and the author may
+* have imported the file and composed it, which is neither "the file" nor
+* "agent.ts" alone.
+*/
+async function systemPromptSource(cwd, resolved) {
+	if (resolved === DEFAULT_SYSTEM_PROMPT) return FRAMEWORK_DEFAULT_PROMPT_SOURCE;
+	const trimmed = (await fs.readFile(path.join(cwd, SYSTEM_PROMPT_FILE), "utf-8").catch(() => void 0))?.trim();
+	if (trimmed === void 0 || trimmed === "" || !resolved.includes(trimmed)) return "agent.ts";
+	return resolved.trim() === trimmed ? SYSTEM_PROMPT_FILE : `agent.ts (composing ${SYSTEM_PROMPT_FILE})`;
+}
+/**
+* Map a {@link runVitest} failure to a CliError — distinguishing a real test
+* failure (test_failed) from the runner not spawning (spawn_failed) instead
+* of a generic command_failed.
+*/
+function testGateError(err) {
+	const { code, message } = classifyVitestError(err);
+	return new CliError(code, message, "Re-run with --skipTests to build without tests", { cause: err });
+}
+async function executeBuild(opts) {
+	const { cwd } = opts;
+	const target = resolveBuildTarget(opts.target);
+	if (!opts.skipTests) try {
+		runVitest(cwd, {
+			candidates: TEST_FILES,
+			all: true
+		});
+	} catch (err) {
+		throw testGateError(err);
+	}
+	await assertTypechecks(cwd, { skip: opts.skipTypecheck });
+	const bundle = await buildAgentBundle(cwd, { minify: true });
+	const agentDef = await evalWorkerBundle(bundle.worker);
+	for (const warning of agentConfigWarnings(agentDef)) notify("warn", warning);
+	for (const warning of determinismWarnings(await scanWorkflowDeterminism(cwd))) notify("warn", warning);
+	const worker = path.join(cwd, WORKER_ARTIFACT_REL);
+	await fs.mkdir(path.dirname(worker), { recursive: true });
+	await fs.writeFile(worker, bundle.worker, "utf-8");
+	await emitTargetFiles(cwd, target);
+	const systemPrompt = await systemPromptSource(cwd, agentDef.systemPrompt);
+	log.info(`System prompt: ${systemPrompt}`);
+	log.success("Build complete");
+	return ok({
+		name: agentDef.name,
+		workerBytes: bundle.worker.length,
+		worker,
+		systemPrompt,
+		target
+	});
+}
+/**
+* Write what a target needs, if it needs anything.
+*
+* `node` writes nothing: a long-lived process runs `aai start`, which needs no
+* generated file. `vercel` writes a complete prebuilt deployment under
+* `.vercel/output/` — see `_vercel-output.ts`, and `VERCEL_OUTPUT_DIR` in
+* `_build-target.ts` for why that directory and not an `api/` entry beside a
+* generated `vercel.json`.
+*/
+async function emitTargetFiles(cwd, target) {
+	if (target === "node") return;
+	await emitVercelOutput(cwd);
+	log.info(`Target ${target}: wrote ${VERCEL_OUTPUT_DIR}`);
+}
+//#endregion
+export { executeBuild };