@alexkroman1/aai-cli 14.0.0 → 15.0.0

package/dist/cli.mjs

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
 import { i as installStdoutGuard, n as fail, o as writeLine, r as getOutputMode, t as CliError } from "./_output-DBP9Op_d.mjs";
-import { n as log, o as silenceOutput } from "./_ui-DCt4qZrk.mjs";
+import { a as parsePort, n as log, o as silenceOutput } from "./_ui-DCt4qZrk.mjs";
 import { c as fileExists, f as readPackageJson, p as resolveCwd, s as errorMessage$1, t as AGENT_ENTRY } from "./_utils-D5JGcjiW.mjs";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { isRecord, plural } from "@alexkroman1/aai/utils";
+import { isRecord, omitUndefined, plural } from "@alexkroman1/aai/utils";
 import { defineCommand, runMain, showUsage } from "citty";
 //#region src/_cli-common.ts
 /** Shared arg definitions for citty commands. */
@@ -395,7 +395,7 @@ const list = defineExec({
 	args: { ...platformArgs },
 	cwd: "any",
 	async run({ args, cwd }) {
-		const { executeList } = await import("./studio-CpHlNHUZ.mjs");
+		const { executeList } = await import("./studio-C_zuRC_z.mjs");
 		return executeList({
 			cwd,
 			server: args.server
@@ -427,7 +427,7 @@ const pull = defineExec({
 	},
 	cwd: "any",
 	async run({ args, cwd }) {
-		const { executePull } = await import("./studio-CpHlNHUZ.mjs");
+		const { executePull } = await import("./studio-C_zuRC_z.mjs");
 		return executePull({
 			cwd,
 			project: args.project,
@@ -448,7 +448,7 @@ const push = defineExec({
 	},
 	cwd: "agent",
 	async run({ args, cwd }) {
-		const { executePush } = await import("./studio-CpHlNHUZ.mjs");
+		const { executePush } = await import("./studio-C_zuRC_z.mjs");
 		return executePush({
 			cwd,
 			server: args.server,
@@ -471,7 +471,7 @@ const publish = defineExec({
 	},
 	cwd: "agent",
 	async run({ args, cwd }) {
-		const { executePublish } = await import("./studio-CpHlNHUZ.mjs");
+		const { executePublish } = await import("./studio-C_zuRC_z.mjs");
 		return executePublish({
 			cwd,
 			server: args.server,
@@ -693,7 +693,7 @@ const init = defineExec({
 		template: {
 			type: "string",
 			alias: "t",
-			description: "Template to use (run `aai templates` for the list)"
+			description: "Template to use (prompted when omitted)"
 		},
 		server: sharedArgs.server,
 		yes: sharedArgs.yes,
@@ -705,7 +705,7 @@ const init = defineExec({
 	},
 	cwd: "none",
 	async run({ args, mode }) {
-		const { executeInit } = await import("./init-DukDxECd.mjs");
+		const { executeInit } = await import("./init-CFyusRbq.mjs");
 		return executeInit({
 			dir: args.dir,
 			force: args.force,
@@ -736,7 +736,7 @@ const dev = defineExec({
 	},
 	cwd: "agent",
 	async run({ args, cwd }) {
-		const { executeDev } = await import("./dev-DApPSaE_.mjs");
+		const { executeDev } = await import("./dev-Bx9gYBHM.mjs");
 		return executeDev({
 			cwd,
 			port: args.port,
@@ -744,6 +744,35 @@ const dev = defineExec({
 		});
 	}
 });
+const start = defineExec({
+	meta: {
+		name: "start",
+		description: "Serve the built agent (production)"
+	},
+	args: {
+		port: {
+			type: "string",
+			alias: "p",
+			description: "Port to listen on"
+		},
+		host: {
+			type: "string",
+			description: "Address to bind (default: loopback)"
+		},
+		json: sharedArgs.json
+	},
+	cwd: "agent",
+	async run({ args, cwd }) {
+		const { executeStart } = await import("./start.mjs");
+		return executeStart({
+			cwd,
+			...omitUndefined({
+				port: args.port === void 0 ? void 0 : parsePort(args.port),
+				host: args.host?.trim() || void 0
+			})
+		});
+	}
+});
 const test = defineExec({
 	meta: {
 		name: "test",
@@ -770,7 +799,7 @@ const evalCommand = defineExec({
 	args: { json: sharedArgs.json },
 	cwd: "agent",
 	async run({ cwd }) {
-		const { executeEval } = await import("./eval-BK47A_K5.mjs");
+		const { executeEval } = await import("./eval-B3I7FqN9.mjs");
 		return executeEval(cwd);
 	}
 });
@@ -788,15 +817,20 @@ const build = defineExec({
 		skipTypecheck: {
 			type: "boolean",
 			description: "Skip type checking before build"
+		},
+		target: {
+			type: "string",
+			description: "Deployment shape to emit (node, vercel; default: detected)"
 		}
 	},
 	cwd: "agent",
 	async run({ args, cwd }) {
-		const { executeBuild } = await import("./build-Mxk8gWvX.mjs");
+		const { executeBuild } = await import("./build-BhEaxBPu.mjs");
 		return executeBuild({
 			cwd,
 			skipTests: args.skipTests,
-			skipTypecheck: args.skipTypecheck
+			skipTypecheck: args.skipTypecheck,
+			target: args.target
 		});
 	}
 });
@@ -819,7 +853,7 @@ const deploy = defineExec({
 	},
 	cwd: "agent",
 	async run({ args, cwd }) {
-		const { executeDeploy } = await import("./deploy-uAJ4NukN.mjs");
+		const { executeDeploy } = await import("./deploy-CGqPU5U-.mjs");
 		return executeDeploy({
 			cwd,
 			server: args.server,
@@ -863,7 +897,7 @@ const templates = defineExec({
 	args: { json: sharedArgs.json },
 	cwd: "none",
 	async run({ mode }) {
-		const { listTemplates } = await import("./_templates-CK4oKoeX.mjs");
+		const { listTemplates } = await import("./_templates-CIlJ3Vay.mjs");
 		const names = await listTemplates();
 		if (mode === "human") {
 			for (const name of names) log.message(name);
@@ -880,6 +914,7 @@ const mainCommand = defineCommand({
 	subCommands: {
 		init,
 		dev,
+		start,
 		test,
 		eval: evalCommand,
 		build,

package/dist/{client-bundler-BJgREAh6.mjs → client-bundler-6mTLs6ny.mjs}

@@ -81,10 +81,10 @@ const DEFAULT_OUT_DIR = ".aai/client";
 * @internal — build hook for aai-server/the studio; not a supported public
 * API and not covered by semver.
 */
-async function buildClient(cwd, opts = {}) {
+async function buildClient(cwd, options = {}) {
 	const clientEntry = path.join(cwd, "client.tsx");
 	if (!await fileExists(clientEntry)) return {};
-	const outDir = opts.outDir ?? DEFAULT_OUT_DIR;
+	const outDir = options.outDir ?? DEFAULT_OUT_DIR;
 	const clientDir = path.join(cwd, outDir);
 	let cleanupHtml = () => {};
 	try {
@@ -93,8 +93,8 @@ async function buildClient(cwd, opts = {}) {
 			root: cwd,
 			base: "./",
 			logLevel: "silent",
-			...opts.configFile === false && { configFile: false },
-			...omitUndefined({ plugins: opts.plugins }),
+			...options.configFile === false && { configFile: false },
+			...omitUndefined({ plugins: options.plugins }),
 			resolve: { dedupe: DEDUPED_PEERS },
 			build: {
 				outDir,

package/dist/client-bundler.d.ts

@@ -27,4 +27,4 @@ export type BuildClientOptions = {
  * @internal — build hook for aai-server/the studio; not a supported public
  * API and not covered by semver.
  */
-export declare function buildClient(cwd: string, opts?: BuildClientOptions): Promise<Record<string, string>>;
+export declare function buildClient(cwd: string, options?: BuildClientOptions): Promise<Record<string, string>>;

package/dist/client-bundler.mjs

@@ -1,3 +1,3 @@
 #!/usr/bin/env node
-import { t as buildClient } from "./client-bundler-BJgREAh6.mjs";
+import { t as buildClient } from "./client-bundler-6mTLs6ny.mjs";
 export { buildClient };

package/dist/{deploy-uAJ4NukN.mjs → deploy-CGqPU5U-.mjs}

@@ -3,8 +3,8 @@ import { a as ok } from "./_output-DBP9Op_d.mjs";
 import { n as log, r as notify, t as fmtUrl } from "./_ui-DCt4qZrk.mjs";
 import { s as errorMessage$1 } from "./_utils-D5JGcjiW.mjs";
 import { s as updateProjectConfig } from "./_config-DYzC6WMD.mjs";
-import { i as evalWorkerConfig, t as buildAgentBundle } from "./_bundler-DolUCMxu.mjs";
-import { t as resolveServerEnv } from "./_server-common-vILJp3it.mjs";
+import { n as resolveServerEnv } from "./_server-common-De0haHr9.mjs";
+import { i as evalWorkerConfig, t as buildAgentBundle } from "./_bundler-DM0d0M7m.mjs";
 import { o as resolveDeployTarget } from "./_agent-BzUeqOdj.mjs";
 import { assertTypechecks } from "./_typecheck-gate-U3jcil8L.mjs";
 import { n as scanWorkflowDeterminism, t as determinismWarnings } from "./_workflow-determinism-CvpqMpdh.mjs";

package/dist/{dev-DApPSaE_.mjs → dev-Bx9gYBHM.mjs}

@@ -12,7 +12,7 @@ import { styleText } from "node:util";
 async function executeDev(opts) {
 	const port = parsePort(opts.port);
 	const agentName = path.basename(path.resolve(opts.cwd));
-	const { startDevServer } = await import("./_dev-server-CSMqF8PN.mjs");
+	const { startDevServer } = await import("./_dev-server-BzWB6-4y.mjs");
 	let cleanup;
 	let shuttingDown = false;
 	const onSignal = () => {

package/dist/{eval-BK47A_K5.mjs → eval-B3I7FqN9.mjs}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { a as ok, n as fail } from "./_output-DBP9Op_d.mjs";
 import { n as log } from "./_ui-DCt4qZrk.mjs";
-import { t as resolveServerEnv } from "./_server-common-vILJp3it.mjs";
+import { n as resolveServerEnv } from "./_server-common-De0haHr9.mjs";
 import { classifyVitestError, runVitest } from "./test-D032V2cA.mjs";
 //#region src/eval.ts
 /**

package/dist/{init-DukDxECd.mjs → init-CFyusRbq.mjs}

@@ -3,6 +3,7 @@ import { a as ok } from "./_output-DBP9Op_d.mjs";
 import { n as log, s as unwrapCancel } from "./_ui-DCt4qZrk.mjs";
 import { c as fileExists, d as readJson, p as resolveCwd, s as errorMessage$1, t as AGENT_ENTRY } from "./_utils-D5JGcjiW.mjs";
 import { r as isDevMode, t as getMonorepoRoot } from "./_agent-BzUeqOdj.mjs";
+import { listTemplates } from "./_templates-CIlJ3Vay.mjs";
 import path from "node:path";
 import { omitUndefined } from "@alexkroman1/aai/utils";
 import { styleText } from "node:util";
@@ -39,6 +40,41 @@ async function promptProjectName(yes) {
 		defaultValue: DEFAULT_PROJECT_NAME
 	}), "Setup cancelled") || DEFAULT_PROJECT_NAME;
 }
+/**
+* The template a non-interactive `init` gets, and the entry the selector opens
+* on — so an author who just presses Enter lands where they used to.
+*/
+const DEFAULT_TEMPLATE = "simple";
+/**
+* Ask which template to scaffold, listing what this CLI actually ships.
+*
+* The options are derived from {@link listTemplates} rather than a roster kept
+* here: that function already backs `aai templates` AND the unknown-template
+* error, so a template added to the package shows up in the picker with no
+* second list to update. {@link DEFAULT_TEMPLATE} is hoisted to the top and
+* pre-selected, which is what keeps a bare `aai init` a single Enter away from
+* the project it produced before there was a picker.
+*
+* Callers must not reach here when there is nobody to answer — `--yes` and
+* JSON mode (auto-detected on a pipe) resolve the default without prompting.
+*/
+async function promptTemplate(list = listTemplates) {
+	const [first, ...rest] = await list();
+	if (first === void 0) return DEFAULT_TEMPLATE;
+	if (rest.length === 0) return first;
+	const names = [first, ...rest];
+	const hasDefault = names.includes(DEFAULT_TEMPLATE);
+	const ordered = hasDefault ? [DEFAULT_TEMPLATE, ...names.filter((name) => name !== DEFAULT_TEMPLATE)] : names;
+	return unwrapCancel(await p.select({
+		message: "Which template?",
+		maxItems: 12,
+		initialValue: hasDefault ? DEFAULT_TEMPLATE : first,
+		options: ordered.map((name) => name === DEFAULT_TEMPLATE ? {
+			value: name,
+			hint: "the default starting point"
+		} : { value: name })
+	}), "Setup cancelled");
+}
 /** Best-effort corepack enable so pnpm is available (scaffold declares packageManager: pnpm). */
 async function ensurePnpm() {
 	await execa("corepack", ["enable"], { reject: false });
@@ -106,7 +142,7 @@ function collectWarnings() {
 }
 /** Publish after init and return deploy metadata if successful. */
 async function tryPublish(cwd, server, warn) {
-	const { executePublish } = await import("./studio-CpHlNHUZ.mjs");
+	const { executePublish } = await import("./studio-C_zuRC_z.mjs");
 	try {
 		const result = await executePublish({
 			cwd,
@@ -127,7 +163,7 @@ async function tryPublish(cwd, server, warn) {
 }
 /** Scaffold the project, optionally showing a spinner. */
 async function scaffoldProject(dir, cwd, template, silent) {
-	const { runInit } = await import("./_init-CQ8idAwo.mjs");
+	const { runInit } = await import("./_init-Bsi3DZNJ.mjs");
 	await withSpinner(silent, {
 		start: `Creating ${dir}`,
 		done: "Project created",
@@ -150,7 +186,7 @@ async function executeInit(opts, extra) {
 	const monorepoRoot = getMonorepoRoot();
 	const cwd = resolveTargetDir(dir);
 	if (!opts.force && await fileExists(path.join(cwd, "agent.ts"))) throw new Error(`${AGENT_ENTRY} already exists in this directory. Use ${styleText("cyanBright", "--force")} to overwrite.`);
-	const template = opts.template ?? "simple";
+	const template = opts.template ?? (opts.yes || suppressUi ? DEFAULT_TEMPLATE : await promptTemplate());
 	const { warn, warnings } = collectWarnings();
 	await scaffoldProject(dir, cwd, template, suppressUi);
 	const installed = await installDeps(cwd, warn, suppressUi);

package/dist/init.d.ts

@@ -17,6 +17,20 @@ type InitData = {
      */
     warnings?: string[];
 };
+/**
+ * Ask which template to scaffold, listing what this CLI actually ships.
+ *
+ * The options are derived from {@link listTemplates} rather than a roster kept
+ * here: that function already backs `aai templates` AND the unknown-template
+ * error, so a template added to the package shows up in the picker with no
+ * second list to update. {@link DEFAULT_TEMPLATE} is hoisted to the top and
+ * pre-selected, which is what keeps a bare `aai init` a single Enter away from
+ * the project it produced before there was a picker.
+ *
+ * Callers must not reach here when there is nobody to answer — `--yes` and
+ * JSON mode (auto-detected on a pipe) resolve the default without prompting.
+ */
+export declare function promptTemplate(list?: () => Promise<string[]>): Promise<string>;
 /** Build the command + args for running pnpm, routing through safe-chain when available. */
 export declare function resolvePnpmCommand(checkSafeChain?: () => Promise<boolean>): Promise<{
     cmd: string;

package/dist/scaffold/CLAUDE.md

@@ -133,8 +133,8 @@ gate in front of `aai build`.
 
 ## Running it yourself (`npm start`)
 
-`server.mjs` serves this agent from a plain Node process — no platform
-account, nothing managed. It is the deployment counterpart of `aai dev`:
+`aai start` serves this agent from a plain Node process — no platform account,
+nothing managed. It is the deployment counterpart of `aai dev`:
 
 ```sh
 npm start                          # http://127.0.0.1:3000
@@ -142,11 +142,18 @@ PORT=8080 HOST=0.0.0.0 npm start   # bind every interface, e.g. in a container
 ```
 
 `npm start` **builds first** (that is the `prestart` script) and then serves
-the result: `server.mjs` boots `.aai/worker.mjs`, the same artifact
+the result: `aai start` boots `.aai/worker.mjs`, the same artifact
 `aai publish` uploads. It serves your own `client.tsx` build when there is one
-and falls back to `defaultClientDir()` (`@alexkroman1/aai-ui/client-dir`), the
-prebuilt default UI shipped inside the package — the only export of `aai-ui`
-that runs on Node rather than in the browser.
+and falls back to the prebuilt default UI shipped inside `@alexkroman1/aai-ui`.
+
+There is no server file in your project, and that is deliberate — the boot
+belongs to the framework, so it improves when you update rather than being
+frozen at the moment you scaffolded. When you need to own it, import
+`createProjectServer` from `@alexkroman1/aai-cli/start`: it builds the server
+and binds nothing, so you decide how it is served. Building one from scratch
+instead, `defaultClientDir()` (`@alexkroman1/aai-ui/client-dir`) is where that
+prebuilt UI lives — the only export of `aai-ui` that runs on Node rather than
+in the browser.
 
 The build is what makes `tools/` work — a tool is registered by existing, and
 the enumeration happens where the bundle is assembled, so a server that loaded
@@ -161,9 +168,31 @@ One thing to know: it binds **loopback by default**, because this server has
 no request authentication of its own; set `HOST=0.0.0.0` only behind your own
 proxy or auth.
 
-Deleting `server.mjs` costs nothing: `aai dev`, `aai publish` and the managed
-platform never read it. `run_code` is the one feature that does not follow —
-it needs the platform's sandbox and refuses outside one.
+`run_code` is the one feature that does not follow — it needs the platform's
+sandbox and refuses outside one.
+
+### Deploying to a host that wants its own entry file
+
+`aai build --target <host>` writes the deployment that host expects into the
+build output. Nothing host-specific lives in your project: the files are
+generated, gitignored, and rewritten by the host's own build.
+
+```sh
+aai build --target vercel   # writes .vercel/output/ (Build Output API v3)
+```
+
+You rarely type it. The target is detected from the host's own build
+environment, so `vercel deploy` (or a git push) picks it up with nothing
+configured; `--target node`, the default everywhere else, emits nothing extra
+and is what `npm start` runs.
+
+One thing to know before deploying a VOICE agent to a serverless host: the
+session is a WebSocket, so the host has to support one. Vercel does — it hands
+the function the raw upgrade, and the emitted entry passes it to the same
+server `aai dev` runs. A host that serves only request/response still runs the
+HTTP surface — `/health`, `/client-config`,
+`/workflows/*` and your static assets — which is everything a workflow app
+needs and none of what a voice agent needs.
 
 ## Project structure
 
@@ -1199,11 +1228,23 @@ statement about pipeline mode, not about the SDK.
 
 ### Answering a phone call
 
-A deployed voice agent already serves carrier media streams — there is nothing
-to switch on. `createRuntimeServer` mounts `WS /phone` whenever the agent is a voice
-agent (`telephony` defaults to `true`, and to `false` for a `page: "static"`
-workflow app, which has no stages to put on a call). Point the carrier at it
-with a `carrier` query parameter naming who is dialling:
+**Say which carriers may call, and `WS /phone` is served for exactly those.**
+`telephony` is an allow-list on `agent()`, and it is the whole of the wiring:
+
+```ts
+import { agent } from "@alexkroman1/aai";
+
+export default agent({
+  name: "Support",
+  greeting: "Support line — what's happened?",
+  // The carrier this agent's number is with. `true` admits every carrier this
+  // build decodes; omit the field and `/phone` is not served at all.
+  telephony: ["twilio"],
+});
+```
+
+Point the carrier at the deployed agent with a `carrier` query parameter naming
+who is dialling:
 
 ```text
 wss://<your-agent-url>/phone?carrier=twilio
@@ -1211,15 +1252,25 @@ wss://<your-agent-url>/phone?carrier=telnyx
 ```
 
 Twilio and Telnyx are the two carriers this build decodes (`CARRIER_CODECS`);
-an unknown `carrier` is declined at the upgrade. Both speak 8 kHz mu-law, which
-the bridge transcodes in both directions, so the agent, its tools and its slots
+an unknown `carrier` is declined at the upgrade with a `400`, and a real one
+this agent did not declare with a `404`. Both speak 8 kHz mu-law, which the
+bridge transcodes in both directions, so the agent, its tools and its slots
 behave exactly as they do in the browser — a phone call is a transport, not a
-mode. Nothing about `agent.ts` changes to support one.
-
-Turn the route off with `telephony: false` on `createRuntimeServer`. If you are
-embedding the runtime yourself rather than deploying, the pieces are
-`createTelephonyBridge`, `startTelephonySession`, `TELEPHONY_PATH` and
-`carrierByName`, all on `@alexkroman1/aai-runtime`.
+mode. Nothing else about `agent.ts` changes to support one.
+
+**An agent that declares nothing answers no carrier**, which is a change from
+earlier releases: every voice agent used to serve both carriers' framing from
+the moment it booted, whether or not it had a phone number. `/phone` is the one
+door dialled from OUTSIDE your deployment, by a carrier following a number, so
+it is opened by a sentence in `agent.ts` rather than inherited. `aai dev` and a
+deployed sandbox honour the same declaration, so a call refused after a deploy
+is refused on your laptop too.
+
+`telephony: false` is the same refusal stated out loud, and an operator can pass
+`telephony` to `createAgentServer` to override one deployment of an agent that
+does declare a carrier. If you are embedding the runtime yourself rather than
+deploying, the pieces are `createTelephonyBridge`, `startTelephonySession`,
+`TELEPHONY_PATH` and `carrierByName`, all on `@alexkroman1/aai-runtime`.
 
 **Silence nudge (pipeline only):** set `silenceTimeoutMs` to make the
 assistant proactively take a turn after that much user silence (e.g.

package/dist/scaffold/package.json

@@ -7,7 +7,7 @@
   "scripts": {
     "dev": "aai dev",
     "prestart": "aai build --skip-tests",
-    "start": "node server.mjs",
+    "start": "aai start",
     "build": "aai build",
     "test": "vitest run --exclude \"**/*.eval.test.*\"",
     "test:agent": "aai test",
@@ -15,9 +15,10 @@
     "publish:agent": "aai publish"
   },
   "dependencies": {
-    "@alexkroman1/aai": "^14.0.0",
-    "@alexkroman1/aai-runtime": "^14.0.0",
-    "@alexkroman1/aai-ui": "^14.0.0",
+    "@alexkroman1/aai": "^15.0.0",
+    "@alexkroman1/aai-cli": "^15.0.0",
+    "@alexkroman1/aai-runtime": "^15.0.0",
+    "@alexkroman1/aai-ui": "^15.0.0",
     "react": "^19.2.8",
     "react-dom": "^19.2.8",
     "tailwindcss": "^4.0.0",
@@ -25,9 +26,8 @@
     "zod": "^4.5.4"
   },
   "devDependencies": {
-    "@alexkroman1/aai-cli": "^14.0.0",
     "@tailwindcss/vite": "^4.3.3",
-    "@types/node": "^26.4.1",
+    "@types/node": "^24.10.1",
     "@types/react": "^19.2.18",
     "@types/react-dom": "^19.2.5",
     "@vitejs/plugin-react": "^6.1.1",

package/dist/start.d.ts

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