@alexkroman1/aai-cli 5.1.0 → 5.2.0

package/dist/{_agent-D39qatZJ.mjs → _agent-D8zBb3M5.mjs}

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as serverOrigin, i as readProjectConfig, n as ensureApiKey, r as readGlobalConfig, t as approveServer } from "./_config-Czjhvaax.mjs";
+import { a as serverOrigin, i as readProjectConfig, n as ensureApiKey, r as readGlobalConfig, t as approveServer } from "./_config-D3F9km8X.mjs";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -71,8 +71,7 @@ function resolveServerUrl(explicit, configUrl, approvedOrigins = []) {
 * the project has never been deployed), server URL, and API key.
 */
 async function resolveDeployTarget(cwd, explicitServer) {
-	const config = await readProjectConfig(cwd);
-	const globalConfig = await readGlobalConfig();
+	const [config, globalConfig] = await Promise.all([readProjectConfig(cwd), readGlobalConfig()]);
 	const serverUrl = resolveServerUrl(explicitServer, config?.serverUrl, globalConfig.approvedServers ?? []);
 	if (explicitServer) await approveServer(serverUrl);
 	return {

package/dist/_agent.d.ts

@@ -0,0 +1,39 @@
+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;
+export declare function isDevMode(): boolean;
+/**
+ * Resolve which platform server to talk to.
+ *
+ * Precedence: an explicit `--server` flag, then dev mode, then the project
+ * config, then the shipped default.
+ *
+ * `configUrl` comes from `.aai/project.json` — a file in the working tree, so
+ * a cloned repo controls it. Because callers pair this URL with the user's API
+ * key (and, for `aai secret`, with secret values), a config-supplied origin is
+ * only honored when it is implicitly trusted or previously approved by the
+ * user via `--server`. Otherwise a repo could redirect a credentialed request
+ * to a host of its choosing simply by shipping a `project.json`, and
+ * `aai deploy` would hand over the developer's key on first run.
+ *
+ * @param approvedOrigins - Origins from the user-owned global config.
+ */
+export declare function resolveServerUrl(explicit?: string, configUrl?: string, approvedOrigins?: readonly string[]): string;
+/**
+ * Resolve everything needed to talk to the platform: project config (null if
+ * the project has never been deployed), server URL, and API key.
+ */
+export declare function resolveDeployTarget(cwd: string, explicitServer?: string): Promise<{
+    config: {
+        slug: string;
+        serverUrl: string;
+    } | null;
+    serverUrl: string;
+    apiKey: string;
+}>;
+/** Like resolveDeployTarget, but requires an existing deployment (project config). */
+export declare function getServerInfo(cwd: string, explicitServer?: string): Promise<{
+    serverUrl: string;
+    slug: string;
+    apiKey: string;
+}>;

package/dist/{_api-client-a6cPMebU.mjs → _api-client-MenP4-O7.mjs}

@@ -9,6 +9,8 @@ import { FetchError, ofetch } from "ofetch";
 * 5xx/429) are retried before surfacing an error.
 */
 const HINT_INVALID_API_KEY = "Your API key may be invalid. Run `aai` to re-enter your AssemblyAI API key.";
+/** 404 hint for requests scoped to a deployed agent's slug. */
+const HINT_NOT_DEPLOYED = "The agent may not be deployed. Check `.aai/project.json` for the correct slug.";
 /**
 * Send an authenticated request to the platform API and return the parsed
 * JSON response. Throws a descriptive error with status-specific hints on
@@ -44,4 +46,4 @@ function toApiError(err, url, opts) {
 	return new Error(`${opts.action} failed: could not reach ${url}\n  ${hint}`, { cause });
 }
 //#endregion
-export { apiRequest as t };
+export { apiRequest as n, HINT_NOT_DEPLOYED as t };

package/dist/_api-client.d.ts

@@ -0,0 +1,37 @@
+export declare const HINT_INVALID_API_KEY = "Your API key may be invalid. Run `aai` to re-enter your AssemblyAI API key.";
+/** 404 hint for requests scoped to a deployed agent's slug. */
+export declare const HINT_NOT_DEPLOYED = "The agent may not be deployed. Check `.aai/project.json` for the correct slug.";
+export type ApiRequestOptions = {
+    apiKey: string;
+    /** Verb used in error messages, e.g. "deploy". */
+    action: string;
+    method?: "GET" | "POST" | "PUT" | "DELETE";
+    /**
+     * Request body. Plain objects are JSON-serialized by ofetch (with
+     * Content-Type set); binary bodies (e.g. a pre-gzipped Buffer) pass
+     * through untouched — set Content-Type/Content-Encoding via `headers`.
+     */
+    body?: unknown;
+    /** Extra request headers, merged with the built-in Authorization header. */
+    headers?: Record<string, string>;
+    /** Extra error hints keyed by HTTP status. The 401 hint is built in. */
+    hints?: Record<number, string>;
+    /**
+     * Transient-failure retry count (default 2). Pass 0 for requests that are
+     * not idempotent server-side — a retry of a request that succeeded but lost
+     * its response would perform the action twice (e.g. a first deploy with no
+     * slug creates a fresh agent per attempt).
+     */
+    retry?: number;
+    /** Delay between retries in ms (default 300). Tests pass 0 so retry-path
+     * assertions don't sleep real wall-clock time. */
+    retryDelay?: number;
+    /** Optional fetch implementation for testing. Defaults to globalThis.fetch. */
+    fetch?: typeof globalThis.fetch;
+};
+/**
+ * Send an authenticated request to the platform API and return the parsed
+ * JSON response. Throws a descriptive error with status-specific hints on
+ * failure (the 401 hint is always included; pass more via `hints`).
+ */
+export declare function apiRequest<T = unknown>(url: string, opts: ApiRequestOptions): Promise<T>;

package/dist/{_bundler-DdmuZzeR.mjs → _bundler-DFS4xxqE.mjs}

@@ -1,7 +1,6 @@
 #!/usr/bin/env node
-import { n as log, u as ok } from "./_ui-DXZ9prrM.mjs";
-import { c as validateAgentExport } from "./_utils-C502jKo8.mjs";
-import { t as buildClient } from "./client-bundler-DO3GgO6p.mjs";
+import { u as validateAgentExport } from "./_utils-Ch0J4s6a.mjs";
+import { t as buildClient } from "./client-bundler-BWDkUeEP.mjs";
 import { buildWorker } from "./worker-bundler.mjs";
 import path from "node:path";
 import { pathToFileURL } from "node:url";
@@ -79,14 +78,5 @@ function createWorkerEvaluator() {
 		return agentDef;
 	};
 }
