@alexkroman1/aai-cli 13.2.0 → 14.0.0

package/bin.mjs

@@ -25,7 +25,7 @@ enableCompileCache();
 // Source wins when present: a checkout that has also been built must keep
 // running `cli.ts`, or `pnpm link --global` would silently serve a stale
 // `dist/` instead of the working tree.
-const source = new URL("./cli.ts", import.meta.url);
+const source = new URL("./src/cli.ts", import.meta.url);
 const entry = existsSync(fileURLToPath(source))
   ? source
   : new URL("./dist/cli.mjs", import.meta.url);

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

@@ -1,10 +1,11 @@
 #!/usr/bin/env node
-import { a as serverOrigin, i as readProjectConfig, n as ensureApiKey, r as readGlobalConfig, t as approveServer } from "./_config-CmJOFsAP.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";
 import { VALID_SLUG_RE } from "@alexkroman1/aai/internal";
-//#region _agent.ts
+//#region src/_agent.ts
 const DEFAULT_SERVER = "https://alexkroman--aai-server-web-server.modal.run";
 const DEFAULT_DEV_SERVER = "http://localhost:8080";
 let _cachedMonorepoRoot;
@@ -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/{_bundler-C31rlcYz.mjs → _bundler-DolUCMxu.mjs}

@@ -1,13 +1,13 @@
 #!/usr/bin/env node
