@agent-team-foundation/first-tree-hub 0.11.1 → 0.11.3

package/dist/{bootstrap-TJRy0B9m.mjs → bootstrap-D4rdqM2F.mjs}

@@ -1,5 +1,6 @@
 import { r as __exportAll } from "./chunk-BSw8zbkd.mjs";
 import { o as logFormatSchema, s as logLevelSchema } from "./logger-core-BTmvdflj-DjW8FM4T.mjs";
+import { t as cliFetch } from "./cli-fetch--tiwKm5S.mjs";
 import { z } from "zod";
 import { dirname, join } from "node:path";
 import { homedir } from "node:os";
@@ -569,10 +570,11 @@ const serverConfigSchema = defineConfig({
 		connectTokenExpiry: field(z.string().default("10m"), { env: "FIRST_TREE_HUB_AUTH_CONNECT_TOKEN_EXPIRY" })
 	},
 	contextTree: optional({
-		repo: field(z.string(), {
+		repo: field(z.string().optional(), {
 			env: "FIRST_TREE_HUB_CONTEXT_TREE_REPO",
 			prompt: { message: "Context Tree repo URL (e.g. https://github.com/org/first-tree):" }
 		}),
+		localPath: field(z.string().optional(), { env: "FIRST_TREE_HUB_CONTEXT_TREE_PATH" }),
 		branch: field(z.string().default("main"))
 	}),
 	github: {
@@ -595,6 +597,7 @@ const serverConfigSchema = defineConfig({
 		max: field(z.number().default(100), { env: "FIRST_TREE_HUB_RATE_LIMIT_MAX" }),
 		loginMax: field(z.number().default(5), { env: "FIRST_TREE_HUB_RATE_LIMIT_LOGIN_MAX" }),
 		webhookMax: field(z.number().default(60), { env: "FIRST_TREE_HUB_RATE_LIMIT_WEBHOOK_MAX" }),
+		contextTreeSnapshotMax: field(z.number().default(6), { env: "FIRST_TREE_HUB_RATE_LIMIT_CONTEXT_TREE_SNAPSHOT_MAX" }),
 		agentMessageMax: field(z.number().default(30), { env: "FIRST_TREE_HUB_RATE_LIMIT_AGENT_MESSAGE_MAX" })
 	}),
 	ws: optional({ maxPayload: field(z.number().int().min(1024).default(262144), { env: "FIRST_TREE_HUB_WS_MAX_PAYLOAD" }) }),
@@ -782,7 +785,7 @@ async function ensureFreshAccessToken(opts) {
 	if (!isTokenStale(creds.accessToken, minValidityMs)) return creds.accessToken;
 	if (inflightRefresh) return inflightRefresh;
 	inflightRefresh = (async () => {
-		const res = await fetch(`${creds.serverUrl}/api/v1/auth/refresh`, {
+		const res = await cliFetch(`${creds.serverUrl}/api/v1/auth/refresh`, {
 			method: "POST",
 			headers: { "Content-Type": "application/json" },
 			body: JSON.stringify({ refreshToken: creds.refreshToken }),

package/dist/cli/index.mjs

@@ -1,14 +1,15 @@
 #!/usr/bin/env node
-import "../observability-C3nY6Jcz-Dpsi3eFk.mjs";
-import { $ as findStaleAliases, A as checkDatabase, B as installClientService, C as runHomeMigration, D as checkAgentConfigs, E as runMigrations, F as checkServerReachable, G as stopClientService, I as checkWebSocket, L as printResults, M as checkNodeVersion, N as checkServerConfig, O as checkBackgroundService, P as checkServerHealth, R as reconcileAgentConfigs, S as saveOnboardState, T as migrateLocalAgentDirs, U as restartClientService, V as isServiceSupported, W as startClientService, X as ClientRuntime, Y as stopPostgres, Z as handleClientOrgMismatch, _ as promptMissingFields, _t as probeCapabilities, a as declineUpdate, at as fail, b as onboardCheck, c as detectInstallMode, ct as print, d as startServer, dt as ClientOrgMismatchError, et as formatStaleReason, f as COMMAND_VERSION, ft as ClientUserMismatchError, g as promptAddAgent, gt as cleanWorkspaces, h as isInteractive, ht as SessionRegistry, i as createExecuteUpdate, it as resolveReplyToFromEnv, j as checkDocker, k as checkClientConfig, l as fetchLatestVersion, lt as setJsonMode, m as uploadClientCapabilities, mt as SdkError, nt as createOwner, o as promptUpdate, ot as success, p as reconcileLocalRuntimeProviders, pt as FirstTreeHubSDK, r as registerSaaSConnectCommand, s as PACKAGE_NAME, tt as removeLocalAgent, u as installGlobalLatest, v as formatCheckReport, vt as applyClientLoggerConfig, w as createApiNameResolver, x as onboardCreate, y as loadOnboardState, yt as configureClientLoggerForService, z as getClientServiceStatus } from "../saas-connect-Bd0g0v_b.mjs";
+import "../observability-BAScT_5S-gw1ODB_o.mjs";
+import { $ as formatStaleReason, A as checkDocker, B as isServiceSupported, C as createApiNameResolver, D as checkBackgroundService, E as checkAgentConfigs, F as checkWebSocket, H as restartClientService, I as printResults, J as stopPostgres, L as reconcileAgentConfigs, M as checkServerConfig, N as checkServerHealth, O as checkClientConfig, P as checkServerReachable, Q as findStaleAliases, R as getClientServiceStatus, S as runHomeMigration, T as runMigrations, U as startClientService, W as stopClientService, X as handleClientOrgMismatch, Y as ClientRuntime, _ as formatCheckReport, a as declineUpdate, at as success, b as onboardCreate, c as detectInstallMode, ct as FirstTreeHubSDK, d as startServer, dt as cleanWorkspaces, et as removeLocalAgent, f as reconcileLocalRuntimeProviders, ft as probeCapabilities, g as promptMissingFields, h as promptAddAgent, i as createExecuteUpdate, it as fail, j as checkNodeVersion, k as checkDatabase, l as fetchLatestVersion, lt as SdkError, m as isInteractive, mt as configureClientLoggerForService, o as promptUpdate, ot as ClientOrgMismatchError, p as uploadClientCapabilities, pt as applyClientLoggerConfig, r as registerSaaSConnectCommand, rt as resolveReplyToFromEnv, s as PACKAGE_NAME, st as ClientUserMismatchError, tt as createOwner, u as installGlobalLatest, ut as SessionRegistry, v as loadOnboardState, w as migrateLocalAgentDirs, x as saveOnboardState, y as onboardCheck, z as installClientService } from "../saas-connect-gcT6Q10z.mjs";
 import "../logger-core-BTmvdflj-DjW8FM4T.mjs";
-import { C as resetConfigMeta, E as setConfigValue, S as resetConfig, T as serverConfigSchema, _ as getConfigValue, a as ensureFreshAdminToken, c as resolveServerUrl, d as DEFAULT_CONFIG_DIR, f as DEFAULT_DATA_DIR, h as clientConfigSchema, i as ensureFreshAccessToken, l as saveAgentConfig, m as agentConfigSchema, o as loadCredentials, p as DEFAULT_HOME_DIR, u as saveCredentials, v as initConfig, w as resolveConfigReadonly, x as readConfigFile, y as loadAgents } from "../bootstrap-TJRy0B9m.mjs";
-import "../dist-BkvrONSQ.mjs";
-import { n as bindFeishuUser, t as bindFeishuBot } from "../feishu-AEMHwT6L.mjs";
-import "../errors-BmyRwN0Y-CIZZ_sDc.mjs";
-import "../client-BCaK653p-CZjDNcdM.mjs";
-import "../src-DNBS5Yjj.mjs";
-import "../invitation-Dnn5gGGX-Ce7zbZpn.mjs";
+import { C as resetConfigMeta, E as setConfigValue, S as resetConfig, T as serverConfigSchema, _ as getConfigValue, a as ensureFreshAdminToken, c as resolveServerUrl, d as DEFAULT_CONFIG_DIR, f as DEFAULT_DATA_DIR, h as clientConfigSchema, i as ensureFreshAccessToken, l as saveAgentConfig, m as agentConfigSchema, o as loadCredentials, p as DEFAULT_HOME_DIR, u as saveCredentials, v as initConfig, w as resolveConfigReadonly, x as readConfigFile, y as loadAgents } from "../bootstrap-D4rdqM2F.mjs";
+import { a as print, n as CLI_USER_AGENT, o as setJsonMode, r as COMMAND_VERSION, t as cliFetch } from "../cli-fetch--tiwKm5S.mjs";
+import "../dist-BAqGZkco.mjs";
+import { n as bindFeishuUser, t as bindFeishuBot } from "../feishu-Th_-ivJ7.mjs";
+import "../errors-BmyRwN0Y-Dad3eV8F.mjs";
+import "../client-CLdRbuml-BRtalKpQ.mjs";
+import "../src-aJMV60mR.mjs";
+import "../invitation-Dnn5gGGX-DXryyvRG.mjs";
 import { join } from "node:path";
 import { existsSync, mkdirSync, readFileSync, readdirSync } from "node:fs";
 import * as semver from "semver";
@@ -16,7 +17,7 @@ import { Command } from "commander";
 import { confirm, input, password, select } from "@inquirer/prompts";
 //#region src/commands/agent-config.ts
 async function resolveAgentRecord(serverUrl, adminToken, agentName) {
-	const res = await fetch(`${serverUrl}/api/v1/me/managed-agents`, {
+	const res = await cliFetch(`${serverUrl}/api/v1/me/managed-agents`, {
 		headers: { Authorization: `Bearer ${adminToken}` },
 		signal: AbortSignal.timeout(1e4)
 	});
@@ -27,7 +28,7 @@ async function resolveAgentRecord(serverUrl, adminToken, agentName) {
 }
 async function adminFetch(url, init) {
 	const { adminToken, headers, ...rest } = init;
-	const res = await fetch(url, {
+	const res = await cliFetch(url, {
 		...rest,
 		headers: {
 			Authorization: `Bearer ${adminToken}`,
@@ -240,7 +241,8 @@ function createSdk(agentName) {
 	return new FirstTreeHubSDK({
 		serverUrl,
 		getAccessToken: (opts) => ensureFreshAccessToken(opts),
-		agentId
+		agentId,
+		userAgent: CLI_USER_AGENT
 	});
 }
 function handleSdkError(error) {
@@ -276,7 +278,7 @@ function readStdin() {
 	});
 }
 async function resolveAgent(serverUrl, adminToken, agentName) {
-	const res = await fetch(`${serverUrl}/api/v1/me/managed-agents`, {
+	const res = await cliFetch(`${serverUrl}/api/v1/me/managed-agents`, {
 		headers: { Authorization: `Bearer ${adminToken}` },
 		signal: AbortSignal.timeout(1e4)
 	});
@@ -339,7 +341,8 @@ function registerAgentCommands(program) {
 			const clientId = readClientId();
 			const sdk = new FirstTreeHubSDK({
 				serverUrl,
-				getAccessToken: (opts) => ensureFreshAccessToken(opts)
+				getAccessToken: (opts) => ensureFreshAccessToken(opts),
+				userAgent: CLI_USER_AGENT
 			});
 			const stale = await findStaleAliases({
 				clientId,
@@ -406,7 +409,7 @@ function registerAgentCommands(program) {
 		try {
 			const serverUrl = resolveServerUrl(options.server);
 			const token = await ensureFreshAccessToken();
-			const res = await fetch(`${serverUrl}/api/v1/me/managed-agents`, {
+			const res = await cliFetch(`${serverUrl}/api/v1/me/managed-agents`, {
 				headers: { Authorization: `Bearer ${token}` },
 				signal: AbortSignal.timeout(1e4)
 			});
@@ -433,7 +436,7 @@ function registerAgentCommands(program) {
 				Authorization: `Bearer ${adminToken}`,
 				"Content-Type": "application/json"
 			};
-			const meRes = await fetch(`${serverUrl}/api/v1/me`, {
+			const meRes = await cliFetch(`${serverUrl}/api/v1/me`, {
 				headers: { Authorization: `Bearer ${adminToken}` },
 				signal: AbortSignal.timeout(1e4)
 			});
@@ -456,7 +459,7 @@ function registerAgentCommands(program) {
 				runtimeProvider: options.runtime
 			};
 			if (options.displayName) createBody.displayName = options.displayName;
-			const createRes = await fetch(`${serverUrl}/api/v1/orgs/${encodeURIComponent(orgId)}/agents`, {
+			const createRes = await cliFetch(`${serverUrl}/api/v1/orgs/${encodeURIComponent(orgId)}/agents`, {
 				method: "POST",
 				headers,
 				body: JSON.stringify(createBody),
@@ -476,14 +479,14 @@ function registerAgentCommands(program) {
 		try {
 			const serverUrl = resolveServerUrl(options.server);
 			const accessToken = await ensureFreshAccessToken();
-			const meRes = await fetch(`${serverUrl}/api/v1/me`, {
+			const meRes = await cliFetch(`${serverUrl}/api/v1/me`, {
 				headers: { Authorization: `Bearer ${accessToken}` },
 				signal: AbortSignal.timeout(1e4)
 			});
 			if (!meRes.ok) fail("ME_ERROR", `Failed to fetch current member (HTTP ${meRes.status})`, 1);
 			const me = await meRes.json();
 			const target = await resolveAgent(serverUrl, accessToken, agentName);
-			const patchRes = await fetch(`${serverUrl}/api/v1/agents/${target.uuid}`, {
+			const patchRes = await cliFetch(`${serverUrl}/api/v1/agents/${target.uuid}`, {
 				method: "PATCH",
 				headers: {
 					Authorization: `Bearer ${accessToken}`,
@@ -526,7 +529,7 @@ function registerAgentCommands(program) {
 			const serverUrl = resolveServerUrl(options.server);
 			const accessToken = await ensureFreshAccessToken();
 			const target = await resolveAgent(serverUrl, accessToken, agentName);
-			const patchRes = await fetch(`${serverUrl}/api/v1/agents/${target.uuid}`, {
+			const patchRes = await cliFetch(`${serverUrl}/api/v1/agents/${target.uuid}`, {
 				method: "PATCH",
 				headers: {
 					Authorization: `Bearer ${accessToken}`,
@@ -636,7 +639,7 @@ function registerAgentCommands(program) {
 		try {
 			const serverUrl = resolveServerUrl(options?.server);
 			const accessToken = await ensureFreshAccessToken();
-			const meRes = await fetch(`${serverUrl}/api/v1/me`, {
+			const meRes = await cliFetch(`${serverUrl}/api/v1/me`, {
 				headers: { Authorization: `Bearer ${accessToken}` },
 				signal: AbortSignal.timeout(1e4)
 			});
@@ -655,7 +658,7 @@ function registerAgentCommands(program) {
 				agents: []
 			};
 			for (const m of me.memberships) {
-				const r = await fetch(`${serverUrl}/api/v1/orgs/${encodeURIComponent(m.organizationId)}/activity`, {
+				const r = await cliFetch(`${serverUrl}/api/v1/orgs/${encodeURIComponent(m.organizationId)}/activity`, {
 					headers: { Authorization: `Bearer ${accessToken}` },
 					signal: AbortSignal.timeout(1e4)
 				});
@@ -704,8 +707,7 @@ function registerAgentCommands(program) {
 	});
 	agent.command("reset <name>").description("Reset agent error state to idle").option("--server <url>", "Hub server URL").action(async (name, options) => {
 		try {
-			const serverUrl = resolveServerUrl(options.server);
-			const response = await fetch(`${serverUrl}/api/v1/agents/${name}/reset-activity`, {
+			const response = await cliFetch(`${resolveServerUrl(options.server)}/api/v1/agents/${name}/reset-activity`, {
 				method: "POST",
 				headers: { Authorization: `Bearer ${await ensureFreshAccessToken()}` },
 				signal: AbortSignal.timeout(1e4)
@@ -721,8 +723,7 @@ function registerAgentCommands(program) {
 			const serverUrl = resolveServerUrl(options.server);
 			const adminToken = await ensureFreshAccessToken();
 			const agentId = (await resolveAgent(serverUrl, adminToken, agentName)).uuid;
-			const qs = options.state ? `?state=${options.state}` : "";
-			const response = await fetch(`${serverUrl}/api/v1/agents/${agentId}/sessions${qs}`, {
+			const response = await cliFetch(`${serverUrl}/api/v1/agents/${agentId}/sessions${options.state ? `?state=${options.state}` : ""}`, {
 				headers: { Authorization: `Bearer ${adminToken}` },
 				signal: AbortSignal.timeout(1e4)
 			});
@@ -751,7 +752,7 @@ function registerAgentCommands(program) {
 			const serverUrl = resolveServerUrl(options.server);
 			const adminToken = await ensureFreshAccessToken();
 			const agentId = (await resolveAgent(serverUrl, adminToken, agentName)).uuid;
-			const response = await fetch(`${serverUrl}/api/v1/agents/${agentId}/sessions/${chatId}/${cmd}`, {
+			const response = await cliFetch(`${serverUrl}/api/v1/agents/${agentId}/sessions/${chatId}/${cmd}`, {
 				method: "POST",
 				headers: { Authorization: `Bearer ${adminToken}` },
 				signal: AbortSignal.timeout(1e4)
@@ -774,7 +775,7 @@ function registerAgentCommands(program) {
 				"Content-Type": "application/json"
 			};
 			const targetAgent = await resolveAgent(serverUrl, adminToken, agentName);
-			const dmRes = await fetch(`${serverUrl}/api/v1/agents/${targetAgent.uuid}/chats`, {
+			const dmRes = await cliFetch(`${serverUrl}/api/v1/agents/${targetAgent.uuid}/chats`, {
 				method: "POST",
 				headers,
 				signal: AbortSignal.timeout(1e4)
@@ -796,7 +797,7 @@ function registerAgentCommands(program) {
 			const pollMessages = async () => {
 				try {
 					const qs = lastSeenAt ? `?limit=50` : `?limit=10`;
-					const msgRes = await fetch(`${serverUrl}/api/v1/chats/${dm.id}/messages${qs}`, {
+					const msgRes = await cliFetch(`${serverUrl}/api/v1/chats/${dm.id}/messages${qs}`, {
 						headers,
 						signal: AbortSignal.timeout(1e4)
 					});
@@ -827,7 +828,7 @@ function registerAgentCommands(program) {
 					return;
 				}
 				try {
-					const sendRes = await fetch(`${serverUrl}/api/v1/chats/${dm.id}/messages`, {
+					const sendRes = await cliFetch(`${serverUrl}/api/v1/chats/${dm.id}/messages`, {
 						method: "POST",
 						headers,
 						body: JSON.stringify({
@@ -963,7 +964,7 @@ function printIsolationGuide(newServerUrl) {
 * Authenticate via connect token — exchange for full JWT credentials.
 */
 async function authenticateWithToken(url, token) {
-	const res = await fetch(`${url}/api/v1/auth/connect-token`, {
+	const res = await cliFetch(`${url}/api/v1/auth/connect-token`, {
 		method: "POST",
 		headers: { "Content-Type": "application/json" },
 		body: JSON.stringify({ token }),
@@ -979,7 +980,7 @@ async function authenticateInteractive(url) {
 	print.line("\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`, {
+	const loginRes = await cliFetch(`${url}/api/v1/auth/login`, {
 		method: "POST",
 		headers: { "Content-Type": "application/json" },
 		body: JSON.stringify({
@@ -1270,7 +1271,8 @@ function registerClientCommands(program) {
 			});
 			const sdk = new FirstTreeHubSDK({
 				serverUrl,
-				getAccessToken: (opts) => ensureFreshAccessToken(opts)
+				getAccessToken: (opts) => ensureFreshAccessToken(opts),
+				userAgent: CLI_USER_AGENT
 			});
 			agentCheck = await reconcileAgentConfigs({
 				clientId: cfg.client.id,
@@ -1396,7 +1398,7 @@ function registerClientCommands(program) {
 		try {
 			const serverUrl = resolveServerUrl(options.server);
 			const token = await ensureFreshAccessToken();
-			const meRes = await fetch(`${serverUrl}/api/v1/me`, {
+			const meRes = await cliFetch(`${serverUrl}/api/v1/me`, {
 				headers: { Authorization: `Bearer ${token}` },
 				signal: AbortSignal.timeout(1e4)
 			});
@@ -1404,7 +1406,7 @@ function registerClientCommands(program) {
 			const adminOrgs = (await meRes.json()).memberships.filter((m) => m.role === "admin");
 			const clients = [];
 			for (const m of adminOrgs) {
-				const r = await fetch(`${serverUrl}/api/v1/orgs/${encodeURIComponent(m.organizationId)}/clients`, {
+				const r = await cliFetch(`${serverUrl}/api/v1/orgs/${encodeURIComponent(m.organizationId)}/clients`, {
 					headers: { Authorization: `Bearer ${token}` },
 					signal: AbortSignal.timeout(1e4)
 				});
@@ -1453,7 +1455,7 @@ function registerClientCommands(program) {
 				}
 			}
 			const token = await ensureFreshAccessToken();
-			const response = await fetch(`${serverUrl}/api/v1/clients/${encodeURIComponent(clientId)}/claim`, {
+			const response = await cliFetch(`${serverUrl}/api/v1/clients/${encodeURIComponent(clientId)}/claim`, {
 				method: "POST",
 				headers: {
 					Authorization: `Bearer ${token}`,
@@ -1471,7 +1473,8 @@ function registerClientCommands(program) {
 			try {
 				const sdk = new FirstTreeHubSDK({
 					serverUrl,
-					getAccessToken: (opts) => ensureFreshAccessToken(opts)
+					getAccessToken: (opts) => ensureFreshAccessToken(opts),
+					userAgent: CLI_USER_AGENT
 				});
 				const stale = await findStaleAliases({
 					clientId,
@@ -1520,7 +1523,7 @@ function registerClientCommands(program) {
 		try {
 			const serverUrl = resolveServerUrl(options.server);
 			const token = await ensureFreshAccessToken();
-			const response = await fetch(`${serverUrl}/api/v1/clients/${encodeURIComponent(clientId)}/disconnect`, {
+			const response = await cliFetch(`${serverUrl}/api/v1/clients/${encodeURIComponent(clientId)}/disconnect`, {
 				method: "POST",
 				headers: { Authorization: `Bearer ${token}` },
 				signal: AbortSignal.timeout(1e4)
@@ -1667,13 +1670,13 @@ function isSecretField(schema, dotPath) {
 //#region src/commands/onboard.ts
 async function promptMissing(args) {
 	if (!args.server) try {
-		const { resolveServerUrl } = await import("../bootstrap-TJRy0B9m.mjs").then((n) => n.r);
+		const { resolveServerUrl } = await import("../bootstrap-D4rdqM2F.mjs").then((n) => n.r);
 		resolveServerUrl();
 	} catch {
 		args.server = await input({ message: "Hub server URL:" });
 		saveOnboardState(args);
 	}
-	const { loadCredentials } = await import("../bootstrap-TJRy0B9m.mjs").then((n) => n.r);
+	const { loadCredentials } = await import("../bootstrap-D4rdqM2F.mjs").then((n) => n.r);
 	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:" });
@@ -1833,7 +1836,7 @@ function registerServerCommands(program) {
 	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`);
+			const res = await cliFetch(`${url}/api/v1/health`);
 			if (res.ok) {
 				const data = await res.json();
 				process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);

package/dist/cli-fetch--tiwKm5S.mjs

@@ -0,0 +1,167 @@
+import { dirname, resolve } from "node:path";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+//#region src/core/output.ts
+/**
+* Print layer — the only place CLI code should write to stdout/stderr.
+*
+* Contract:
+* - `print.result(data)` / `print.fail(...)` emit machine-readable JSON on
+*   stdout / stderr respectively. Scripts pipe into `jq` and expect a clean
+*   envelope, so nothing else may touch stdout.
+* - `print.status` / `print.check` / `print.blank` / `print.line` are
+*   human-friendly and go to stderr so they never pollute a redirected stdout.
+*   In `--json` mode they are silenced — scripted consumers only care about
+*   the envelope.
+*/
+let jsonMode = false;
+function setJsonMode(enabled) {
+	jsonMode = enabled;
+}
+function result(data) {
+	process.stdout.write(`${JSON.stringify({
+		ok: true,
+		data
+	})}\n`);
+}
+function fail(code, message, exitCode = 1) {
+	process.stderr.write(`${JSON.stringify({
+		ok: false,
+		error: {
+			code,
+			message
+		}
+	})}\n`);
+	process.exit(exitCode);
+}
+function status(label, message) {
+	if (jsonMode) return;
+	process.stderr.write(`  ${label.padEnd(20)} ${message}\n`);
+}
+function check(pass, label, detail = "") {
+	if (jsonMode) return;
+	const icon = pass ? "✓" : "✗";
+	const tail = detail ? ` ${detail}` : "";
+	process.stderr.write(`  ${icon} ${label.padEnd(22)}${tail}\n`);
+}
+function blank() {
+	if (jsonMode) return;
+	process.stderr.write("\n");
+}
+/**
+* Generic stderr writer for pre-formatted human text (multi-line tables,
+* interactive prompts). Prefer `status` / `check` when the text fits; this
+* exists so the `--json` mode gate can silence arbitrary human chatter.
+*/
+function line(text) {
+	if (jsonMode) return;
+	process.stderr.write(text);
+}
+const print = {
+	result,
+	fail,
+	status,
+	check,
+	blank,
+	line
+};
+//#endregion
+//#region src/core/version.ts
+/**
+* Version of the consumer-facing `@agent-team-foundation/first-tree-hub`
+* package. Read once at module load so the CLI, client runtime, and server
+* bootstrap all quote the same string.
+*
+* Path-based lookups (`require("../../package.json")`) do not survive the
+* tsdown bundle: the source lives at `src/core/version.ts` but every
+* emitted chunk lands in `dist/` — shifting the relative depth by one and
+* pointing at `packages/package.json` instead of our own manifest (the
+* v0.9.1 "Cannot find module ../../package.json" crash). Walk up from this
+* module's URL and accept the first `package.json` whose `name` matches, so
+* dev runs (`tsx src/cli/index.ts`) and the published bundle
+* (`dist/cli/index.mjs`) both resolve the same file.
+*/
+const PACKAGE_NAME = "@agent-team-foundation/first-tree-hub";
+/**
+* Sentinel returned when the walker exhausts every parent directory without
+* finding our manifest. Deliberately NOT valid SemVer so the client-side
+* `UpdateManager` drops into its `semver.valid(current) === false` warn-and-
+* skip branch instead of treating it as `< target` and triggering a spurious
+* self-update loop (the scenario where the startup crash this module fixes
+* would otherwise quietly reincarnate as repeated `npm install -g @latest`).
+*/
+const UNRESOLVED_VERSION = "unknown";
+/**
+* Exported for tests. Walks up from `moduleUrl`'s directory looking for a
+* `package.json` whose `name` field equals {@link PACKAGE_NAME}. Returns
+* {@link UNRESOLVED_VERSION} as a last-resort fallback so the CLI never
+* crashes on a missing manifest.
+*/
+function resolveCommandVersion(moduleUrl = import.meta.url) {
+	let dir = dirname(fileURLToPath(moduleUrl));
+	for (let i = 0; i < 10; i++) {
+		try {
+			const pkg = JSON.parse(readFileSync(resolve(dir, "package.json"), "utf8"));
+			if (pkg.name === PACKAGE_NAME && typeof pkg.version === "string" && pkg.version.length > 0) return pkg.version;
+		} catch (err) {
+			const code = err.code;
+			if (code !== "ENOENT" && code !== "ENOTDIR") {
+				const message = err instanceof Error ? err.message : String(err);
+				print.line(`[first-tree-hub] warning: could not read ${dir}/package.json: ${message}\n`);
+			}
+		}
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return UNRESOLVED_VERSION;
+}
+const COMMAND_VERSION = resolveCommandVersion();
+/**
+* `User-Agent` string sent on every CLI-originated HTTP request (SDK fetches,
+* `/auth/refresh`, etc.). Without this Node defaults to `User-Agent: node`,
+* which hides install / version / platform context from server-side trace
+* backends — see issue #246. The format follows RFC 7231 §5.5.3 conventions
+* (`product/version (comment)`).
+*/
+const CLI_USER_AGENT = `first-tree-hub-cli/${COMMAND_VERSION} (${process.platform} ${process.arch})`;
+//#endregion
+//#region src/core/cli-fetch.ts
+/**
+* Drop-in `fetch` wrapper that stamps `User-Agent: first-tree-hub-cli/<version> (<platform> <arch>)`
+* on every request.
+*
+* Issue #246: every CLI-originated HTTP request must carry a stable
+* `User-Agent` so trace backends can group failures (401 / 429 / 5xx) by
+* install. Plain `globalThis.fetch` defaults to `User-Agent: node`, which
+* collapses every install into a single bucket. Centralising the header
+* here means new direct-fetch sites pick the right UA up automatically —
+* no need to remember at each call site.
+*
+* SDK-routed requests stamp UA via {@link FirstTreeHubSDK} (see
+* `packages/client/src/sdk.ts`). This helper is for the
+* direct-`fetch` paths the SDK doesn't cover (auth bootstrap,
+* doctor probes, raw admin calls).
+*
+* Header precedence: caller-provided `User-Agent` in `init.headers` wins,
+* so callers can override (e.g. tests injecting a deterministic UA).
+*/
+function cliFetch(input, init) {
+	const merged = mergeHeaders(init?.headers);
+	return fetch(input, {
+		...init,
+		headers: merged
+	});
+}
+function mergeHeaders(provided) {
+	const out = {};
+	if (provided) if (provided instanceof Headers) provided.forEach((v, k) => {
+		out[k] = v;
+	});
+	else if (Array.isArray(provided)) for (const [k, v] of provided) out[k] = v;
+	else Object.assign(out, provided);
+	if (!Object.keys(out).some((k) => k.toLowerCase() === "user-agent")) out["User-Agent"] = CLI_USER_AGENT;
+	return out;
+}
+//#endregion
+export { print as a, blank as i, CLI_USER_AGENT as n, setJsonMode as o, COMMAND_VERSION as r, status as s, cliFetch as t };

package/dist/client-By1K4VVT-C5K7WZo6.mjs

@@ -0,0 +1,4 @@
+import "./dist-BAqGZkco.mjs";
+import "./errors-BmyRwN0Y-Dad3eV8F.mjs";
+import { y as listMyPinnedAgents } from "./client-CLdRbuml-BRtalKpQ.mjs";
+export { listMyPinnedAgents };

package/dist/{client-BCaK653p-CZjDNcdM.mjs → client-CLdRbuml-BRtalKpQ.mjs}

@@ -1,8 +1,8 @@
-import { C as clientCapabilitiesSchema } from "./dist-BkvrONSQ.mjs";
-import { a as ConflictError, i as ClientUserMismatchError, l as organizations, n as BadRequestError, s as NotFoundError, u as users } from "./errors-BmyRwN0Y-CIZZ_sDc.mjs";
+import { C as clientCapabilitiesSchema } from "./dist-BAqGZkco.mjs";
+import { a as ConflictError, i as ClientUserMismatchError, l as organizations, n as BadRequestError, s as NotFoundError, u as users } from "./errors-BmyRwN0Y-Dad3eV8F.mjs";
 import { and, eq, inArray, ne, sql } from "drizzle-orm";
 import { index, integer, jsonb, pgTable, text, timestamp, unique } from "drizzle-orm/pg-core";
-//#region ../server/dist/client-BCaK653p.mjs
+//#region ../server/dist/client-CLdRbuml.mjs
 /**
 * Client connections. A client is a single SDK process (AgentRuntime) that may
 * host multiple agents. From the unified-user-token milestone on, a client is
@@ -400,6 +400,14 @@ async function updateClientCapabilities(db, clientId, capabilities) {
 	await db.update(clients).set({ metadata: merged }).where(eq(clients.id, clientId));
 }
 /**
+* Scope-aware client listing. Returns the caller's own clients (cross-org —
+* a client is owned by a user, not an org). The admin route adds a separate
+* `?organizationId=` cross-user view via {@link listClientsForOrgAdmin}.
+*/
+async function listClients(db, scope) {
+	return attachAgentCounts(db, await db.select().from(clients).where(eq(clients.userId, scope.userId)));
+}
+/**
 * Admin-only cross-user listing: every client owned by an active member of
 * `orgId`. Joining `clients → members.user_id` instead of `clients.organization_id`
 * keeps the read path consistent with the rule that connection has no
@@ -513,4 +521,4 @@ async function cleanupStaleClients(db, staleSeconds = 60) {
 	return result.length;
 }
 //#endregion
-export { serverInstances as C, unbindAgent as D, touchAgent as E, updateClientCapabilities as O, retireClient as S, setRuntimeState as T, listClientsForOrgAdmin as _, claimClient as a, members as b, clients as c, getClient as d, getOnlineCount as f, listActiveAgentsPinnedToClient as g, heartbeatInstance as h, bindAgent as i, deriveAuthState as l, heartbeatClient as m, agents as n, cleanupStaleClients as o, getPresence as p, assertClientOwner as r, cleanupStalePresence as s, agentPresence as t, disconnectClient as u, listMyPinnedAgents as v, setOffline as w, registerClient as x, markStaleAgents as y };
+export { retireClient as C, touchAgent as D, setRuntimeState as E, unbindAgent as O, registerClient as S, setOffline as T, listClients as _, claimClient as a, markStaleAgents as b, clients as c, getClient as d, getOnlineCount as f, listActiveAgentsPinnedToClient as g, heartbeatInstance as h, bindAgent as i, updateClientCapabilities as k, deriveAuthState as l, heartbeatClient as m, agents as n, cleanupStaleClients as o, getPresence as p, assertClientOwner as r, cleanupStalePresence as s, agentPresence as t, disconnectClient as u, listClientsForOrgAdmin as v, serverInstances as w, members as x, listMyPinnedAgents as y };

package/dist/{dist-BkvrONSQ.mjs → dist-BAqGZkco.mjs}

@@ -679,6 +679,104 @@ const paginationQuerySchema = z.object({
 	limit: z.coerce.number().int().min(1).max(100).default(20),
 	cursor: z.string().optional()
 });
+const contextTreeSnapshotStatusSchema = z.enum([
+	"active",
+	"stale",
+	"unavailable"
+]);
+const contextTreeStatusSeveritySchema = z.enum([
+	"ok",
+	"warning",
+	"error"
+]);
+const contextTreeStatusSchema = z.object({
+	label: z.string(),
+	detail: z.string().nullable(),
+	severity: contextTreeStatusSeveritySchema
+});
+const contextTreeNodeKindSchema = z.enum([
+	"root",
+	"domain",
+	"subdomain",
+	"leaf"
+]);
+const contextTreeChangeTypeSchema = z.enum([
+	"added",
+	"edited",
+	"removed"
+]);
+const contextTreeEdgeKindSchema = z.enum([
+	"parent",
+	"soft_link",
+	"markdown_link"
+]);
+const contextTreeRiskLevelSchema = z.enum([
+	"low",
+	"medium",
+	"high"
+]);
+const contextTreeNodeSchema = z.object({
+	id: z.string(),
+	path: z.string(),
+	sourcePath: z.string().nullable(),
+	title: z.string(),
+	kind: contextTreeNodeKindSchema,
+	owners: z.array(z.string()),
+	parentId: z.string().nullable(),
+	preview: z.string().nullable(),
+	relatedNodeIds: z.array(z.string()),
+	affectedContextArea: z.string(),
+	changeType: contextTreeChangeTypeSchema.nullable(),
+	changedAtCommit: z.string().nullable()
+});
+const contextTreeEdgeSchema = z.object({
+	source: z.string(),
+	target: z.string(),
+	kind: contextTreeEdgeKindSchema
+});
+const contextTreeChangeSchema = z.object({
+	path: z.string(),
+	nodeId: z.string().nullable(),
+	type: contextTreeChangeTypeSchema,
+	commit: z.string().nullable(),
+	changedAt: z.string().nullable(),
+	changedBy: z.string().nullable(),
+	summary: z.string().nullable()
+});
+const contextTreeUpdateSchema = z.object({
+	id: z.string(),
+	nodeId: z.string().nullable(),
+	path: z.string(),
+	title: z.string(),
+	changeType: contextTreeChangeTypeSchema,
+	affectedContextArea: z.string(),
+	reason: z.string(),
+	summary: z.string(),
+	changedBy: z.string().nullable(),
+	owners: z.array(z.string()),
+	relatedNodeIds: z.array(z.string()),
+	sourceCommit: z.string().nullable(),
+	riskLevel: contextTreeRiskLevelSchema
+});
+const contextTreeSummarySchema = z.object({
+	addedCount: z.number().int().nonnegative(),
+	editedCount: z.number().int().nonnegative(),
+	removedCount: z.number().int().nonnegative(),
+	changedNodeCount: z.number().int().nonnegative()
+});
+const contextTreeSnapshotSchema = z.object({
+	repo: z.string().nullable(),
+	branch: z.string().nullable(),
+	headCommit: z.string().nullable(),
+	syncedAt: z.string().nullable(),
+	snapshotStatus: contextTreeSnapshotStatusSchema,
+	contextStatus: contextTreeStatusSchema,
+	summary: contextTreeSummarySchema,
+	updates: z.array(contextTreeUpdateSchema),
+	nodes: z.array(contextTreeNodeSchema),
+	edges: z.array(contextTreeEdgeSchema),
+	changes: z.array(contextTreeChangeSchema)
+});
 const supportedImageMimeSchema = z.enum([
 	"image/png",
 	"image/jpeg",
@@ -1369,4 +1467,4 @@ z.object({
 	capabilities: serverCapabilitiesSchema.optional()
 }).passthrough();
 //#endregion
-export { paginationQuerySchema as $, createMeChatSchema as A, githubStartQuerySchema as B, clientCapabilitiesSchema as C, wsAuthFrameSchema as Ct, createAdapterMappingSchema as D, createAdapterConfigSchema as E, delegateFeishuUserSchema as F, isRedactedEnvValue as G, inboxAckFrameSchema as H, dryRunAgentRuntimeConfigSchema as I, linkTaskChatSchema as J, isReservedAgentName as K, extractMentions as L, createOrgFromMeSchema as M, createTaskSchema as N, createAgentSchema as O, defaultRuntimeConfigPayload as P, notificationQuerySchema as Q, githubCallbackQuerySchema as R, agentTypeSchema as S, updateTaskStatusSchema as St, connectTokenExchangeSchema as T, inboxDeliverFrameSchema as U, imageInlineContentSchema as V, inboxPollQuerySchema as W, loginSchema as X, listMeChatsQuerySchema as Y, messageSourceSchema as Z, adminCreateTaskSchema as _, updateAgentSchema as _t, AGENT_STATUSES as a, selfServiceFeishuBotSchema as at, agentPinnedMessageSchema as b, updateMemberSchema as bt, DEFAULT_RUNTIME_PROVIDER as c, sessionCompletionMessageSchema as ct, TASK_HEALTH_SIGNALS as d, sessionReconcileRequestSchema as dt, rebindAgentSchema as et, TASK_STATUSES as f, sessionStateMessageSchema as ft, addParticipantSchema as g, updateAgentRuntimeConfigSchema as gt, addMeChatParticipantsSchema as h, updateAdapterConfigSchema as ht, AGENT_SOURCES as i, scanMentionTokens as it, createMemberSchema as j, createChatSchema as k, MENTION_REGEX as l, sessionEventMessageSchema as lt, WS_AUTH_FRAME_TIMEOUT_MS as m, taskListQuerySchema as mt, AGENT_NAME_REGEX as n, runtimeStateMessageSchema as nt, AGENT_TYPES as o, sendMessageSchema as ot, TASK_TERMINAL_STATUSES as p, stripCode as pt, joinByInvitationSchema as q, AGENT_SELECTOR_HEADER as r, safeRedirectPath as rt, AGENT_VISIBILITY as s, sendToAgentSchema as st, AGENT_BIND_REJECT_REASONS as t, refreshTokenSchema as tt, TASK_CREATOR_TYPES as u, sessionEventSchema as ut, adminUpdateTaskSchema as v, updateChatSchema as vt, clientRegisterSchema as w, agentRuntimeConfigPayloadSchema as x, updateOrganizationSchema as xt, agentBindRequestSchema as y, updateClientCapabilitiesSchema as yt, githubDevCallbackQuerySchema as z };
+export { notificationQuerySchema as $, createChatSchema as A, githubDevCallbackQuerySchema as B, clientCapabilitiesSchema as C, updateTaskStatusSchema as Ct, createAdapterConfigSchema as D, contextTreeSnapshotSchema as E, defaultRuntimeConfigPayload as F, inboxPollQuerySchema as G, imageInlineContentSchema as H, delegateFeishuUserSchema as I, joinByInvitationSchema as J, isRedactedEnvValue as K, dryRunAgentRuntimeConfigSchema as L, createMemberSchema as M, createOrgFromMeSchema as N, createAdapterMappingSchema as O, createTaskSchema as P, messageSourceSchema as Q, extractMentions as R, agentTypeSchema as S, updateOrganizationSchema as St, connectTokenExchangeSchema as T, inboxAckFrameSchema as U, githubStartQuerySchema as V, inboxDeliverFrameSchema as W, listMeChatsQuerySchema as X, linkTaskChatSchema as Y, loginSchema as Z, adminCreateTaskSchema as _, updateAgentRuntimeConfigSchema as _t, AGENT_STATUSES as a, scanMentionTokens as at, agentPinnedMessageSchema as b, updateClientCapabilitiesSchema as bt, DEFAULT_RUNTIME_PROVIDER as c, sendToAgentSchema as ct, TASK_HEALTH_SIGNALS as d, sessionEventSchema as dt, paginationQuerySchema as et, TASK_STATUSES as f, sessionReconcileRequestSchema as ft, addParticipantSchema as g, updateAdapterConfigSchema as gt, addMeChatParticipantsSchema as h, taskListQuerySchema as ht, AGENT_SOURCES as i, safeRedirectPath as it, createMeChatSchema as j, createAgentSchema as k, MENTION_REGEX as l, sessionCompletionMessageSchema as lt, WS_AUTH_FRAME_TIMEOUT_MS as m, stripCode as mt, AGENT_NAME_REGEX as n, refreshTokenSchema as nt, AGENT_TYPES as o, selfServiceFeishuBotSchema as ot, TASK_TERMINAL_STATUSES as p, sessionStateMessageSchema as pt, isReservedAgentName as q, AGENT_SELECTOR_HEADER as r, runtimeStateMessageSchema as rt, AGENT_VISIBILITY as s, sendMessageSchema as st, AGENT_BIND_REJECT_REASONS as t, rebindAgentSchema as tt, TASK_CREATOR_TYPES as u, sessionEventMessageSchema as ut, adminUpdateTaskSchema as v, updateAgentSchema as vt, clientRegisterSchema as w, wsAuthFrameSchema as wt, agentRuntimeConfigPayloadSchema as x, updateMemberSchema as xt, agentBindRequestSchema as y, updateChatSchema as yt, githubCallbackQuerySchema as z };