-async function executeBuild(cwd) {
-	const bundle = await buildAgentBundle(cwd, { minify: true });
-	const agentDef = await evalWorkerBundle(bundle.worker);
-	log.success("Build complete");
-	return ok({
-		name: agentDef.name,
-		workerBytes: bundle.worker.length
-	});
-}
 //#endregion
-export { buildAgentBundle, createWorkerEvaluator, executeBuild };
+export { createWorkerEvaluator as n, evalWorkerBundle as r, buildAgentBundle as t };

package/dist/_bundler.d.ts

@@ -0,0 +1,46 @@
+import type { AgentDef } from "@alexkroman1/aai";
+import { type BuildWorkerOptions } from "./worker-bundler.ts";
+/** Output from the bundler: worker ESM + client files. */
+export type DirectoryBundleOutput = {
+    /** ESM bundle of agent.ts (tool execute functions + hook handlers). */
+    worker: string;
+    /** Static client files from Vite build. Empty if no client.tsx. */
+    clientFiles: Record<string, string>;
+};
+/**
+ * Bundle an agent directory: build agent.ts into worker ESM + client files.
+ *
+ * agent.ts is the single entry point: `export default agent({...})`. The
+ * worker self-describes (it exports `__aaiConfig` — see `worker-bundler.ts`),
+ * so nothing here evaluates the bundle: the server extracts the config inside
+ * a guest sandbox at deploy time.
+ */
+export declare function buildAgentBundle(cwd: string, opts?: BuildWorkerOptions): Promise<DirectoryBundleOutput>;
+/**
+ * Import the worker ESM from a uniquely named temp file and return the
+ * AgentDef default export. A real `file:` URL, not a `data:` URL: deploy
+ * bundles ship the SDK runtime, whose CJS interop calls
+ * `createRequire(import.meta.url)` — which rejects anything that isn't a
+ * file URL or absolute path. (The guest harness imports bundles the same
+ * way, for the same reason.) The file is removed after import; the module
+ * lives on in memory.
+ *
+ * Each call imports a unique URL, and Node's ESM registry never evicts — so
+ * every call retains one bundle for the process lifetime. That is fine for
+ * one-shot commands (`aai build`); long-lived callers must go through
+ * `createWorkerEvaluator` to at least dedupe identical builds. Evaluating in
+ * a discardable context is not an option: tool `execute` functions from the
+ * returned AgentDef are called in-process by the dev runtime, which rules
+ * out worker threads, and `node:vm` ESM evaluation is still flagged
+ * experimental.
+ */
+export declare function evalWorkerBundle(code: string): Promise<AgentDef>;
+/**
+ * Memoizing wrapper around `evalWorkerBundle` for long-lived callers (the
+ * dev server): byte-identical worker code returns the previously evaluated
+ * AgentDef without touching the ESM registry. No-op saves and formatter
+ * churn are the common watcher events, so this caps the registry leak (see
+ * `evalWorkerBundle`) to genuinely-new bundles — the residual one-module-per-
+ * distinct-build leak is accepted for the reasons documented there.
+ */
+export declare function createWorkerEvaluator(): (code: string) => Promise<AgentDef>;

