@agent-team-foundation/first-tree-hub 0.6.2 → 0.6.3

package/dist/{bootstrap-DW7aIpmE.mjs → bootstrap-DNL1cEwv.mjs}

@@ -56,6 +56,10 @@ const clientConfigSchema = defineConfig({
 			default: "http://localhost:8000"
 		}
 	}) },
+	client: { id: field(z.string().regex(/^client_[a-f0-9]{8}$/), {
+		auto: "client-id",
+		env: "FIRST_TREE_HUB_CLIENT_ID"
+	}) },
 	logLevel: field(z.enum([
 		"debug",
 		"info",
@@ -112,6 +116,7 @@ function coerceEnvValue(value, schema) {
 	return value;
 }
 function builtinAutoGenerate(strategy) {
+	if (strategy === "client-id") return `client_${randomBytes(4).toString("hex")}`;
 	const match = /^random:(\w+):(\d+)$/.exec(strategy);
 	if (!match) throw new Error(`Unknown auto-generation strategy: ${strategy}`);
 	const encoding = match[1];
@@ -505,13 +510,13 @@ function resolveServerUrl(flagValue) {
 * Resolve the current member access JWT from persisted credentials.
 *
 * Unified-user-token milestone: the CLI has a single credential store and a
-* single onboarding path (`first-tree-hub connect`). The legacy
+* single onboarding path (`first-tree-hub client connect`). The legacy
 * `FIRST_TREE_HUB_TOKEN` env var is no longer read — callers get a clear
-* error pointing at `connect` instead.
+* error pointing at `client connect` instead.
 */
 function resolveAccessToken() {
 	const creds = loadCredentials();
-	if (!creds) throw new Error("No credentials found. Run `first-tree-hub connect <server-url>` to sign in.");
+	if (!creds) throw new Error("No credentials found. Run `first-tree-hub client connect <server-url>` to sign in.");
 	return creds.accessToken;
 }
 /**
@@ -521,7 +526,7 @@ function resolveAccessToken() {
 */
 async function ensureFreshAccessToken() {
 	const creds = loadCredentials();
-	if (!creds) throw new Error("No credentials found. Run `first-tree-hub connect <server-url>` to sign in.");
+	if (!creds) throw new Error("No credentials found. Run `first-tree-hub client connect <server-url>` to sign in.");
 	if (!isTokenExpired(creds.accessToken)) return creds.accessToken;
 	const res = await fetch(`${creds.serverUrl}/api/v1/auth/refresh`, {
 		method: "POST",
@@ -529,7 +534,7 @@ async function ensureFreshAccessToken() {
 		body: JSON.stringify({ refreshToken: creds.refreshToken }),
 		signal: AbortSignal.timeout(1e4)
 	});
-	if (!res.ok) throw new Error("Access token expired and refresh failed. Run `first-tree-hub connect <server-url>`.");
+	if (!res.ok) throw new Error("Access token expired and refresh failed. Run `first-tree-hub client connect <server-url>`.");
 	const data = await res.json();
 	saveCredentials({
 		...creds,

package/dist/cli/index.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { C as setConfigValue, S as serverConfigSchema, _ as loadAgents, b as resetConfigMeta, c as saveCredentials, f as agentConfigSchema, g as initConfig, h as getConfigValue, l as DEFAULT_CONFIG_DIR, n as ensureFreshAccessToken, o as resolveServerUrl, p as clientConfigSchema, r as ensureFreshAdminToken, s as saveAgentConfig, u as DEFAULT_DATA_DIR, v as readConfigFile, y as resetConfig } from "../bootstrap-DW7aIpmE.mjs";
-import { A as SdkError, D as createOwner, E as ClientRuntime, M as cleanWorkspaces, T as stopPostgres, _ as checkServerHealth, a as formatCheckReport, b as printResults, c as onboardCreate, d as checkAgentConfigs, f as checkClientConfig, g as checkServerConfig, h as checkNodeVersion, i as promptMissingFields, j as SessionRegistry, k as FirstTreeHubSDK, l as saveOnboardState, m as checkDocker, n as isInteractive, o as loadOnboardState, p as checkDatabase, r as promptAddAgent, s as onboardCheck, t as startServer, u as runMigrations, v as checkServerReachable, y as checkWebSocket } from "../core-RXUUKkCO.mjs";
-import { n as bindFeishuUser, t as bindFeishuBot } from "../feishu-BZ8pnMrQ.mjs";
+import { C as setConfigValue, S as serverConfigSchema, _ as loadAgents, b as resetConfigMeta, c as saveCredentials, f as agentConfigSchema, g as initConfig, h as getConfigValue, l as DEFAULT_CONFIG_DIR, n as ensureFreshAccessToken, o as resolveServerUrl, p as clientConfigSchema, r as ensureFreshAdminToken, s as saveAgentConfig, u as DEFAULT_DATA_DIR, v as readConfigFile, y as resetConfig } from "../bootstrap-DNL1cEwv.mjs";
+import { A as SdkError, D as createOwner, E as ClientRuntime, M as cleanWorkspaces, T as stopPostgres, _ as checkServerHealth, a as formatCheckReport, b as printResults, c as onboardCreate, d as checkAgentConfigs, f as checkClientConfig, g as checkServerConfig, h as checkNodeVersion, i as promptMissingFields, j as SessionRegistry, k as FirstTreeHubSDK, l as saveOnboardState, m as checkDocker, n as isInteractive, o as loadOnboardState, p as checkDatabase, r as promptAddAgent, s as onboardCheck, t as startServer, u as runMigrations, v as checkServerReachable, y as checkWebSocket } from "../core-B10jgThe.mjs";
+import { n as bindFeishuUser, t as bindFeishuBot } from "../feishu-BoMJHlOv.mjs";
 import { createRequire } from "node:module";
 import { Command } from "commander";
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync } from "node:fs";
@@ -362,7 +362,7 @@ function registerAgentCommands(program) {
 			process.stderr.write("  No agents configured.\n");
 		}
 	});
-	agent.command("create <name>").description("Create an agent on Hub and bind it locally").requiredOption("--type <type>", "Agent type (human, personal_assistant, autonomous_agent)").requiredOption("--client-id <id>", "Client (machine) that will run this agent — must be owned by you. Run `first-tree-hub connect` on that machine first.").option("--runtime <runtime>", "Runtime handler (default: claude-code)", "claude-code").option("--display-name <name>", "Display name").option("--server <url>", "Hub server URL").action(async (name, options) => {
+	agent.command("create <name>").description("Create an agent on Hub and bind it locally").requiredOption("--type <type>", "Agent type (human, personal_assistant, autonomous_agent)").requiredOption("--client-id <id>", "Client (machine) that will run this agent — must be owned by you. Run `first-tree-hub client connect` on that machine first.").option("--runtime <runtime>", "Runtime handler (default: claude-code)", "claude-code").option("--display-name <name>", "Display name").option("--server <url>", "Hub server URL").action(async (name, options) => {
 		try {
 			const serverUrl = resolveServerUrl(options.server);
 			const headers = {
@@ -740,9 +740,94 @@ function registerAgentCommands(program) {
 	});
 }
 //#endregion
+//#region src/commands/connect.ts
+/**
+* Authenticate via connect token — exchange for full JWT credentials.
+*/
+async function authenticateWithToken(url, token) {
+	const res = await fetch(`${url}/api/v1/auth/connect-token`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({ token }),
+		signal: AbortSignal.timeout(1e4)
+	});
+	if (!res.ok) fail("AUTH_ERROR", (await res.json().catch(() => ({}))).error ?? `Token exchange failed (HTTP ${res.status})`, 1);
+	return await res.json();
+}
+/**
+* Authenticate via interactive username/password login.
+*/
+async function authenticateInteractive(url) {
+	process.stderr.write("\n  Log in to Hub:\n");
+	const username = await input({ message: "  Username:" });
+	const pw = await password({ message: "  Password:" });
+	const loginRes = await fetch(`${url}/api/v1/auth/login`, {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({
+			username,
+			password: pw
+		}),
+		signal: AbortSignal.timeout(1e4)
+	});
+	if (!loginRes.ok) fail("AUTH_ERROR", (await loginRes.json().catch(() => ({}))).error ?? `Login failed (HTTP ${loginRes.status})`, 1);
+	return await loginRes.json();
+}
+function registerConnectCommand(parent) {
+	parent.command("connect <server-url>").description("Connect to a Hub server — configure, authenticate, and start client").option("--token <token>", "Connect token (from Hub web console) — skips interactive login").action(async (serverUrl, options) => {
+		try {
+			const url = serverUrl.replace(/\/+$/, "");
+			setConfigValue(join(DEFAULT_CONFIG_DIR, "client.yaml"), "server.url", url);
+			process.stderr.write(`\n  \u2713 Server configured: ${url}\n`);
+			saveCredentials({
+				...options.token ? await authenticateWithToken(url, options.token) : await authenticateInteractive(url),
+				serverUrl: url
+			});
+			process.stderr.write("  ✓ Authenticated\n");
+			resetConfig();
+			resetConfigMeta();
+			const config = await initConfig({
+				schema: clientConfigSchema,
+				role: "client"
+			});
+			const agentsDir = join(DEFAULT_CONFIG_DIR, "agents");
+			const agents = loadAgents({
+				schema: agentConfigSchema,
+				agentsDir
+			});
+			process.stderr.write(`\n  Starting client (id: ${config.client.id})...\n`);
+			const runtime = new ClientRuntime(config.server.url, config.client.id);
+			for (const [name, agentConfig] of agents) runtime.addAgent(name, agentConfig);
+			await runtime.start();
+			runtime.watchAgentsDir(agentsDir);
+			const shutdown = async () => {
+				process.stderr.write("\n  Shutting down...\n");
+				runtime.unwatchAgentsDir();
+				await runtime.stop();
+				process.exit(0);
+			};
+			process.on("SIGINT", () => void shutdown());
+			process.on("SIGTERM", () => void shutdown());
+			await new Promise(() => {});
+		} 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);
+		} finally {
+			resetConfig();
+			resetConfigMeta();
+		}
+	});
+}
+//#endregion
 //#region src/commands/client.ts
 function registerClientCommands(program) {
 	const client = program.command("client").description("Client runtime — connect agents to the server");
+	registerConnectCommand(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({
@@ -759,8 +844,8 @@ function registerClientCommands(program) {
 				schema: agentConfigSchema,
 				agentsDir
 			});
-			process.stderr.write(`\n  Connecting to ${config.server.url}...\n`);
-			const runtime = new ClientRuntime(config.server.url);
+			process.stderr.write(`\n  Connecting to ${config.server.url} (client id: ${config.client.id})...\n`);
+			const runtime = new ClientRuntime(config.server.url, config.client.id);
 			for (const [name, agentConfig] of agents) runtime.addAgent(name, agentConfig);
 			await runtime.start();
 			runtime.watchAgentsDir(agentsDir);
@@ -961,101 +1046,17 @@ function isSecretField(schema, dotPath) {
 	return false;
 }
 //#endregion
-//#region src/commands/connect.ts
-/**
-* Authenticate via connect token — exchange for full JWT credentials.
-*/
-async function authenticateWithToken(url, token) {
-	const res = await fetch(`${url}/api/v1/auth/connect-token`, {
-		method: "POST",
-		headers: { "Content-Type": "application/json" },
-		body: JSON.stringify({ token }),
-		signal: AbortSignal.timeout(1e4)
-	});
-	if (!res.ok) fail("AUTH_ERROR", (await res.json().catch(() => ({}))).error ?? `Token exchange failed (HTTP ${res.status})`, 1);
-	return await res.json();
-}
-/**
-* Authenticate via interactive username/password login.
-*/
-async function authenticateInteractive(url) {
-	process.stderr.write("\n  Log in to Hub:\n");
-	const username = await input({ message: "  Username:" });
-	const pw = await password({ message: "  Password:" });
-	const loginRes = await fetch(`${url}/api/v1/auth/login`, {
-		method: "POST",
-		headers: { "Content-Type": "application/json" },
-		body: JSON.stringify({
-			username,
-			password: pw
-		}),
-		signal: AbortSignal.timeout(1e4)
-	});
-	if (!loginRes.ok) fail("AUTH_ERROR", (await loginRes.json().catch(() => ({}))).error ?? `Login failed (HTTP ${loginRes.status})`, 1);
-	return await loginRes.json();
-}
-function registerConnectCommand(program) {
-	program.command("connect <server-url>").description("Connect to a Hub server — configure, authenticate, and start client").option("--token <token>", "Connect token (from Hub web console) — skips interactive login").action(async (serverUrl, options) => {
-		try {
-			const url = serverUrl.replace(/\/+$/, "");
-			setConfigValue(join(DEFAULT_CONFIG_DIR, "client.yaml"), "server.url", url);
-			process.stderr.write(`\n  \u2713 Server configured: ${url}\n`);
-			saveCredentials({
-				...options.token ? await authenticateWithToken(url, options.token) : await authenticateInteractive(url),
-				serverUrl: url
-			});
-			process.stderr.write("  ✓ Authenticated\n");
-			resetConfig();
-			resetConfigMeta();
-			const config = await initConfig({
-				schema: clientConfigSchema,
-				role: "client"
-			});
-			const agentsDir = join(DEFAULT_CONFIG_DIR, "agents");
-			const agents = loadAgents({
-				schema: agentConfigSchema,
-				agentsDir
-			});
-			process.stderr.write(`\n  Starting client...\n`);
-			const runtime = new ClientRuntime(config.server.url);
-			for (const [name, agentConfig] of agents) runtime.addAgent(name, agentConfig);
-			await runtime.start();
-			runtime.watchAgentsDir(agentsDir);
-			const shutdown = async () => {
-				process.stderr.write("\n  Shutting down...\n");
-				runtime.unwatchAgentsDir();
-				await runtime.stop();
-				process.exit(0);
-			};
-			process.on("SIGINT", () => void shutdown());
-			process.on("SIGTERM", () => void shutdown());
-			await new Promise(() => {});
-		} 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);
-		} finally {
-			resetConfig();
-			resetConfigMeta();
-		}
-	});
-}
-//#endregion
 //#region src/commands/onboard.ts
 async function promptMissing(args) {
 	if (!args.server) try {
-		const { resolveServerUrl } = await import("../bootstrap-DW7aIpmE.mjs").then((n) => n.t);
+		const { resolveServerUrl } = await import("../bootstrap-DNL1cEwv.mjs").then((n) => n.t);
 		resolveServerUrl();
 	} catch {
 		args.server = await input({ message: "Hub server URL:" });
 		saveOnboardState(args);
 	}
-	const { loadCredentials } = await import("../bootstrap-DW7aIpmE.mjs").then((n) => n.t);
-	if (!loadCredentials()) throw new Error("No saved credentials. Run `first-tree-hub connect <server-url>` before onboarding.");
+	const { loadCredentials } = await import("../bootstrap-DNL1cEwv.mjs").then((n) => n.t);
+	if (!loadCredentials()) throw new Error("No saved credentials. Run `first-tree-hub client connect <server-url>` before onboarding.");
 	if (!args.id) {
 		args.id = await input({ message: "Agent ID:" });
 		saveOnboardState(args);
@@ -1080,11 +1081,9 @@ async function promptMissing(args) {
 		});
 		saveOnboardState(args);
 	}
-	if (args.type !== "human" && !args.clientId) {
-		args.clientId = await input({
-			message: "Client ID (machine that will run this agent — must be owned by you):",
-			validate: (v) => v.length > 0 ? true : "clientId is required for non-human agents"
-		});
+	if (args.type !== "human" && args.clientId === void 0) {
+		args.clientId = await input({ message: "Client ID (Enter to leave unbound — first WS connect will claim it):" });
+		if (!args.clientId) args.clientId = void 0;
 		saveOnboardState(args);
 	}
 	if (!args.role) {
@@ -1117,10 +1116,7 @@ async function promptMissing(args) {
 				message: "Assistant ID:",
 				default: `${args.id}-assistant`
 			});
-			if (!args.clientId) args.clientId = await input({
-				message: "Client ID for the assistant (must be owned by you):",
-				validate: (v) => v.length > 0 ? true : "clientId is required"
-			});
+			if (args.clientId === void 0) args.clientId = await input({ message: "Client ID for the assistant (Enter to leave unbound):" }) || void 0;
 			saveOnboardState(args);
 		}
 	}
@@ -1327,7 +1323,6 @@ registerClientCommands(program);
 registerAgentCommands(program);
 registerConfigCommands(program);
 registerStatusCommand(program);
-registerConnectCommand(program);
 registerOnboardCommand(program);
 program.parse();
 //#endregion

package/dist/{core-RXUUKkCO.mjs → core-B10jgThe.mjs}

@@ -1,5 +1,5 @@
-import { C as setConfigValue, S as serverConfigSchema, _ as loadAgents, d as DEFAULT_HOME_DIR$1, f as agentConfigSchema, g as initConfig, i as loadCredentials, l as DEFAULT_CONFIG_DIR, m as collectMissingPrompts, n as ensureFreshAccessToken, o as resolveServerUrl, p as clientConfigSchema, s as saveAgentConfig, u as DEFAULT_DATA_DIR$1, x as resolveConfigReadonly } from "./bootstrap-DW7aIpmE.mjs";
-import { $ as updateOrganizationSchema, A as createOrganizationSchema, B as paginationQuerySchema, C as clientRegisterSchema, D as createAgentSchema, E as createAdapterMappingSchema, F as isRedactedEnvValue, G as sendToAgentSchema, H as runtimeStateMessageSchema, I as linkTaskChatSchema, J as taskListQuerySchema, K as sessionOutputMessageSchema, L as loginSchema, M as delegateFeishuUserSchema, N as dryRunAgentRuntimeConfigSchema, O as createChatSchema, P as inboxPollQuerySchema, Q as updateMemberSchema, R as messageSourceSchema$1, S as agentTypeSchema$1, T as createAdapterConfigSchema, U as selfServiceFeishuBotSchema, V as refreshTokenSchema, W as sendMessageSchema, X as updateAgentRuntimeConfigSchema, Y as updateAdapterConfigSchema, Z as updateAgentSchema, _ as addParticipantSchema, a as AGENT_SELECTOR_HEADER$1, b as agentBindRequestSchema, c as AGENT_TYPES, d as SYSTEM_CONFIG_DEFAULTS, et as updateSystemConfigSchema, f as TASK_CREATOR_TYPES, g as WS_AUTH_FRAME_TIMEOUT_MS, h as TASK_TERMINAL_STATUSES, i as AGENT_BIND_REJECT_REASONS, j as createTaskSchema, k as createMemberSchema, l as AGENT_VISIBILITY, m as TASK_STATUSES, nt as wsAuthFrameSchema, o as AGENT_SOURCES, p as TASK_HEALTH_SIGNALS, q as sessionStateMessageSchema, s as AGENT_STATUSES, tt as updateTaskStatusSchema, u as DEFAULT_AGENT_RUNTIME_CONFIG_PAYLOAD, v as adminCreateTaskSchema, w as connectTokenExchangeSchema, x as agentRuntimeConfigPayloadSchema$1, y as adminUpdateTaskSchema, z as notificationQuerySchema } from "./feishu-BZ8pnMrQ.mjs";
+import { C as setConfigValue, S as serverConfigSchema, _ as loadAgents, d as DEFAULT_HOME_DIR$1, f as agentConfigSchema, g as initConfig, i as loadCredentials, l as DEFAULT_CONFIG_DIR, m as collectMissingPrompts, n as ensureFreshAccessToken, o as resolveServerUrl, p as clientConfigSchema, s as saveAgentConfig, u as DEFAULT_DATA_DIR$1, x as resolveConfigReadonly } from "./bootstrap-DNL1cEwv.mjs";
+import { $ as updateOrganizationSchema, A as createOrganizationSchema, B as paginationQuerySchema, C as clientRegisterSchema, D as createAgentSchema, E as createAdapterMappingSchema, F as isRedactedEnvValue, G as sendToAgentSchema, H as runtimeStateMessageSchema, I as linkTaskChatSchema, J as taskListQuerySchema, K as sessionOutputMessageSchema, L as loginSchema, M as delegateFeishuUserSchema, N as dryRunAgentRuntimeConfigSchema, O as createChatSchema, P as inboxPollQuerySchema, Q as updateMemberSchema, R as messageSourceSchema$1, S as agentTypeSchema$1, T as createAdapterConfigSchema, U as selfServiceFeishuBotSchema, V as refreshTokenSchema, W as sendMessageSchema, X as updateAgentRuntimeConfigSchema, Y as updateAdapterConfigSchema, Z as updateAgentSchema, _ as addParticipantSchema, a as AGENT_SELECTOR_HEADER$1, b as agentBindRequestSchema, c as AGENT_TYPES, d as SYSTEM_CONFIG_DEFAULTS, et as updateSystemConfigSchema, f as TASK_CREATOR_TYPES, g as WS_AUTH_FRAME_TIMEOUT_MS, h as TASK_TERMINAL_STATUSES, i as AGENT_BIND_REJECT_REASONS, j as createTaskSchema, k as createMemberSchema, l as AGENT_VISIBILITY, m as TASK_STATUSES, nt as wsAuthFrameSchema, o as AGENT_SOURCES, p as TASK_HEALTH_SIGNALS, q as sessionStateMessageSchema, s as AGENT_STATUSES, tt as updateTaskStatusSchema, u as DEFAULT_AGENT_RUNTIME_CONFIG_PAYLOAD, v as adminCreateTaskSchema, w as connectTokenExchangeSchema, x as agentRuntimeConfigPayloadSchema$1, y as adminUpdateTaskSchema, z as notificationQuerySchema } from "./feishu-BoMJHlOv.mjs";
 import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, renameSync, rmSync, statSync, watch, writeFileSync } from "node:fs";
 import { dirname, join, resolve } from "node:path";
 import { ZodError, z } from "zod";
@@ -11,7 +11,7 @@ import WebSocket from "ws";
 import { query } from "@anthropic-ai/claude-agent-sdk";
 import { execFileSync, execSync, spawn } from "node:child_process";
 import bcrypt from "bcrypt";
-import { and, asc, count, desc, eq, gt, inArray, isNotNull, lt, ne, or, sql } from "drizzle-orm";
+import { and, asc, count, desc, eq, gt, inArray, isNotNull, isNull, lt, ne, or, sql } from "drizzle-orm";
 import { drizzle } from "drizzle-orm/postgres-js";
 import postgres from "postgres";
 import { fileURLToPath } from "node:url";
@@ -172,7 +172,7 @@ z.object({
 	visibility: agentVisibilitySchema.optional(),
 	metadata: z.record(z.string(), z.unknown()).optional(),
 	managerId: z.string().nullable().optional(),
-	clientId: z.string().optional()
+	clientId: z.string().min(1).max(100).nullable().optional()
 });
 z.object({
 	uuid: z.string(),
@@ -1277,6 +1277,10 @@ defineConfig({
 			default: "http://localhost:8000"
 		}
 	}) },
+	client: { id: field(z.string().regex(/^client_[a-f0-9]{8}$/), {
+		auto: "client-id",
+		env: "FIRST_TREE_HUB_CLIENT_ID"
+	}) },
 	logLevel: field(z.enum([
 		"debug",
 		"info",
@@ -3036,10 +3040,11 @@ var ClientRuntime = class {
 	agentNames = /* @__PURE__ */ new Set();
 	watcher = null;
 	debounceTimer = null;
-	constructor(serverUrl) {
+	constructor(serverUrl, clientId) {
 		this.serverUrl = serverUrl;
 		this.connection = new ClientConnection({
 			serverUrl,
+			clientId,
 			getAccessToken: () => ensureFreshAccessToken()
 		});
 		registerBuiltinHandlers();
@@ -3655,7 +3660,7 @@ async function onboardCheck(args) {
 		key: "connect",
 		label: "Signed in",
 		status: "missing_required",
-		hint: "Run `first-tree-hub connect <server-url>` first"
+		hint: "Run `first-tree-hub client connect <server-url>` first"
 	});
 	try {
 		const serverUrl = resolveServerUrl(args.server);
@@ -3713,11 +3718,17 @@ async function onboardCheck(args) {
 		status: "missing_required",
 		hint: "Provide via --type"
 	});
-	if (args.type && args.type !== "human" && !args.clientId) items.push({
+	if (args.type && args.type !== "human") if (args.clientId) items.push({
 		key: "client",
 		label: "Target client",
-		status: "missing_required",
-		hint: "Non-human agents must pin a client via --client-id <id>"
+		status: "ok",
+		value: args.clientId
+	});
+	else items.push({
+		key: "client",
+		label: "Target client",
+		status: "ok",
+		value: "(unbound — claimed on first WS connect)"
 	});
 	return items;
 }
@@ -3788,7 +3799,7 @@ async function onboardCreate(args) {
 	}
 	const runtimeAgent = args.type === "human" ? args.assistant : args.id;
 	if (args.feishuBotAppId && args.feishuBotAppSecret) {
-		const { bindFeishuBot } = await import("./feishu-BZ8pnMrQ.mjs").then((n) => n.r);
+		const { bindFeishuBot } = await import("./feishu-BoMJHlOv.mjs").then((n) => n.r);
 		const targetAgentUuid = args.type === "human" ? assistantUuid : primary.uuid;
 		if (!targetAgentUuid) process.stderr.write(`Warning: Cannot bind Feishu bot — no runtime agent available for "${args.id}".\n`);
 		else {
@@ -3929,7 +3940,7 @@ function setNestedByDot(obj, dotPath, value) {
 	if (lastKey !== void 0) current[lastKey] = value;
 }
 //#endregion
-//#region ../server/dist/app-C7MR8S4r.mjs
+//#region ../server/dist/app-BjIHPMKY.mjs
 var __defProp = Object.defineProperty;
 var __exportAll = (all, no_symbols) => {
 	let target = {};
@@ -4852,18 +4863,20 @@ function defaultVisibility(type) {
 /**
 * Resolve + validate the client that will own the new agent.
 *
-* Rule (unified-user-token M1):
-*   - Non-human agents MUST pin a client at creation time. The pinned client
-*     must belong to the manager's user (Rule R-RUN upstream).
-*   - Human agents represent the member themselves and have no runtime, so a
-*     missing `clientId` is allowed and the column stays NULL.
+* Rule (unified-user-token, post-first-bind relaxation):
+*   - Human agents represent the member themselves and have no runtime; a
+*     missing `clientId` is required and the column stays NULL.
+*   - Non-human agents MAY omit `clientId` at creation; the row stays NULL
+*     and is claimed on the first WS bind (see `api/agent/ws-client.ts`).
+*   - When a non-human agent IS created with a `clientId`, the pinned client
+*     must already be owned by the manager's user (Rule R-RUN).
 */
 async function resolveAgentClient(db, data) {
 	if (data.type === "human") {
 		if (data.clientId) throw new BadRequestError("Human agents cannot be pinned to a client");
 		return null;
 	}
-	if (!data.clientId) throw new BadRequestError("clientId is required — every non-human agent must be pinned to a client at creation time. Run `first-tree-hub connect` on the target machine first.");
+	if (!data.clientId) return null;
 	const [manager] = await db.select({ userId: members.userId }).from(members).where(eq(members.id, data.managerId)).limit(1);
 	if (!manager) throw new BadRequestError(`Manager "${data.managerId}" not found`);
 	const [client] = await db.select({
@@ -4871,7 +4884,7 @@ async function resolveAgentClient(db, data) {
 		userId: clients.userId
 	}).from(clients).where(eq(clients.id, data.clientId)).limit(1);
 	if (!client) throw new BadRequestError(`Client "${data.clientId}" not found`);
-	if (!client.userId) throw new BadRequestError(`Client "${data.clientId}" has not been claimed by a user yet. Have the operator run \`first-tree-hub connect\` on that machine before pinning an agent to it.`);
+	if (!client.userId) throw new BadRequestError(`Client "${data.clientId}" has not been claimed by a user yet. Have the operator run \`first-tree-hub client connect\` on that machine before pinning an agent to it.`);
 	if (client.userId !== manager.userId) throw new ForbiddenError(`Client "${data.clientId}" is not owned by the manager's user — pick a client belonging to that user.`);
 	return client.id;
 }
@@ -4973,8 +4986,11 @@ async function listAgentsForMember(db, scope, limit, cursor, type) {
 	};
 }
 async function updateAgent(db, uuid, data) {
-	if (data.clientId !== void 0) throw new BadRequestError("clientId is immutable in this milestone — delete and re-create the agent on the target client to move it");
 	const agent = await getAgent(db, uuid);
+	if (data.clientId !== void 0) {
+		if (data.clientId === null) throw new BadRequestError("clientId cannot be cleared — once bound, an agent stays bound to its client");
+		if (agent.clientId !== null && agent.clientId !== data.clientId) throw new BadRequestError("clientId is immutable once set — delete and re-create the agent on the target client to move it");
+	}
 	const updates = { updatedAt: /* @__PURE__ */ new Date() };
 	if (data.type !== void 0) updates.type = data.type;
 	if (data.displayName !== void 0) updates.displayName = data.displayName;
@@ -4991,6 +5007,14 @@ async function updateAgent(db, uuid, data) {
 		if (manager.organizationId !== agent.organizationId) throw new BadRequestError("Manager must belong to the same organization as the agent");
 		updates.managerId = data.managerId;
 	}
+	if (data.clientId !== void 0 && data.clientId !== null && agent.clientId === null) {
+		const resolvedClientId = await resolveAgentClient(db, {
+			clientId: data.clientId,
+			managerId: updates.managerId ?? agent.managerId,
+			type: agent.type
+		});
+		if (resolvedClientId !== null) updates.clientId = resolvedClientId;
+	}
 	const [updated] = await db.update(agents).set(updates).where(eq(agents.uuid, agent.uuid)).returning();
 	if (!updated) throw new Error("Unexpected: UPDATE RETURNING produced no row");
 	return updated;
@@ -5982,7 +6006,7 @@ async function adminAgentRoutes(app) {
 		};
 		if (health === "disconnected") return reply.status(200).send({
 			status: "offline",
-			message: "Agent is not connected. Start the client with: first-tree-hub connect <server-url>",
+			message: "Agent is not connected. Start the client with: first-tree-hub client connect <server-url>",
 			connection
 		});
 		if (health === "stale") return reply.status(200).send({
@@ -8226,8 +8250,9 @@ function clientWsRoutes(notifier, instanceId) {
 							inboxId: agents.inboxId,
 							status: agents.status,
 							clientId: agents.clientId,
-							clientUserId: clients.userId
-						}).from(agents).leftJoin(clients, eq(agents.clientId, clients.id)).where(and(eq(agents.uuid, bindRequest.agentId))).limit(1);
+							clientUserId: clients.userId,
+							managerUserId: members.userId
+						}).from(agents).leftJoin(clients, eq(agents.clientId, clients.id)).leftJoin(members, eq(agents.managerId, members.id)).where(and(eq(agents.uuid, bindRequest.agentId))).limit(1);
 						if (!agent) {
 							sendRejected(socket, ref, AGENT_BIND_REJECT_REASONS.UNKNOWN_AGENT);
 							return;
@@ -8240,11 +8265,22 @@ function clientWsRoutes(notifier, instanceId) {
 							sendRejected(socket, ref, AGENT_BIND_REJECT_REASONS.AGENT_SUSPENDED);
 							return;
 						}
-						if (!agent.clientId || agent.clientId !== clientId) {
+						if (agent.clientId === null) {
+							if (!agent.managerUserId || agent.managerUserId !== session.userId) {
+								sendRejected(socket, ref, AGENT_BIND_REJECT_REASONS.NOT_OWNED);
+								return;
+							}
+							if ((await app.db.update(agents).set({
+								clientId,
+								updatedAt: /* @__PURE__ */ new Date()
+							}).where(and(eq(agents.uuid, agent.id), isNull(agents.clientId))).returning({ uuid: agents.uuid })).length === 0) {
+								sendRejected(socket, ref, AGENT_BIND_REJECT_REASONS.WRONG_CLIENT);
+								return;
+							}
+						} else if (agent.clientId !== clientId) {
 							sendRejected(socket, ref, AGENT_BIND_REJECT_REASONS.WRONG_CLIENT);
 							return;
-						}
-						if (!agent.clientUserId || agent.clientUserId !== session.userId) {
+						} else if (!agent.clientUserId || agent.clientUserId !== session.userId) {
 							sendRejected(socket, ref, AGENT_BIND_REJECT_REASONS.NOT_OWNED);
 							return;
 						}
@@ -8601,7 +8637,7 @@ async function meRoutes(app) {
 		return {
 			token,
 			expiresIn,
-			command: `first-tree-hub connect ${`${request.headers["x-forwarded-proto"] ?? request.protocol}://${request.headers["x-forwarded-host"] ?? request.headers.host ?? request.hostname}`} --token ${token}`
+			command: `first-tree-hub client connect ${`${request.headers["x-forwarded-proto"] ?? request.protocol}://${request.headers["x-forwarded-host"] ?? request.headers.host ?? request.hostname}`} --token ${token}`
 		};
 	});
 }