electric-ax 0.1.15 → 0.1.16

package/dist/completions.d.cts

@@ -1,4 +1,4 @@
-import { ElectricCliEnv } from "./index-BNTf2uZL.cjs";
+import { ElectricCliEnv } from "./index-Dgoj3VzA.cjs";
 
 //#region src/completions.d.ts
 declare function fetchEntityTypeNames(env: ElectricCliEnv): Promise<Array<string>>;

package/dist/completions.d.ts

@@ -1,4 +1,4 @@
-import { ElectricCliEnv } from "./index-DS2RpaPZ.js";
+import { ElectricCliEnv } from "./index-si6k6XW1.js";
 
 //#region src/completions.d.ts
 declare function fetchEntityTypeNames(env: ElectricCliEnv): Promise<Array<string>>;

package/dist/{index-BNTf2uZL.d.cts → index-Dgoj3VzA.d.cts}

@@ -42,6 +42,7 @@ declare function startBuiltinAgentsServer(options: StartBuiltinCommandOptions, p
   env?: NodeJS.ProcessEnv;
   cwd?: string;
   agentServerUrl?: string;
+  printStartedMessage?: boolean;
 }): Promise<StartedBuiltinAgentsEnvironment>;
 
 //#endregion
@@ -93,7 +94,19 @@ interface InvocationEnv {
   npm_command?: string;
   npm_config_user_agent?: string;
 }
+interface QuickstartBackendStartedMessageOptions {
+  commandPrefix: string;
+  uiUrl: string;
+  color?: boolean;
+  trueColor?: boolean;
+}
 declare function getElectricCliEnv(env?: NodeJS.ProcessEnv): ElectricCliEnv;