package/dist/{_config-Czjhvaax.mjs → _config-D3F9km8X.mjs}

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { a as unwrapCancel, n as log, o as CliError } from "./_ui-DXZ9prrM.mjs";
-import { l as writeJson, o as readJson, r as errorMessage } from "./_utils-C502jKo8.mjs";
+import { a as unwrapCancel, n as log, o as CliError } from "./_ui-8kOEB-JH.mjs";
+import { a as errorMessage, c as readJson, d as writeJson } from "./_utils-Ch0J4s6a.mjs";
 import path from "node:path";
 import * as p from "@clack/prompts";
 import envPaths from "env-paths";
@@ -116,7 +116,7 @@ async function ensureApiKey(configDir) {
 		return envKey;
 	}
 	if (!process.stdin.isTTY) throw new CliError("no_api_key", "No API key configured and no TTY to prompt for one.", "Set the ASSEMBLYAI_API_KEY environment variable, or run `aai` interactively once to save a key.");
-	const apiKey = unwrapCancel(await p.password({ message: "Enter your AssemblyAI API key" }));
+	const apiKey = unwrapCancel(await p.password({ message: "Enter your AssemblyAI API key" }), "Setup cancelled");
 	await trySaveApiKey(dir, config, apiKey);
 	return apiKey;
 }

package/dist/_config.d.ts

@@ -0,0 +1,57 @@
+import { z } from "zod";
+/**
+ * `.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.
+ */
+declare const ProjectConfigSchema: z.ZodObject<{
+    slug: z.ZodString;
+    serverUrl: z.ZodString;
+}, z.core.$strip>;
+/**
+ * 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.
+ */
+export declare function getConfigDir(): string;
+export type ProjectConfig = z.infer<typeof ProjectConfigSchema>;
+export declare function readProjectConfig(agentDir: string): Promise<ProjectConfig | null>;
+export declare function writeProjectConfig(agentDir: string, data: ProjectConfig): Promise<void>;
+export type GlobalConfig = {
+    apiKey?: string;
+    /**
+     * Origins the user has explicitly pointed the CLI at with `--server`.
+     *
+     * Lives in the user-owned global config, never in the repo: it is what makes
+     * a `serverUrl` from `.aai/project.json` trustworthy enough to receive an
+     * API key. See `resolveServerUrl`.
+     */
+    approvedServers?: string[];
+};
+/**
+ * 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.
+ */
+export declare function serverOrigin(url: string): string | null;
+/**
+ * Record `url`'s origin as user-approved, so later commands in this project
+ * may send credentials there without re-passing `--server`.
+ */
+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>;
+export declare function ensureApiKey(configDir?: string): Promise<string>;
+export {};

package/dist/_default-html.d.ts

