@alexkroman1/aai-cli 13.3.0 → 15.0.0

package/dist/{_agent-Clbq3a4h.mjs → _agent-BzUeqOdj.mjs}

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
-import { a as serverOrigin, i as readProjectConfig, n as ensureApiKey, r as readGlobalConfig, t as approveServer } from "./_config-ZY2euhdh.mjs";
+import { m as stripTrailingSlash } from "./_utils-D5JGcjiW.mjs";
+import { a as serverOrigin, i as readProjectConfig, n as ensureApiKey, r as readGlobalConfig, t as approveServer } from "./_config-DYzC6WMD.mjs";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -18,9 +19,6 @@ function isDevMode() {
 	if (process.env.AAI_NO_DEV === "1") return false;
 	return getMonorepoRoot() !== null;
 }
-function stripTrailingSlash(url) {
-	return url.replace(/\/+$/, "");
-}
 /**
 * Whether `origin` may receive a credential without prior user approval.
 *
@@ -82,14 +80,39 @@ function assertValidConfigSlug(slug) {
 	throw new Error(`Invalid slug in .aai/project.json: ${JSON.stringify(slug)}\n  Expected lowercase letters, digits, \`-\`, \`_\` (2-64 chars). Fix or delete the file — \`aai publish\` will create a fresh deployment.`);
 }
 /**
-* Resolve everything needed to talk to the platform: project config (null if
-* the project has never been deployed), server URL, and API key.
+* Everything `resolveDeployTarget` decides BEFORE a credential is involved:
+* the project config (null when never deployed, or when `cwd` is null), the
+* user's global config, and the trust-checked, approved server URL.
 */
