@alexkroman1/aai-cli 13.3.0 → 15.0.0

package/dist/typecheck.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { n as binFromManifest, o as errorMessage, u as readPackageJson } from "./_utils-Dhd058D9.mjs";
+import { f as readPackageJson, n as binFromManifest, s as errorMessage } from "./_utils-D5JGcjiW.mjs";
 import { existsSync } from "node:fs";
 import path from "node:path";
 import { spawn } from "node:child_process";

package/dist/worker-bundler.d.ts

@@ -34,4 +34,4 @@ export type BuildWorkerOptions = {
  * @internal — build hook for aai-server/the studio; not a supported public
  * API and not covered by semver.
  */
-export declare function buildWorker(cwd: string, opts?: BuildWorkerOptions): Promise<string>;
+export declare function buildWorker(cwd: string, options?: BuildWorkerOptions): Promise<string>;

package/dist/worker-bundler.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { i as errorCode } from "./_utils-Dhd058D9.mjs";
+import { a as errorCode } from "./_utils-D5JGcjiW.mjs";
 import { n as withPreservedNodeEnv } from "./_vite-env-kejF0p2L.mjs";
 import path from "node:path";
 import fs from "node:fs/promises";
@@ -92,8 +92,8 @@ export const __aaiConfig = {
   ...toAgentConfig(__aaiAgent),
   toolSchemas: agentToolsToSchemas(__aaiAgent.tools ?? {}),
 };
-${runtime ? `export const __aaiCreateRuntime = (opts: Record<string, unknown>) =>
-  createRuntime({ ...opts, agent: __aaiAgent });
+${runtime ? `export const __aaiCreateRuntime = (options: Record<string, unknown>) =>
+  createRuntime({ ...options, agent: __aaiAgent });
 ` : ""}`;
 }
 /**
@@ -105,21 +105,21 @@ ${runtime ? `export const __aaiCreateRuntime = (opts: Record<string, unknown>) =
 * @internal — build hook for aai-server/the studio; not a supported public
 * API and not covered by semver.
 */
-async function buildWorker(cwd, opts = {}) {
+async function buildWorker(cwd, options = {}) {
 	const wrapperPath = path.join(cwd, WRAPPER_ENTRY_REL);
 	const [, toolFiles, systemPromptFile] = await Promise.all([
 		fs.mkdir(path.dirname(wrapperPath), { recursive: true }),
 		discoverToolFiles(cwd),
 		hasSystemPromptFile(cwd)
 	]);
-	await fs.writeFile(wrapperPath, wrapperEntrySource(opts.runtime !== false, toolFiles, systemPromptFile), "utf-8");
-	const plugins = opts.plugins ?? [];
+	await fs.writeFile(wrapperPath, wrapperEntrySource(options.runtime !== false, toolFiles, systemPromptFile), "utf-8");
+	const plugins = options.plugins ?? [];
 	let result;
 	try {
 		result = await withPreservedNodeEnv(() => build({
 			root: cwd,
 			logLevel: "silent",
-			...opts.configFile === false && { configFile: false },
+			...options.configFile === false && { configFile: false },
 			...plugins.length > 0 && { plugins },
 			ssr: { noExternal: true },
 			build: {
@@ -130,7 +130,7 @@ async function buildWorker(cwd, opts = {}) {
 					fileName: "worker"
 				},
 				target: "node20",
-				minify: opts.minify ? "oxc" : false,
+				minify: options.minify ? "oxc" : false,
 				write: false,
 				rollupOptions: { output: {
 					entryFileNames: "[name].js",

package/dist/{workflow-BZyKLkhV.mjs → workflow-CVioyO3V.mjs}

@@ -1,8 +1,9 @@
 #!/usr/bin/env node
-import { a as ok, n as fail, t as CliError } from "./_output-DbJt9gsl.mjs";
+import { a as ok, n as fail, t as CliError } from "./_output-DBP9Op_d.mjs";
 import { n as log } from "./_ui-DCt4qZrk.mjs";
-import { i as readProjectConfig } from "./_config-ZY2euhdh.mjs";
-import { n as getServerInfo } from "./_agent-Clbq3a4h.mjs";
+import { m as stripTrailingSlash } from "./_utils-D5JGcjiW.mjs";
+import { i as readProjectConfig } from "./_config-DYzC6WMD.mjs";
+import { n as getServerInfo } from "./_agent-BzUeqOdj.mjs";
 import { errorMessage, omitUndefined } from "@alexkroman1/aai/utils";
 import { createWorkflowApiClient } from "@alexkroman1/aai/workflow-api";
 //#region src/workflow.ts
@@ -38,7 +39,7 @@ const DEFAULT_RUN_LIMIT = 20;
 /**
 * The base URL {@link createWorkflowApiClient} is given for `--agent`.
 *
-* A dev server has no slug: `createServer` mounts the workflow API at
+* A dev server has no slug: `createRuntimeServer` mounts the workflow API at
 * `WORKFLOW_API_PREFIX` on the ORIGIN, where the platform serves it under
 * `/:slug`. So targeting one is not a matter of a different origin — it is the
 * absence of the path segment, which nothing in this command could express.
@@ -61,7 +62,7 @@ function agentBaseUrl(raw) {
 	const url = URL.parse(raw);
 	if (url === null) throw new CliError("bad_agent_url", `--agent is not a URL: ${JSON.stringify(raw)}`, HINT_URL);
 	if (url.protocol !== "http:" && url.protocol !== "https:") throw new CliError("bad_agent_url", `--agent must be http or https, not ${url.protocol.replace(":", "")}`, HINT_URL);
-	return raw.replace(/\/+$/, "");
+	return stripTrailingSlash(raw);
 }
 /**
 * A client for the agent's workflow API, plus the bearer when one was given.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexkroman1/aai-cli",
-  "version": "13.3.0",
+  "version": "15.0.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -38,6 +38,11 @@
       "@dev/source": "./src/project-config.ts",
       "types": "./dist/project-config.d.ts",
       "import": "./dist/project-config.mjs"
+    },
+    "./start": {
+      "@dev/source": "./src/start.ts",
+      "types": "./dist/start.d.ts",
+      "import": "./dist/start.mjs"
     }
   },
   "dependencies": {
@@ -52,9 +57,9 @@
     "p-timeout": "^7.0.1",
     "vite": "^8.2.2",
     "zod": "^4.5.4",
-    "@alexkroman1/aai": "13.3.0",
-    "@alexkroman1/aai-runtime": "13.3.0",
-    "@alexkroman1/aai-ui": "13.3.0"
+    "@alexkroman1/aai": "15.0.0",
+    "@alexkroman1/aai-runtime": "15.0.0",
+    "@alexkroman1/aai-ui": "15.0.0"
   },
   "devDependencies": {
     "playwright": "^1.62.1",

package/dist/_server-common-BV4_CrP3.mjs

@@ -1,43 +0,0 @@
-#!/usr/bin/env node
-import { i as errorCode } from "./_utils-Dhd058D9.mjs";
-import path from "node:path";
-import { parseEnv } from "node:util";
-import fs from "node:fs/promises";
-//#region src/_server-common.ts
-/**
-* 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).
-*/
-async function resolveServerEnv(cwd, baseEnv) {
-	let fileEntries = {};
-	if (cwd) {
-		let content = null;
-		try {
-			content = await fs.readFile(path.join(cwd, ".env"), "utf-8");
-		} catch (err) {
-			if (errorCode(err) !== "ENOENT") throw err;
-		}
-		if (content !== null) fileEntries = parseEnv(content);
-	}
-	const source = baseEnv ?? process.env;
-	const env = {};
-	for (const [key, fileVal] of Object.entries(fileEntries)) {
-		const val = source[key] ?? fileVal;
-		if (val !== void 0 && val !== "") env[key] = val;
-	}
-	return env;
-}
-//#endregion
-export { resolveServerEnv as t };

package/dist/build-CWyFGe-W.mjs

@@ -1,69 +0,0 @@
-#!/usr/bin/env node
-import { a as ok, t as CliError } from "./_output-DbJt9gsl.mjs";
-import { n as log, r as notify } from "./_ui-DCt4qZrk.mjs";
-import { r as evalWorkerBundle, t as buildAgentBundle } from "./_bundler-DEkjO1d8.mjs";
-import { assertTypechecks } from "./_typecheck-gate-sV4N5F93.mjs";
-import { n as scanWorkflowDeterminism, t as determinismWarnings } from "./_workflow-determinism-C9l8uC2R.mjs";
-import { TEST_FILES, classifyVitestError, runVitest } from "./test-guenJUxi.mjs";
-import path from "node:path";
-import fs from "node:fs/promises";
-import { agentConfigWarnings } from "@alexkroman1/aai/manifest";
-//#region src/build.ts
-/**
-* `aai build` — bundle the agent without deploying, behind the same gates
-* deploy runs (tests, then typecheck), so the command previews the deploy
-* artifact and its failures alike.
-*
-* It also LEAVES that artifact on disk, at {@link WORKER_ARTIFACT_REL}, which is
-* what makes self-hosting work: `server.mjs` loads the built worker rather than
-* `agent.ts`, because a tool is discovered by the bundler enumerating `tools/`
-* and no un-bundled loader can see that directory. See the scaffold's own
-* `server.mjs` and "Self-hosting runs the built worker" in
-* `packages/aai-templates/CLAUDE.md`.
-*/
-/**
-* Where the built worker lands, relative to the project root — under `.aai/`,
-* beside the built client, so one gitignore rule covers every build output.
-*
-* `server.mjs` hardcodes this path: it is a plain `.mjs` file in a user's
-* project and may not import from the CLI (which a deployed project does not
-* install at all). The pair is covered end-to-end by the `npm start` leg of
-* `e2e.test.ts` — the only tier that runs both halves as a user does.
-*/
-const WORKER_ARTIFACT_REL = path.join(".aai", "worker.mjs");
-/**
-* Map a {@link runVitest} failure to a CliError — distinguishing a real test
-* failure (test_failed) from the runner not spawning (spawn_failed) instead
-* of a generic command_failed.
-*/
-function testGateError(err) {
-	const { code, message } = classifyVitestError(err);
-	return new CliError(code, message, "Re-run with --skipTests to build without tests", { cause: err });
-}
-async function executeBuild(opts) {
-	const { cwd } = opts;
-	if (!opts.skipTests) try {
-		runVitest(cwd, {
-			candidates: TEST_FILES,
-			all: true
-		});
-	} catch (err) {
-		throw testGateError(err);
-	}
-	if (!opts.skipTypecheck) await assertTypechecks(cwd);
-	const bundle = await buildAgentBundle(cwd, { minify: true });
-	const agentDef = await evalWorkerBundle(bundle.worker);
-	for (const warning of agentConfigWarnings(agentDef)) notify("warn", warning);
-	for (const warning of determinismWarnings(await scanWorkflowDeterminism(cwd))) notify("warn", warning);
-	const worker = path.join(cwd, WORKER_ARTIFACT_REL);
-	await fs.mkdir(path.dirname(worker), { recursive: true });
-	await fs.writeFile(worker, bundle.worker, "utf-8");
-	log.success("Build complete");
-	return ok({
-		name: agentDef.name,
-		workerBytes: bundle.worker.length,
-		worker
-	});
-}
-//#endregion
-export { executeBuild };

package/dist/scaffold/server.mjs

@@ -1,204 +0,0 @@
-// Self-hosted entrypoint — this is what `npm start` runs.
-//
-// It serves the agent over HTTP + WebSocket from your own Node process: no
-// platform account, no managed anything. `aai dev` is the development
-// counterpart (file watching, Vite, a browser that opens itself); this file is
-// the deployment.
-//
-//   npm start                          # http://127.0.0.1:3000
-//   PORT=8080 HOST=0.0.0.0 npm start   # bind every interface, e.g. in a container
-//
-// Anything that can run Node can host it: copy the project, install
-// dependencies, provide the secrets, run `npm start`. Deleting this file costs
-// nothing — `aai dev`, `aai publish` and the managed platform never read it.
-
-import { existsSync } from "node:fs";
-import { readFile } from "node:fs/promises";
-import path from "node:path";
-import { fileURLToPath, pathToFileURL } from "node:url";
-import { parseEnv } from "node:util";
-import {
-  createAgentServer,
-  ensureSessionStateSchema,
-  ensureWorkflowJournalSchema,
-  withHostCredentialFallback,
-} from "@alexkroman1/aai-runtime";
-import { defaultClientDir } from "@alexkroman1/aai-ui/client-dir";
-
-const root = path.dirname(fileURLToPath(import.meta.url));
-
-/**
- * The built agent — `.aai/worker.mjs`, produced by `aai build`, which the
- * `prestart` script runs for you. It is the SAME artifact `aai publish` uploads
- * and the managed platform runs, so a self-hosted agent and a deployed one
- * cannot behave differently.
- *
- * Loading the build rather than `agent.ts` directly is what makes `tools/`
- * work. A tool is registered by EXISTING — its file name is the name the model
- * calls, and nothing anywhere lists them — and the only place a directory can
- * be turned into modules is where the bundle is assembled: a deployed agent is
- * handed one ESM string and has no filesystem to scan. So the bundler
- * enumerates `tools/` and emits the imports, and every loader that skips it
- * would serve an agent with no tools at all.
- *
- * It also settles two things the bundler already resolves, and this file used
- * to re-implement with `node:module` hooks: `import prompt from
- * "./system-prompt.md?raw"` (a Vite convention — Node looks for a file
- * literally named `system-prompt.md?raw`) and `import data from "./data.json"`
- * with no import attribute (TypeScript's `resolveJsonModule` allows it, Node
- * requires `with { type: "json" }`). Both are inlined into the bundle, so
- * there is nothing left to teach Node.
- */
-const workerPath = path.join(root, ".aai", "worker.mjs");
-if (!existsSync(workerPath)) {
-  console.error(
-    `No built agent at ${path.relative(root, workerPath)}.\n` +
-      "Run `npm run build` (or `aai build`) first — `npm start` normally does it for you.",
-  );
-  process.exit(1);
-}
-// A file: URL rather than a relative specifier, so the path is correct on
-// Windows, where a bare POSIX-looking path is not a valid module specifier.
-const worker = await import(pathToFileURL(workerPath).href);
-const agent = worker.default;
-
-/**
- * Parse a dotenv-syntax file into a record; `{}` when it does not exist.
- *
- * @param {string} file - Path relative to the project root.
- * @returns {Promise<Record<string, string | undefined>>}
- */
-async function readEnvFile(file) {
-  try {
-    return parseEnv(await readFile(path.join(root, file), "utf-8"));
-  } catch (err) {
-    // Absent is normal — `.env` is gitignored, and a container usually has
-    // neither file. Unreadable is not: the agent would boot with no
-    // credentials and fail later as an opaque provider auth error.
-    if (err.code !== "ENOENT") throw err;
-    return {};
-  }
-}
-
-/**
- * Build `ctx.env` — what this agent's own tool code reads.
- *
- * The rule is the one `aai dev` follows: only DECLARED keys are exposed, and a
- * real environment variable wins over the file's value. Nothing else from
- * process.env comes along, so the agent cannot come to depend on a variable
- * (PATH, HOME, …) that will not exist wherever you deploy it.
- *
- * `.env.example` counts as a declaration too, which is what lets a container
- * run with no `.env` at all: the committed file names the secrets the agent
- * needs, and `docker run -e MY_API_KEY=…` supplies the values. Declare
- * `DATABASE_URL` the same way to give your tools `ctx.db`.
- */
-async function resolveAgentEnv() {
-  const declared = { ...(await readEnvFile(".env.example")), ...(await readEnvFile(".env")) };
-  /** @type {Record<string, string>} */
-  const env = {};
-  for (const [key, fileValue] of Object.entries(declared)) {
-    const value = process.env[key] ?? fileValue;
-    // An empty value is worse than a missing one: a provider would try to
-    // authenticate with "" rather than report the credential as absent. The
-    // example file is full of them by design (`BRAVE_API_KEY=`). A key the
-    // parser saw with no value at all is the same case.
-    if (value !== undefined && value !== "") env[key] = value;
-  }
-  return env;
-}
-
-/**
- * Static assets served at `/`: this project's own UI once `client.tsx` has been
- * built (the same `aai build` leaves it in `.aai/client`), otherwise the
- * prebuilt default client that ships inside @alexkroman1/aai-ui.
- */
-function resolveClientDir() {
-  const built = path.join(root, ".aai", "client");
-  if (existsSync(path.join(built, "index.html"))) return built;
-  if (existsSync(path.join(root, "client.tsx"))) {
-    console.warn("client.tsx is not built — serving the default UI. Run `npm run build` first.");
-  }
-  return defaultClientDir();
-}
-
-const env = await resolveAgentEnv();
-
-/**
- * Where THIS server is reachable from outside — `PUBLIC_URL`, e.g.
- * `https://agent.example.com`. Set it whenever a durable workflow has to hand a
- * URL to somebody else: `ctx.workflows.publicWebhookUrl(token)` is built from it,
- * and without it that call throws rather than minting a `http://localhost:3000`
- * URL that a payment provider will try, days later, and fail.
- *
- * Nothing else reads it, so it is not a startup requirement: an agent with no
- * webhooks needs no value here. It is deliberately NOT derived from `PORT`/`HOST`
- * — those describe the socket this process binds, which behind a reverse proxy is
- * not what the outside world dials.
- */
-const publicUrl = process.env.PUBLIC_URL?.trim();
-
-/**
- * Create the session-state tables, when this agent has a database.
- *
- * A `DATABASE_URL` puts session state in Postgres, and those tables come with
- * whoever OWNS the database — which for a self-hosted agent is you, with no
- * migration step anywhere to hang them off. Without this the server starts,
- * reports `sessionState: postgres, durable: true`, and then every session dies
- * at start with a fatal error the browser shows as "Session failed to start",
- * the real reason (`relation "aai_session_events" does not exist`) appearing
- * only in this process's log.
- *
- * Best-effort: if a real migration already created them and this role may not
- * CREATE, it warns and the server starts anyway.
- */
-if (env.DATABASE_URL) {
-  await ensureSessionStateSchema({ url: env.DATABASE_URL, logger: console });
-  // And the durable-run journal's, which is a separate set of tables owned by
-  // the same deployment. Without it a project with a `DATABASE_URL` boots
-  // claiming durable runs and fails on the first one.
-  await ensureWorkflowJournalSchema({ url: env.DATABASE_URL, logger: console });
-}
-
-const server = createAgentServer({
-  agent,
-  env,
-  // Provider credentials may ALSO arrive straight from the environment without
-  // being declared, and without becoming ctx.env — the ordinary way to hand
-  // ASSEMBLYAI_API_KEY to a container. Anything in `env` still wins.
-  providerEnv: withHostCredentialFallback(env),
-  clientDir: resolveClientDir(),
-  ...(publicUrl ? { publicUrl } : {}),
-  // Durable workflows need nothing passed here. A `DATABASE_URL` in `env` puts
-  // the runs in Postgres and they survive a restart; without one they live in a
-  // per-process directory and do not, which is the same trade `aai dev` makes.
-  //
-  // Two options used to sit here — the compiled workflow surface, carried on the
-  // bundle as `__aaiWorkflowCode`/`__aaiStepCode` because a `"use workflow"` body
-  // had to go through a compiler at BUILD time. The engine reads the agent's own
-  // `workflows` declaration instead, so there is no artifact to hand over.
-});
-
-// Loopback by default: this server has no request authentication of its own,
-// so exposing it is a deliberate act. Set HOST=0.0.0.0 to bind every interface
-// behind your own proxy or auth. An empty HOST means unset, not "everything".
-const host = process.env.HOST?.trim() || undefined;
-await server.listen(Number(process.env.PORT ?? 3000), host);
-console.log(`${agent.name} listening on http://${host ?? "127.0.0.1"}:${server.port}`);
-
-for (const signal of ["SIGINT", "SIGTERM"]) {
-  // A SYNCHRONOUS listener. An `async` one hands its promise to `process`,
-  // which discards what a listener returns — so a `close()` that rejects would
-  // surface as an unhandled rejection, i.e. a crash with a stack trace on
-  // Ctrl-C, instead of the non-zero exit a failed shutdown should be.
-  process.once(signal, () => {
-    // close() shuts the runtime down too — no separate runtime.shutdown().
-    server.close().then(
-      () => process.exit(0),
-      (error) => {
-        console.error(`shutdown failed: ${error?.message ?? error}`);
-        process.exit(1);
-      },
-    );
-  });
-}