@@ -0,0 +1,12 @@
+import type { Plugin } from "vite";
+export declare const DEFAULT_HTML = "<!DOCTYPE html>\n<html lang=\"en\">\n  <head>\n    <meta charset=\"UTF-8\" />\n    <meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0, viewport-fit=cover\" />\n    <title>aai</title>\n    <link rel=\"icon\" href=\"./favicon.ico\" />\n    <style>html, body { background: #FBF8F2; margin: 0; }</style>\n  </head>\n  <body>\n    <main id=\"app\"></main>\n    <script type=\"module\" src=\"./client.tsx\"></script>\n  </body>\n</html>";
+/**
+ * Vite plugin that serves a fallback index.html in dev mode when one doesn't
+ * exist on disk. No-op if index.html exists (user override).
+ */
+export declare function fallbackHtmlPlugin(root: string): Plugin;
+/**
+ * Write a temporary index.html for Vite build (HTML must be on disk for build).
+ * Returns a cleanup function to remove it. No-op if index.html already exists.
+ */
+export declare function writeTempHtml(root: string): () => void;

package/dist/_deploy.d.ts

@@ -0,0 +1,28 @@
+import type { DirectoryBundleOutput } from "./_bundler.ts";
+export type DeployOpts = {
+    url: string;
+    bundle: DirectoryBundleOutput;
+    /** Env var values from .env to send to the server. */
+    env: Record<string, string>;
+    /** Existing slug for redeployment. Omit for first deploy — server generates one. */
+    slug?: string;
+    apiKey: string;
+    /**
+     * Ask the server to WARN (in `warnings`) instead of rejecting when the
+     * agent's providers are missing credentials — `aai deploy
+     * --allow-missing-secrets`, for setting them post-deploy with
+     * `aai secret put` (the studio's publish flow relies on this: its Secrets
+     * panel needs a deployed slug to attach secrets to).
+     */
+    allowMissingSecrets?: boolean;
+    /** Retry delay override for tests (0 = no real sleeps on retry paths). */
+    retryDelay?: number;
+    /** Optional fetch implementation for testing. Defaults to globalThis.fetch. */
+    fetch?: typeof globalThis.fetch;
+};
+export type DeployResult = {
+    slug: string;
+    /** Server-side deploy warnings (e.g. the missing-credential preflight). */
+    warnings?: string[];
+};
+export declare function runDeploy(opts: DeployOpts): Promise<DeployResult>;

package/dist/{_dev-server-BCbEUhmv.mjs → _dev-server-BBUWo0sb.mjs}

@@ -1,16 +1,16 @@
 #!/usr/bin/env node
-import { n as log } from "./_ui-DXZ9prrM.mjs";
-import { r as errorMessage, t as errorCode } from "./_utils-C502jKo8.mjs";
-import { n as fallbackHtmlPlugin } from "./client-bundler-DO3GgO6p.mjs";
+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-BWDkUeEP.mjs";
 import { buildWorker } from "./worker-bundler.mjs";
-import { createWorkerEvaluator } from "./_bundler-DdmuZzeR.mjs";
-import { n as ensureApiKey } from "./_config-Czjhvaax.mjs";
-import { t as resolveServerEnv } from "./_server-common-B75oco06.mjs";
+import { n as createWorkerEvaluator } from "./_bundler-DFS4xxqE.mjs";
+import { n as ensureApiKey } from "./_config-D3F9km8X.mjs";
+import { t as resolveServerEnv } from "./_server-common-CnaP_Urf.mjs";
 import { createRequire } from "node:module";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { setTimeout } from "node:timers/promises";
-import { requiredProviderEnvVars, withHostCredentialFallback } from "@alexkroman1/aai/runtime";
+import { createRuntime, createServer, requiredProviderEnvVars, withHostCredentialFallback } from "@alexkroman1/aai/runtime";
 import { watch } from "chokidar";
 import getPort, { portNumbers } from "get-port";
 import pDebounce from "p-debounce";