-async function resolveDeployTarget(cwd, explicitServer) {
-	const [config, globalConfig] = await Promise.all([readProjectConfig(cwd), readGlobalConfig()]);
+async function resolveApprovedServer(cwd, explicitServer) {
+	const [config, globalConfig] = await Promise.all([cwd === null ? null : readProjectConfig(cwd), readGlobalConfig()]);
 	const serverUrl = resolveServerUrl(explicitServer, config?.serverUrl, globalConfig.approvedServers ?? []);
 	if (explicitServer) await approveServer(serverUrl);
 	assertValidConfigSlug(config?.slug);
+	return {
+		config,
+		globalConfig,
+		serverUrl
+	};
+}
+/**
+* Resolve everything needed to talk to the platform: project config (null if
+* the project has never been deployed), server URL, and API key.
+*
+* `resolveApprovedServer` plus the key, rather than one function, because
+* `aai login` needs the first half and cannot have the second — it is the
+* command that PUTS the key on disk. It had its own copy of the
+* read → `resolveServerUrl` → `approveServer` sequence, which is security
+* policy ("passing `--server` is what approves an origin"), so a change to that
+* policy landed here and silently missed the one command whose whole job is to
+* write a credential for the origin in question. Same shape as the slug-guard
+* incident `assertValidConfigSlug` was moved down here for.
+*
+* The key comes from the config document already in hand — `ensureApiKey` would
+* read and parse the same file a second time, on every platform command.
+*/
+async function resolveDeployTarget(cwd, explicitServer) {
+	const { config, serverUrl } = await resolveApprovedServer(cwd, explicitServer);
 	return {
 		config,
 		serverUrl,
@@ -126,4 +149,4 @@ async function getServerInfo(cwd, explicitServer) {
 	};
 }
 //#endregion
-export { resolveDeployTarget as a, requireDeployedSlug as i, getServerInfo as n, resolveServerUrl as o, isDevMode as r, getMonorepoRoot as t };
+export { resolveApprovedServer as a, requireDeployedSlug as i, getServerInfo as n, resolveDeployTarget as o, isDevMode as r, getMonorepoRoot as t };

package/dist/_agent.d.ts

@@ -1,3 +1,4 @@
+import { type GlobalConfig, type ProjectConfig } from "./_config.ts";
 export declare const DEFAULT_SERVER = "https://alexkroman--aai-server-web-server.modal.run";
 export declare const DEFAULT_DEV_SERVER = "http://localhost:8080";
 export declare function getMonorepoRoot(): string | null;
@@ -19,9 +20,31 @@ export declare function isDevMode(): boolean;
  * @param approvedOrigins - Origins from the user-owned global config.
  */
 export declare function resolveServerUrl(explicit?: string, configUrl?: string, approvedOrigins?: readonly string[]): string;
+/**
+ * Everything `resolveDeployTarget` decides BEFORE a credential is involved:
+ * the project config (null when never deployed, or when `cwd` is null), the
+ * user's global config, and the trust-checked, approved server URL.
+ */
+export declare function resolveApprovedServer(cwd: string | null, explicitServer?: string): Promise<{
+    config: ProjectConfig | null;
+    globalConfig: GlobalConfig;
+    serverUrl: string;
+}>;
 /**
  * Resolve everything needed to talk to the platform: project config (null if
  * the project has never been deployed), server URL, and API key.
+ *
+ * `resolveApprovedServer` plus the key, rather than one function, because
+ * `aai login` needs the first half and cannot have the second — it is the
+ * command that PUTS the key on disk. It had its own copy of the
+ * read → `resolveServerUrl` → `approveServer` sequence, which is security
+ * policy ("passing `--server` is what approves an origin"), so a change to that
+ * policy landed here and silently missed the one command whose whole job is to
+ * write a credential for the origin in question. Same shape as the slug-guard
+ * incident `assertValidConfigSlug` was moved down here for.
+ *
+ * The key comes from the config document already in hand — `ensureApiKey` would
+ * read and parse the same file a second time, on every platform command.
  */
 export declare function resolveDeployTarget(cwd: string, explicitServer?: string): Promise<{
     config: {

package/dist/_artifacts-BJOYGQPp.mjs

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+import path from "node:path";
+//#region src/_artifacts.ts
+/**
+* The `.aai/` layout — where `aai build` leaves what `aai start` and the
+* deployment targets read back.
+*
+* A LEAF module, and that is the whole reason it exists. These two paths were
+* declared where they were first needed (`build.ts`, `start.ts`), which was
+* fine while the readers were the writers. `_vercel-output.ts` needs both and
+* is imported BY `build.ts`, so taking them from there is an import cycle —
+* one Biome rejects, and one that would fail at runtime rather than at build
+* time, since a `const` read across a cycle is a `ReferenceError` decided by
+* import order. Both original homes re-export, so no published subpath moved.
+*/
+/** Where `aai build` leaves the worker bundle, relative to the project root. */
+const WORKER_ARTIFACT_REL = path.join(".aai", "worker.mjs");
+/** Where `aai build` leaves the built browser client, relative to the root. */
+const CLIENT_ARTIFACT_REL = path.join(".aai", "client");
+//#endregion
+export { WORKER_ARTIFACT_REL as n, CLIENT_ARTIFACT_REL as t };

package/dist/_artifacts.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The `.aai/` layout — where `aai build` leaves what `aai start` and the
+ * deployment targets read back.
+ *
+ * A LEAF module, and that is the whole reason it exists. These two paths were
+ * declared where they were first needed (`build.ts`, `start.ts`), which was
+ * fine while the readers were the writers. `_vercel-output.ts` needs both and
+ * is imported BY `build.ts`, so taking them from there is an import cycle —
+ * one Biome rejects, and one that would fail at runtime rather than at build
+ * time, since a `const` read across a cycle is a `ReferenceError` decided by
+ * import order. Both original homes re-export, so no published subpath moved.
+ */
+/** Where `aai build` leaves the worker bundle, relative to the project root. */
+export declare const WORKER_ARTIFACT_REL: string;
+/** Where `aai build` leaves the built browser client, relative to the root. */
+export declare const CLIENT_ARTIFACT_REL: string;

package/dist/_build-target.d.ts

@@ -0,0 +1,172 @@
+/**
+ * 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. */
+export declare const BUILD_TARGETS: readonly ["node", "vercel"];
+export type BuildTarget = (typeof BUILD_TARGETS)[number];
+/**
+ * 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.
+ */
+export declare const DEFAULT_BUILD_TARGET: BuildTarget;
+/**
+ * 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.
+ */
+export declare const TARGET_ENV_MARKERS: Readonly<Record<string, BuildTarget>>;
+export declare function isBuildTarget(value: string): value is BuildTarget;
+/**
+ * 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.
+ */
+export declare function resolveBuildTarget(explicit: string | undefined, env?: Record<string, string | undefined>): BuildTarget;
+/**
+ * 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
+ */
+export declare const VERCEL_OUTPUT_DIR: string;
+/**
+ * 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.
+ */
+export declare const VERCEL_FUNCTION_DIR: string;
+/**
+ * The route {@link VERCEL_FUNCTION_DIR} is served at — its directory name
+ * without `.func`, which is how the Build Output API names a function.
+ */
+export declare const VERCEL_FUNCTION_ROUTE = "/__server";
+/** Static assets the Vercel CDN serves directly, never reaching the function. */
+export declare const VERCEL_STATIC_DIR: string;
+/** `nodejs<major>.x` for the Node running this build, clamped to what Vercel offers. */
+export declare function vercelNodeRuntime(version?: string): string;
+/**
+ * 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.
+ */
+export declare const VERCEL_ENTRY_SOURCE = "// Generated by `aai build --target vercel` \u2014 do not edit, and do not commit.\n// Vercel invokes this handler per request and delivers a WebSocket upgrade\n// through its request context. See @alexkroman1/aai-cli/start.\nimport { createProjectServer } from \"@alexkroman1/aai-cli/start\";\n\nconst server = (await createProjectServer({ cwd: import.meta.dirname })).node;\n\nconst REQUEST_CONTEXT = Symbol.for(\"@vercel/request-context\");\n\nexport default function handler(req, res) {\n  if (req.method === \"GET\" && req.headers.upgrade?.toLowerCase() === \"websocket\") {\n    const upgrade = globalThis[REQUEST_CONTEXT]?.get?.()?.upgradeWebSocket?.();\n    if (upgrade) {\n      server.emit(\"upgrade\", upgrade.req, upgrade.socket, upgrade.head);\n      if (!res.headersSent && !res.writableEnded) {\n        res.statusCode = 204;\n        res.end();\n      }\n      return;\n    }\n  }\n  server.emit(\"request\", req, res);\n}\n";
+/**
+ * `.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.
+ */
+export declare function vercelFunctionConfigSource(runtime?: string): string;
+/**
+ * `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.
+ */
+export declare const VERCEL_BUILD_CONFIG_SOURCE: string;

package/dist/{_bundler-DEkjO1d8.mjs → _bundler-DM0d0M7m.mjs}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { f as validateAgentExport } from "./_utils-Dhd058D9.mjs";
-import { t as buildClient } from "./client-bundler-CT-_26c5.mjs";
+import { h as validateAgentExport } from "./_utils-D5JGcjiW.mjs";
+import { t as buildClient } from "./client-bundler-6mTLs6ny.mjs";
 import { buildWorker } from "./worker-bundler.mjs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
@@ -86,14 +86,15 @@ async function evalWorkerConfig(code) {
 * distinct-build leak is accepted for the reasons documented there.
 */
 function createWorkerEvaluator() {
-	let lastHash;
-	let lastWorker;
+	let last;
 	return async (code) => {
 		const codeHash = hash("sha256", code);
-		if (lastWorker && codeHash === lastHash) return lastWorker;
+		if (last?.hash === codeHash) return last.worker;
 		const worker = await evalWorkerBundle(code);
-		lastHash = codeHash;
-		lastWorker = worker;
+		last = {
+			hash: codeHash,
+			worker
+		};
 		return worker;
 	};
 }

package/dist/_cli-common.d.ts

@@ -17,6 +17,26 @@ export declare const sharedArgs: {
         readonly description: "Output JSON (auto-detected in non-TTY)";
     };
 };
+/**
+ * What every PLATFORM command accepts — the pair, as a group to spread.
+ *
+ * `sharedArgs` supplies the field VALUES, so each of the twelve credentialed
+ * commands still restated the shape (`server: sharedArgs.server, json:
+ * sharedArgs.json`). A flag all of them should take is then twelve edits, and
+ * `assertKnownArgv` refuses the flag on whichever one was missed — after
+ * release. `cli-workflow.ts`'s `workflowArgs` is the same pattern for its group.
+ */
+export declare const platformArgs: {
+    readonly server: {
+        readonly type: "string";
+        readonly alias: "s";
+        readonly description: "Platform server URL";
+    };
+    readonly json: {
+        readonly type: "boolean";
+        readonly description: "Output JSON (auto-detected in non-TTY)";
+    };
+};
 /**
  * Flags in `rawArgs` that `argsDef` doesn't declare, in the form the user
  * typed them.
@@ -44,15 +64,34 @@ type AnyCommandDef = CommandDef<ArgsDef>;
  * the narrowing.
  */
 export declare function commandPath<T extends ArgsDef>(cmd: CommandDef<T>, parent?: CommandDef<T>): string;
+/** What {@link resolveArgv} learned by walking the command tree once. */
+export type ArgvSelection = {
+    /** `["aai", "secret", "put"]` — the path walked, for a `--help` sentence. */
+    named: string[];
+    /**
+     * The first non-flag token that named no subcommand where one was expected,
+     * i.e. a mistyped command. `undefined` when the walk reached a real command.
+     */
+    unknownCommand?: string;
+    /** Args declared by the command the argv selected. */
+    argsDef: ArgsDef;
+    /** argv from the first token that is not a subcommand — flags and positionals. */
+    rest: string[];
+};
 /**
- * Unknown flags in `argv` for whichever (possibly nested) subcommand it
- * selects — `[]` when everything is declared.
+ * Walk the real command tree for `argv` and report everything the pre-parse
+ * guards in `cli.ts` need: which command it selects, what that command
+ * declares, and whether a token mistyped a subcommand.
  *
- * Walks the real command tree rather than re-listing flags, so this cannot
- * drift from what the commands accept. An unknown SUBCOMMAND is not reported:
- * citty already answers that with usage text and a non-zero exit.
+ * ONE walk, because there used to be two — this one and a copy in `cli.ts`,
+ * each with its own `Resolvable` narrowing, whose only difference was the
+ * terminal action. The copies also had an ORDERING dependency nothing
+ * enforced: the flag guard reports nothing for a mistyped subcommand (the
+ * flags would be matched against the wrong command's definition), which is
+ * only safe because the command guard ran first. Answering both from one
+ * result removes the ordering rather than documenting it.
  */
-export declare function unknownFlagsForArgv(root: AnyCommandDef, argv: string[]): Promise<string[]>;
+export declare function resolveArgv(root: AnyCommandDef, argv: string[]): Promise<ArgvSelection>;
 /** Shared command setup: resolve cwd, optionally require agent.ts. */
 export declare function setup(opts?: {
     agent?: boolean;

package/dist/{_config-ZY2euhdh.mjs → _config-DYzC6WMD.mjs}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { t as CliError } from "./_output-DbJt9gsl.mjs";
-import { c as isEexist, l as readJson, o as errorMessage, p as writeJson } from "./_utils-Dhd058D9.mjs";
+import { t as CliError } from "./_output-DBP9Op_d.mjs";
+import { d as readJson, g as writeJson, s as errorMessage, u as isEexist } from "./_utils-D5JGcjiW.mjs";
 import { mkdtempSync } from "node:fs";
 import path from "node:path";
 import fs from "node:fs/promises";

package/dist/_dev-env.d.ts

@@ -17,7 +17,7 @@
  */
 import type { Logger } from "@alexkroman1/aai-runtime";
 /**
- * The env handed to `createServer` for host-mode connections: provider
+ * The env handed to `createRuntimeServer` for host-mode connections: provider
  * credentials plus the `AAI_ALLOW_HOST` gate read straight from the shell
  * (it is a control variable, not something an agent declares in `.env`).
  */

package/dist/{_dev-server-C13xuGB1.mjs → _dev-server-BzWB6-4y.mjs}

@@ -1,27 +1,27 @@
 #!/usr/bin/env node
 import { i as outputSilenced, r as notify } from "./_ui-DCt4qZrk.mjs";
-import { i as errorCode, o as errorMessage$1 } from "./_utils-Dhd058D9.mjs";
-import { n as fallbackHtmlPlugin } from "./client-bundler-CT-_26c5.mjs";
+import { a as errorCode, s as errorMessage$1 } from "./_utils-D5JGcjiW.mjs";
+import { n as fallbackHtmlPlugin } from "./client-bundler-6mTLs6ny.mjs";
 import { t as DEDUPED_PEERS } from "./_vite-env-kejF0p2L.mjs";
 import { buildWorker } from "./worker-bundler.mjs";
 import { typecheckProject } from "./typecheck.mjs";
-import { n as ensureApiKey } from "./_config-ZY2euhdh.mjs";
-import { n as createWorkerEvaluator } from "./_bundler-DEkjO1d8.mjs";
-import { t as resolveServerEnv } from "./_server-common-BV4_CrP3.mjs";
+import { n as ensureApiKey } from "./_config-DYzC6WMD.mjs";
+import { n as resolveServerEnv } from "./_server-common-De0haHr9.mjs";
+import { n as createWorkerEvaluator } from "./_bundler-DM0d0M7m.mjs";
 import { existsSync, statSync } from "node:fs";
 import path from "node:path";
-import { omitUndefined } from "@alexkroman1/aai/utils";
+import { omitUndefined, plural } from "@alexkroman1/aai/utils";
 import { createCoalescingRunner, requestPath, sleep } from "@alexkroman1/aai/internal";
-import { agentConfigWarnings } from "@alexkroman1/aai/manifest";
-import { DEFAULT_LISTEN_HOST, WORKFLOW_API_PREFIX, createRuntime, createServer, ensureSessionStateSchema, ensureWorkflowJournalSchema, requiredProviderEnvVars, withHostCredentialFallback } from "@alexkroman1/aai-runtime";
-import { WORKFLOW_DATA_DIR_ENV, consoleLogger, createMemoryJournal, handleWorkflowRequest, publishStepEnv } from "@alexkroman1/aai-runtime/internal";
+import { DEFAULT_LISTEN_HOST, WORKFLOW_API_PREFIX, createRuntime, createRuntimeServer, ensureSessionStateSchema, ensureWorkflowJournalSchema, requiredProviderEnvVars, withHostCredentialFallback } from "@alexkroman1/aai-runtime";
 import { defaultClientDir } from "@alexkroman1/aai-ui/client-dir";
+import { agentConfigWarnings } from "@alexkroman1/aai/manifest";
+import { WORKFLOW_DATA_DIR_ENV, consoleLogger, createMemoryJournal, handleWorkflowRequest, isPathInside, publishStepEnv } from "@alexkroman1/aai-runtime/internal";
 import { watch } from "chokidar";
 import getPort, { portNumbers } from "get-port";
 import pDebounce from "p-debounce";
 //#region src/_dev-env.ts
 /**
-* The env handed to `createServer` for host-mode connections: provider
+* The env handed to `createRuntimeServer` for host-mode connections: provider
 * credentials plus the `AAI_ALLOW_HOST` gate read straight from the shell
 * (it is a control variable, not something an agent declares in `.env`).
 */
@@ -338,7 +338,7 @@ function createDevTypecheck(cwd, report = notify) {
 * send `..` where a browser would normalize it — and a malformed percent-escape
 * is left to the API, which is where a path we cannot resolve belongs.
 */
-function workflowPathServedByVite(root, rawUrl) {
+function workflowPathServedByVite(base, rawUrl) {
 	if (rawUrl === void 0) return void 0;
 	let decoded;
 	try {
@@ -346,9 +346,8 @@ function workflowPathServedByVite(root, rawUrl) {
 	} catch {
 		return;
 	}
-	const base = path.resolve(root);
 	const resolved = path.resolve(base, `.${decoded}`);
-	if (resolved !== base && !resolved.startsWith(base + path.sep)) return void 0;
+	if (!isPathInside(base, resolved)) return void 0;
 	try {
 		if (!statSync(resolved).isFile()) return void 0;
 	} catch {
@@ -362,13 +361,13 @@ function workflowPathServedByVite(root, rawUrl) {
 * 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 thing to hold in mind before adding a route to `createRuntimeServer`. 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
+* (`workflowApp()`) has no session and no socket: `mountPage()` 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
@@ -396,7 +395,7 @@ function workflowPathServedByVite(root, rawUrl) {
 * `http://localhost:<port>` either way — a caller that resolves IPv4-only, or
 * dials the literal, gets a connection refused against a server that is up.
 *
-* The two halves of `aai dev` also disagreed: `createServer` binds
+* The two halves of `aai dev` also disagreed: `createRuntimeServer` binds
 * {@link DEFAULT_LISTEN_HOST} explicitly, Vite took its own default, and only a
 * set `AAI_DEV_HOST` brought them back together. Taking the same constant is
 * what makes them agree by construction rather than by two matching literals.
@@ -444,6 +443,7 @@ function workflowPathServedByVite(root, rawUrl) {
 */
 function viteDevConfig(cwd, vitePort, backendPort) {
 	const target = `http://127.0.0.1:${backendPort}`;
+	const viteRoot = path.resolve(cwd);
 	return {
 		root: cwd,
 		plugins: [fallbackHtmlPlugin(cwd)],
@@ -461,7 +461,7 @@ function viteDevConfig(cwd, vitePort, backendPort) {
 				},
 				[WORKFLOW_API_PREFIX]: {
 					target,
-					bypass: (req) => workflowPathServedByVite(cwd, req.url)
+					bypass: (req) => workflowPathServedByVite(viteRoot, req.url)
 				}
 			}
 		}
@@ -491,16 +491,14 @@ function viteDevConfig(cwd, vitePort, backendPort) {
 *   can't mask one that would be missing both here and after deploy.
 */
 function agentEnvWarnings(agentDef, env, shellEnv = process.env) {
-	const s = (names) => names.length > 1 ? "s" : "";
-	const them = (names) => names.length > 1 ? "them" : "it";
 	const required = requiredProviderEnvVars(agentDef);
 	const warnings = [];
 	const missing = required.filter((name) => !(env[name] || shellEnv[name]));
-	if (missing.length > 0) warnings.push(`Missing provider credential${s(missing)}: ${missing.join(", ")}. Set ${them(missing)} in .env or the environment.`);
+	if (missing.length > 0) warnings.push(`Missing provider ${plural(missing.length, "credential")}: ${missing.join(", ")}. Set ${plural(missing.length, "it", "them")} in .env or the environment.`);
 	const shellOnly = required.filter((name) => !env[name] && shellEnv[name]);
-	if (shellOnly.length > 0) warnings.push(`${shellOnly.join(", ")} resolved from your shell, not .env — deployed agents won't have ${them(shellOnly)}. Declare ${them(shellOnly)} in .env before \`aai publish\`.`);
+	if (shellOnly.length > 0) warnings.push(`${shellOnly.join(", ")} resolved from your shell, not .env — deployed agents won't have ${plural(shellOnly.length, "it", "them")}. Declare ${plural(shellOnly.length, "it", "them")} in .env before \`aai publish\`.`);
 	const declared = (agentDef.requiredEnv ?? []).filter((name) => !env[name]);
-	if (declared.length > 0) warnings.push(`Missing requiredEnv key${s(declared)} declared by the agent: ${declared.join(", ")}. Set ${them(declared)} in .env — ctx.env will not contain ${them(declared)} otherwise.`);
+	if (declared.length > 0) warnings.push(`Missing requiredEnv ${plural(declared.length, "key")} declared by the agent: ${declared.join(", ")}. Set ${plural(declared.length, "it", "them")} in .env — ctx.env will not contain ${plural(declared.length, "it", "them")} otherwise.`);
 	return warnings;
 }
 async function resolveAgentEnv(root, agentDef) {
@@ -634,13 +632,16 @@ async function startDevServer(opts) {
 			journal,
 			publicUrl: process.env.PUBLIC_URL?.trim() || `http://localhost:${backendPort}`
 		});
-		return createServer({
+		return createRuntimeServer({
 			runtime,
 			name: agentDef.name,
 			env: hostModeEnv(providerEnv),
 			hostBaseAgent: agentDef,
 			greeting: agentDef.greeting,
-			...omitUndefined({ page: agentDef.page }),
+			...omitUndefined({
+				page: agentDef.page,
+				telephony: agentDef.telephony
+			}),
 			request: (req, res, url, method) => handleWorkflowRequest(req, res, url, method, {
 				deliver: () => runtime.deliverWorkflow,
 				logger: devLogger

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

@@ -12,13 +12,13 @@
  * 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 thing to hold in mind before adding a route to `createRuntimeServer`. 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
+ * (`workflowApp()`) has no session and no socket: `mountPage()` 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
@@ -46,7 +46,7 @@
  * `http://localhost:<port>` either way — a caller that resolves IPv4-only, or
  * dials the literal, gets a connection refused against a server that is up.
  *
- * The two halves of `aai dev` also disagreed: `createServer` binds
+ * The two halves of `aai dev` also disagreed: `createRuntimeServer` binds
  * {@link DEFAULT_LISTEN_HOST} explicitly, Vite took its own default, and only a
  * set `AAI_DEV_HOST` brought them back together. Taking the same constant is
  * what makes them agree by construction rather than by two matching literals.

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

@@ -61,7 +61,7 @@ export declare function waitForHealth(url: string, child?: ChildProcess, timeout
 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`.
+ * the project's own `prestart` (`aai build`) and then `aai start`.
  *
  * 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