@agent-team-foundation/first-tree-hub 0.7.2 → 0.8.1

package/dist/{bootstrap-CRDR6NwE.mjs → bootstrap-8nCntTrK.mjs}

@@ -520,6 +520,14 @@ function resolveAccessToken() {
 	return creds.accessToken;
 }
 /**
+* In-flight refresh promise. Multiple callers (WS handshake, proactive
+* refresh timer, every SDK request) can see an expired token within the same
+* millisecond — without dedupe each would fire an independent `/auth/refresh`
+* round-trip and race to write `credentials.json`. Share one in-flight
+* promise so N concurrent callers resolve from a single HTTP call.
+*/
+let inflightRefresh = null;
+/**
 * Ensure the persisted access token is fresh. Call before any API request
 * when using persisted credentials. Returns the (possibly refreshed) access
 * token. Service-user API keys are out of scope for this milestone.
@@ -528,19 +536,27 @@ async function ensureFreshAccessToken() {
 	const creds = loadCredentials();
 	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",
-		headers: { "Content-Type": "application/json" },
-		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 client connect <server-url>`.");
-	const data = await res.json();
-	saveCredentials({
-		...creds,
-		accessToken: data.accessToken
-	});
-	return data.accessToken;
+	if (inflightRefresh) return inflightRefresh;
+	inflightRefresh = (async () => {
+		const res = await fetch(`${creds.serverUrl}/api/v1/auth/refresh`, {
+			method: "POST",
+			headers: { "Content-Type": "application/json" },
+			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 client connect <server-url>`.");
+		const data = await res.json();
+		saveCredentials({
+			...creds,
+			accessToken: data.accessToken
+		});
+		return data.accessToken;
+	})();
+	try {
+		return await inflightRefresh;
+	} finally {
+		inflightRefresh = null;
+	}
 }
 /** Back-compat alias retained so existing call sites keep compiling. */
 const ensureFreshAdminToken = ensureFreshAccessToken;

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-CRDR6NwE.mjs";
-import { A as stopPostgres, C as checkServerReachable, F as SdkError, I as SessionRegistry, L as cleanWorkspaces, M as createOwner, P as FirstTreeHubSDK, S as checkServerHealth, T as printResults, _ as checkClientConfig, a as uninstallClientService, b as checkNodeVersion, c as promptAddAgent, d as loadOnboardState, f as onboardCheck, g as checkAgentConfigs, h as runMigrations, j as ClientRuntime, l as promptMissingFields, m as saveOnboardState, n as installClientService, o as startServer, p as onboardCreate, r as isServiceSupported, s as isInteractive, t as getClientServiceStatus, u as formatCheckReport, v as checkDatabase, w as checkWebSocket, x as checkServerConfig, y as checkDocker } from "../core-6-paFwyo.mjs";
-import { n as bindFeishuUser, t as bindFeishuBot } from "../feishu-CJ08ntOD.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-8nCntTrK.mjs";
+import { A as stopPostgres, C as checkServerReachable, F as SdkError, I as SessionRegistry, L as cleanWorkspaces, M as createOwner, P as FirstTreeHubSDK, S as checkServerHealth, T as printResults, _ as checkClientConfig, a as uninstallClientService, b as checkNodeVersion, c as promptAddAgent, d as loadOnboardState, f as onboardCheck, g as checkAgentConfigs, h as runMigrations, j as ClientRuntime, l as promptMissingFields, m as saveOnboardState, n as installClientService, o as startServer, p as onboardCreate, r as isServiceSupported, s as isInteractive, t as getClientServiceStatus, u as formatCheckReport, v as checkDatabase, w as checkWebSocket, x as checkServerConfig, y as checkDocker } from "../core-BA5U1v9L.mjs";
+import { n as bindFeishuUser, t as bindFeishuBot } from "../feishu-D9JkMZnU.mjs";
 import { createRequire } from "node:module";
 import { Command } from "commander";
 import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync } from "node:fs";