@@ -183,7 +183,6 @@ function viteDevConfig(cwd, vitePort, backendPort) {
 */
 async function startDevServer(opts) {
 	const { cwd, port } = opts;
-	const { createRuntime, createServer } = await import("@alexkroman1/aai/runtime");
 	const hasClient = existsSync(path.join(cwd, "client.tsx"));
 	const backendPort = hasClient ? await getPort({ port: portNumbers(port + 1, port + 100) }) : port;
 	const vitePort = port;
@@ -194,13 +193,12 @@ async function startDevServer(opts) {
 		const agentDef = await loadAgentDef(cwd, evaluateWorker);
 		const env = await resolveAgentEnv(cwd, agentDef);
 		const providerEnv = withHostCredentialFallback(env);
-		const runtime = createRuntime({
-			agent: agentDef,
-			env,
-			providerEnv
-		});
 		return createServer({
-			runtime,
+			runtime: createRuntime({
+				agent: agentDef,
+				env,
+				providerEnv
+			}),
 			name: agentDef.name,
 			env: hostModeEnv(providerEnv),
 			hostBaseAgent: agentDef,

package/dist/_dev-server.d.ts

@@ -0,0 +1,74 @@
+/**
+ * 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
+ * client SPA HMR.
+ */
+import type { AgentDef } from "@alexkroman1/aai";
+import { type FSWatcher } from "chokidar";
+/**
+ * Warnings about the agent's credentials, computed against the `.env`-derived
+ * env and the shell. Pure so it is directly testable; `resolveAgentEnv` logs
+ * each entry. Three cases, in increasing subtlety:
+ *
+ * - a provider key found nowhere → the first session will fail auth;
+ * - a provider key found only in the shell → works here (the
+ *   `withHostCredentialFallback` ergonomic) but is invisible to `aai deploy`,
+ *   which uploads `.env` — the classic "works locally, dead on deploy";
+ * - a declared `requiredEnv` key absent from `.env` → `ctx.env` won't contain
+ *   it at all: custom keys never fall back to the shell, so a shell export
+ *   can't mask one that would be missing both here and after deploy.
+ */
+export declare function agentEnvWarnings(agentDef: Pick<AgentDef, "stt" | "llm" | "tts" | "s2s" | "requiredEnv">, env: Record<string, string>, shellEnv?: Record<string, string | undefined>): string[];
+/**
+ * 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.)
+ * stay in Node's ESM registry, so edits to them are ignored on reload.
+ * Bundling picks them up.
+ *
+ * The bundle comes from the same Vite pass deploy runs (`buildWorker`), so
+ * dev and deploy can't drift; a warm rebuild is well under 100ms. Compile
+ * errors in the agent's code propagate — the restart loop reports them and
+ * keeps the old server. Evaluation goes through the memoizing evaluator so
+ * a no-op save doesn't leak another module into the ESM registry.
+ */
+export declare function loadAgentDef(cwd: string, evaluate: (code: string) => Promise<AgentDef>): Promise<AgentDef>;
+/**
+ * True for paths that should never trigger a restart: anything inside
+ * `node_modules/` and any dot-entry (`.git/`, `.aai/`, `.DS_Store`, …).
+ * `.git/` especially matters — commits and status checks churn the index
+ * and would otherwise cause spurious full backend restarts.
+ *
+ * Exception: `.env` / `.env.*` files stay watched — env edits should
+ * restart the server with the new values.
+ */
+export declare function isIgnoredPath(dir: string, filePath: string): boolean;
+/**
+ * Watch the agent directory for changes and call `onChange` when detected.
+ * Debounces to avoid rapid restarts. Uses chokidar for reliable recursive
+ * watching across platforms (raw `fs.watch` misses events on Linux).
+ */
+export declare function watchDirectory(dir: string, onChange: () => void): FSWatcher;
+export type DevServerOptions = {
+    cwd: string;
+    port: number;
+};
+/**
+ * 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`
+ * with a `client.tsx` serves a page whose WebSocket never connects.
+ *
+ * `strictPort` because the reported URL is `http://localhost:<port>` —
+ * without it, Vite silently binds port+N when the port is busy and the
+ * printed/JSON-returned URL points at whatever else was listening.
+ */
+export declare function viteDevConfig(cwd: string, vitePort: number, backendPort: number): import("vite").InlineConfig;
+/**
+ * Start the dev server for a directory-based agent.
+ *
+ * Returns a cleanup function to shut down the server and watchers.
+ */
+export declare function startDevServer(opts: DevServerOptions): Promise<() => Promise<void>>;

package/dist/{_init-H-lw7czL.mjs → _init-DU-sXH6S.mjs}

@@ -1,85 +1,67 @@
 #!/usr/bin/env node
-import { a as isEexist, l as writeJson, o as readJson, r as errorMessage } from "./_utils-C502jKo8.mjs";
-import { r as isDevMode, t as getMonorepoRoot } from "./_agent-D39qatZJ.mjs";
+import { a as errorMessage, c as readJson, d as writeJson, s as isEexist } from "./_utils-Ch0J4s6a.mjs";
+import { r as isDevMode, t as getMonorepoRoot } from "./_agent-D8zBb3M5.mjs";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import fs from "node:fs/promises";
-import os from "node:os";
-import { downloadTemplate } from "giget";
-//#region _templates.ts
-const GIGET_SOURCE = "github:alexkroman/agent/packages/aai-templates";
-const GIGET_REF = process.env.AAI_TEMPLATES_REF ?? "main";
-const VALID_REF_RE = /^[\w./-]+$/;
-const noCleanup = async () => void 0;
-/** Resolve the templates directory — local in dev, giget download in prod. */
-async function resolveTemplatesDir() {
-	if (process.env.AAI_TEMPLATES_DIR) return {
-		root: process.env.AAI_TEMPLATES_DIR,
-		cleanup: noCleanup
-	};
+const REPO_URL = `https://github.com/alexkroman/agent`;
+/**
+* Templates as shipped inside the published tarball, copied into `dist/` by
+* `bundle-templates.mjs` at build time — so this resolves to `dist/` for a
+* published CLI and to the (template-less) package root when running source
+* in the monorepo, where the branch above wins.
+*
+* They used to be fetched at `init` time with giget from
+* `github:alexkroman/agent/packages/aai-templates#main`. That required a
+* network for every `init`, and pinned templates to `main` regardless of the
+* CLI version the user had installed, so a template written against a newer
+* SDK could land in a project resolving an older one. Bundling pins the two
+* together by construction. It also puts the templates inside the studio's
+* guest sandbox, which has the CLI in its baked toolchain but no way to fetch
+* anything from GitHub.
+*/
+function bundledTemplatesDir() {
+	return import.meta.dirname;
+}
+/** Resolve the templates root — env override, then monorepo, then bundled. */
+function resolveTemplatesDir() {
+	const override = process.env.AAI_TEMPLATES_DIR;
+	if (override) return override;
 	const monorepoRoot = getMonorepoRoot();
-	if (monorepoRoot) return {
-		root: path.join(monorepoRoot, "packages", "aai-templates"),
-		cleanup: noCleanup
-	};
-	if (!VALID_REF_RE.test(GIGET_REF)) throw new Error(`Invalid AAI_TEMPLATES_REF: ${JSON.stringify(GIGET_REF)} is not a git ref.`);
-	const extractDir = await fs.mkdtemp(path.join(os.tmpdir(), "aai-templates-"));
-	const cleanup = async () => {
-		await fs.rm(extractDir, {
-			recursive: true,
-			force: true
-		}).catch(() => void 0);
-	};
-	try {
-		const { dir } = await downloadTemplate(`${GIGET_SOURCE}#${GIGET_REF}`, {
-			dir: extractDir,
-			force: true,
-			forceClean: true
-		});
-		return {
-			root: dir,
-			cleanup
-		};
-	} catch (err) {
-		await cleanup();
-		throw new Error(`Failed to download templates from ${GIGET_SOURCE}#${GIGET_REF}: ${errorMessage(err)}`, { cause: err });
-	}
+	if (monorepoRoot) return path.join(monorepoRoot, "packages", "aai-templates");
+	return bundledTemplatesDir();
 }
 /**
-* Download a template into targetDir, merging scaffold files underneath.
+* Copy a template into targetDir, merging scaffold files underneath.
 */
 async function downloadAndMergeTemplate(template, targetDir) {
-	const { root, cleanup } = await resolveTemplatesDir();
+	const root = resolveTemplatesDir();
+	const templatesDir = path.join(root, "templates");
+	let available;
 	try {
-		const templatesDir = path.join(root, "templates");
-		let available;
-		try {
-			available = await fs.readdir(templatesDir, { withFileTypes: true });
-		} catch (err) {
-			throw new Error(`Templates directory is missing or unreadable at ${templatesDir} (corrupt or incomplete template download?): ${errorMessage(err)}`, { cause: err });
-		}
-		const names = available.filter((e) => e.isDirectory()).map((e) => e.name);
-		if (!names.includes(template)) throw new Error(`Unknown template "${template}". Available templates: ${names.join(", ")}`);
-		await fs.cp(path.join(templatesDir, template), targetDir, {
-			recursive: true,
-			force: true
-		});
-		const scaffoldDir = path.join(root, "scaffold");
-		if (existsSync(scaffoldDir)) await fs.cp(scaffoldDir, targetDir, {
-			recursive: true,
-			force: false,
-			errorOnExist: false
-		});
-	} finally {
-		await cleanup();
+		available = await fs.readdir(templatesDir, { withFileTypes: true });
+	} catch (err) {
+		throw new Error(`Templates directory is missing or unreadable at ${templatesDir} (incomplete @alexkroman1/aai-cli install?): ${errorMessage(err)}`, { cause: err });
 	}
+	const names = available.filter((e) => e.isDirectory()).map((e) => e.name);
+	if (!names.includes(template)) throw new Error(`Unknown template "${template}". Available templates: ${names.join(", ")}`);
+	await fs.cp(path.join(templatesDir, template), targetDir, {
+		recursive: true,
+		force: true
+	});
+	const scaffoldDir = path.join(root, "scaffold");
+	if (existsSync(scaffoldDir)) await fs.cp(scaffoldDir, targetDir, {
+		recursive: true,
+		force: false,
+		errorOnExist: false
+	});
 }
 //#endregion
 //#region _init.ts
 function readmeContent(slug) {
 	return `# ${slug}
 
-A voice agent built with [aai](https://github.com/anthropics/aai).
+A voice agent built with [aai](${REPO_URL}).
 
 ## Getting started
 

package/dist/_init.d.ts

@@ -0,0 +1,7 @@
+export type InitOptions = {
+    targetDir: string;
+    template: string;
+};
+/** Rewrite workspace deps to link: paths so pnpm links to local source. */
+export declare function patchPackageJsonForWorkspace(targetDir: string): Promise<void>;
+export declare function runInit(opts: InitOptions): Promise<void>;

package/dist/_mock-api.d.ts

@@ -0,0 +1,22 @@
+export interface RecordedRequest {
+    method: string;
+    path: string;
+    headers: Record<string, string | string[] | undefined>;
+    /** Decoded body text (inflated first when sent with Content-Encoding: gzip). */
+    body: string;
+}
+export interface MockApi {
+    /** Base URL of the mock server (http://localhost:<port>) */
+    url: string;
+    /** All recorded requests */
+    requests: RecordedRequest[];
+    /** Secrets currently stored */
+    secrets: Record<string, string>;
+    /** Override response for a specific method+path pattern */
+    override(method: string, pathPattern: string, status: number, body?: string): void;
+    /** Clear recorded requests */
+    clear(): void;
+    /** Stop the server */
+    stop(): Promise<void>;
+}
+export declare function startMockApi(): Promise<MockApi>;

package/dist/_mock-registry.d.ts

@@ -0,0 +1,17 @@
+export interface MockRegistry {
+    /** Local registry URL (http://localhost:<port>) */
+    registryUrl: string;
+    /** The unique version string used for published workspace packages */
+    testVersion: string;
+    /** Environment variables to set for child processes using this registry */
+    env: Record<string, string>;
+    /** Stop the registry and clean up */
+    stop: () => Promise<void>;
+}
+/**
+ * Start a mock npm registry, build and publish workspace packages to it.
+ *
+ * @param packagesDir - Path to the `packages/` directory in the monorepo
+ * @param packageNames - Directory names under `packages/` to publish (e.g. ["aai", "aai-ui", "aai-cli"])
+ */
+export declare function startMockRegistry(packagesDir: string, packageNames: string[]): Promise<MockRegistry>;