electric-ax 0.1.0

package/dist/index.cjs

@@ -0,0 +1,629 @@
+#!/usr/bin/env node
+"use strict";
+const require_chunk = require('./chunk-BCwAaXi7.cjs');
+const require_completions = require('./completions-CO5UBiNh.cjs');
+const node_fs = require_chunk.__toESM(require("node:fs"));
+const node_os = require_chunk.__toESM(require("node:os"));
+const node_path = require_chunk.__toESM(require("node:path"));
+const node_url = require_chunk.__toESM(require("node:url"));
+const commander = require_chunk.__toESM(require("commander"));
+const node_child_process = require_chunk.__toESM(require("node:child_process"));
+const __electric_ax_agents = require_chunk.__toESM(require("@electric-ax/agents"));
+
+//#region src/start.ts
+const DEFAULT_ELECTRIC_AGENTS_PORT = 4437;
+const DEFAULT_BUILTIN_AGENTS_PORT = 4448;
+const DOCKER_COMPOSE_FILE = (0, node_url.fileURLToPath)(new URL(`../docker-compose.full.yml`, require("url").pathToFileURL(__filename).href));
+function parseDotEnvValue(raw) {
+	const trimmed = raw.trim();
+	if (trimmed.startsWith(`"`) && trimmed.endsWith(`"`) || trimmed.startsWith(`'`) && trimmed.endsWith(`'`)) return trimmed.slice(1, -1);
+	const hashIndex = trimmed.indexOf(`#`);
+	return hashIndex === -1 ? trimmed : trimmed.slice(0, hashIndex).trim();
+}
+function readDotEnvFile(cwd = process.cwd()) {
+	const envPath = (0, node_path.resolve)(cwd, `.env`);
+	try {
+		const content = (0, node_fs.readFileSync)(envPath, `utf8`);
+		const values = {};
+		for (const line of content.split(/\r?\n/)) {
+			const trimmed = line.trim();
+			if (!trimmed || trimmed.startsWith(`#`)) continue;
+			const equalsIndex = trimmed.indexOf(`=`);
+			if (equalsIndex <= 0) continue;
+			const key = trimmed.slice(0, equalsIndex).trim();
+			const value = parseDotEnvValue(trimmed.slice(equalsIndex + 1));
+			values[key] = value;
+		}
+		return values;
+	} catch (error) {
+		if (error.code === `ENOENT`) return {};
+		throw error;
+	}
+}
+function resolveAnthropicApiKey(options, env = process.env, fileEnv = readDotEnvFile()) {
+	const candidate = options.anthropicApiKey?.trim() || env.ANTHROPIC_API_KEY?.trim() || fileEnv.ANTHROPIC_API_KEY?.trim();
+	if (!candidate) throw new Error(`ANTHROPIC_API_KEY is required. Pass --anthropic-api-key, export it in your shell, or set it in .env.`);
+	return candidate;
+}
+function resolveBuiltinAgentsPort(env = process.env, fileEnv = readDotEnvFile()) {
+	const raw = env.ELECTRIC_AGENTS_BUILTIN_PORT?.trim() || fileEnv.ELECTRIC_AGENTS_BUILTIN_PORT?.trim();
+	const parsed = raw ? Number(raw) : DEFAULT_BUILTIN_AGENTS_PORT;
+	if (!Number.isInteger(parsed) || parsed <= 0) throw new Error(`ELECTRIC_AGENTS_BUILTIN_PORT must be a positive integer`);
+	return parsed;
+}
+function resolveElectricAgentsPort(env = process.env, fileEnv = readDotEnvFile()) {
+	const raw = env.ELECTRIC_AGENTS_PORT?.trim() || fileEnv.ELECTRIC_AGENTS_PORT?.trim();
+	const parsed = raw ? Number(raw) : DEFAULT_ELECTRIC_AGENTS_PORT;
+	if (!Number.isInteger(parsed) || parsed <= 0) throw new Error(`ELECTRIC_AGENTS_PORT must be a positive integer`);
+	return parsed;
+}
+function getStartedEnvironmentMessage(started) {
+	return [
+		`Electric Agents dev environment is up.`,
+		`Server + UI: ${started.uiUrl}`,
+		`Docker project: ${started.composeProjectName}`
+	].join(`\n`);
+}
+function getStoppedEnvironmentMessage(stopped) {
+	return [
+		`Electric Agents dev environment is down.`,
+		`Docker project: ${stopped.composeProjectName}`,
+		stopped.removedVolumes ? `Volumes removed: yes` : `Volumes removed: no`
+	].join(`\n`);
+}
+function getStartedBuiltinAgentsMessage(started) {
+	return [
+		`Builtin Horton server is up.`,
+		`Webhook server: ${started.url}`,
+		`Registers with: ${started.agentServerUrl}`,
+		`Press Ctrl-C to stop.`
+	].join(`\n`);
+}
+function slugify(input) {
+	return input.toLowerCase().replace(/[^a-z0-9]+/g, `-`).replace(/^-+|-+$/g, ``);
+}
+function resolveComposeProjectName(cwd = process.cwd(), env = process.env) {
+	const explicit = env.ELECTRIC_AGENTS_COMPOSE_PROJECT?.trim();
+	if (explicit) return explicit;
+	const base = slugify((0, node_path.basename)(cwd)) || `workspace`;
+	return `electric-agents-${base}`;
+}
+async function runDockerCompose(args, env) {
+	await new Promise((resolve, reject) => {
+		const child = (0, node_child_process.spawn)(`docker`, args, {
+			cwd: process.cwd(),
+			env,
+			stdio: `inherit`
+		});
+		child.on(`error`, (error) => {
+			reject(new Error(`Failed to run docker compose: ${error instanceof Error ? error.message : String(error)}`));
+		});
+		child.on(`exit`, (code) => {
+			if (code === 0) {
+				resolve();
+				return;
+			}
+			reject(new Error(`docker compose exited with code ${code ?? `unknown`}`));
+		});
+	});
+}
+function delay(ms) {
+	return new Promise((resolve) => {
+		setTimeout(resolve, ms);
+	});
+}
+async function waitForElectricAgentsServer(baseUrl, options = {}) {
+	const fetchImpl = options.fetchImpl ?? globalThis.fetch;
+	const timeoutMs = options.timeoutMs ?? 6e4;
+	const intervalMs = options.intervalMs ?? 1e3;
+	const deadline = Date.now() + timeoutMs;
+	const healthUrl = `${baseUrl.replace(/\/$/, ``)}/_electric/health`;
+	let lastError = null;
+	while (Date.now() < deadline) {
+		try {
+			const response = await fetchImpl(healthUrl, { signal: AbortSignal.timeout(5e3) });
+			if (response.ok) return;
+			lastError = `healthcheck returned ${response.status}`;
+		} catch (error) {
+			lastError = error instanceof Error ? error.message : String(error);
+		}
+		await delay(intervalMs);
+	}
+	throw new Error(`Timed out waiting for Electric Agents server at ${healthUrl}${lastError ? `: ${lastError}` : ``}`);
+}
+async function startElectricAgentsDevEnvironment(_options = {}, env = process.env, cwd = process.cwd()) {
+	const fileEnv = readDotEnvFile(cwd);
+	const port = resolveElectricAgentsPort(env, fileEnv);
+	const composeProjectName = resolveComposeProjectName(cwd, env);
+	await runDockerCompose([
+		`compose`,
+		`-f`,
+		DOCKER_COMPOSE_FILE,
+		`up`,
+		`-d`
+	], {
+		...env,
+		COMPOSE_PROJECT_NAME: composeProjectName,
+		ELECTRIC_AGENTS_PORT: String(port)
+	});
+	const uiUrl = `http://localhost:${port}`;
+	await waitForElectricAgentsServer(uiUrl);
+	return {
+		port,
+		uiUrl,
+		composeProjectName
+	};
+}
+async function stopElectricAgentsDevEnvironment(options, env = process.env, cwd = process.cwd()) {
+	const composeProjectName = resolveComposeProjectName(cwd, env);
+	const args = [
+		`compose`,
+		`-f`,
+		DOCKER_COMPOSE_FILE,
+		`down`
+	];
+	if (options.removeVolumes) args.push(`--volumes`);
+	await runDockerCompose(args, {
+		...env,
+		COMPOSE_PROJECT_NAME: composeProjectName
+	});
+	return {
+		composeProjectName,
+		removedVolumes: options.removeVolumes ?? false
+	};
+}
+function waitForShutdown(stop, signalSource = process) {
+	return new Promise((resolve, reject) => {
+		let stopping = false;
+		const cleanup = () => {
+			signalSource.off(`SIGINT`, onSigint);
+			signalSource.off(`SIGTERM`, onSigterm);
+		};
+		const shutdown = (signal) => {
+			if (stopping) return;
+			stopping = true;
+			cleanup();
+			stop().then(resolve).catch((error) => {
+				reject(new Error(`Failed to stop builtin agents server after ${signal}: ${error instanceof Error ? error.message : String(error)}`));
+			});
+		};
+		const onSigint = () => {
+			shutdown(`SIGINT`);
+		};
+		const onSigterm = () => {
+			shutdown(`SIGTERM`);
+		};
+		signalSource.on(`SIGINT`, onSigint);
+		signalSource.on(`SIGTERM`, onSigterm);
+	});
+}
+async function startBuiltinAgentsServer(options, params = {}) {
+	const env = params.env ?? process.env;
+	const cwd = params.cwd ?? process.cwd();
+	const fileEnv = readDotEnvFile(cwd);
+	const anthropicApiKey = resolveAnthropicApiKey(options, env, fileEnv);
+	const port = resolveBuiltinAgentsPort(env, fileEnv);
+	const agentServerUrl = params.agentServerUrl ?? env.ELECTRIC_AGENTS_URL?.trim() ?? `http://localhost:${resolveElectricAgentsPort(env, fileEnv)}`;
+	process.env.ANTHROPIC_API_KEY = anthropicApiKey;
+	await waitForElectricAgentsServer(agentServerUrl);
+	const server = new __electric_ax_agents.BuiltinAgentsServer({
+		agentServerUrl,
+		port,
+		workingDirectory: cwd
+	});
+	await server.start();
+	const started = {
+		port,
+		url: server.url,
+		registeredBaseUrl: server.registeredBaseUrl,
+		agentServerUrl
+	};
+	console.log(getStartedBuiltinAgentsMessage(started));
+	await waitForShutdown(() => server.stop());
+	return started;
+}
+
+//#endregion
+//#region src/index.ts
+const DEFAULT_ELECTRIC_AGENTS_URL = `http://localhost:4437`;
+var CliError = class extends Error {};
+function getDefaultElectricAgentsIdentity() {
+	return `${(0, node_os.userInfo)().username}@${(0, node_os.hostname)()}`;
+}
+function getElectricCliEnv(env = process.env) {
+	return {
+		electricAgentsUrl: env.ELECTRIC_AGENTS_URL || DEFAULT_ELECTRIC_AGENTS_URL,
+		electricAgentsIdentity: env.ELECTRIC_AGENTS_IDENTITY || getDefaultElectricAgentsIdentity()
+	};
+}
+function getErrorMessage(error) {
+	return error instanceof Error ? error.message : String(error);
+}
+function fail(message) {
+	throw new CliError(message);
+}
+function relativeTime(epochMs) {
+	const seconds = Math.floor((Date.now() - epochMs) / 1e3);
+	if (seconds < 5) return `just now`;
+	if (seconds < 60) return `${seconds}s ago`;
+	const minutes = Math.floor(seconds / 60);
+	if (minutes < 60) return `${minutes}m ago`;
+	const hours = Math.floor(minutes / 60);
+	if (hours < 24) return `${hours}h ago`;
+	const days = Math.floor(hours / 24);
+	return `${days}d ago`;
+}
+function parsePayload(input, json) {
+	if (json) try {
+		return JSON.parse(input);
+	} catch (error) {
+		fail(`Invalid JSON: ${getErrorMessage(error)}`);
+	}
+	return { text: input };
+}
+function normalizeVariadicArg(value) {
+	if (value === void 0) return [];
+	return Array.isArray(value) ? value : [value];
+}
+function getCommandActionArg(args) {
+	return args[args.length - 1];
+}
+function resolveCommandName(argv) {
+	const invoked = (0, node_path.basename)(argv[1] ?? ``);
+	if (!invoked) return `electric`;
+	if (invoked === `index.js` || invoked === `index.ts` || invoked === `node`) return `electric`;
+	return invoked.replace(/\.(c|m)?js$/, ``);
+}
+function commandExample(commandName) {
+	return `${commandName} agent`;
+}
+function resolveCommandPrefix(argv, env = process.env) {
+	if (env.npm_command === `exec`) {
+		const userAgent = env.npm_config_user_agent ?? ``;
+		if (userAgent.startsWith(`pnpm/`)) return `pnpx electric-ax agent`;
+		if (userAgent.startsWith(`npm/`)) return `npx electric-ax agent`;
+	}
+	return commandExample(resolveCommandName(argv));
+}
+async function electricAgentsFetch(env, path, opts = {}) {
+	try {
+		return await fetch(`${env.electricAgentsUrl}${path}`, {
+			...opts,
+			headers: {
+				"content-type": `application/json`,
+				...opts.headers
+			}
+		});
+	} catch (error) {
+		fail(`Could not connect to ${env.electricAgentsUrl} — is the Electric Agents server running?\n  Set ELECTRIC_AGENTS_URL to point to a different server.\n  Original error: ${getErrorMessage(error)}`);
+	}
+}
+async function parseJsonResponse(res) {
+	const text = await res.text();
+	try {
+		return JSON.parse(text);
+	} catch (error) {
+		if (!(error instanceof SyntaxError)) throw error;
+		return { error: { message: text || res.statusText } };
+	}
+}
+function failFromResponse(data, res) {
+	const err = data.error;
+	fail(String(err?.message ?? res.statusText));
+}
+async function fetchEntityTypes(env) {
+	const res = await electricAgentsFetch(env, `/_electric/entity-types`);
+	const data = await res.json();
+	if (!res.ok) fail(typeof data === `object` && data !== null ? String(data.error?.message ?? res.statusText) : res.statusText);
+	if (!Array.isArray(data)) fail(`Unexpected response from server when listing entity types`);
+	return data;
+}
+async function listTypes(env) {
+	const rows = await fetchEntityTypes(env);
+	if (rows.length === 0) {
+		console.log(`No entity types found`);
+		return;
+	}
+	const types = rows.map((entityType) => ({
+		name: entityType.name,
+		description: entityType.description,
+		serve_endpoint: entityType.serve_endpoint
+	}));
+	const { renderTypesTable } = await import(`./types-table.js`);
+	renderTypesTable(types);
+}
+async function fetchEntities(env, options = {}) {
+	const searchParams = new URLSearchParams();
+	if (options.type) searchParams.set(`type`, options.type);
+	if (options.status) searchParams.set(`status`, options.status);
+	if (options.parent) searchParams.set(`parent`, options.parent);
+	const suffix = searchParams.size > 0 ? `?${searchParams.toString()}` : ``;
+	const res = await electricAgentsFetch(env, `/_electric/entities${suffix}`);
+	const data = await res.json();
+	if (!res.ok) fail(typeof data === `object` && data !== null ? String(data.error?.message ?? res.statusText) : res.statusText);
+	if (!Array.isArray(data)) fail(`Unexpected response from server when listing entities`);
+	return data;
+}
+async function inspectType(env, name) {
+	const res = await electricAgentsFetch(env, `/_electric/entity-types/${encodeURIComponent(name)}`);
+	const data = await parseJsonResponse(res);
+	if (!res.ok) failFromResponse(data, res);
+	console.log(JSON.stringify(data, null, 2));
+}
+async function deleteType(env, name) {
+	const res = await electricAgentsFetch(env, `/_electric/entity-types/${encodeURIComponent(name)}`, { method: `DELETE` });
+	if (!res.ok) {
+		const data = await parseJsonResponse(res);
+		failFromResponse(data, res);
+	}
+	console.log(`Deleted entity type ${name}`);
+}
+async function spawnEntity(env, urlPath, options) {
+	let spawnArgs = {};
+	if (options.args) try {
+		spawnArgs = JSON.parse(options.args);
+	} catch (error) {
+		fail(`--args must be valid JSON: ${getErrorMessage(error)}`);
+	}
+	const res = await electricAgentsFetch(env, urlPath, {
+		method: `PUT`,
+		body: JSON.stringify({ args: spawnArgs })
+	});
+	const data = await parseJsonResponse(res);
+	if (!res.ok) failFromResponse(data, res);
+	const entity = data;
+	if (!entity.url || !entity.status) fail(`Unexpected response from server: ${JSON.stringify(data)}`);
+	console.log(`Spawned ${entity.url} (type: ${entity.type ?? `unknown`}, status: ${entity.status})`);
+}
+async function sendMessage(env, url, message, options) {
+	const payload = parsePayload(message, options.json ?? false);
+	const body = {
+		from: env.electricAgentsIdentity,
+		payload
+	};
+	if (options.type) body.type = options.type;
+	const res = await electricAgentsFetch(env, `${url}/send`, {
+		method: `POST`,
+		body: JSON.stringify(body)
+	});
+	if (!res.ok) {
+		const data = await parseJsonResponse(res);
+		failFromResponse(data, res);
+	}
+	console.log(`Message sent`);
+}
+async function observeEntity(env, url, options) {
+	if (!process.stdout.isTTY) fail(`observe requires an interactive terminal`);
+	const { renderObserve } = await import(`./observe-ui.js`);
+	renderObserve({
+		entityUrl: url,
+		baseUrl: env.electricAgentsUrl,
+		identity: env.electricAgentsIdentity,
+		initialOffset: options.from
+	});
+}
+async function inspectEntity(env, url) {
+	const res = await electricAgentsFetch(env, url);
+	const data = await parseJsonResponse(res);
+	if (!res.ok) failFromResponse(data, res);
+	console.log(JSON.stringify(data, null, 2));
+}
+async function listEntities(env, options) {
+	const entities = await fetchEntities(env, options);
+	if (entities.length === 0) {
+		console.log(`No entities found`);
+		return;
+	}
+	entities.sort((a, b) => {
+		const aTime = Number(a.updated_at) || 0;
+		const bTime = Number(b.updated_at) || 0;
+		return bTime - aTime;
+	});
+	console.log(`${`URL`.padEnd(30)} ${`STATUS`.padEnd(10)} ${`CREATED`.padEnd(16)} LAST ACTIVE`);
+	console.log(`${`─`.repeat(30)} ${`─`.repeat(10)} ${`─`.repeat(16)} ${`─`.repeat(16)}`);
+	for (const entity of entities) {
+		const created = entity.created_at ? relativeTime(Number(entity.created_at)) : `-`;
+		const lastActive = entity.updated_at ? relativeTime(Number(entity.updated_at)) : `-`;
+		console.log(`${entity.url.padEnd(30)} ${entity.status.padEnd(10)} ${created.padEnd(16)} ${lastActive}`);
+	}
+}
+async function killEntity(env, url) {
+	const res = await electricAgentsFetch(env, url, { method: `DELETE` });
+	if (!res.ok) {
+		const data = await parseJsonResponse(res);
+		failFromResponse(data, res);
+	}
+	console.log(`Killed ${url}`);
+}
+function printStartedEnvironment(env) {
+	console.log(getStartedEnvironmentMessage(env));
+}
+function printStoppedEnvironment(env) {
+	console.log(getStoppedEnvironmentMessage(env));
+}
+function createElectricCliHandlers(env, commandPrefix = commandExample(`electric`)) {
+	return {
+		listTypes: () => listTypes(env),
+		inspectType: (name) => inspectType(env, name),
+		deleteType: (name) => deleteType(env, name),
+		spawn: (urlPath, options) => spawnEntity(env, urlPath, options),
+		send: (url, message, options) => sendMessage(env, url, message, options),
+		observe: (url, options) => observeEntity(env, url, options),
+		inspect: (url) => inspectEntity(env, url),
+		ps: (options) => listEntities(env, options),
+		kill: (url) => killEntity(env, url),
+		start: async (options) => {
+			const started = await startElectricAgentsDevEnvironment(options);
+			printStartedEnvironment(started);
+			return started;
+		},
+		startBuiltin: async (options) => {
+			return startBuiltinAgentsServer(options, { agentServerUrl: env.electricAgentsUrl });
+		},
+		stop: async (options) => {
+			const stopped = await stopElectricAgentsDevEnvironment(options);
+			printStoppedEnvironment(stopped);
+			return stopped;
+		},
+		quickstart: async (options) => {
+			const started = await startElectricAgentsDevEnvironment();
+			printStartedEnvironment(started);
+			console.log(``);
+			console.log([
+				`electric agents server is up`,
+				``,
+				`Open a separate terminal and run:`,
+				`  ${commandPrefix} spawn /horton/onboarding`,
+				`  ${commandPrefix} send /horton/onboarding "Please walk me through onboarding for the Electric agents"`,
+				`  ${commandPrefix} observe /horton/onboarding`,
+				``,
+				`UI: ${started.uiUrl}`,
+				`This terminal will now run the built-in Horton server in the foreground.`
+			].join(`\n`));
+			console.log(``);
+			await startBuiltinAgentsServer(options, { agentServerUrl: started.uiUrl });
+		}
+	};
+}
+function getHelpText(commandName) {
+	const agentsCommand = commandExample(commandName);
+	return `
+Environment:
+  ELECTRIC_AGENTS_URL        Base URL of the server (default: ${DEFAULT_ELECTRIC_AGENTS_URL})
+  ELECTRIC_AGENTS_IDENTITY   Sender identity for messages (default: ${getDefaultElectricAgentsIdentity()})
+  ANTHROPIC_API_KEY          Required for '${agentsCommand} start-builtin' and '${agentsCommand} quickstart'
+
+Examples:
+  $ ${agentsCommand} types
+  $ ${agentsCommand} spawn /horton/onboarding
+  $ ${agentsCommand} send /horton/onboarding "Please walk me through onboarding for the Electric agents"
+  $ ${agentsCommand} observe /horton/onboarding --from 0
+  $ ${agentsCommand} start
+  $ ${agentsCommand} start-builtin --anthropic-api-key sk-ant-...
+  $ ${agentsCommand} stop --remove-volumes
+`;
+}
+function createElectricProgram({ env = getElectricCliEnv(), commandName = `electric`, commandPrefix = commandExample(commandName), handlers = createElectricCliHandlers(env, commandPrefix) } = {}) {
+	const program = new commander.Command();
+	program.name(commandName).description(`Manage Electric tooling`).showHelpAfterError().showSuggestionAfterError().addHelpText(`after`, getHelpText(commandName));
+	const agentsCommand = program.command(`agent`).alias(`agents`).description(`Manage Electric Agents`);
+	const typesCommand = agentsCommand.command(`types`).description(`List entity types`).action(async () => {
+		await handlers.listTypes();
+	});
+	typesCommand.command(`inspect <name>`).description(`Show entity type details`).action(async (name) => {
+		await handlers.inspectType(name);
+	});
+	typesCommand.command(`delete <name>`).description(`Delete an entity type`).action(async (name) => {
+		await handlers.deleteType(name);
+	});
+	agentsCommand.command(`spawn <url-path>`).description(`Spawn an entity from a typed URL path`).option(`--args <json>`, `Spawn arguments as JSON`).action(async (...actionArgs) => {
+		const urlPath = actionArgs[0];
+		const command = getCommandActionArg(actionArgs);
+		await handlers.spawn(urlPath, command.opts());
+	});
+	agentsCommand.command(`send <url> <message...>`).description(`Send a message to an entity`).option(`--type <msg-type>`, `Message type`).option(`--json`, `Parse message as JSON`).action(async (...actionArgs) => {
+		const url = actionArgs[0];
+		const message = actionArgs[1];
+		const command = getCommandActionArg(actionArgs);
+		const messageText = normalizeVariadicArg(message).join(` `);
+		await handlers.send(url, messageText, command.opts());
+	});
+	agentsCommand.command(`observe <url>`).description(`Observe an entity conversation`).option(`--from <offset>`, `Initial offset`).action(async (...actionArgs) => {
+		const url = actionArgs[0];
+		const command = getCommandActionArg(actionArgs);
+		await handlers.observe(url, command.opts());
+	});
+	agentsCommand.command(`inspect <url>`).description(`Show entity details`).action(async (url) => {
+		await handlers.inspect(url);
+	});
+	agentsCommand.command(`ps`).description(`List entities`).option(`--type <type>`, `Filter by entity type`).option(`--status <status>`, `Filter by status`).option(`--parent <url>`, `Filter by parent URL`).action(async (...actionArgs) => {
+		const command = getCommandActionArg(actionArgs);
+		await handlers.ps(command.opts());
+	});
+	agentsCommand.command(`kill <url>`).description(`Delete an entity`).action(async (url) => {
+		await handlers.kill(url);
+	});
+	agentsCommand.command(`start`).description(`Start the Electric Agents coordinator server`).action(async (...actionArgs) => {
+		const command = getCommandActionArg(actionArgs);
+		await handlers.start(command.opts());
+	});
+	agentsCommand.command(`start-builtin`).description(`Start runtime for Horton & other builtin agents`).option(`--anthropic-api-key <key>`, `Anthropic API key for the builtin Horton server`).action(async (...actionArgs) => {
+		const command = getCommandActionArg(actionArgs);
+		await handlers.startBuiltin(command.opts());
+	});
+	agentsCommand.command(`stop`).description(`Stop the local Electric Agents dev environment`).option(`--remove-volumes`, `Remove Docker volumes as well`).action(async (...actionArgs) => {
+		const command = getCommandActionArg(actionArgs);
+		await handlers.stop(command.opts());
+	});
+	agentsCommand.command(`quickstart`).description(`Start the coordinator server, print onboarding steps, and run builtin agents locally`).option(`--anthropic-api-key <key>`, `Anthropic API key for the builtin Horton server`).action(async (...actionArgs) => {
+		const command = getCommandActionArg(actionArgs);
+		await handlers.quickstart(command.opts());
+	});
+	const completionCommand = agentsCommand.command(`completion [action]`).description(`Set up shell completion`).addHelpText(`after`, `
+Setup (add to your shell init file):
+
+  Bash:  eval "$(${commandName} --completion)"        # add to .bashrc
+  Zsh:   eval "$(${commandName} --completion)"        # add to .zshrc
+  Fish:  ${commandName} --completion-fish | source    # add to config.fish
+
+Auto-install (detects your shell and updates init file):
+  ${commandName} agent completion install
+`).action((action) => {
+		if (action === `install`) {
+			try {
+				console.log(`Installing shell completions...`);
+				require_completions.installCompletions(commandName);
+			} catch (error) {
+				fail(`Could not install completions: ${getErrorMessage(error)}\n  Try manual setup instead: eval "$(${commandName} --completion)"`);
+			}
+			return;
+		}
+		console.log(`Set up shell completions for ${commandName}.\n`);
+		console.log(`Add to your shell init file:`);
+		console.log(`  Bash/Zsh:  eval "$(${commandName} --completion)"`);
+		console.log(`  Fish:      ${commandName} --completion-fish | source\n`);
+		console.log(`Or auto-install:  ${commandName} agent completion install`);
+	});
+	completionCommand.alias(`completions`);
+	return program;
+}
+async function run(argv = process.argv) {
+	const env = getElectricCliEnv();
+	const commandName = resolveCommandName(argv);
+	const commandPrefix = resolveCommandPrefix(argv);
+	require_completions.setupCompletions(env, commandName);
+	if (argv.includes(`--compgen`)) return;
+	const program = createElectricProgram({
+		env,
+		commandName,
+		commandPrefix
+	});
+	if (argv.length <= 2) program.help({ error: true });
+	await program.parseAsync(argv);
+}
+function isMainModule() {
+	if (!process.argv[1]) return false;
+	try {
+		const scriptPath = (0, node_fs.realpathSync)((0, node_path.resolve)(process.argv[1]));
+		const modulePath = (0, node_fs.realpathSync)((0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href));
+		return scriptPath === modulePath;
+	} catch (error) {
+		if (!(error instanceof Error) || !(`code` in error) || error.code !== `ENOENT`) throw error;
+		const scriptPath = (0, node_path.resolve)(process.argv[1]);
+		const modulePath = (0, node_url.fileURLToPath)(require("url").pathToFileURL(__filename).href);
+		return scriptPath === modulePath;
+	}
+}
+if (isMainModule()) run().catch((error) => {
+	if (error instanceof CliError) console.error(`Error: ${error.message}`);
+	else console.error(`Fatal: ${getErrorMessage(error)}`);
+	process.exit(1);
+});
+
+//#endregion
+exports.DEFAULT_ELECTRIC_AGENTS_URL = DEFAULT_ELECTRIC_AGENTS_URL
+exports.createElectricCliHandlers = createElectricCliHandlers
+exports.createElectricProgram = createElectricProgram
+exports.getElectricCliEnv = getElectricCliEnv
+exports.resolveCommandPrefix = resolveCommandPrefix
+exports.run = run

