@alexkroman1/aai-cli 5.8.1 → 5.10.0

package/README.md

@@ -52,8 +52,12 @@ required credentials, and print the agent's public URL.
   outside one it runs `init`.
 - `--server <url>` targets a self-hosted platform; the origin is remembered
   in your user config after explicit approval.
+- `aai login` is the only way to authenticate — it links an account already
+  signed in to the studio. An exported `ASSEMBLYAI_API_KEY` does not log you
+  in; in a project that variable is a provider credential for `aai dev`.
 - The API key is stored `0600` in your user config dir (`AAI_CONFIG_DIR`
-  overrides the location).
+  overrides the location). Non-interactive callers point `AAI_CONFIG_DIR` at a
+  config dir holding a key from an interactive `aai login`.
 
 ## Documentation
 

package/bin.mjs

@@ -0,0 +1,32 @@
+#!/usr/bin/env node
+// The `aai` bin in BOTH layouts — the source checkout (`pnpm link --global`,
+// where it loads `cli.ts` directly) and the published tarball (where only
+// `dist/` ships, so it loads `dist/cli.mjs`). It used to be the dev bin only,
+// with `publishConfig.bin` pointing straight at `dist/cli.mjs`.
+//
+// One bin for both is what makes the compile cache reachable. The cache only
+// covers modules compiled AFTER the call, and every dependency of the CLI is
+// external (`deps.neverBundle` in tsdown.config.ts), so `dist/cli.mjs` carries
+// hoisted `import` statements for citty, execa and the rest — all evaluated
+// before any statement in that file could run. A banner or a first-line call
+// inside `cli.ts` would therefore cache nothing that costs anything. Loading
+// the entry through a DYNAMIC import from a wrapper is the only ordering that
+// puts the enable genuinely first.
+import { existsSync } from "node:fs";
+import { enableCompileCache } from "node:module";
+import { fileURLToPath } from "node:url";
+
+// Caches V8 bytecode per (Node version, file content) under the user's cache
+// dir, so `aai` pays parse+compile once per version rather than per
+// invocation. Deliberately unguarded: this returns a `{ status }` result and
+// does not throw, so an unwritable cache dir degrades to today's behaviour.
+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 entry = existsSync(fileURLToPath(source))
+  ? source
+  : new URL("./dist/cli.mjs", import.meta.url);
+await import(entry.href);

package/dist/{_agent-2nVugrN3.mjs → _agent-DS2PUJcl.mjs}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as readProjectConfig, i as readGlobalConfig, n as ensureApiKey, o as serverOrigin, t as approveServer } from "./_config-Y5V-5Krn.mjs";
+import { a as serverOrigin, i as readProjectConfig, n as ensureApiKey, r as readGlobalConfig, t as approveServer } from "./_config-DMyolIk9.mjs";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";

package/dist/{_bundler-Cjaxa2wi.mjs → _bundler-DC17suWN.mjs}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { u as validateAgentExport } from "./_utils-Ch0J4s6a.mjs";
-import { t as buildClient } from "./client-bundler-yiWoXrgb.mjs";
+import { u as validateAgentExport } from "./_utils-8KKw-bzi.mjs";
+import { t as buildClient } from "./client-bundler-DONm-khu.mjs";
 import { buildWorker } from "./worker-bundler.mjs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";