-import { f as validateAgentExport } from "./_utils-B8QmtFhK.mjs";
-import { t as buildClient } from "./client-bundler-j5c46x0G.mjs";
+import { h as validateAgentExport } from "./_utils-D5JGcjiW.mjs";
+import { t as buildClient } from "./client-bundler-BJgREAh6.mjs";
 import { buildWorker } from "./worker-bundler.mjs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
 import { mkdtemp, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { hash } from "node:crypto";
-//#region _bundler.ts
+//#region src/_bundler.ts
 /**
 * Bundle an agent directory: build agent.ts into worker ESM + client files.
 *
@@ -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-CmJOFsAP.mjs → _config-DYzC6WMD.mjs}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { t as CliError } from "./_output-CKkmWs7i.mjs";
-import { c as isEexist, l as readJson, o as errorMessage, p as writeJson } from "./_utils-B8QmtFhK.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";
@@ -8,7 +8,7 @@ import { sleep } from "@alexkroman1/aai/internal";
 import { tmpdir } from "node:os";
 import envPaths from "env-paths";
 import { z } from "zod";
-//#region _config.ts
+//#region src/_config.ts
 /**
 * `.aai/project.json` lives in the working tree, so everything in it is
 * untrusted input — a cloned repo can supply any value.
@@ -230,6 +230,8 @@ async function readGlobalConfig(configDir) {
 async function writeGlobalConfig(configDir, data) {
 	await writeJson(path.join(configDir, "config.json"), data, { mode: 384 });
 }
+/** Local-session remedies FIRST — the two that need no account at all. */
+const LOCAL_SESSION_HINT = "Any ONE of these is enough, and the first two need no aai account:\n  1. Put ASSEMBLYAI_API_KEY=<your key> in this project's .env — the same file `aai publish` uploads.\n  2. Or export it in your shell: export ASSEMBLYAI_API_KEY=<your key>\n  3. Or run `aai login`, and `aai dev` will use your account's key.\nGet a key at https://www.assemblyai.com/dashboard.";
 /**
 * The credential every platform command runs on.
 *
@@ -251,9 +253,10 @@ async function writeGlobalConfig(configDir, data) {
 * pointing `AAI_CONFIG_DIR` at a config dir holding a key from an interactive
 * `aai login`.
 */
-async function ensureApiKey(configDir) {
+async function ensureApiKey(configDir, use = "platform") {
 	const config = await readGlobalConfig(configDir ?? getConfigDir());
 	if (config.apiKey) return config.apiKey;
+	if (use === "local-session") throw new CliError("missing_assemblyai_key", "ASSEMBLYAI_API_KEY is not set, and this agent's pipeline needs it to start a session.", LOCAL_SESSION_HINT);
 	throw new CliError("not_logged_in", "You're not logged in.", "Run `aai login` to link your account. Non-interactive setups can point AAI_CONFIG_DIR at a config dir holding a logged-in key.");
 }
 //#endregion

package/dist/_config.d.ts

@@ -73,6 +73,30 @@ export declare function updateGlobalConfig(update: (current: GlobalConfig) => Gl
 export declare function approveServer(url: string, configDir?: string): Promise<void>;
 export declare function readGlobalConfig(configDir?: string): Promise<GlobalConfig>;
 export declare function writeGlobalConfig(configDir: string, data: GlobalConfig): Promise<void>;
+/**
+ * Why the caller wants the key, which is what the FAILURE has to answer.
+ *
+ * One source, two questions. `"platform"` asks "who is this CLI logged in
+ * as?" — for `publish`/`push`/`logs`/`secret` a platform account genuinely IS
+ * the requirement, so the refusal is account-shaped and points at
+ * `aai login`. `"local-session"` is `aai dev` asking for a PROVIDER
+ * credential that the logged-in account merely happens to be able to supply:
+ * `ASSEMBLYAI_API_KEY` in `.env`, or exported in the shell, starts the same
+ * server with no account anywhere (see `resolveAgentEnv` in `_dev-server.ts`,
+ * which reaches here only when neither carries one).
+ *
+ * Answering the second question with the first's sentence is the defect this
+ * parameter exists to fix: `not_logged_in` names only account remedies
+ * (`aai login`, `AAI_CONFIG_DIR`), so `aai dev` read as "local development is
+ * gated on a cloud account" — and most of a twenty-persona DX audit believed
+ * it and abandoned the documented primary feedback loop, which was never
+ * gated at all.
+ *
+ * A PARAMETER rather than a second exported function because the source is
+ * shared: both answers must keep reading the one slot `aai login` writes, and
+ * a sibling function is how the two come to disagree about where a key lives.
+ */
+export type ApiKeyUse = "platform" | "local-session";
 /**
  * The credential every platform command runs on.
  *
@@ -94,5 +118,5 @@ export declare function writeGlobalConfig(configDir: string, data: GlobalConfig)
  * pointing `AAI_CONFIG_DIR` at a config dir holding a key from an interactive
  * `aai login`.
  */
-export declare function ensureApiKey(configDir?: string): Promise<string>;
+export declare function ensureApiKey(configDir?: string, use?: ApiKeyUse): Promise<string>;
 export {};

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-DWvkNoIS.mjs → _dev-server-CSMqF8PN.mjs}

@@ -1,27 +1,27 @@
 #!/usr/bin/env node
-import { i as outputSilenced, r as notify } from "./_ui-u7T4YooX.mjs";
-import { i as errorCode, o as errorMessage$1 } from "./_utils-B8QmtFhK.mjs";
-import { n as fallbackHtmlPlugin } from "./client-bundler-j5c46x0G.mjs";
-import { t as DEDUPED_PEERS } from "./_vite-env-D9Qj6KPX.mjs";
+import { i as outputSilenced, r as notify } from "./_ui-DCt4qZrk.mjs";
+import { a as errorCode, s as errorMessage$1 } from "./_utils-D5JGcjiW.mjs";
+import { n as fallbackHtmlPlugin } from "./client-bundler-BJgREAh6.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-CmJOFsAP.mjs";
-import { n as createWorkerEvaluator } from "./_bundler-C31rlcYz.mjs";
-import { t as resolveServerEnv } from "./_server-common-6e0QI4mq.mjs";
+import { n as ensureApiKey } from "./_config-DYzC6WMD.mjs";
+import { n as createWorkerEvaluator } from "./_bundler-DolUCMxu.mjs";
+import { t as resolveServerEnv } from "./_server-common-vILJp3it.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 { WORKFLOW_DATA_DIR_ENV, consoleLogger, createMemoryJournal, handleWorkflowRequest, isPathInside, publishStepEnv } from "@alexkroman1/aai-runtime/internal";
 import { defaultClientDir } from "@alexkroman1/aai-ui/client-dir";
 import { watch } from "chokidar";
 import getPort, { portNumbers } from "get-port";
 import pDebounce from "p-debounce";
-//#region _dev-env.ts
+//#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`).
 */
@@ -97,7 +97,7 @@ function createDevLogger(silenced) {
 	};
 }
 //#endregion
-//#region _dev-restart.ts
+//#region src/_dev-restart.ts
 /**
 * Restart supervision for `aai dev`.
 *
@@ -230,7 +230,7 @@ function createRestartSupervisor(ops) {
 	};
 }
 //#endregion
-//#region _dev-typecheck.ts
+//#region src/_dev-typecheck.ts
 /**
 * The background typecheck under `aai dev`.
 *
@@ -276,7 +276,7 @@ function createDevTypecheck(cwd, report = notify) {
 	} };
 }
 //#endregion
-//#region _dev-vite-config.ts
+//#region src/_dev-vite-config.ts
 /**
 * The Vite dev server's config for a project with a `client.tsx`.
 *
@@ -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,14 +461,14 @@ function viteDevConfig(cwd, vitePort, backendPort) {
 				},
 				[WORKFLOW_API_PREFIX]: {
 					target,
-					bypass: (req) => workflowPathServedByVite(cwd, req.url)
+					bypass: (req) => workflowPathServedByVite(viteRoot, req.url)
 				}
 			}
 		}
 	};
 }
 //#endregion
-//#region _dev-server.ts
+//#region src/_dev-server.ts
 /**
 * Dev server for directory-based agents.
 *
@@ -491,23 +491,21 @@ 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) {
 	const env = await resolveServerEnv(root);
 	const required = requiredProviderEnvVars(agentDef);
 	const hasShellKey = Boolean(process.env.ASSEMBLYAI_API_KEY);
-	if (required.includes("ASSEMBLYAI_API_KEY") && !env.ASSEMBLYAI_API_KEY && !hasShellKey) env.ASSEMBLYAI_API_KEY = await ensureApiKey();
+	if (required.includes("ASSEMBLYAI_API_KEY") && !env.ASSEMBLYAI_API_KEY && !hasShellKey) env.ASSEMBLYAI_API_KEY = await ensureApiKey(void 0, "local-session");
 	for (const warning of agentEnvWarnings(agentDef, env)) notify("warn", warning);
 	for (const warning of agentConfigWarnings(agentDef)) notify("warn", warning);
 	return env;
@@ -634,7 +632,7 @@ 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),

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

@@ -5,22 +5,30 @@
  */
 import { type ChildProcess } from "node:child_process";
 import type { MockRegistry } from "./_mock-registry.ts";
-export declare const dir: string;
+export declare const packageDir: 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.
+ * {@link aai}, but CAPTURING and expecting the CLI to FAIL — for the cases
+ * whose subject is what it SAID on its way to a non-zero exit.
  *
- * 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.
+ * Capturing is separate from {@link aai} rather than a flag on it, 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.
+ *
+ * The exit code is asserted HERE rather than left to the caller. `execaSync`
+ * throws on a non-zero exit, so the capturing helper this replaced could only
+ * be pointed at commands that succeed — and a `try`/`catch` around it would
+ * pass just as happily on a zero exit, which is the bug the one caller exists
+ * to catch (`aai test` named its unrun specs and exited 0 anyway).
  */
-export declare function aaiOutput(aaiBin: string, args: string[], cwd: string, timeoutMs?: number): {
+export declare function aaiOutputFailing(aaiBin: string, args: string[], cwd: string, timeoutMs?: number): {
     stdout: string;
     stderr: string;
+    exitCode: number;
 };
 /**
  * Build the CLI and return the path to the built binary.