@alexkroman1/aai-cli 5.1.1 → 5.2.0

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.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.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.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.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-B-LEVTHx.mjs → _init-DU-sXH6S.mjs}

@@ -4,78 +4,57 @@ 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
-/** The GitHub repo (owner/name) that hosts this project and its templates. */
-const REPO = "alexkroman/agent";
-const REPO_URL = `https://github.com/${REPO}`;
-const GIGET_SOURCE = `github:${REPO}/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

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>;

package/dist/_output.d.ts

@@ -0,0 +1,50 @@
+/**
+ * Structured output support for CLI commands.
+ *
+ * In JSON mode (non-TTY or --json), commands emit exactly one JSON line to
+ * stdout. In human mode (TTY, default), commands use @clack/prompts as before.
+ */
+export type OutputMode = "json" | "human";
+export type CommandResult<T> = {
+    ok: true;
+    data: T;
+} | {
+    ok: false;
+    error: string;
+    code: string;
+    hint?: string;
+};
+/**
+ * Determine output mode from CLI flags and TTY state.
+ *
+ * Priority: --json flag > --no-json flag > TTY auto-detection.
+ */
+export declare function getOutputMode(args: {
+    json?: boolean | undefined;
+}, isTTY?: boolean): OutputMode;
+/**
+ * Write a line to stdout, resolving only once it has been flushed.
+ *
+ * Resolves (never rejects) even when the write fails: the common failure is
+ * EPIPE — the consumer closed the pipe (`aai … --json | head -1`) — and there
+ * is nothing useful to do about a broken stdout except carry on and exit.
+ * Stream-level `'error'` events are handled by {@link installStdoutGuard}.
+ */
+export declare function writeLine(line: string): Promise<void>;
+/**
+ * Install an `'error'` listener on stdout so a broken pipe doesn't crash the
+ * CLI with an unhandled `'error'` event. EPIPE (consumer went away, e.g.
+ * `aai … --json | head -1`) exits quietly; anything else is reported on
+ * stderr and exits non-zero.
+ */
+export declare function installStdoutGuard(stream?: NodeJS.WriteStream): void;
+/** Create an ok result. */
+export declare function ok<T>(data: T): CommandResult<T>;
+/** Create an error result. */
+export declare function fail<T>(code: string, error: string, hint?: string): CommandResult<T>;
+/** Typed CLI error that carries a structured error code and optional hint. */
+export declare class CliError extends Error {
+    readonly code: string;
+    readonly hint?: string | undefined;
+    constructor(code: string, message: string, hint?: string, options?: ErrorOptions);
+}

package/dist/_server-common.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Build the `ctx.env` record that agent tools will see at runtime.
+ *
+ * Only variables explicitly declared in `.env` are included — matching
+ * the platform sandbox behavior where `ctx.env`
+ * contains only secrets set via `aai secret put`. This prevents agents
+ * from accidentally depending on shell-level vars (PATH, HOME, etc.) that
+ * won't exist in production.
+ *
+ * Values are resolved by merging the `.env` file with the current
+ * environment — existing shell exports take precedence over `.env`
+ * defaults, without mutating `process.env`.
+ *
+ * @param cwd - Project directory containing `.env` (optional).
+ * @param baseEnv - Override the environment to read values from (tests only).
+ */
+export declare function resolveServerEnv(cwd?: string, baseEnv?: Record<string, string | undefined>): Promise<Record<string, string>>;

package/dist/_slug-api.d.ts

@@ -0,0 +1,15 @@
+import { type ApiRequestOptions } from "./_api-client.ts";
+/**
+ * Authenticated request against a deployed agent's slug-scoped resource
+ * (`${serverUrl}/${slug}${resourcePath}`) — the one shape every per-agent
+ * command (secret, storage) shares, including the standard "not deployed"
+ * 404 hint.
+ *
+ * Its own module (rather than living beside `getServerInfo` in `_agent.ts`)
+ * so tests can mock `_agent.ts`/`_api-client.ts` while this composition
+ * stays real — an intra-module call would bypass those mocks.
+ */
+export declare function slugRequest<T = unknown>(cwd: string, resourcePath: string, init: Pick<ApiRequestOptions, "method" | "body" | "action">, server?: string): Promise<{
+    data: T;
+    slug: string;
+}>;

package/dist/_templates.d.ts

@@ -0,0 +1,21 @@
+export declare 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.
+ */
+export declare function bundledTemplatesDir(): string;
+/**
+ * Copy a template into targetDir, merging scaffold files underneath.
+ */
+export declare function downloadAndMergeTemplate(template: string, targetDir: string): Promise<void>;

package/dist/_typecheck-gate.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The build/deploy typecheck gate: run the project's own `tsc --noEmit`
+ * (see `typecheck.ts`) and turn a failure into a structured CliError. The
+ * bundlers strip types unchecked, so without this a type-broken agent
+ * ships and misbehaves at runtime instead of failing here.
+ */
+export declare function assertTypechecks(cwd: string): Promise<void>;

package/dist/_ui.d.ts

@@ -0,0 +1,22 @@
+import * as p from "@clack/prompts";
+type Log = typeof p.log;
+/** Log instance that delegates to clack (human mode) or no-ops (JSON mode). */
+export declare const log: Log;
+/** Replace all log methods with no-ops. Call once in JSON mode. */
+export declare function silenceOutput(): void;
+/**
+ * Unwrap a clack prompt result, exiting cleanly if the user cancelled.
+ * `message` lets the caller name what was cancelled (e.g. "Setup cancelled").
+ */
+export declare function unwrapCancel<T>(result: T | symbol, message?: string): T;
+/** Format a URL for display. */
+export declare function fmtUrl(url: string): string;
+/**
+ * Parse and validate a port string. Returns the numeric port or throws.
+ *
+ * Deliberately zod-free: this module loads on every CLI invocation
+ * (including `aai --help`), and keeping zod off that path is the same
+ * startup-cost invariant `_utils.ts` documents for its error helpers.
+ */
+export declare function parsePort(raw: string): number;
+export {};