package/dist/_config-DMyolIk9.mjs

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+import { t as CliError } from "./_output-CC300DzW.mjs";
+import { a as errorMessage, c as readJson, d as writeJson } from "./_utils-8KKw-bzi.mjs";
+import { mkdtempSync } from "node:fs";
+import path from "node:path";
+import fs from "node:fs/promises";
+import { setTimeout } from "node:timers/promises";
+import { tmpdir } from "node:os";
+import envPaths from "env-paths";
+import { z } from "zod";
+//#region _config.ts
+/**
+* `.aai/project.json` lives in the working tree, so everything in it is
+* untrusted input — a cloned repo can supply any value.
+*
+* `serverUrl` is deliberately NOT validated here. A failed field makes
+* `readProjectConfig` return null for the whole file, which discards the
+* `slug` too — and a deploy with no slug generates a fresh one, silently
+* creating a duplicate agent and overwriting the config. The URL is instead
+* validated where it is used, by `resolveServerUrl`, which rejects anything
+* that isn't an approved http(s) origin.
+*/
+const ProjectConfigSchema = z.object({
+	/** Deployed agent slug — absent for a pulled project never published. */
+	slug: z.string().optional(),
+	serverUrl: z.string(),
+	/** Studio project this directory is linked to (`aai pull`/`aai push`). */
+	studioProject: z.string().optional(),
+	/**
+	* The workspace files hash at the last pull/push — `aai push` sends it
+	* back as the fast-forward token, so an edit made in the studio since
+	* then surfaces as a 409 instead of being silently overwritten.
+	*/
+	studioSourceHash: z.string().optional()
+});
+/**
+* Resolve the global config directory (the platform-conventional env-paths
+* location).
+*
+* `AAI_CONFIG_DIR` overrides everything — it exists so tests (and unusual
+* setups) can redirect ALL global-config reads and writes away from the
+* user's real config. The test suite's `approveServer` calls used to
+* permanently pollute `~/.config/aai/config.json` with approved origins.
+*/
+function getConfigDir() {
+	const override = process.env.AAI_CONFIG_DIR?.trim();
+	if (override) return override;
+	if (process.env.VITEST) return testConfigDir();
+	return envPaths("aai", { suffix: "" }).config;
+}
+/**
+* Per-process throwaway config dir used only under vitest. Memoized: callers
+* read-modify-write the same config across calls, so a fresh dir per call
+* would silently drop what the previous one wrote.
+*/
+let _testConfigDir;
+function testConfigDir() {
+	_testConfigDir ??= mkdtempSync(path.join(tmpdir(), "aai-vitest-config-"));
+	return _testConfigDir;
+}
+async function readProjectConfig(agentDir) {
+	const file = path.join(agentDir, ".aai", "project.json");
+	let data;
+	try {
+		data = await readJson(file);
+	} catch (err) {
+		const reason = errorMessage(err).replace(`Invalid JSON in ${file}: `, "");
+		throw new Error(`project.json is corrupted at ${file}: ${reason}\n  Fix or delete the file — deploying without it would create a new agent under a fresh slug.`, { cause: err });
+	}
+	if (data === null) return null;
+	const parsed = ProjectConfigSchema.safeParse(data);
+	if (!parsed.success) return null;
+	return parsed.data;
+}
+async function writeProjectConfig(agentDir, data) {
+	await writeJson(path.join(agentDir, ".aai", "project.json"), data);
+}
+/**
+* Merge `patch` into the existing project config rather than replacing the
+* file — a publish recording its `slug` must not drop the studio link
+* fields a pull wrote, and vice versa.
+*/
+async function updateProjectConfig(agentDir, patch) {
+	let existing = null;
+	try {
+		existing = await readProjectConfig(agentDir);
+	} catch {}
+	const merged = {
+		...existing,
+		...patch
+	};
+	await writeProjectConfig(agentDir, merged);
+	return merged;
+}
+/**
+* Origin of `url`, or `null` when it is not an absolute http(s) URL.
+*
+* Non-HTTP schemes are rejected rather than returned: `new URL()` yields the
+* opaque origin `"null"` for them, which would otherwise flow on as if it
+* were a real origin.
+*/
+function serverOrigin(url) {
+	let parsed;
+	try {
+		parsed = new URL(url);
+	} catch {
+		return null;
+	}
+	if (parsed.protocol !== "http:" && parsed.protocol !== "https:") return null;
+	return parsed.origin;
+}
+/** Bounded so a stuck lock degrades to the old racy write, never a hang. */
+const CONFIG_LOCK_TIMEOUT_MS = 2e3;
+const CONFIG_LOCK_RETRY_MS = 20;
+/** Older than this and the holder is assumed dead (crashed mid-update). */
+const CONFIG_LOCK_STALE_MS = 1e4;
+/**
+* Serialize a read-modify-write of the global config ACROSS PROCESSES.
+*
+* `writeJson` makes each individual write atomic, so no reader ever sees a
+* torn file — but the read→modify→write SPAN is not atomic, and every writer
+* here replaces the whole document. Two concurrent CLI invocations therefore
+* lose each other's updates: measured on this repo, 8 parallel commands each
+* approving a distinct origin recorded only 5 of them, and — the case that
+* matters — a concurrent `approveServer` straddling the final write of
+* `aai login` DISCARDS THE API KEY the login just reported saving, leaving
+* the next command with `not_logged_in`. That window is wide open in practice:
+* `aai login` polls for up to five minutes while the user approves in the
+* browser, so any other command run in that time can be mid-update when the
+* key lands.
+*
+* The lock is a `wx` (exclusive-create) lockfile — atomic on every platform
+* we target, and the only primitive available across processes without a
+* daemon. Three deliberate properties:
+*
+* - **Acquisition is bounded** (`CONFIG_LOCK_TIMEOUT_MS`). On timeout the
+*   update proceeds UNLOCKED rather than throwing: these are small
+*   convenience files, and failing `aai login` because a lockfile is stuck
+*   would be strictly worse than the lost update the lock exists to prevent.
+* - **A stale lock is broken** (`CONFIG_LOCK_STALE_MS`). A process killed
+*   mid-update leaves the file behind; without this, one crash would make
+*   every later config write take the unlocked path forever.
+* - **Never nest.** Re-entering from inside `fn` would self-deadlock until the
+*   timeout. `executeLogin` calls `approveServer` and the key update in
+*   sequence, not nested — keep it that way.
+*/
+async function withGlobalConfigLock(dir, fn) {
+	const lockPath = path.join(dir, "config.lock");
+	const deadline = Date.now() + CONFIG_LOCK_TIMEOUT_MS;
+	let held = false;
+	for (;;) try {
+		await fs.mkdir(dir, {
+			recursive: true,
+			mode: 448
+		});
+		await (await fs.open(lockPath, "wx", 384)).close();
+		held = true;
+		break;
+	} catch (err) {
+		if (err.code !== "EEXIST") break;
+		if (await fs.stat(lockPath).then((s) => Date.now() - s.mtimeMs).catch(() => 0) > CONFIG_LOCK_STALE_MS) {
+			await fs.rm(lockPath, { force: true }).catch(() => void 0);
+			continue;
+		}
+		if (Date.now() >= deadline) break;
+		await setTimeout(CONFIG_LOCK_RETRY_MS);
+	}
+	try {
+		return await fn();
+	} finally {
+		if (held) await fs.rm(lockPath, { force: true }).catch(() => void 0);
+	}
+}
+/**
+* Apply `update` to the global config under the cross-process lock, re-reading
+* inside it so the merge is against current contents rather than a snapshot
+* taken before the lock was held. Every read-modify-write of the global config
+* must go through this — a direct `readGlobalConfig`/`writeGlobalConfig` pair
+* is the bug this exists to prevent.
+*
+* Returning the argument unchanged skips the write, so the common no-op case
+* (an origin already approved — i.e. most `--server` invocations) costs a read
+* rather than a rewrite plus the lock contention that comes with it.
+*/
+async function updateGlobalConfig(update, configDir) {
+	const dir = configDir ?? getConfigDir();
+	await withGlobalConfigLock(dir, async () => {
+		const current = await readGlobalConfig(dir);
+		const next = update(current);
+		if (next !== current) await writeGlobalConfig(dir, next);
+	});
+}
+/**
+* Record `url`'s origin as user-approved, so later commands in this project
+* may send credentials there without re-passing `--server`.
+*/
+async function approveServer(url, configDir) {
+	const origin = serverOrigin(url);
+	if (!origin) return;
+	await updateGlobalConfig((config) => {
+		const approved = config.approvedServers ?? [];
+		return approved.includes(origin) ? config : {
+			...config,
+			approvedServers: [...approved, origin]
+		};
+	}, configDir);
+}
+async function readGlobalConfig(configDir) {
+	const dir = configDir ?? getConfigDir();
+	return await readJson(path.join(dir, "config.json")) ?? {};
+}
+async function writeGlobalConfig(configDir, data) {
+	await writeJson(path.join(configDir, "config.json"), data, { mode: 384 });
+}
+/**
+* The credential every platform command runs on.
+*
+* ONE source: the key `aai login` saved to the global config. Nothing else
+* authenticates the CLI.
+*
+* There is deliberately no "paste a key" prompt and no `ASSEMBLYAI_API_KEY`
+* fallback. Both produced the same half-configured CLI — able to push,
+* publish, and read/write another account's secrets while linked to no
+* account the user could see in the studio — and both made `aai login`, the
+* real onboarding path, optional in practice. The env var was the worse of
+* the two: it applies to every invocation in a shell, it silently PERSISTED
+* itself into the global config on first use (so the CLI stayed authenticated
+* as that key long after the export was gone), and it collides with the
+* variable the same name serves in a project `.env`, where it is a *provider*
+* credential for the local dev server rather than a platform identity.
+*
+* Non-interactive callers (CI, scripts, the eval harnesses) authenticate by
+* pointing `AAI_CONFIG_DIR` at a config dir holding a key from an interactive
+* `aai login`.
+*/
+async function ensureApiKey(configDir) {
+	const config = await readGlobalConfig(configDir ?? getConfigDir());
+	if (config.apiKey) return config.apiKey;
+	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
+export { serverOrigin as a, writeProjectConfig as c, readProjectConfig as i, ensureApiKey as n, updateGlobalConfig as o, readGlobalConfig as r, updateProjectConfig as s, approveServer as t };

package/dist/_config.d.ts

@@ -54,6 +54,18 @@ export type GlobalConfig = {
  * were a real origin.
  */
 export declare function serverOrigin(url: string): string | null;
+/**
+ * Apply `update` to the global config under the cross-process lock, re-reading
+ * inside it so the merge is against current contents rather than a snapshot
+ * taken before the lock was held. Every read-modify-write of the global config
+ * must go through this — a direct `readGlobalConfig`/`writeGlobalConfig` pair
+ * is the bug this exists to prevent.
+ *
+ * Returning the argument unchanged skips the write, so the common no-op case
+ * (an origin already approved — i.e. most `--server` invocations) costs a read
+ * rather than a rewrite plus the lock contention that comes with it.
+ */
+export declare function updateGlobalConfig(update: (current: GlobalConfig) => GlobalConfig, configDir?: string): Promise<void>;
 /**
  * Record `url`'s origin as user-approved, so later commands in this project
  * may send credentials there without re-passing `--server`.
@@ -64,16 +76,23 @@ export declare function writeGlobalConfig(configDir: string, data: GlobalConfig)
 /**
  * The credential every platform command runs on.
  *
- * Two sources, in order: the key `aai login` saved, then
- * `ASSEMBLYAI_API_KEY` for non-interactive callers (CI, scripts, the eval
- * harnesses).
+ * ONE source: the key `aai login` saved to the global config. Nothing else
+ * authenticates the CLI.
+ *
+ * There is deliberately no "paste a key" prompt and no `ASSEMBLYAI_API_KEY`
+ * fallback. Both produced the same half-configured CLI — able to push,
+ * publish, and read/write another account's secrets while linked to no
+ * account the user could see in the studio — and both made `aai login`, the
+ * real onboarding path, optional in practice. The env var was the worse of
+ * the two: it applies to every invocation in a shell, it silently PERSISTED
+ * itself into the global config on first use (so the CLI stayed authenticated
+ * as that key long after the export was gone), and it collides with the
+ * variable the same name serves in a project `.env`, where it is a *provider*
+ * credential for the local dev server rather than a platform identity.
  *
- * There is deliberately NO "paste a key" prompt. Pasting one produced a
- * half-configured CLI — able to push and publish while linked to no account
- * the user could see in the studio — and it made `aai login`, which is the
- * real onboarding path, optional in practice. It was also the riskier code
- * path: a hidden password prompt reads stdin, so a piped invocation could
- * have its input eaten and persisted as the API key.
+ * Non-interactive callers (CI, scripts, the eval harnesses) authenticate by
+ * 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 {};

package/dist/_dev-env.d.ts

@@ -0,0 +1,38 @@
+/**
+ * The dev server's CONTROL variables — the three things read straight from the
+ * shell rather than from the agent's `.env`.
+ *
+ * That distinction is the reason these live together. `resolveServerEnv` builds
+ * `ctx.env` from `.env`-declared keys only, deliberately, so an agent cannot
+ * come to depend on a shell variable that will not exist after deploy. These
+ * three are not agent config at all — they configure the *dev server process*
+ * (who may connect, where it binds, whether it restarts), so they are read from
+ * the environment on purpose and must never leak into `ctx.env`.
+ *
+ * Split out of `_dev-server.ts` purely to keep that module under the
+ * file-length cap; it is the only consumer.
+ */
+/**
+ * The env handed to `createServer` 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`).
+ */
+export declare function hostModeEnv(providerEnv: Record<string, string>): Record<string, string>;
+/**
+ * Explicit bind host for the dev server, or `undefined` to take the
+ * loopback default. An empty `AAI_DEV_HOST` means "unset", not "every
+ * interface" — Node treats `listen(port, "")` as 0.0.0.0, which would quietly
+ * undo the loopback default this exists to guard.
+ */
+export declare function devBindHost(): string | undefined;
+/**
+ * File watching is OPT-IN — `AAI_DEV_WATCH=1` turns it on.
+ *
+ * A restart rebuilds the bundle and replaces the server, which drops nothing
+ * mid-request but does end in-flight voice sessions. That is the right default
+ * while editing an agent and the wrong one while a benchmark is driving the
+ * host for twenty minutes: a stray formatter save, a `.env` touch, or a git
+ * operation restarts the server underneath the run, and the harness reports it
+ * as a provider failure several records deep.
+ */
+export declare function devWatchEnabled(): boolean;

package/dist/{_dev-server-BB5N8kdh.mjs → _dev-server-B3ivqyEd.mjs}

@@ -1,26 +1,77 @@
 #!/usr/bin/env node
-import { n as log } from "./_ui-8kOEB-JH.mjs";
-import { a as errorMessage, r as errorCode } from "./_utils-Ch0J4s6a.mjs";
-import { n as fallbackHtmlPlugin } from "./client-bundler-yiWoXrgb.mjs";
+import { n as log, r as notify } from "./_ui-DfwfDbT-.mjs";
+import { a as errorMessage, r as errorCode } from "./_utils-8KKw-bzi.mjs";
+import { n as fallbackHtmlPlugin } from "./client-bundler-DONm-khu.mjs";
 import { buildWorker } from "./worker-bundler.mjs";
-import { n as createWorkerEvaluator } from "./_bundler-Cjaxa2wi.mjs";
-import { n as ensureApiKey } from "./_config-Y5V-5Krn.mjs";
-import { t as resolveServerEnv } from "./_server-common-CnaP_Urf.mjs";
-import { createRequire } from "node:module";
+import { n as createWorkerEvaluator } from "./_bundler-DC17suWN.mjs";
+import { n as ensureApiKey } from "./_config-DMyolIk9.mjs";
+import { t as resolveServerEnv } from "./_server-common-DX8Bfrf5.mjs";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { setTimeout } from "node:timers/promises";
 import { createRuntime, createServer, requiredProviderEnvVars, withHostCredentialFallback } from "@alexkroman1/aai/runtime";
+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
+/**
+* The dev server's CONTROL variables — the three things read straight from the
+* shell rather than from the agent's `.env`.
+*
+* That distinction is the reason these live together. `resolveServerEnv` builds
+* `ctx.env` from `.env`-declared keys only, deliberately, so an agent cannot
+* come to depend on a shell variable that will not exist after deploy. These
+* three are not agent config at all — they configure the *dev server process*
+* (who may connect, where it binds, whether it restarts), so they are read from
+* the environment on purpose and must never leak into `ctx.env`.
+*
+* Split out of `_dev-server.ts` purely to keep that module under the
+* file-length cap; it is the only consumer.
+*/
+/**
+* The env handed to `createServer` 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`).
+*/
+function hostModeEnv(providerEnv) {
+	const gate = process.env.AAI_ALLOW_HOST;
+	return gate === void 0 ? providerEnv : {
+		...providerEnv,
+		AAI_ALLOW_HOST: gate
+	};
+}
+/**
+* Explicit bind host for the dev server, or `undefined` to take the
+* loopback default. An empty `AAI_DEV_HOST` means "unset", not "every
+* interface" — Node treats `listen(port, "")` as 0.0.0.0, which would quietly
+* undo the loopback default this exists to guard.
+*/
+function devBindHost() {
+	const host = process.env.AAI_DEV_HOST?.trim();
+	return host ? host : void 0;
+}
+/**
+* File watching is OPT-IN — `AAI_DEV_WATCH=1` turns it on.
+*
+* A restart rebuilds the bundle and replaces the server, which drops nothing
+* mid-request but does end in-flight voice sessions. That is the right default
+* while editing an agent and the wrong one while a benchmark is driving the
+* host for twenty minutes: a stray formatter save, a `.env` touch, or a git
+* operation restarts the server underneath the run, and the harness reports it
+* as a provider failure several records deep.
+*/
+function devWatchEnabled() {
+	return /^(1|true|yes|on)$/i.test(process.env.AAI_DEV_WATCH?.trim() ?? "");
+}
+//#endregion
 //#region _dev-server.ts
 /**
 * Dev server for directory-based agents.
 *
 * Imports agent.ts directly for the full agent definition,
-* builds a runtime, and starts an HTTP+WebSocket server. Watches for
-* file changes and restarts automatically. Optionally runs Vite for
+* builds a runtime, and starts an HTTP+WebSocket server. File watching is
+* opt-in via `AAI_DEV_WATCH=1` (see devWatchEnabled). Optionally runs Vite for
 * client SPA HMR.
 */
 /**
@@ -51,33 +102,13 @@ function agentEnvWarnings(agentDef, env, shellEnv = process.env) {
 }
 async function resolveAgentEnv(root, agentDef) {
 	const env = await resolveServerEnv(root);
-	if (requiredProviderEnvVars(agentDef).includes("ASSEMBLYAI_API_KEY") && !env.ASSEMBLYAI_API_KEY) env.ASSEMBLYAI_API_KEY = await ensureApiKey();
+	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();
 	for (const warning of agentEnvWarnings(agentDef, env)) log.warn(warning);
 	return env;
 }
 /**
-* The env handed to `createServer` 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`).
-*/
-function hostModeEnv(providerEnv) {
-	const gate = process.env.AAI_ALLOW_HOST;
-	return gate === void 0 ? providerEnv : {
-		...providerEnv,
-		AAI_ALLOW_HOST: gate
-	};
-}
-/**
-* Explicit bind host for the dev server, or `undefined` to take the
-* loopback default. An empty `AAI_DEV_HOST` means "unset", not "every
-* interface" — Node treats `listen(port, "")` as 0.0.0.0, which would quietly
-* undo the loopback default this exists to guard.
-*/
-function devBindHost() {
-	const host = process.env.AAI_DEV_HOST?.trim();
-	return host ? host : void 0;
-}
-/**
 * Load the agent definition by bundling agent.ts (and all its local imports)
 * into a single ESM file, then importing that. A raw `import(agent.ts?t=...)`
 * only cache-busts agent.ts itself — transitive imports (./tools.ts, etc.)
@@ -118,7 +149,7 @@ function isIgnoredPath(dir, filePath) {
 */
 function watchDirectory(dir, onChange) {
 	const debouncedChange = pDebounce(() => {
-		log.info("File change detected, restarting...");
+		notify("info", "File change detected, restarting...");
 		onChange();
 	}, 300);
 	const watcher = watch(dir, {
@@ -128,26 +159,15 @@ function watchDirectory(dir, onChange) {
 	});
 	watcher.on("error", (err) => {
 		const hint = errorCode(err) === "ENOSPC" ? " The inotify watch limit was reached — raise the fs.inotify max_user_watches sysctl." : "";
-		log.error(`File watcher error: ${errorMessage(err)}.${hint} Auto-restart on file changes may have stopped; restart \`aai dev\` after fixing.`);
+		notify("error", `File watcher error: ${errorMessage(err)}.${hint} Auto-restart on file changes may have stopped; restart \`aai dev\` after fixing.`);
 	});
 	watcher.on("all", () => {
 		debouncedChange().catch((err) => {
-			log.error(`Watch handler failed: ${errorMessage(err)}`);
+			notify("error", `Watch handler failed: ${errorMessage(err)}`);
 		});
 	});
 	return watcher;
 }
-/** Locate the pre-built default aai-ui client (served when no custom client.tsx). */
-function resolveDefaultClientDir() {
-	const require = createRequire(import.meta.url);
-	let pkgPath;
-	try {
-		pkgPath = require.resolve("@alexkroman1/aai-ui/package.json");
-	} catch (err) {
-		throw new Error(`Could not locate the default client UI (${errorMessage(err)}) — is @alexkroman1/aai-ui installed? Try reinstalling dependencies (pnpm install).`, { cause: err });
-	}
-	return path.join(path.dirname(pkgPath), "dist", "default-client");
-}
 /**
 * Vite dev-server config for the client SPA. Extracted so the proxy wiring
 * is unit-testable: `/websocket` MUST proxy with `ws: true` or `aai dev`
@@ -186,7 +206,7 @@ async function startDevServer(opts) {
 	const hasClient = existsSync(path.join(cwd, "client.tsx"));
 	const backendPort = hasClient ? await getPort({ port: portNumbers(port + 1, port + 100) }) : port;
 	const vitePort = port;
-	const clientDirOpt = hasClient ? {} : { clientDir: resolveDefaultClientDir() };
+	const clientDirOpt = hasClient ? {} : { clientDir: defaultClientDir() };
 	const evaluateWorker = createWorkerEvaluator();
 	/** Full build sequence, shared by initial startup and every restart. */
 	async function buildServer() {
@@ -217,12 +237,12 @@ async function startDevServer(opts) {
 		}
 		restarting = true;
 		restart().catch((err) => {
-			log.error(`Restart failed: ${errorMessage(err)}`);
+			notify("error", `Restart failed: ${errorMessage(err)}`);
 		}).finally(() => {
 			restarting = false;
 		});
 	}
-	const watcher = watchDirectory(cwd, kickRestart);
+	const watcher = devWatchEnabled() ? watchDirectory(cwd, kickRestart) : void 0;
 	let viteServer;
 	try {
 		currentServer = await buildServer();
@@ -232,11 +252,11 @@ async function startDevServer(opts) {
 			viteServer = await createViteServer(viteDevConfig(cwd, vitePort, backendPort));
 			await viteServer.listen();
 			viteServer.httpServer?.on("error", (err) => {
-				log.error(`Vite dev server error: ${errorMessage(err)}`);
+				notify("error", `Vite dev server error: ${errorMessage(err)}`);
 			});
 		}
 	} catch (err) {
-		await watcher.close().catch(() => void 0);
+		await watcher?.close().catch(() => void 0);
 		await viteServer?.close().catch(() => void 0);
 		throw err;
 	}
@@ -253,7 +273,7 @@ async function startDevServer(opts) {
 		try {
 			newServer = await buildServer();
 		} catch (err) {
-			log.error(`Restart failed: ${errorMessage(err)} (previous server still running)`);
+			notify("error", `Restart failed: ${errorMessage(err)} (previous server still running)`);
 			return;
 		}
 		if (closed) {
@@ -270,9 +290,9 @@ async function startDevServer(opts) {
 				await newServer.close().catch(() => void 0);
 				return;
 			}
-			log.success("Restarted");
+			notify("success", "Restarted");
 		} catch (err) {
-			log.error(`Restart failed: ${errorMessage(err)} — dev server is down; save a file to retry.`);
+			notify("error", `Restart failed: ${errorMessage(err)} — dev server is down; save a file to retry.`);
 			await newServer.close().catch(() => void 0);
 		}
 	}
@@ -297,7 +317,7 @@ async function startDevServer(opts) {
 	return () => {
 		cleanupPromise ??= (async () => {
 			closed = true;
-			await watcher.close().catch(() => void 0);
+			await watcher?.close().catch(() => void 0);
 			await viteServer?.close().catch(() => void 0);
 			await currentServer.close().catch(() => void 0);
 		})();

package/dist/_dev-server.d.ts

@@ -2,8 +2,8 @@
  * Dev server for directory-based agents.
  *
  * Imports agent.ts directly for the full agent definition,
- * builds a runtime, and starts an HTTP+WebSocket server. Watches for
- * file changes and restarts automatically. Optionally runs Vite for
+ * builds a runtime, and starts an HTTP+WebSocket server. File watching is
+ * opt-in via `AAI_DEV_WATCH=1` (see devWatchEnabled). Optionally runs Vite for
  * client SPA HMR.
  */
 import type { AgentDef } from "@alexkroman1/aai";

package/dist/{_init-Dei2JRmn.mjs → _init-CYLvYU-B.mjs}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { c as readJson, d as writeJson, s as isEexist } from "./_utils-Ch0J4s6a.mjs";
-import { r as isDevMode, t as getMonorepoRoot } from "./_agent-2nVugrN3.mjs";
-import { REPO_URL, downloadAndMergeTemplate } from "./_templates-BfyRyE7z.mjs";
+import { c as readJson, d as writeJson, s as isEexist } from "./_utils-8KKw-bzi.mjs";
+import { r as isDevMode, t as getMonorepoRoot } from "./_agent-DS2PUJcl.mjs";
+import { REPO_URL, downloadAndMergeTemplate } from "./_templates-BWJOiWOO.mjs";
 import path from "node:path";
 import fs from "node:fs/promises";
 //#region _init.ts