package/dist/index.d.cts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { DEFAULT_ELECTRIC_AGENTS_URL, ElectricCliEnv, ElectricCliHandlers, ObserveCommandOptions, PsCommandOptions, SendCommandOptions, SpawnCommandOptions, StartBuiltinCommandOptions, StartCommandOptions, StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StopCommandOptions, StoppedDevEnvironment, createElectricCliHandlers, createElectricProgram, getElectricCliEnv, resolveCommandPrefix, run } from "./index-B6gIlecl.cjs";
+export { DEFAULT_ELECTRIC_AGENTS_URL, ElectricCliEnv, ElectricCliHandlers, ObserveCommandOptions, PsCommandOptions, SendCommandOptions, SpawnCommandOptions, StartBuiltinCommandOptions, StartCommandOptions, StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StopCommandOptions, StoppedDevEnvironment, createElectricCliHandlers, createElectricProgram, getElectricCliEnv, resolveCommandPrefix, run };

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { DEFAULT_ELECTRIC_AGENTS_URL, ElectricCliEnv, ElectricCliHandlers, ObserveCommandOptions, PsCommandOptions, SendCommandOptions, SpawnCommandOptions, StartBuiltinCommandOptions, StartCommandOptions, StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StopCommandOptions, StoppedDevEnvironment, createElectricCliHandlers, createElectricProgram, getElectricCliEnv, resolveCommandPrefix, run } from "./index-BJvlcIKL.js";
+export { DEFAULT_ELECTRIC_AGENTS_URL, ElectricCliEnv, ElectricCliHandlers, ObserveCommandOptions, PsCommandOptions, SendCommandOptions, SpawnCommandOptions, StartBuiltinCommandOptions, StartCommandOptions, StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StopCommandOptions, StoppedDevEnvironment, createElectricCliHandlers, createElectricProgram, getElectricCliEnv, resolveCommandPrefix, run };