@agent-team-foundation/first-tree-hub 0.2.0

package/dist/cli/index.mjs

@@ -0,0 +1,636 @@
+#!/usr/bin/env node
+import { A as loadRuntimeConfig, B as readConfigFile, C as stopPostgres, D as FirstTreeHubSDK, E as AgentSlot, F as agentConfigSchema, H as resetConfigMeta, I as clientConfigSchema, L as getConfigValue, M as createAdminUser, O as SdkError, P as DEFAULT_CONFIG_DIR, R as initConfig, T as AgentRuntime, U as serverConfigSchema, V as resetConfig, W as setConfigValue, _ as checkWebSocket, a as runMigrations, c as checkClientConfig, d as checkDocker, f as checkGitHubToken, g as checkServerReachable, h as checkServerHealth, i as promptMissingFields, j as registerBuiltinHandlers, k as getHandlerFactory, l as checkContextTreeRepo, m as checkServerConfig, o as checkAgentConfigs, p as checkNodeVersion, r as promptAddAgent, s as checkAgentTokens, t as startServer, u as checkDatabase, v as printResults, w as ClientRuntime, z as loadAgents } from "../core-CD3xEbyB.mjs";
+import { createRequire } from "node:module";
+import { Command } from "commander";
+import { existsSync, mkdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+//#region src/commands/admin.ts
+function registerAdminCommands(program) {
+	program.command("admin").description("Admin user management").command("create").description("Create an admin user").option("-u, --username <name>", "Admin username", "admin").option("-p, --password <pass>", "Admin password (auto-generated if omitted)").action(async (options) => {
+		try {
+			const result = await createAdminUser((await initConfig({
+				schema: serverConfigSchema,
+				role: "server"
+			})).database.url, options.username, options.password);
+			process.stderr.write(`  Admin user "${result.username}" created.\n`);
+			if (!options.password) process.stderr.write(`  Password: ${result.password}  (save this — shown only once)\n`);
+		} catch (error) {
+			const msg = error instanceof Error ? error.message : String(error);
+			process.stderr.write(`  Error: ${msg}\n`);
+			process.exit(1);
+		}
+	});
+}
+//#endregion
+//#region src/cli/output.ts
+/** Write a success JSON envelope to stdout. */
+function success(data) {
+	process.stdout.write(`${JSON.stringify({
+		ok: true,
+		data
+	})}\n`);
+}
+/** Write an error JSON envelope to stderr and exit with the given code. */
+function fail(code, message, exitCode = 1) {
+	process.stderr.write(`${JSON.stringify({
+		ok: false,
+		error: {
+			code,
+			message
+		}
+	})}\n`);
+	process.exit(exitCode);
+}
+//#endregion
+//#region src/commands/agent.ts
+function resolveAgentConfig() {
+	const token = process.env.FIRST_TREE_HUB_TOKEN;
+	if (!token) fail("MISSING_TOKEN", "FIRST_TREE_HUB_TOKEN environment variable is required.", 2);
+	return {
+		serverUrl: process.env.FIRST_TREE_HUB_SERVER ?? "http://localhost:8000",
+		token
+	};
+}
+function createSdk$1() {
+	return new FirstTreeHubSDK(resolveAgentConfig());
+}
+function handleError$1(error) {
+	if (error instanceof SdkError) {
+		const exitCode = error.statusCode === 401 ? 3 : 1;
+		fail(`HTTP_${error.statusCode}`, error.message, exitCode);
+	}
+	if (error instanceof TypeError && "cause" in error) fail("CONNECTION_ERROR", `Cannot connect to server: ${error.message}`, 6);
+	fail("UNKNOWN_ERROR", error instanceof Error ? error.message : String(error), 1);
+}
+function registerAgentCommands(program) {
+	program.command("register").description("Register this agent and return identity info").action(async () => {
+		try {
+			success(await createSdk$1().register());
+		} catch (error) {
+			handleError$1(error);
+		}
+	});
+	program.command("pull").description("Pull pending messages from inbox").option("-l, --limit <number>", "Maximum entries to return", "10").option("-a, --ack", "Automatically ACK entries after pulling").action(async (options) => {
+		try {
+			const sdk = createSdk$1();
+			const limit = Number.parseInt(options.limit, 10);
+			if (Number.isNaN(limit) || limit < 1 || limit > 50) fail("INVALID_LIMIT", "Limit must be between 1 and 50.", 2);
+			const result = await sdk.pull(limit);
+			if (options.ack && result.entries.length > 0) await Promise.all(result.entries.map((entry) => sdk.ack(entry.id)));
+			success(result);
+		} catch (error) {
+			handleError$1(error);
+		}
+	});
+}
+//#endregion
+//#region src/cli/util.ts
+function resolveConfig() {
+	const token = process.env.FIRST_TREE_HUB_TOKEN;
+	if (!token) fail("MISSING_TOKEN", "FIRST_TREE_HUB_TOKEN environment variable is required.", 2);
+	return {
+		serverUrl: process.env.FIRST_TREE_HUB_SERVER ?? "http://localhost:8000",
+		token
+	};
+}
+function createSdk() {
+	return new FirstTreeHubSDK(resolveConfig());
+}
+function handleError(error) {
+	if (error instanceof SdkError) {
+		const exitCode = error.statusCode === 401 ? 3 : 1;
+		fail(`HTTP_${error.statusCode}`, error.message, exitCode);
+	}
+	if (error instanceof TypeError && "cause" in error) fail("CONNECTION_ERROR", `Cannot connect to server: ${error.message}`, 6);
+	fail("UNKNOWN_ERROR", error instanceof Error ? error.message : String(error), 1);
+}
+/** Parse and validate a numeric limit option from Commander string. */
+function parseLimit(value, max) {
+	const limit = Number.parseInt(value, 10);
+	if (Number.isNaN(limit) || limit < 1 || limit > max) fail("INVALID_LIMIT", `Limit must be between 1 and ${max}.`, 2);
+	return limit;
+}
+/** Write a log line to stderr. */
+function log(tag, message) {
+	process.stderr.write(`[${tag}] ${message}\n`);
+}
+//#endregion
+//#region src/commands/chats.ts
+function registerChatsCommand(program) {
+	program.command("chats").description("List chats this agent participates in").option("-l, --limit <number>", "Maximum chats to return (1-100)", "20").option("--cursor <cursor>", "Pagination cursor from previous response").action(async (options) => {
+		try {
+			const limit = parseLimit(options.limit, 100);
+			success(await createSdk().listChats({
+				limit,
+				cursor: options.cursor
+			}));
+		} catch (error) {
+			handleError(error);
+		}
+	});
+}
+//#endregion
+//#region src/commands/client.ts
+function registerClientCommands(program) {
+	const client = program.command("client").description("Manage First Tree Hub client");
+	client.command("start").description("Start client — connect all configured agents to the server").option("--no-interactive", "Skip interactive prompts (for Docker/CI)").action(async (options) => {
+		try {
+			await promptMissingFields({
+				schema: clientConfigSchema,
+				role: "client",
+				noInteractive: options.interactive === false
+			});
+			const config = await initConfig({
+				schema: clientConfigSchema,
+				role: "client"
+			});
+			const agents = loadAgents({
+				schema: agentConfigSchema,
+				agentsDir: join(DEFAULT_CONFIG_DIR, "agents")
+			});
+			if (agents.size === 0) {
+				process.stderr.write("  No agents configured.\n");
+				process.stderr.write("  Add one with: first-tree-hub client add <name> --token <token>\n");
+				process.exit(1);
+			}
+			process.stderr.write(`\n  Connecting to ${config.server.url}...\n`);
+			const runtime = new ClientRuntime(config.server.url);
+			for (const [name, agentConfig] of agents) runtime.addAgent(name, agentConfig);
+			await runtime.start();
+			const shutdown = async () => {
+				process.stderr.write("\n  Shutting down...\n");
+				await runtime.stop();
+				process.exit(0);
+			};
+			process.on("SIGINT", () => void shutdown());
+			process.on("SIGTERM", () => void shutdown());
+			await new Promise(() => {});
+		} catch (error) {
+			const msg = error instanceof Error ? error.message : String(error);
+			process.stderr.write(`  Error: ${msg}\n`);
+			process.exit(1);
+		} finally {
+			resetConfig();
+			resetConfigMeta();
+		}
+	});
+	client.command("doctor").description("Check client environment readiness").action(async () => {
+		process.stderr.write("\n  First Tree Hub Client Doctor\n\n");
+		printResults([
+			checkNodeVersion(),
+			checkClientConfig(),
+			await checkServerReachable(),
+			checkAgentConfigs(),
+			await checkAgentTokens(),
+			await checkWebSocket()
+		]);
+	});
+	client.command("stop").description("Stop the client (sends SIGTERM to running process)").action(() => {
+		process.stderr.write("  Client stop: use Ctrl+C or `kill` the running process.\n");
+		process.stderr.write("  Daemon mode with PID file is planned for a future release.\n");
+	});
+	client.command("status").description("Show client and agent connection status").action(() => {
+		const agentsDir = join(DEFAULT_CONFIG_DIR, "agents");
+		try {
+			const agents = loadAgents({
+				schema: agentConfigSchema,
+				agentsDir
+			});
+			if (agents.size === 0) {
+				process.stderr.write("  No agents configured.\n");
+				return;
+			}
+			process.stderr.write("\n  Configured agents:\n\n");
+			for (const [name, config] of agents) {
+				const masked = config.token.length > 8 ? `${config.token.slice(0, 6)}***${config.token.slice(-2)}` : "***";
+				process.stderr.write(`  ${name.padEnd(20)} type: ${config.type.padEnd(14)} token: ${masked}\n`);
+			}
+			process.stderr.write("\n");
+		} catch {
+			process.stderr.write("  No agents directory found.\n");
+		}
+	});
+	client.command("add [name]").description("Add an agent instance").option("-t, --token <token>", "Agent token").action(async (name, options) => {
+		try {
+			let agentName = name;
+			let agentToken = options?.token;
+			if (!agentName || !agentToken) {
+				const result = await promptAddAgent();
+				agentName = agentName ?? result.name;
+				agentToken = agentToken ?? result.token;
+			}
+			const agentDir = join(DEFAULT_CONFIG_DIR, "agents", agentName);
+			mkdirSync(agentDir, {
+				recursive: true,
+				mode: 448
+			});
+			setConfigValue(join(agentDir, "agent.yaml"), "token", agentToken);
+			process.stderr.write(`  Agent "${agentName}" added.\n`);
+			process.stderr.write(`  Config: ${join(agentDir, "agent.yaml")}\n`);
+		} catch (error) {
+			if (error.name === "ExitPromptError") {
+				process.stderr.write("\n  Cancelled.\n");
+				return;
+			}
+			const msg = error instanceof Error ? error.message : String(error);
+			process.stderr.write(`  Error: ${msg}\n`);
+			process.exit(1);
+		}
+	});
+	client.command("remove <name>").description("Remove an agent instance").action((name) => {
+		const agentDir = join(DEFAULT_CONFIG_DIR, "agents", name);
+		if (!existsSync(agentDir)) {
+			process.stderr.write(`  Agent "${name}" not found.\n`);
+			process.exit(1);
+		}
+		rmSync(agentDir, {
+			recursive: true,
+			force: true
+		});
+		process.stderr.write(`  Agent "${name}" removed.\n`);
+	});
+	client.command("list").description("List configured agents").action(() => {
+		const agentsDir = join(DEFAULT_CONFIG_DIR, "agents");
+		try {
+			const agents = loadAgents({
+				schema: agentConfigSchema,
+				agentsDir
+			});
+			if (agents.size === 0) {
+				process.stderr.write("  No agents configured.\n");
+				return;
+			}
+			for (const [name, config] of agents) {
+				const masked = config.token.length > 8 ? `${config.token.slice(0, 6)}***${config.token.slice(-2)}` : "***";
+				process.stderr.write(`  ${name.padEnd(20)} type: ${config.type.padEnd(14)} token: ${masked}\n`);
+			}
+		} catch {
+			process.stderr.write("  No agents configured.\n");
+		}
+	});
+}
+//#endregion
+//#region src/commands/config.ts
+function resolveConfigPath(flags) {
+	if (flags.agent) return {
+		path: join(DEFAULT_CONFIG_DIR, "agents", flags.agent, "agent.yaml"),
+		schema: agentConfigSchema
+	};
+	if (flags.client) return {
+		path: join(DEFAULT_CONFIG_DIR, "client.yaml"),
+		schema: clientConfigSchema
+	};
+	return {
+		path: join(DEFAULT_CONFIG_DIR, "server.yaml"),
+		schema: serverConfigSchema
+	};
+}
+function addScopeOptions(cmd) {
+	return cmd.option("-s, --server", "Server config scope (default)").option("-c, --client", "Client config scope").option("-a, --agent <name>", "Agent config scope");
+}
+function registerConfigCommands(program) {
+	const config = program.command("config").description("Configuration management");
+	config.command("setup").description("Interactive configuration wizard").option("-s, --server", "Configure server (default)").option("-c, --client", "Configure client").action(async (flags) => {
+		try {
+			await promptMissingFields({
+				schema: flags.client ? clientConfigSchema : serverConfigSchema,
+				role: flags.client ? "client" : "server"
+			});
+			process.stderr.write("\n  Configuration saved.\n");
+		} catch (error) {
+			if (error.name === "ExitPromptError") {
+				process.stderr.write("\n  Cancelled.\n");
+				return;
+			}
+			throw error;
+		}
+	});
+	addScopeOptions(config.command("set").description("Set a config value")).argument("<key>", "Config key (dot notation, e.g. database.url)").argument("<value>", "Config value").action((key, value, flags) => {
+		const { path } = resolveConfigPath(flags);
+		let parsed = value;
+		if (value === "true") parsed = true;
+		else if (value === "false") parsed = false;
+		else if (/^\d+$/.test(value)) parsed = Number(value);
+		setConfigValue(path, key, parsed);
+		process.stderr.write(`  Set ${key} in ${path}\n`);
+	});
+	addScopeOptions(config.command("get").description("Get a config value")).argument("<key>", "Config key (dot notation)").option("--show-secrets", "Show secret values in plaintext").action((key, flags) => {
+		const { path, schema } = resolveConfigPath(flags);
+		const value = getConfigValue(path, key);
+		if (value === void 0) process.stderr.write(`  ${key}: (not set)\n`);
+		else {
+			const display = isSecretField(schema, key) && !flags.showSecrets ? "***" : String(value);
+			process.stderr.write(`  ${key}: ${display}\n`);
+		}
+	});
+	addScopeOptions(config.command("list").description("List all config values")).option("--show-secrets", "Show secret values in plaintext").action((flags) => {
+		const { path, schema } = resolveConfigPath(flags);
+		const values = readConfigFile(path);
+		if (Object.keys(values).length === 0) {
+			process.stderr.write(`  No config found at ${path}\n`);
+			return;
+		}
+		process.stderr.write(`\n  Config: ${path}\n\n`);
+		printFlat(values, schema, "", flags.showSecrets ?? false);
+		process.stderr.write("\n");
+	});
+}
+function printFlat(obj, schema, prefix, showSecrets) {
+	for (const [key, value] of Object.entries(obj)) {
+		const fullKey = prefix ? `${prefix}.${key}` : key;
+		if (typeof value === "object" && value !== null && !Array.isArray(value)) printFlat(value, schema, fullKey, showSecrets);
+		else {
+			const display = isSecretField(schema, fullKey) && !showSecrets ? "***" : String(value);
+			process.stderr.write(`  ${fullKey.padEnd(30)} ${display}\n`);
+		}
+	}
+}
+/** Check if a dot-path corresponds to a secret field in the schema. */
+function isSecretField(schema, dotPath) {
+	const parts = dotPath.split(".");
+	let current = schema;
+	for (const part of parts) {
+		if (current === null || current === void 0 || typeof current !== "object") return false;
+		const obj = current;
+		if (obj._tag === "optional") current = obj.shape[part];
+		else if (obj._tag === "field") return false;
+		else current = obj[part];
+	}
+	if (typeof current === "object" && current !== null && "_tag" in current) {
+		const field = current;
+		if (field._tag === "field") return field.options?.secret ?? false;
+	}
+	return false;
+}
+//#endregion
+//#region src/commands/db.ts
+function registerDbCommands(program) {
+	program.command("db").description("Database management").command("migrate").description("Run database migrations").action(async () => {
+		try {
+			const tableCount = await runMigrations((await initConfig({
+				schema: serverConfigSchema,
+				role: "server"
+			})).database.url);
+			process.stderr.write(`  Migrations complete (${tableCount} tables)\n`);
+		} catch (error) {
+			const msg = error instanceof Error ? error.message : String(error);
+			process.stderr.write(`  Error: ${msg}\n`);
+			process.exit(1);
+		}
+	});
+}
+//#endregion
+//#region src/commands/history.ts
+function registerHistoryCommand(program) {
+	program.command("history <chatId>").description("View message history in a chat").option("-l, --limit <number>", "Maximum messages to return (1-100)", "20").option("--cursor <cursor>", "Pagination cursor from previous response").action(async (chatId, options) => {
+		try {
+			const limit = parseLimit(options.limit, 100);
+			success(await createSdk().listMessages(chatId, {
+				limit,
+				cursor: options.cursor
+			}));
+		} catch (error) {
+			handleError(error);
+		}
+	});
+}
+//#endregion
+//#region src/commands/send.ts
+const MAX_STDIN_BYTES = 10 * 1024 * 1024;
+/** Read all of stdin as a string. Returns null if stdin is a TTY. */
+function readStdin() {
+	if (process.stdin.isTTY) return Promise.resolve(null);
+	return new Promise((resolve, reject) => {
+		const chunks = [];
+		let totalSize = 0;
+		process.stdin.on("data", (chunk) => {
+			totalSize += chunk.length;
+			if (totalSize > MAX_STDIN_BYTES) {
+				process.stdin.destroy();
+				reject(/* @__PURE__ */ new Error(`stdin exceeds ${MAX_STDIN_BYTES} bytes`));
+				return;
+			}
+			chunks.push(chunk);
+		});
+		process.stdin.on("end", () => resolve(Buffer.concat(chunks).toString("utf-8")));
+		process.stdin.on("error", reject);
+	});
+}
+function registerSendCommand(program) {
+	program.command("send <target> [message]").description("Send a message to an agent or chat").option("-f, --format <format>", "Message format (text|markdown|card)", "text").option("--chat", "Treat target as chat ID instead of agent ID").option("-m, --metadata <json>", "JSON metadata to attach").option("--reply-to <messageId>", "Message ID to reply to").option("--reply-to-inbox <inboxId>", "Cross-chat reply target inbox").option("--reply-to-chat <chatId>", "Cross-chat reply target chat").action(async (target, message, options) => {
+		try {
+			const content = message ?? await readStdin();
+			if (!content) fail("NO_MESSAGE", "No message provided. Pass as argument or pipe via stdin.", 2);
+			let metadata;
+			if (options.metadata) try {
+				metadata = JSON.parse(options.metadata);
+			} catch {
+				fail("INVALID_METADATA", "Metadata must be valid JSON.", 2);
+			}
+			const sdk = createSdk();
+			if (options.chat) success(await sdk.sendMessage(target, {
+				format: options.format,
+				content,
+				metadata,
+				inReplyTo: options.replyTo,
+				replyToInbox: options.replyToInbox,
+				replyToChat: options.replyToChat
+			}));
+			else success(await sdk.sendToAgent(target, {
+				format: options.format,
+				content,
+				metadata,
+				replyToInbox: options.replyToInbox,
+				replyToChat: options.replyToChat
+			}));
+		} catch (error) {
+			handleError(error);
+		}
+	});
+}
+//#endregion
+//#region src/commands/server.ts
+function registerServerCommands(program) {
+	const server = program.command("server").description("Manage First Tree Hub server");
+	server.command("start").description("Start the server (auto-provisions PostgreSQL if needed)").option("--port <number>", "Server port (default: 8000)", Number.parseInt).option("--host <address>", "Bind address (default: 127.0.0.1)").option("--database-url <url>", "Use an existing PostgreSQL (skip Docker)").option("--no-interactive", "Skip interactive prompts (for Docker/CI)").action(async (options) => {
+		try {
+			await startServer({
+				...options,
+				noInteractive: options.interactive === false
+			});
+		} catch (error) {
+			const msg = error instanceof Error ? error.message : String(error);
+			process.stderr.write(`\n  Error: ${msg}\n\n`);
+			process.exit(1);
+		}
+	});
+	server.command("stop").description("Stop the managed PostgreSQL container").action(() => {
+		if (stopPostgres()) process.stderr.write("  PostgreSQL container stopped.\n");
+		else process.stderr.write("  No managed PostgreSQL container found.\n");
+	});
+	server.command("doctor").description("Check server environment readiness").action(async () => {
+		process.stderr.write("\n  First Tree Hub Server Doctor\n\n");
+		printResults([
+			checkNodeVersion(),
+			checkDocker(),
+			checkServerConfig(),
+			await checkDatabase(),
+			await checkGitHubToken(),
+			await checkContextTreeRepo(),
+			await checkServerHealth()
+		]);
+	});
+	server.command("status").description("Show server health and status").action(async () => {
+		const url = process.env.FIRST_TREE_HUB_SERVER_URL ?? "http://localhost:8000";
+		try {
+			const res = await fetch(`${url}/api/v1/health`);
+			if (res.ok) {
+				const data = await res.json();
+				console.log(JSON.stringify(data, null, 2));
+			} else {
+				process.stderr.write(`  Server returned ${res.status}\n`);
+				process.exit(1);
+			}
+		} catch {
+			process.stderr.write(`  Cannot connect to ${url}\n`);
+			process.exit(1);
+		}
+	});
+}
+//#endregion
+//#region src/commands/status.ts
+function registerStatusCommand(program) {
+	program.command("status").description("Global overview — server health + configured agents").action(async () => {
+		process.stderr.write("\n");
+		const serverConfig = readConfigFile(join(DEFAULT_CONFIG_DIR, "server.yaml"));
+		const serverPort = getNestedValue(serverConfig, "server.port") ?? 8e3;
+		const serverUrl = `http://${getNestedValue(serverConfig, "server.host") ?? "127.0.0.1"}:${serverPort}`;
+		try {
+			const res = await fetch(`${serverUrl}/api/v1/health`);
+			if (res.ok) {
+				const data = await res.json();
+				const uptime = data.uptime_seconds ? formatUptime(data.uptime_seconds) : "unknown";
+				process.stderr.write(`  Server:     ✓ running (${serverUrl}, uptime: ${uptime})\n`);
+			} else process.stderr.write(`  Server:     ✗ unhealthy (${res.status})\n`);
+		} catch {
+			process.stderr.write(`  Server:     ✗ not running (${serverUrl})\n`);
+		}
+		const dbProvider = getNestedValue(serverConfig, "database.provider") ?? "unknown";
+		const hasDbUrl = getNestedValue(serverConfig, "database.url") !== void 0;
+		process.stderr.write(`  Database:   ${hasDbUrl ? "✓ configured" : "✗ not configured"} (${dbProvider})\n`);
+		const agentsDir = join(DEFAULT_CONFIG_DIR, "agents");
+		if (existsSync(agentsDir)) try {
+			const agents = loadAgents({
+				schema: agentConfigSchema,
+				agentsDir
+			});
+			process.stderr.write(`  Agents:     ${agents.size} configured\n`);
+		} catch {
+			process.stderr.write("  Agents:     error reading config\n");
+		}
+		else process.stderr.write("  Agents:     0 configured\n");
+		const clientConfigPath = join(DEFAULT_CONFIG_DIR, "client.yaml");
+		if (existsSync(clientConfigPath)) {
+			const clientServerUrl = getNestedValue(readConfigFile(clientConfigPath), "server.url");
+			process.stderr.write(`  Client:     configured → ${clientServerUrl}\n`);
+		} else process.stderr.write("  Client:     not configured\n");
+		process.stderr.write("\n");
+	});
+}
+function getNestedValue(obj, dotPath) {
+	const parts = dotPath.split(".");
+	let current = obj;
+	for (const part of parts) {
+		if (current === null || current === void 0 || typeof current !== "object") return void 0;
+		current = current[part];
+	}
+	return current;
+}
+function formatUptime(seconds) {
+	const days = Math.floor(seconds / 86400);
+	const hours = Math.floor(seconds % 86400 / 3600);
+	const mins = Math.floor(seconds % 3600 / 60);
+	if (days > 0) return `${days}d ${hours}h`;
+	if (hours > 0) return `${hours}h ${mins}m`;
+	return `${mins}m`;
+}
+//#endregion
+//#region src/cli/connect.ts
+function registerConnectCommand(program) {
+	program.command("connect").description("Connect a single agent to server and process messages").option("-t, --type <type>", "Handler type", "claude-code").option("--concurrency <n>", "Max parallel message processing", "5").option("--server <url>", "Override FIRST_TREE_HUB_SERVER").action(async (options) => {
+		try {
+			registerBuiltinHandlers();
+			const config = resolveConfig();
+			if (options.server) config.serverUrl = options.server;
+			const concurrency = Number.parseInt(options.concurrency, 10) || 5;
+			const handlerFactory = getHandlerFactory(options.type);
+			const slot = new AgentSlot({
+				name: "connect",
+				serverUrl: config.serverUrl,
+				token: config.token,
+				type: options.type,
+				handlerFactory,
+				session: {
+					idle_timeout: 300,
+					max_sessions: 10
+				},
+				concurrency
+			});
+			const agent = await slot.start();
+			log("connect", `Registered as ${agent.displayName ?? agent.agentId} (${agent.agentId})`);
+			const shutdown = async () => {
+				log("connect", "Shutting down...");
+				await slot.stop();
+				process.exit(0);
+			};
+			process.on("SIGINT", () => void shutdown());
+			process.on("SIGTERM", () => void shutdown());
+		} catch (error) {
+			handleError(error);
+		}
+	});
+}
+//#endregion
+//#region src/cli/start.ts
+function registerStartCommand(program) {
+	program.command("start").description("Start the Agent Runtime — manage multiple agents from a config file").option("-c, --config <path>", "Path to agents.yaml config file", "./agents.yaml").option("--server <url>", "Override server URL from config").option("--shutdown-timeout <ms>", "Graceful shutdown timeout in ms", "30000").action(async (options) => {
+		try {
+			registerBuiltinHandlers();
+			log("runtime", `Loading config from ${options.config}`);
+			const config = loadRuntimeConfig(options.config);
+			if (options.server) config.server = options.server;
+			const shutdownTimeout = Number.parseInt(options.shutdownTimeout, 10);
+			if (Number.isNaN(shutdownTimeout) || shutdownTimeout < 0) fail("INVALID_OPTION", "shutdown-timeout must be a positive number", 2);
+			await new AgentRuntime({
+				config,
+				shutdownTimeout
+			}).start();
+		} catch (error) {
+			if (error instanceof Error) {
+				log("runtime", `Fatal: ${error.message}`);
+				process.exit(1);
+			}
+			throw error;
+		}
+	});
+}
+//#endregion
+//#region src/cli/index.ts
+const { version } = createRequire(import.meta.url)("../../package.json");
+const program = new Command();
+program.name("first-tree-hub").description("First Tree Hub — centralized collaboration platform for agent teams").version(version);
+registerServerCommands(program);
+registerClientCommands(program);
+registerDbCommands(program);
+registerAdminCommands(program);
+registerConfigCommands(program);
+registerStatusCommand(program);
+registerConnectCommand(program);
+registerStartCommand(program);
+registerAgentCommands(program);
+registerSendCommand(program);
+registerChatsCommand(program);
+registerHistoryCommand(program);
+program.parse();
+//#endregion
+export {};