+declare function formatQuickstartBackendStartedMessage({
+  commandPrefix,
+  uiUrl,
+  color,
+  trueColor
+}: QuickstartBackendStartedMessageOptions): string;
 declare function resolveCommandPrefix(argv: Array<string>, env?: InvocationEnv): string;
 declare function createElectricCliHandlers(env: ElectricCliEnv, commandPrefix?: string): ElectricCliHandlers;
 declare function createElectricProgram({
@@ -110,4 +123,4 @@ declare function createElectricProgram({
 declare function run(argv?: Array<string>): Promise<void>;
 
 //#endregion
-export { DEFAULT_ELECTRIC_AGENTS_URL, ElectricCliEnv, ElectricCliHandlers, ObserveCommandOptions, PsCommandOptions, SendCommandOptions, SpawnCommandOptions, StartBuiltinCommandOptions, StartCommandOptions, StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StopCommandOptions, StoppedDevEnvironment, createElectricCliHandlers, createElectricProgram, getElectricCliEnv, getStartedBuiltinAgentsMessage, getStartedEnvironmentMessage, getStoppedEnvironmentMessage, readDotEnvFile, resolveAnthropicApiKey, resolveBuiltinAgentsPort, resolveCommandPrefix, resolveComposeProjectName, resolveElectricAgentsPort, run, startBuiltinAgentsServer, startElectricAgentsDevEnvironment, stopElectricAgentsDevEnvironment, waitForElectricAgentsServer };
+export { DEFAULT_ELECTRIC_AGENTS_URL, ElectricCliEnv, ElectricCliHandlers, ObserveCommandOptions, PsCommandOptions, SendCommandOptions, SpawnCommandOptions, StartBuiltinCommandOptions, StartCommandOptions, StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StopCommandOptions, StoppedDevEnvironment, createElectricCliHandlers, createElectricProgram, formatQuickstartBackendStartedMessage, getElectricCliEnv, getStartedBuiltinAgentsMessage, getStartedEnvironmentMessage, getStoppedEnvironmentMessage, readDotEnvFile, resolveAnthropicApiKey, resolveBuiltinAgentsPort, resolveCommandPrefix, resolveComposeProjectName, resolveElectricAgentsPort, run, startBuiltinAgentsServer, startElectricAgentsDevEnvironment, stopElectricAgentsDevEnvironment, waitForElectricAgentsServer };

package/dist/{index-DS2RpaPZ.d.ts → index-si6k6XW1.d.ts}

@@ -42,6 +42,7 @@ declare function startBuiltinAgentsServer(options: StartBuiltinCommandOptions, p
   env?: NodeJS.ProcessEnv;
   cwd?: string;
   agentServerUrl?: string;
+  printStartedMessage?: boolean;
 }): Promise<StartedBuiltinAgentsEnvironment>;
 
 //#endregion
@@ -93,7 +94,19 @@ interface InvocationEnv {
   npm_command?: string;
   npm_config_user_agent?: string;
 }
+interface QuickstartBackendStartedMessageOptions {
+  commandPrefix: string;
+  uiUrl: string;
+  color?: boolean;
+  trueColor?: boolean;
+}
 declare function getElectricCliEnv(env?: NodeJS.ProcessEnv): ElectricCliEnv;
+declare function formatQuickstartBackendStartedMessage({
+  commandPrefix,
+  uiUrl,
+  color,
+  trueColor
+}: QuickstartBackendStartedMessageOptions): string;
 declare function resolveCommandPrefix(argv: Array<string>, env?: InvocationEnv): string;
 declare function createElectricCliHandlers(env: ElectricCliEnv, commandPrefix?: string): ElectricCliHandlers;
 declare function createElectricProgram({
@@ -110,4 +123,4 @@ declare function createElectricProgram({
 declare function run(argv?: Array<string>): Promise<void>;
 
 //#endregion
-export { DEFAULT_ELECTRIC_AGENTS_URL, ElectricCliEnv, ElectricCliHandlers, ObserveCommandOptions, PsCommandOptions, SendCommandOptions, SpawnCommandOptions, StartBuiltinCommandOptions, StartCommandOptions, StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StopCommandOptions, StoppedDevEnvironment, createElectricCliHandlers, createElectricProgram, getElectricCliEnv, getStartedBuiltinAgentsMessage, getStartedEnvironmentMessage, getStoppedEnvironmentMessage, readDotEnvFile, resolveAnthropicApiKey, resolveBuiltinAgentsPort, resolveCommandPrefix, resolveComposeProjectName, resolveElectricAgentsPort, run, startBuiltinAgentsServer, startElectricAgentsDevEnvironment, stopElectricAgentsDevEnvironment, waitForElectricAgentsServer };
+export { DEFAULT_ELECTRIC_AGENTS_URL, ElectricCliEnv, ElectricCliHandlers, ObserveCommandOptions, PsCommandOptions, SendCommandOptions, SpawnCommandOptions, StartBuiltinCommandOptions, StartCommandOptions, StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StopCommandOptions, StoppedDevEnvironment, createElectricCliHandlers, createElectricProgram, formatQuickstartBackendStartedMessage, getElectricCliEnv, getStartedBuiltinAgentsMessage, getStartedEnvironmentMessage, getStoppedEnvironmentMessage, readDotEnvFile, resolveAnthropicApiKey, resolveBuiltinAgentsPort, resolveCommandPrefix, resolveComposeProjectName, resolveElectricAgentsPort, run, startBuiltinAgentsServer, startElectricAgentsDevEnvironment, stopElectricAgentsDevEnvironment, waitForElectricAgentsServer };

package/dist/index.cjs

@@ -11,33 +11,11 @@ const commander = require_chunk.__toESM(require("commander"));
 const node_readline_promises = require_chunk.__toESM(require("node:readline/promises"));
 
 //#region src/prompt-api-key.ts
-const FRIENDLY_INTRO = [
-	``,
-	`The Electric Agents quickstart requires setting an API key to connect to an LLM provider.`,
-	``,
-	`Currently (in this initial developer preview release) the key must be an ANTHROPIC_API_KEY.`,
-	`Support for other LLM providers is coming very soon.`,
-	``,
-	`Note that your API key never leaves your local computer. It's used by the agent entities`,
-	`installed by default in the Electric Agents runtime and by the example agents included`,
-	`in the quickstart template.`,
-	``,
-	`Would you like to:`,
-	``,
-	`  1. manually setup a .env file with ANTHROPIC_API_KEY=...`,
-	`  2. paste your api key into a prompt and we'll set it up for you`,
-	``
-].join(`\n`);
-const MANUAL_SETUP_INSTRUCTIONS = [
-	``,
-	`No problem. To finish setup:`,
-	``,
-	`  1. Get a key from https://console.anthropic.com/settings/keys`,
-	`  2. Add a line to your .env file:`,
-	`         ANTHROPIC_API_KEY=sk-ant-...`,
-	`  3. Re-run the command.`,
-	``
-].join(`\n`);
+const FRIENDLY_INTRO = `\n${[
+	`Provide an Anthropic Claude key to connect Electric Agents to an LLM provider. Support for other LLM providers is coming soon.`,
+	`Your API key never leaves your local computer. It's used by the agent entities installed by default in the Electric Agents runtime and by the example agents included in the quickstart template.`,
+	`Paste the Anthropic key, or press Enter without typing a key to cancel and set it up manually in .env or pass --anthropic-api-key on the command line.`
+].join(`\n\n`)}\n\n`;
 function defaultPromptIO() {
 	return {
 		input: process.stdin,
@@ -47,37 +25,91 @@ function defaultPromptIO() {
 		exit: process.exit.bind(process)
 	};
 }
+function parsePastedAnthropicApiKey(input) {
+	const trimmed = input.trim();
+	const match = trimmed.match(/^(?:export\s+)?ANTHROPIC_API_KEY\s*[:=]\s*(.*)$/s);
+	const value = (match?.[1] ?? trimmed).trim();
+	if (value.startsWith(`"`) && value.endsWith(`"`) || value.startsWith(`'`) && value.endsWith(`'`)) return value.slice(1, -1).trim();
+	return value;
+}
+function assertAnthropicApiKeyPrefix(key) {
+	if (!key.startsWith(`sk-ant-`)) throw new Error(`ANTHROPIC_API_KEY must look like an Anthropic API key (expected it to start with sk-ant-).`);
+}
+async function validateAnthropicApiKey(key, fetchImpl = globalThis.fetch) {
+	let response;
+	try {
+		response = await fetchImpl(`https://api.anthropic.com/v1/models?limit=1`, {
+			headers: {
+				"anthropic-version": `2023-06-01`,
+				"x-api-key": key
+			},
+			signal: AbortSignal.timeout(5e3)
+		});
+	} catch (error) {
+		throw new Error(`Could not validate ANTHROPIC_API_KEY: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (response.ok) return;
+	const body = await response.text();
+	let detail = body.trim();
+	try {
+		const parsed = JSON.parse(body);
+		detail = parsed.error?.message ?? detail;
+	} catch {}
+	if (response.status === 401 || response.status === 403) throw new Error(`ANTHROPIC_API_KEY validation failed: ${detail || response.statusText}`);
+	throw new Error(`Could not validate ANTHROPIC_API_KEY: Anthropic returned ${response.status}${detail ? ` (${detail})` : ``}`);
+}
 async function ensureAnthropicApiKey(options, io = defaultPromptIO()) {
+	const validate = io.validateAnthropicApiKey ?? validateAnthropicApiKey;
+	const explicitKey = options.anthropicApiKey?.trim();
+	let initialError;
+	if (explicitKey) {
+		assertAnthropicApiKeyPrefix(explicitKey);
+		await validate(explicitKey);
+		return explicitKey;
+	}
 	try {
-		return require_env.resolveAnthropicApiKey(options);
+		const key = require_env.resolveAnthropicApiKey(options);
+		assertAnthropicApiKeyPrefix(key);
+		await validate(key);
+		return key;
 	} catch (error) {
 		if (!io.isTTY) throw error;
+		initialError = error;
 	}
 	io.output.write(FRIENDLY_INTRO);
+	if (initialError) io.output.write(`${formatValidationError(initialError)}\n\n`);
 	const rl = (0, node_readline_promises.createInterface)({
 		input: io.input,
 		output: io.output
 	});
 	try {
-		const choice = (await rl.question(`Enter 1/2: `)).trim();
-		if (choice === `1`) {
-			io.output.write(MANUAL_SETUP_INSTRUCTIONS);
-			io.exit(0);
-			throw new Error(`unreachable`);
-		}
-		if (choice === `2`) {
-			const key = (await rl.question(`Paste your ANTHROPIC_API_KEY: `)).trim();
-			if (!key) throw new Error(`No API key provided. Re-run the command and try again.`);
+		for (;;) {
+			const pasted = await rl.question(`ANTHROPIC_API_KEY: `);
+			const key = parsePastedAnthropicApiKey(pasted);
+			if (!key) {
+				io.output.write(`\nCancelled. Add ANTHROPIC_API_KEY=sk-ant-... to .env and re-run the command.\n\n`);
+				io.exit(0);
+				throw new Error(`unreachable`);
+			}
+			try {
+				assertAnthropicApiKeyPrefix(key);
+				await validate(key);
+			} catch (error) {
+				io.output.write(`${formatValidationError(error)}\n\n`);
+				continue;
+			}
 			const envPath = writeApiKeyToDotEnv(key, io.cwd);
 			process.env.ANTHROPIC_API_KEY = key;
 			io.output.write(`\nSaved ANTHROPIC_API_KEY to ${envPath}\n\n`);
 			return key;
 		}
-		throw new Error(`Unrecognized choice ${JSON.stringify(choice)}. Please re-run the command and enter 1 or 2.`);
 	} finally {
 		rl.close();
 	}
 }
+function formatValidationError(error) {
+	return `Could not use that Anthropic key: ${error instanceof Error ? error.message : String(error)}`;
+}
 function writeApiKeyToDotEnv(key, cwd) {
 	const envPath = (0, node_path.resolve)(cwd, `.env`);
 	const newLine = `ANTHROPIC_API_KEY=${key}`;
@@ -150,6 +182,79 @@ function resolveCommandName(argv) {
 function commandExample(commandName) {
 	return `${commandName} agents`;
 }
+function stripAnsi(value) {
+	return value.replace(/\x1b\[[0-9;]*m/g, ``);
+}
+function visibleLength(value) {
+	return stripAnsi(value).length;
+}
+function supportsColor(output = process.stdout, env = process.env) {
+	if (env.NO_COLOR !== void 0) return false;
+	if (env.FORCE_COLOR !== void 0 && env.FORCE_COLOR !== `0`) return true;
+	if (!output.isTTY) return false;
+	return output.getColorDepth(env) >= 4;
+}
+function supportsTrueColor(output = process.stdout, env = process.env) {
+	if (!supportsColor(output, env)) return false;
+	return output.getColorDepth(env) >= 24;
+}
+function colorBorder(value, opts) {
+	if (!opts.color) return value;
+	const color = opts.trueColor ? `\x1b[38;2;86;232;234m` : `\x1b[36m`;
+	return `${color}${value}\x1b[0m`;
+}
+function styleCommandPrefix(commandPrefix) {
+	return commandPrefix;
+}
+function styleElectricAgentsWithOptions(value, opts) {
+	if (!opts.color) return value;
+	const color = opts.trueColor ? `\x1b[38;2;86;232;234m` : `\x1b[36m`;
+	return `\x1b[1m${color}${value}\x1b[0m`;
+}
+function underline(value, color) {
+	if (!color) return value;
+	return `\x1b[4m${value}\x1b[24m`;
+}
+function grey(value, color) {
+	if (!color) return value;
+	return `\x1b[90m${value}\x1b[0m`;
+}
+function boxLines(lines, opts) {
+	const width = Math.max(...lines.map(visibleLength));
+	const top = colorBorder(`╔${`═`.repeat(width + 2)}╗`, opts);
+	const body = lines.map((line) => {
+		const padding = ` `.repeat(width - visibleLength(line));
+		return `${colorBorder(`║`, opts)} ${line}${padding} ` + colorBorder(`║`, opts);
+	});
+	const bottom = colorBorder(`╚${`═`.repeat(width + 2)}╝`, opts);
+	return [
+		top,
+		...body,
+		bottom
+	].join(`\n`);
+}
+function formatQuickstartBackendStartedMessage({ commandPrefix, uiUrl, color = supportsColor(), trueColor = supportsTrueColor() }) {
+	const styledCommandPrefix = styleCommandPrefix(commandPrefix);
+	return boxLines([
+		`${styleElectricAgentsWithOptions(`electric agents`, {
+			color,
+			trueColor
+		})} server is up`,
+		``,
+		`Open a separate terminal and run:`,
+		`  ${styledCommandPrefix} spawn /horton/onboarding`,
+		`  ${styledCommandPrefix} send /horton/onboarding "Onboard me to Electric Agents"`,
+		``,
+		`You can see all agents in the UI or CLI:`,
+		`  UI: ${underline(uiUrl, color)}`,
+		`  CLI: ${styledCommandPrefix} observe /horton/onboarding`,
+		``,
+		grey(`Keep this window open to run the built-in agents`, color)
+	], {
+		color,
+		trueColor
+	});
+}
 function resolveCommandPrefix(argv, env = process.env) {
 	if (env.npm_command === `exec`) {
 		const userAgent = env.npm_config_user_agent ?? ``;
@@ -345,7 +450,11 @@ function createElectricCliHandlers(env, commandPrefix = commandExample(`electric
 			return started;
 		},
 		startBuiltin: async (options) => {
-			options.anthropicApiKey = await ensureAnthropicApiKey(options);
+			try {
+				options.anthropicApiKey = await ensureAnthropicApiKey(options);
+			} catch (error) {
+				fail(getErrorMessage(error));
+			}
 			const { startBuiltinAgentsServer } = await loadStartModule();
 			return startBuiltinAgentsServer(options, { agentServerUrl: env.electricAgentsUrl });
 		},
@@ -356,24 +465,24 @@ function createElectricCliHandlers(env, commandPrefix = commandExample(`electric
 			return stopped;
 		},
 		quickstart: async (options) => {
-			options.anthropicApiKey = await ensureAnthropicApiKey(options);
+			try {
+				options.anthropicApiKey = await ensureAnthropicApiKey(options);
+			} catch (error) {
+				fail(getErrorMessage(error));
+			}
 			const { startBuiltinAgentsServer, startElectricAgentsDevEnvironment } = await loadStartModule();
 			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(formatQuickstartBackendStartedMessage({
+				commandPrefix,
+				uiUrl: started.uiUrl
+			}));
 			console.log(``);
-			await startBuiltinAgentsServer(options, { agentServerUrl: started.uiUrl });
+			await startBuiltinAgentsServer(options, {
+				agentServerUrl: started.uiUrl,
+				printStartedMessage: false
+			});
 		},
 		init: async (projectName) => {
 			const { initProject } = await import(`./init.js`);
@@ -392,8 +501,8 @@ Environment:
 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} send /horton/onboarding "Help me onboard to Electric Agents"
+  $ ${agentsCommand} observe /horton/onboarding
   $ ${agentsCommand} start
   $ ${agentsCommand} start-builtin --anthropic-api-key sk-ant-...
   $ ${agentsCommand} stop --remove-volumes
@@ -524,6 +633,7 @@ if (isMainModule()) run().catch((error) => {
 exports.DEFAULT_ELECTRIC_AGENTS_URL = DEFAULT_ELECTRIC_AGENTS_URL
 exports.createElectricCliHandlers = createElectricCliHandlers
 exports.createElectricProgram = createElectricProgram
+exports.formatQuickstartBackendStartedMessage = formatQuickstartBackendStartedMessage
 exports.getElectricCliEnv = getElectricCliEnv
 exports.resolveCommandPrefix = resolveCommandPrefix
 exports.run = run

package/dist/index.d.cts

@@ -1,3 +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-BNTf2uZL.cjs";
-export { DEFAULT_ELECTRIC_AGENTS_URL, ElectricCliEnv, ElectricCliHandlers, ObserveCommandOptions, PsCommandOptions, SendCommandOptions, SpawnCommandOptions, StartBuiltinCommandOptions, StartCommandOptions, StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StopCommandOptions, StoppedDevEnvironment, createElectricCliHandlers, createElectricProgram, getElectricCliEnv, resolveCommandPrefix, run };
+import { DEFAULT_ELECTRIC_AGENTS_URL, ElectricCliEnv, ElectricCliHandlers, ObserveCommandOptions, PsCommandOptions, SendCommandOptions, SpawnCommandOptions, StartBuiltinCommandOptions, StartCommandOptions, StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StopCommandOptions, StoppedDevEnvironment, createElectricCliHandlers, createElectricProgram, formatQuickstartBackendStartedMessage, getElectricCliEnv, resolveCommandPrefix, run } from "./index-Dgoj3VzA.cjs";
+export { DEFAULT_ELECTRIC_AGENTS_URL, ElectricCliEnv, ElectricCliHandlers, ObserveCommandOptions, PsCommandOptions, SendCommandOptions, SpawnCommandOptions, StartBuiltinCommandOptions, StartCommandOptions, StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StopCommandOptions, StoppedDevEnvironment, createElectricCliHandlers, createElectricProgram, formatQuickstartBackendStartedMessage, getElectricCliEnv, resolveCommandPrefix, run };

package/dist/index.d.ts

@@ -1,3 +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-DS2RpaPZ.js";
-export { DEFAULT_ELECTRIC_AGENTS_URL, ElectricCliEnv, ElectricCliHandlers, ObserveCommandOptions, PsCommandOptions, SendCommandOptions, SpawnCommandOptions, StartBuiltinCommandOptions, StartCommandOptions, StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StopCommandOptions, StoppedDevEnvironment, createElectricCliHandlers, createElectricProgram, getElectricCliEnv, resolveCommandPrefix, run };
+import { DEFAULT_ELECTRIC_AGENTS_URL, ElectricCliEnv, ElectricCliHandlers, ObserveCommandOptions, PsCommandOptions, SendCommandOptions, SpawnCommandOptions, StartBuiltinCommandOptions, StartCommandOptions, StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StopCommandOptions, StoppedDevEnvironment, createElectricCliHandlers, createElectricProgram, formatQuickstartBackendStartedMessage, getElectricCliEnv, resolveCommandPrefix, run } from "./index-si6k6XW1.js";
+export { DEFAULT_ELECTRIC_AGENTS_URL, ElectricCliEnv, ElectricCliHandlers, ObserveCommandOptions, PsCommandOptions, SendCommandOptions, SpawnCommandOptions, StartBuiltinCommandOptions, StartCommandOptions, StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StopCommandOptions, StoppedDevEnvironment, createElectricCliHandlers, createElectricProgram, formatQuickstartBackendStartedMessage, getElectricCliEnv, resolveCommandPrefix, run };

package/dist/index.js

@@ -9,33 +9,11 @@ import { Command } from "commander";
 import { createInterface } from "node:readline/promises";
 
 //#region src/prompt-api-key.ts
-const FRIENDLY_INTRO = [
-	``,
-	`The Electric Agents quickstart requires setting an API key to connect to an LLM provider.`,
-	``,
-	`Currently (in this initial developer preview release) the key must be an ANTHROPIC_API_KEY.`,
-	`Support for other LLM providers is coming very soon.`,
-	``,
-	`Note that your API key never leaves your local computer. It's used by the agent entities`,
-	`installed by default in the Electric Agents runtime and by the example agents included`,
-	`in the quickstart template.`,
-	``,
-	`Would you like to:`,
-	``,
-	`  1. manually setup a .env file with ANTHROPIC_API_KEY=...`,
-	`  2. paste your api key into a prompt and we'll set it up for you`,
-	``
-].join(`\n`);
-const MANUAL_SETUP_INSTRUCTIONS = [
-	``,
-	`No problem. To finish setup:`,
-	``,
-	`  1. Get a key from https://console.anthropic.com/settings/keys`,
-	`  2. Add a line to your .env file:`,
-	`         ANTHROPIC_API_KEY=sk-ant-...`,
-	`  3. Re-run the command.`,
-	``
-].join(`\n`);
+const FRIENDLY_INTRO = `\n${[
+	`Provide an Anthropic Claude key to connect Electric Agents to an LLM provider. Support for other LLM providers is coming soon.`,
+	`Your API key never leaves your local computer. It's used by the agent entities installed by default in the Electric Agents runtime and by the example agents included in the quickstart template.`,
+	`Paste the Anthropic key, or press Enter without typing a key to cancel and set it up manually in .env or pass --anthropic-api-key on the command line.`
+].join(`\n\n`)}\n\n`;
 function defaultPromptIO() {
 	return {
 		input: process.stdin,
@@ -45,37 +23,91 @@ function defaultPromptIO() {
 		exit: process.exit.bind(process)
 	};
 }
+function parsePastedAnthropicApiKey(input) {
+	const trimmed = input.trim();
+	const match = trimmed.match(/^(?:export\s+)?ANTHROPIC_API_KEY\s*[:=]\s*(.*)$/s);
+	const value = (match?.[1] ?? trimmed).trim();
+	if (value.startsWith(`"`) && value.endsWith(`"`) || value.startsWith(`'`) && value.endsWith(`'`)) return value.slice(1, -1).trim();
+	return value;
+}
+function assertAnthropicApiKeyPrefix(key) {
+	if (!key.startsWith(`sk-ant-`)) throw new Error(`ANTHROPIC_API_KEY must look like an Anthropic API key (expected it to start with sk-ant-).`);
+}
+async function validateAnthropicApiKey(key, fetchImpl = globalThis.fetch) {
+	let response;
+	try {
+		response = await fetchImpl(`https://api.anthropic.com/v1/models?limit=1`, {
+			headers: {
+				"anthropic-version": `2023-06-01`,
+				"x-api-key": key
+			},
+			signal: AbortSignal.timeout(5e3)
+		});
+	} catch (error) {
+		throw new Error(`Could not validate ANTHROPIC_API_KEY: ${error instanceof Error ? error.message : String(error)}`);
+	}
+	if (response.ok) return;
+	const body = await response.text();
+	let detail = body.trim();
+	try {
+		const parsed = JSON.parse(body);
+		detail = parsed.error?.message ?? detail;
+	} catch {}
+	if (response.status === 401 || response.status === 403) throw new Error(`ANTHROPIC_API_KEY validation failed: ${detail || response.statusText}`);
+	throw new Error(`Could not validate ANTHROPIC_API_KEY: Anthropic returned ${response.status}${detail ? ` (${detail})` : ``}`);
+}
 async function ensureAnthropicApiKey(options, io = defaultPromptIO()) {
+	const validate = io.validateAnthropicApiKey ?? validateAnthropicApiKey;
+	const explicitKey = options.anthropicApiKey?.trim();
+	let initialError;
+	if (explicitKey) {
+		assertAnthropicApiKeyPrefix(explicitKey);
+		await validate(explicitKey);
+		return explicitKey;
+	}
 	try {
-		return resolveAnthropicApiKey(options);
+		const key = resolveAnthropicApiKey(options);
+		assertAnthropicApiKeyPrefix(key);
+		await validate(key);
+		return key;
 	} catch (error) {
 		if (!io.isTTY) throw error;
+		initialError = error;
 	}
 	io.output.write(FRIENDLY_INTRO);
+	if (initialError) io.output.write(`${formatValidationError(initialError)}\n\n`);
 	const rl = createInterface({
 		input: io.input,
 		output: io.output
 	});
 	try {
-		const choice = (await rl.question(`Enter 1/2: `)).trim();
-		if (choice === `1`) {
-			io.output.write(MANUAL_SETUP_INSTRUCTIONS);
-			io.exit(0);
-			throw new Error(`unreachable`);
-		}
-		if (choice === `2`) {
-			const key = (await rl.question(`Paste your ANTHROPIC_API_KEY: `)).trim();
-			if (!key) throw new Error(`No API key provided. Re-run the command and try again.`);
+		for (;;) {
+			const pasted = await rl.question(`ANTHROPIC_API_KEY: `);
+			const key = parsePastedAnthropicApiKey(pasted);
+			if (!key) {
+				io.output.write(`\nCancelled. Add ANTHROPIC_API_KEY=sk-ant-... to .env and re-run the command.\n\n`);
+				io.exit(0);
+				throw new Error(`unreachable`);
+			}
+			try {
+				assertAnthropicApiKeyPrefix(key);
+				await validate(key);
+			} catch (error) {
+				io.output.write(`${formatValidationError(error)}\n\n`);
+				continue;
+			}
 			const envPath = writeApiKeyToDotEnv(key, io.cwd);
 			process.env.ANTHROPIC_API_KEY = key;
 			io.output.write(`\nSaved ANTHROPIC_API_KEY to ${envPath}\n\n`);
 			return key;
 		}
-		throw new Error(`Unrecognized choice ${JSON.stringify(choice)}. Please re-run the command and enter 1 or 2.`);
 	} finally {
 		rl.close();
 	}
 }
+function formatValidationError(error) {
+	return `Could not use that Anthropic key: ${error instanceof Error ? error.message : String(error)}`;
+}
 function writeApiKeyToDotEnv(key, cwd) {
 	const envPath = resolve(cwd, `.env`);
 	const newLine = `ANTHROPIC_API_KEY=${key}`;
@@ -148,6 +180,79 @@ function resolveCommandName(argv) {
 function commandExample(commandName) {
 	return `${commandName} agents`;
 }
+function stripAnsi(value) {
+	return value.replace(/\x1b\[[0-9;]*m/g, ``);
+}
+function visibleLength(value) {
+	return stripAnsi(value).length;
+}
+function supportsColor(output = process.stdout, env = process.env) {
+	if (env.NO_COLOR !== void 0) return false;
+	if (env.FORCE_COLOR !== void 0 && env.FORCE_COLOR !== `0`) return true;
+	if (!output.isTTY) return false;
+	return output.getColorDepth(env) >= 4;
+}
+function supportsTrueColor(output = process.stdout, env = process.env) {
+	if (!supportsColor(output, env)) return false;
+	return output.getColorDepth(env) >= 24;
+}
+function colorBorder(value, opts) {
+	if (!opts.color) return value;
+	const color = opts.trueColor ? `\x1b[38;2;86;232;234m` : `\x1b[36m`;
+	return `${color}${value}\x1b[0m`;
+}
+function styleCommandPrefix(commandPrefix) {
+	return commandPrefix;
+}
+function styleElectricAgentsWithOptions(value, opts) {
+	if (!opts.color) return value;
+	const color = opts.trueColor ? `\x1b[38;2;86;232;234m` : `\x1b[36m`;
+	return `\x1b[1m${color}${value}\x1b[0m`;
+}
+function underline(value, color) {
+	if (!color) return value;
+	return `\x1b[4m${value}\x1b[24m`;
+}
+function grey(value, color) {
+	if (!color) return value;
+	return `\x1b[90m${value}\x1b[0m`;
+}
+function boxLines(lines, opts) {
+	const width = Math.max(...lines.map(visibleLength));
+	const top = colorBorder(`╔${`═`.repeat(width + 2)}╗`, opts);
+	const body = lines.map((line) => {
+		const padding = ` `.repeat(width - visibleLength(line));
+		return `${colorBorder(`║`, opts)} ${line}${padding} ` + colorBorder(`║`, opts);
+	});
+	const bottom = colorBorder(`╚${`═`.repeat(width + 2)}╝`, opts);
+	return [
+		top,
+		...body,
+		bottom
+	].join(`\n`);
+}
+function formatQuickstartBackendStartedMessage({ commandPrefix, uiUrl, color = supportsColor(), trueColor = supportsTrueColor() }) {
+	const styledCommandPrefix = styleCommandPrefix(commandPrefix);
+	return boxLines([
+		`${styleElectricAgentsWithOptions(`electric agents`, {
+			color,
+			trueColor
+		})} server is up`,
+		``,
+		`Open a separate terminal and run:`,
+		`  ${styledCommandPrefix} spawn /horton/onboarding`,
+		`  ${styledCommandPrefix} send /horton/onboarding "Onboard me to Electric Agents"`,
+		``,
+		`You can see all agents in the UI or CLI:`,
+		`  UI: ${underline(uiUrl, color)}`,
+		`  CLI: ${styledCommandPrefix} observe /horton/onboarding`,
+		``,
+		grey(`Keep this window open to run the built-in agents`, color)
+	], {
+		color,
+		trueColor
+	});
+}
 function resolveCommandPrefix(argv, env = process.env) {
 	if (env.npm_command === `exec`) {
 		const userAgent = env.npm_config_user_agent ?? ``;
@@ -343,7 +448,11 @@ function createElectricCliHandlers(env, commandPrefix = commandExample(`electric
 			return started;
 		},
 		startBuiltin: async (options) => {
-			options.anthropicApiKey = await ensureAnthropicApiKey(options);
+			try {
+				options.anthropicApiKey = await ensureAnthropicApiKey(options);
+			} catch (error) {
+				fail(getErrorMessage(error));
+			}
 			const { startBuiltinAgentsServer } = await loadStartModule();
 			return startBuiltinAgentsServer(options, { agentServerUrl: env.electricAgentsUrl });
 		},
@@ -354,24 +463,24 @@ function createElectricCliHandlers(env, commandPrefix = commandExample(`electric
 			return stopped;
 		},
 		quickstart: async (options) => {
-			options.anthropicApiKey = await ensureAnthropicApiKey(options);
+			try {
+				options.anthropicApiKey = await ensureAnthropicApiKey(options);
+			} catch (error) {
+				fail(getErrorMessage(error));
+			}
 			const { startBuiltinAgentsServer, startElectricAgentsDevEnvironment } = await loadStartModule();
 			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(formatQuickstartBackendStartedMessage({
+				commandPrefix,
+				uiUrl: started.uiUrl
+			}));
 			console.log(``);
-			await startBuiltinAgentsServer(options, { agentServerUrl: started.uiUrl });
+			await startBuiltinAgentsServer(options, {
+				agentServerUrl: started.uiUrl,
+				printStartedMessage: false
+			});
 		},
 		init: async (projectName) => {
 			const { initProject } = await import(`./init.js`);
@@ -390,8 +499,8 @@ Environment:
 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} send /horton/onboarding "Help me onboard to Electric Agents"
+  $ ${agentsCommand} observe /horton/onboarding
   $ ${agentsCommand} start
   $ ${agentsCommand} start-builtin --anthropic-api-key sk-ant-...
   $ ${agentsCommand} stop --remove-volumes
@@ -519,4 +628,4 @@ if (isMainModule()) run().catch((error) => {
 });
 
 //#endregion
-export { DEFAULT_ELECTRIC_AGENTS_URL, createElectricCliHandlers, createElectricProgram, getElectricCliEnv, resolveCommandPrefix, run };
+export { DEFAULT_ELECTRIC_AGENTS_URL, createElectricCliHandlers, createElectricProgram, formatQuickstartBackendStartedMessage, getElectricCliEnv, resolveCommandPrefix, run };

package/dist/start.cjs

@@ -193,7 +193,7 @@ async function startBuiltinAgentsServer(options, params = {}) {
 		registeredBaseUrl: server.registeredBaseUrl,
 		agentServerUrl
 	};
-	console.log(getStartedBuiltinAgentsMessage(started));
+	if (params.printStartedMessage ?? true) console.log(getStartedBuiltinAgentsMessage(started));
 	await waitForShutdown(() => server.stop());
 	return started;
 }

package/dist/start.d.cts

@@ -1,2 +1,2 @@
-import { StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StoppedDevEnvironment, getStartedBuiltinAgentsMessage, getStartedEnvironmentMessage, getStoppedEnvironmentMessage, readDotEnvFile, resolveAnthropicApiKey, resolveBuiltinAgentsPort, resolveComposeProjectName, resolveElectricAgentsPort, startBuiltinAgentsServer, startElectricAgentsDevEnvironment, stopElectricAgentsDevEnvironment, waitForElectricAgentsServer } from "./index-BNTf2uZL.cjs";
+import { StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StoppedDevEnvironment, getStartedBuiltinAgentsMessage, getStartedEnvironmentMessage, getStoppedEnvironmentMessage, readDotEnvFile, resolveAnthropicApiKey, resolveBuiltinAgentsPort, resolveComposeProjectName, resolveElectricAgentsPort, startBuiltinAgentsServer, startElectricAgentsDevEnvironment, stopElectricAgentsDevEnvironment, waitForElectricAgentsServer } from "./index-Dgoj3VzA.cjs";
 export { StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StoppedDevEnvironment, getStartedBuiltinAgentsMessage, getStartedEnvironmentMessage, getStoppedEnvironmentMessage, readDotEnvFile, resolveAnthropicApiKey, resolveBuiltinAgentsPort, resolveComposeProjectName, resolveElectricAgentsPort, startBuiltinAgentsServer, startElectricAgentsDevEnvironment, stopElectricAgentsDevEnvironment, waitForElectricAgentsServer };

package/dist/start.d.ts

@@ -1,2 +1,2 @@
-import { StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StoppedDevEnvironment, getStartedBuiltinAgentsMessage, getStartedEnvironmentMessage, getStoppedEnvironmentMessage, readDotEnvFile, resolveAnthropicApiKey, resolveBuiltinAgentsPort, resolveComposeProjectName, resolveElectricAgentsPort, startBuiltinAgentsServer, startElectricAgentsDevEnvironment, stopElectricAgentsDevEnvironment, waitForElectricAgentsServer } from "./index-DS2RpaPZ.js";
+import { StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StoppedDevEnvironment, getStartedBuiltinAgentsMessage, getStartedEnvironmentMessage, getStoppedEnvironmentMessage, readDotEnvFile, resolveAnthropicApiKey, resolveBuiltinAgentsPort, resolveComposeProjectName, resolveElectricAgentsPort, startBuiltinAgentsServer, startElectricAgentsDevEnvironment, stopElectricAgentsDevEnvironment, waitForElectricAgentsServer } from "./index-si6k6XW1.js";
 export { StartedBuiltinAgentsEnvironment, StartedDevEnvironment, StoppedDevEnvironment, getStartedBuiltinAgentsMessage, getStartedEnvironmentMessage, getStoppedEnvironmentMessage, readDotEnvFile, resolveAnthropicApiKey, resolveBuiltinAgentsPort, resolveComposeProjectName, resolveElectricAgentsPort, startBuiltinAgentsServer, startElectricAgentsDevEnvironment, stopElectricAgentsDevEnvironment, waitForElectricAgentsServer };

package/dist/start.js

@@ -191,7 +191,7 @@ async function startBuiltinAgentsServer(options, params = {}) {
 		registeredBaseUrl: server.registeredBaseUrl,
 		agentServerUrl
 	};
-	console.log(getStartedBuiltinAgentsMessage(started));
+	if (params.printStartedMessage ?? true) console.log(getStartedBuiltinAgentsMessage(started));
 	await waitForShutdown(() => server.stop());
 	return started;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "electric-ax",
-  "version": "0.1.15",
+  "version": "0.1.16",
   "description": "CLI for Electric Agents",
   "author": "ElectricSQL team and contributors",
   "license": "Apache-2.0",
@@ -46,7 +46,7 @@
     "ink": "^6.8.0",
     "omelette": "^0.4.17",
     "react": "^19.2.0",
-    "@electric-ax/agents": "0.2.3",
+    "@electric-ax/agents": "0.2.4",
     "@electric-ax/agents-runtime": "0.1.2"
   },
   "devDependencies": {