@@ -1126,13 +1126,13 @@ function isSecretField(schema, dotPath) {
 //#region src/commands/onboard.ts
 async function promptMissing(args) {
 	if (!args.server) try {
-		const { resolveServerUrl } = await import("../bootstrap-CRDR6NwE.mjs").then((n) => n.t);
+		const { resolveServerUrl } = await import("../bootstrap-8nCntTrK.mjs").then((n) => n.t);
 		resolveServerUrl();
 	} catch {
 		args.server = await input({ message: "Hub server URL:" });
 		saveOnboardState(args);
 	}
-	const { loadCredentials } = await import("../bootstrap-CRDR6NwE.mjs").then((n) => n.t);
+	const { loadCredentials } = await import("../bootstrap-8nCntTrK.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:" });

package/dist/{core-6-paFwyo.mjs → core-BA5U1v9L.mjs}

@@ -1,9 +1,9 @@
-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-CRDR6NwE.mjs";
-import { $ as updateAgentSchema, 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 sessionEventSchema$1, K as sessionCompletionMessageSchema, L as loginSchema, M as delegateFeishuUserSchema, N as dryRunAgentRuntimeConfigSchema, O as createChatSchema, P as inboxPollQuerySchema, Q as updateAgentRuntimeConfigSchema, R as messageSourceSchema$1, S as agentTypeSchema$1, T as createAdapterConfigSchema, U as selfServiceFeishuBotSchema, V as refreshTokenSchema, W as sendMessageSchema, X as taskListQuerySchema, Y as sessionStateMessageSchema, Z as updateAdapterConfigSchema, _ as addParticipantSchema, a as AGENT_SELECTOR_HEADER$1, b as agentBindRequestSchema, c as AGENT_TYPES, d as SYSTEM_CONFIG_DEFAULTS, et as updateMemberSchema, f as TASK_CREATOR_TYPES, g as WS_AUTH_FRAME_TIMEOUT_MS, h as TASK_TERMINAL_STATUSES, i as AGENT_BIND_REJECT_REASONS, it as wsAuthFrameSchema, j as createTaskSchema, k as createMemberSchema, l as AGENT_VISIBILITY, m as TASK_STATUSES, nt as updateSystemConfigSchema, o as AGENT_SOURCES, p as TASK_HEALTH_SIGNALS, q as sessionEventMessageSchema, rt as updateTaskStatusSchema, s as AGENT_STATUSES, tt as updateOrganizationSchema, 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-CJ08ntOD.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-8nCntTrK.mjs";
+import { $ as updateAgentRuntimeConfigSchema, A as createMemberSchema, B as notificationQuerySchema, C as agentTypeSchema$1, D as createAdapterMappingSchema, E as createAdapterConfigSchema, F as inboxPollQuerySchema, G as sendMessageSchema, H as refreshTokenSchema, I as isRedactedEnvValue, J as sessionEventMessageSchema, K as sendToAgentSchema, L as linkTaskChatSchema, M as createTaskSchema, N as delegateFeishuUserSchema, O as createAgentSchema, P as dryRunAgentRuntimeConfigSchema, Q as updateAdapterConfigSchema, R as loginSchema, S as agentRuntimeConfigPayloadSchema$1, T as connectTokenExchangeSchema, U as runtimeStateMessageSchema, V as paginationQuerySchema, W as selfServiceFeishuBotSchema, X as sessionStateMessageSchema, Y as sessionEventSchema$1, Z as taskListQuerySchema, _ as addParticipantSchema, a as AGENT_SELECTOR_HEADER$1, at as wsAuthFrameSchema, b as agentBindRequestSchema, c as AGENT_TYPES, d as SYSTEM_CONFIG_DEFAULTS, et as updateAgentSchema, f as TASK_CREATOR_TYPES, g as WS_AUTH_FRAME_TIMEOUT_MS, h as TASK_TERMINAL_STATUSES, i as AGENT_BIND_REJECT_REASONS, it as updateTaskStatusSchema, j as createOrganizationSchema, k as createChatSchema, l as AGENT_VISIBILITY, m as TASK_STATUSES, nt as updateOrganizationSchema, o as AGENT_SOURCES, p as TASK_HEALTH_SIGNALS, q as sessionCompletionMessageSchema, rt as updateSystemConfigSchema, s as AGENT_STATUSES, tt as updateMemberSchema, u as DEFAULT_AGENT_RUNTIME_CONFIG_PAYLOAD, v as adminCreateTaskSchema, w as clientRegisterSchema, x as agentPinnedMessageSchema$1, y as adminUpdateTaskSchema, z as messageSourceSchema$1 } from "./feishu-D9JkMZnU.mjs";
 import { copyFileSync, existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, watch, writeFileSync } from "node:fs";
 import { dirname, isAbsolute, join, resolve } from "node:path";
 import { ZodError, z } from "zod";
-import "yaml";
+import { stringify } from "yaml";
 import { createCipheriv, createDecipheriv, createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 import { homedir, hostname, platform, userInfo } from "node:os";
 import { EventEmitter } from "node:events";
@@ -198,6 +198,19 @@ z.object({
 	branch: z.string().nullable()
 });
 /**
+* Server → client WebSocket frame announcing that an agent has just been
+* pinned to the connected client (either created with `clientId` or bound via
+* PATCH NULL → ID). The client can auto-register a local config from this so
+* the operator doesn't have to run `first-tree-hub agent add` manually.
+*/
+const agentPinnedMessageSchema = z.object({
+	type: z.literal("agent:pinned"),
+	agentId: z.string(),
+	name: z.string().nullable(),
+	displayName: z.string().nullable(),
+	agentType: agentTypeSchema
+});
+/**
 * Agent runtime configuration — M1 (Claude Code only).
 *
 * Defines the 5 user-tunable field groups that the Hub centrally manages
@@ -933,6 +946,7 @@ var ClientConnection = class extends EventEmitter {
 		this.serverUrl = config.serverUrl.replace(/\/+$/, "");
 		this.sdkVersion = config.sdkVersion;
 		this.getAccessToken = config.getAccessToken;
+		this.on("error", () => {});
 	}
 	get isConnected() {
 		return this.ws !== null && this.ws.readyState === WebSocket.OPEN && this.registered;
@@ -1165,6 +1179,11 @@ var ClientConnection = class extends EventEmitter {
 			this.emit("agent:unbound", agentId);
 			return;
 		}
+		if (type === "agent:pinned") {
+			const parsed = agentPinnedMessageSchema.safeParse(msg);
+			if (parsed.success) this.emit("agent:pinned", parsed.data);
+			return;
+		}
 		if (type === "agent:force_disconnect") {
 			const agentId = msg.agentId;
 			if (agentId && this.boundAgents.has(agentId)) {
@@ -1440,6 +1459,75 @@ function bootstrapWorkspace(options) {
 	}
 	writeFileSync(join(agentDir, "tools.md"), generateToolsDoc(), "utf-8");
 }
+function defaultInstallExec(command, args, options) {
+	execFileSync(command, args, {
+		cwd: options.cwd,
+		stdio: "pipe",
+		timeout: options.timeout,
+		encoding: "utf-8"
+	});
+}
+/**
+* Install the first-tree skill and FIRST-TREE-SOURCE-INTEGRATION block into
+* the workspace by shelling out to `first-tree tree integrate`.
+*
+* Resolution order for the CLI binary:
+*   1. `first-tree` on PATH — preferred for runtime images that pre-install it.
+*   2. `npx -y first-tree@latest` — fallback that downloads on first run.
+*
+* Graceful degradation: returns false on failure and logs. The session still
+* starts; the agent just doesn't have the first-tree skill wired up.
+*/
+function installFirstTreeIntegration(options) {
+	const { workspacePath, contextTreePath, workspaceId, treeRepoUrl, log } = options;
+	const exec = options.exec ?? defaultInstallExec;
+	const integrateArgs = [
+		"tree",
+		"integrate",
+		"--source-path",
+		workspacePath,
+		"--tree-path",
+		contextTreePath,
+		"--mode",
+		"workspace-root",
+		"--workspace-id",
+		workspaceId,
+		...treeRepoUrl ? ["--tree-url", treeRepoUrl] : []
+	];
+	const attempts = [{
+		command: "first-tree",
+		args: integrateArgs,
+		label: "first-tree (PATH)"
+	}, {
+		command: "npx",
+		args: [
+			"-y",
+			"first-tree@latest",
+			...integrateArgs
+		],
+		label: "npx first-tree@latest"
+	}];
+	for (let index = 0; index < attempts.length; index += 1) {
+		const attempt = attempts[index];
+		if (!attempt) continue;
+		try {
+			exec(attempt.command, attempt.args, {
+				cwd: workspacePath,
+				timeout: 12e4
+			});
+			log(`First-tree integration installed via ${attempt.label}`);
+			return true;
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			const binaryMissing = /ENOENT|not found|command not found/i.test(msg);
+			const isLastAttempt = index === attempts.length - 1;
+			if (binaryMissing && !isLastAttempt) continue;
+			log(`First-tree integration skipped (${attempt.label}): ${msg.slice(0, 200)}`);
+			return false;
+		}
+	}
+	return false;
+}
 function generateToolsDoc() {
 	return `# Agent Hub SDK
 
@@ -2454,6 +2542,12 @@ const createClaudeCodeHandler = (config) => {
 			chatId: sessionCtx.chatId
 		});
 		generateClaudeMd(workspace, sessionCtx.agent, contextTreePath);
+		if (contextTreePath) installFirstTreeIntegration({
+			workspacePath: workspace,
+			contextTreePath,
+			workspaceId: sessionCtx.chatId,
+			log: (msg) => sessionCtx.log(msg)
+		});
 	}
 	const handler = {
 		async start(message, sessionCtx) {
@@ -3445,8 +3539,15 @@ var ClientRuntime = class {
 	connection;
 	agents = [];
 	agentNames = /* @__PURE__ */ new Set();
+	agentIds = /* @__PURE__ */ new Set();
 	watcher = null;
 	debounceTimer = null;
+	/**
+	* Directory we write auto-registered agent configs into (same path that
+	* `first-tree-hub agent add` uses). Set by `watchAgentsDir` so the
+	* `agent:pinned` handler knows where to materialise new configs.
+	*/
+	agentsDir = null;
 	constructor(serverUrl, clientId) {
 		this.serverUrl = serverUrl;
 		this.connection = new ClientConnection({
@@ -3458,6 +3559,12 @@ var ClientRuntime = class {
 		this.connection.on("auth:expired", () => {
 			process.stderr.write("  ⚠️  Access token expired — reconnecting after refresh...\n");
 		});
+		this.connection.on("error", (err) => {
+			process.stderr.write(`  \u26A0\uFE0F  Client connection error: ${err.message}\n`);
+		});
+		this.connection.on("agent:pinned", (message) => {
+			this.handleAgentPinned(message);
+		});
 	}
 	addAgent(name, config) {
 		if (this.agentNames.has(name)) return;
@@ -3480,6 +3587,7 @@ var ClientRuntime = class {
 			slot
 		});
 		this.agentNames.add(name);
+		this.agentIds.add(config.agentId);
 	}
 	async start() {
 		await this.connection.connect();
@@ -3502,6 +3610,7 @@ var ClientRuntime = class {
 		process.stderr.write(`\n  ${connected} agent(s) running. Press Ctrl+C to stop.\n`);
 	}
 	watchAgentsDir(agentsDir) {
+		this.agentsDir = agentsDir;
 		if (this.watcher) return;
 		if (!existsSync(agentsDir)) return;
 		this.watcher = watch(agentsDir, { recursive: true }, () => {
@@ -3535,12 +3644,68 @@ var ClientRuntime = class {
 			});
 			for (const [name, config] of all) {
 				if (this.agentNames.has(name)) continue;
+				if (this.agentIds.has(config.agentId)) continue;
 				process.stderr.write(`\n  New agent detected: ${name}\n`);
 				this.addAgent(name, config);
 				this.startAgent(name);
 			}
 		} catch {}
 	}
+	/**
+	* React to an `agent:pinned` server push by writing the local config file
+	* (same shape `first-tree-hub agent add` produces) and scheduling the new
+	* slot — so the operator doesn't have to run `agent add` manually after
+	* creating an agent from the admin UI or API.
+	*/
+	handleAgentPinned(message) {
+		if (this.agentIds.has(message.agentId)) return;
+		if (!this.agentsDir) {
+			process.stderr.write(`  \u26A0\uFE0F  Agent pinned (${message.agentId}) but no agents dir set — cannot auto-register.\n`);
+			return;
+		}
+		const localName = this.pickLocalName(message);
+		const agentDir = join(this.agentsDir, localName);
+		try {
+			mkdirSync(agentDir, {
+				recursive: true,
+				mode: 448
+			});
+			const yaml = stringify({
+				agentId: message.agentId,
+				runtime: "claude-code"
+			});
+			writeFileSync(join(agentDir, "agent.yaml"), yaml, { mode: 384 });
+			process.stderr.write(`  \u2713 Auto-added agent "${localName}" (${message.agentId}) from server push.\n`);
+		} catch (err) {
+			const msg = err instanceof Error ? err.message : String(err);
+			process.stderr.write(`  \u2717 Failed to auto-add agent "${localName}": ${msg}\n`);
+			return;
+		}
+		this.scanForNewAgents(this.agentsDir);
+	}
+	/**
+	* Choose the directory name under `agents/<name>/agent.yaml` for an agent
+	* pushed by the server. Prefer the server-side `name` when set and not
+	* already claimed; otherwise fall back to a UUID-derived name with a numeric
+	* suffix on collision.
+	*
+	* UUID v7 packs the unix-ms timestamp in the high bits, so two agents
+	* created in the same millisecond share the first 8 hex chars. Take 16 chars
+	* (the full ms-timestamp segment plus the random tail) to make accidental
+	* collisions astronomically unlikely, and re-check `agentNames` so even an
+	* adversarial collision falls through to a `-2`, `-3`, … suffix.
+	*/
+	pickLocalName(message) {
+		const preferred = message.name;
+		if (preferred && !this.agentNames.has(preferred)) return preferred;
+		const base = `agent-${message.agentId.replace(/[^a-z0-9]/gi, "").slice(0, 16).toLowerCase()}`;
+		if (!this.agentNames.has(base)) return base;
+		for (let suffix = 2; suffix < 1e3; suffix++) {
+			const candidate = `${base}-${suffix}`;
+			if (!this.agentNames.has(candidate)) return candidate;
+		}
+		return `agent-${message.agentId.replace(/[^a-z0-9]/gi, "").toLowerCase()}`;
+	}
 	startAgent(name) {
 		const entry = this.agents.find((a) => a.name === name);
 		if (!entry) return;
@@ -4206,7 +4371,7 @@ async function onboardCreate(args) {
 	}
 	const runtimeAgent = args.type === "human" ? args.assistant : args.id;
 	if (args.feishuBotAppId && args.feishuBotAppSecret) {
-		const { bindFeishuBot } = await import("./feishu-CJ08ntOD.mjs").then((n) => n.r);
+		const { bindFeishuBot } = await import("./feishu-D9JkMZnU.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 {
@@ -4347,7 +4512,7 @@ function setNestedByDot(obj, dotPath, value) {
 	if (lastKey !== void 0) current[lastKey] = value;
 }
 //#endregion
-//#region ../server/dist/app-CWKBBGod.mjs
+//#region ../server/dist/app-TMhTLXuz.mjs
 var __defProp = Object.defineProperty;
 var __exportAll = (all, no_symbols) => {
 	let target = {};
@@ -5947,6 +6112,23 @@ async function getClient(db, clientId) {
 	const [row] = await db.select().from(clients).where(eq(clients.id, clientId)).limit(1);
 	return row ?? null;
 }
+/**
+* List the active agents currently pinned to a client. Used by the WS
+* registration handshake to backfill `agent:pinned` notifications missed while
+* the client was offline — without it, an admin who pinned an agent during a
+* client outage would still need a manual `first-tree-hub agent add`.
+*
+* Excludes soft-deleted agents (status = "deleted"). Human agents are
+* naturally excluded by the `clientId` filter — they never carry a clientId.
+*/
+async function listActiveAgentsPinnedToClient(db, clientId) {
+	return db.select({
+		uuid: agents.uuid,
+		name: agents.name,
+		displayName: agents.displayName,
+		type: agents.type
+	}).from(agents).where(and(eq(agents.clientId, clientId), ne(agents.status, "deleted")));
+}
 async function listClients(db, userId) {
 	const rows = await db.select().from(clients).where(eq(clients.userId, userId));
 	const counts = await db.select({
@@ -6084,6 +6266,13 @@ function removeClientConnection(clientId, ws) {
 	clientConnections.delete(clientId);
 	return agentIds;
 }
+/** Send a message to a client's WebSocket. Returns true if delivered. */
+function sendToClient(clientId, message) {
+	const entry = clientConnections.get(clientId);
+	if (!entry || entry.ws.readyState !== 1) return false;
+	entry.ws.send(JSON.stringify(message));
+	return true;
+}
 /** Send a message to a specific agent via its client's WebSocket. Returns true if delivered. */
 function sendToAgent$1(agentId, message) {
 	const clientId = agentToClient.get(agentId);
@@ -6350,6 +6539,34 @@ function notifyRecipients(notifier, recipients, messageId) {
 	for (const inboxId of recipients) notifier.notify(inboxId, messageId).catch(() => {});
 }
 async function adminAgentRoutes(app) {
+	/**
+	* Push an `agent:pinned` frame to the connected client so it can auto-register
+	* the agent locally without the operator running `first-tree-hub agent add`.
+	*
+	* Best-effort: if the client is not currently connected to this server
+	* instance, the notification is silently dropped here — the client picks the
+	* pinning up on its next `client:register` handshake via the backfill path
+	* in `api/agent/ws-client.ts`.
+	*/
+	function notifyClientAgentPinned(agent) {
+		if (!agent.clientId) return;
+		const parsed = agentPinnedMessageSchema$1.safeParse({
+			type: "agent:pinned",
+			agentId: agent.uuid,
+			name: agent.name,
+			displayName: agent.displayName,
+			agentType: agent.type
+		});
+		if (!parsed.success) {
+			app.log.warn({
+				err: parsed.error.flatten(),
+				agentId: agent.uuid,
+				clientId: agent.clientId
+			}, "agent:pinned frame failed schema validation — not sending");
+			return;
+		}
+		sendToClient(agent.clientId, parsed.data);
+	}
 	const listAgentsFilterSchema = z.object({ type: agentTypeSchema$1.optional() });
 	app.get("/", async (request) => {
 		const query = paginationQuerySchema.parse(request.query);
@@ -6380,6 +6597,7 @@ async function adminAgentRoutes(app) {
 			source: body.source ?? "admin-api",
 			managerId
 		});
+		notifyClientAgentPinned(agent);
 		return reply.status(201).send({
 			...agent,
 			createdAt: agent.createdAt.toISOString(),
@@ -6392,7 +6610,9 @@ async function adminAgentRoutes(app) {
 		const body = updateAgentSchema.parse(request.body);
 		const member = requireMember(request);
 		if (body.managerId !== void 0 && member.role !== "admin") throw new ForbiddenError("Only admins can reassign an agent's manager");
+		const before = body.clientId !== void 0 ? await getAgent(app.db, request.params.uuid) : null;
 		const agent = await updateAgent(app.db, request.params.uuid, body);
+		if (before && before.clientId === null && agent.clientId !== null) notifyClientAgentPinned(agent);
 		return {
 			...agent,
 			createdAt: agent.createdAt.toISOString(),
@@ -8785,6 +9005,32 @@ function clientWsRoutes(notifier, instanceId) {
 							type: "client:registered",
 							clientId: data.clientId
 						}));
+						try {
+							const pinned = await listActiveAgentsPinnedToClient(app.db, data.clientId);
+							for (const agent of pinned) {
+								const parsed = agentPinnedMessageSchema$1.safeParse({
+									type: "agent:pinned",
+									agentId: agent.uuid,
+									name: agent.name,
+									displayName: agent.displayName,
+									agentType: agent.type
+								});
+								if (!parsed.success) {
+									app.log.warn({
+										err: parsed.error.flatten(),
+										agentId: agent.uuid,
+										clientId: data.clientId
+									}, "agent:pinned backfill frame failed schema validation — skipping");
+									continue;
+								}
+								socket.send(JSON.stringify(parsed.data));
+							}
+						} catch (err) {
+							app.log.error({
+								err,
+								clientId: data.clientId
+							}, "agent:pinned backfill on client:register failed — client may need manual `agent add`");
+						}
 					} else if (type === "agent:bind") {
 						if (!clientId) {
 							socket.send(JSON.stringify({

package/dist/{feishu-CJ08ntOD.mjs → feishu-D9JkMZnU.mjs}

@@ -199,6 +199,19 @@ z.object({
 	branch: z.string().nullable()
 });
 /**
+* Server → client WebSocket frame announcing that an agent has just been
+* pinned to the connected client (either created with `clientId` or bound via
+* PATCH NULL → ID). The client can auto-register a local config from this so
+* the operator doesn't have to run `first-tree-hub agent add` manually.
+*/
+const agentPinnedMessageSchema = z.object({
+	type: z.literal("agent:pinned"),
+	agentId: z.string(),
+	name: z.string().nullable(),
+	displayName: z.string().nullable(),
+	agentType: agentTypeSchema
+});
+/**
 * Agent runtime configuration — M1 (Claude Code only).
 *
 * Defines the 5 user-tunable field groups that the Hub centrally manages
@@ -877,4 +890,4 @@ async function bindFeishuUser(serverUrl, accessToken, agentId, humanAgentId, fei
 	}
 }
 //#endregion
-export { updateAgentSchema as $, createOrganizationSchema as A, paginationQuerySchema as B, clientRegisterSchema as C, createAgentSchema as D, createAdapterMappingSchema as E, isRedactedEnvValue as F, sendToAgentSchema as G, runtimeStateMessageSchema as H, linkTaskChatSchema as I, sessionEventSchema as J, sessionCompletionMessageSchema as K, loginSchema as L, delegateFeishuUserSchema as M, dryRunAgentRuntimeConfigSchema as N, createChatSchema as O, inboxPollQuerySchema as P, updateAgentRuntimeConfigSchema as Q, messageSourceSchema as R, agentTypeSchema as S, createAdapterConfigSchema as T, selfServiceFeishuBotSchema as U, refreshTokenSchema as V, sendMessageSchema as W, taskListQuerySchema as X, sessionStateMessageSchema as Y, updateAdapterConfigSchema as Z, addParticipantSchema as _, AGENT_SELECTOR_HEADER as a, agentBindRequestSchema as b, AGENT_TYPES as c, SYSTEM_CONFIG_DEFAULTS as d, updateMemberSchema as et, TASK_CREATOR_TYPES as f, WS_AUTH_FRAME_TIMEOUT_MS as g, TASK_TERMINAL_STATUSES as h, AGENT_BIND_REJECT_REASONS as i, wsAuthFrameSchema as it, createTaskSchema as j, createMemberSchema as k, AGENT_VISIBILITY as l, TASK_STATUSES as m, bindFeishuUser as n, updateSystemConfigSchema as nt, AGENT_SOURCES as o, TASK_HEALTH_SIGNALS as p, sessionEventMessageSchema as q, feishu_exports as r, updateTaskStatusSchema as rt, AGENT_STATUSES as s, bindFeishuBot as t, updateOrganizationSchema as tt, DEFAULT_AGENT_RUNTIME_CONFIG_PAYLOAD as u, adminCreateTaskSchema as v, connectTokenExchangeSchema as w, agentRuntimeConfigPayloadSchema as x, adminUpdateTaskSchema as y, notificationQuerySchema as z };
+export { updateAgentRuntimeConfigSchema as $, createMemberSchema as A, notificationQuerySchema as B, agentTypeSchema as C, createAdapterMappingSchema as D, createAdapterConfigSchema as E, inboxPollQuerySchema as F, sendMessageSchema as G, refreshTokenSchema as H, isRedactedEnvValue as I, sessionEventMessageSchema as J, sendToAgentSchema as K, linkTaskChatSchema as L, createTaskSchema as M, delegateFeishuUserSchema as N, createAgentSchema as O, dryRunAgentRuntimeConfigSchema as P, updateAdapterConfigSchema as Q, loginSchema as R, agentRuntimeConfigPayloadSchema as S, connectTokenExchangeSchema as T, runtimeStateMessageSchema as U, paginationQuerySchema as V, selfServiceFeishuBotSchema as W, sessionStateMessageSchema as X, sessionEventSchema as Y, taskListQuerySchema as Z, addParticipantSchema as _, AGENT_SELECTOR_HEADER as a, wsAuthFrameSchema as at, agentBindRequestSchema as b, AGENT_TYPES as c, SYSTEM_CONFIG_DEFAULTS as d, updateAgentSchema as et, TASK_CREATOR_TYPES as f, WS_AUTH_FRAME_TIMEOUT_MS as g, TASK_TERMINAL_STATUSES as h, AGENT_BIND_REJECT_REASONS as i, updateTaskStatusSchema as it, createOrganizationSchema as j, createChatSchema as k, AGENT_VISIBILITY as l, TASK_STATUSES as m, bindFeishuUser as n, updateOrganizationSchema as nt, AGENT_SOURCES as o, TASK_HEALTH_SIGNALS as p, sessionCompletionMessageSchema as q, feishu_exports as r, updateSystemConfigSchema as rt, AGENT_STATUSES as s, bindFeishuBot as t, updateMemberSchema as tt, DEFAULT_AGENT_RUNTIME_CONFIG_PAYLOAD as u, adminCreateTaskSchema as v, clientRegisterSchema as w, agentPinnedMessageSchema as x, adminUpdateTaskSchema as y, messageSourceSchema as z };

package/dist/index.mjs

@@ -1,4 +1,4 @@
-import { a as resolveAccessToken, n as ensureFreshAccessToken, o as resolveServerUrl, r as ensureFreshAdminToken } from "./bootstrap-CRDR6NwE.mjs";
-import { A as stopPostgres, C as checkServerReachable, D as status, E as blank, F as SdkError, M as createOwner, N as hasUser, O as ensurePostgres, P as FirstTreeHubSDK, S as checkServerHealth, T as printResults, _ as checkClientConfig, a as uninstallClientService, b as checkNodeVersion, c as promptAddAgent, f as onboardCheck, g as checkAgentConfigs, h as runMigrations, i as resolveCliInvocation, j as ClientRuntime, k as isDockerAvailable, l as promptMissingFields, n as installClientService, o as startServer, p as onboardCreate, r as isServiceSupported, s as isInteractive, t as getClientServiceStatus, u as formatCheckReport, v as checkDatabase, w as checkWebSocket, x as checkServerConfig, y as checkDocker } from "./core-6-paFwyo.mjs";
-import { n as bindFeishuUser, t as bindFeishuBot } from "./feishu-CJ08ntOD.mjs";
+import { a as resolveAccessToken, n as ensureFreshAccessToken, o as resolveServerUrl, r as ensureFreshAdminToken } from "./bootstrap-8nCntTrK.mjs";
+import { A as stopPostgres, C as checkServerReachable, D as status, E as blank, F as SdkError, M as createOwner, N as hasUser, O as ensurePostgres, P as FirstTreeHubSDK, S as checkServerHealth, T as printResults, _ as checkClientConfig, a as uninstallClientService, b as checkNodeVersion, c as promptAddAgent, f as onboardCheck, g as checkAgentConfigs, h as runMigrations, i as resolveCliInvocation, j as ClientRuntime, k as isDockerAvailable, l as promptMissingFields, n as installClientService, o as startServer, p as onboardCreate, r as isServiceSupported, s as isInteractive, t as getClientServiceStatus, u as formatCheckReport, v as checkDatabase, w as checkWebSocket, x as checkServerConfig, y as checkDocker } from "./core-BA5U1v9L.mjs";
+import { n as bindFeishuUser, t as bindFeishuBot } from "./feishu-D9JkMZnU.mjs";
 export { ClientRuntime, FirstTreeHubSDK, SdkError, bindFeishuBot, bindFeishuUser, blank, checkAgentConfigs, checkClientConfig, checkDatabase, checkDocker, checkNodeVersion, checkServerConfig, checkServerHealth, checkServerReachable, checkWebSocket, createOwner, ensureFreshAccessToken, ensureFreshAdminToken, ensurePostgres, formatCheckReport, getClientServiceStatus, hasUser, installClientService, isDockerAvailable, isInteractive, isServiceSupported, onboardCheck, onboardCreate, printResults, promptAddAgent, promptMissingFields, resolveAccessToken, resolveCliInvocation, resolveServerUrl, runMigrations, startServer, status, stopPostgres, uninstallClientService };