@agent-team-foundation/first-tree-hub 0.9.6 → 0.9.8

package/dist/{core-USyOOh7y.mjs → core-DKA6g1lL.mjs}

@@ -2,19 +2,20 @@ import { m as __toESM } from "./esm-CYu4tXXn.mjs";
 import { _ as withSpan, a as endWsConnectionSpan, b as require_pino, c as messageAttrs, d as rootLogger$1, g as startWsConnectionSpan, i as currentTraceId, n as applyLoggerConfig, o as getFastifyOtelPlugin, p as setWsConnectionAttrs, r as createLogger$1, t as adapterAttrs, u as observabilityPlugin, v as withWsMessageSpan, y as FIRST_TREE_HUB_ATTR } from "./observability-DV_fQKqV-CuLWzBxQ.mjs";
 import { s as formatPrettyEntry$1, t as LOG_LEVELS$1, u as parseLogLevel$1 } from "./logger-core-BTmvdflj-DhdipBkV.mjs";
 import { C as serverConfigSchema, S as resolveConfigReadonly, _ 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, v as migrateLegacyHome, w as setConfigValue } from "./bootstrap-DWifXj9b.mjs";
-import { $ as updateAdapterConfigSchema, 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 taskListQuerySchema, R as loginSchema, S as agentRuntimeConfigPayloadSchema$1, T as connectTokenExchangeSchema, U as runtimeStateMessageSchema, V as paginationQuerySchema, W as selfServiceFeishuBotSchema, X as sessionReconcileRequestSchema, Y as sessionEventSchema$1, Z as sessionStateMessageSchema, _ as addParticipantSchema, a as AGENT_SELECTOR_HEADER$1, at as updateSystemConfigSchema, b as agentBindRequestSchema, c as AGENT_TYPES, d as SYSTEM_CONFIG_DEFAULTS, et as updateAgentRuntimeConfigSchema, 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 updateOrganizationSchema, j as createOrganizationSchema, k as createChatSchema, l as AGENT_VISIBILITY, m as TASK_STATUSES, nt as updateChatSchema, o as AGENT_SOURCES, ot as updateTaskStatusSchema, p as TASK_HEALTH_SIGNALS, q as sessionCompletionMessageSchema, rt as updateMemberSchema, s as AGENT_STATUSES, st as wsAuthFrameSchema, tt as updateAgentSchema, 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-GlaczcVf.mjs";
+import { $ as sessionStateMessageSchema, A as createMemberSchema, B as loginSchema, C as agentTypeSchema$1, D as createAdapterMappingSchema, E as createAdapterConfigSchema, F as extractMentions, G as runtimeStateMessageSchema, H as notificationQuerySchema, I as imageInlineContentSchema, J as sendToAgentSchema, K as selfServiceFeishuBotSchema, L as inboxPollQuerySchema, M as createTaskSchema, N as delegateFeishuUserSchema, O as createAgentSchema, P as dryRunAgentRuntimeConfigSchema, Q as sessionReconcileRequestSchema, R as isRedactedEnvValue, S as agentRuntimeConfigPayloadSchema$1, T as connectTokenExchangeSchema, U as paginationQuerySchema, V as messageSourceSchema$1, W as refreshTokenSchema, X as sessionEventMessageSchema, Y as sessionCompletionMessageSchema, Z as sessionEventSchema$1, _ as addParticipantSchema, a as AGENT_SELECTOR_HEADER$1, at as updateMemberSchema, b as agentBindRequestSchema, c as AGENT_TYPES, ct as updateTaskStatusSchema, d as SYSTEM_CONFIG_DEFAULTS, et as taskListQuerySchema, 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 updateChatSchema, j as createOrganizationSchema, k as createChatSchema, l as AGENT_VISIBILITY, lt as wsAuthFrameSchema, m as TASK_STATUSES, nt as updateAgentRuntimeConfigSchema, o as AGENT_SOURCES, ot as updateOrganizationSchema, p as TASK_HEALTH_SIGNALS, q as sendMessageSchema, rt as updateAgentSchema, s as AGENT_STATUSES, st as updateSystemConfigSchema, tt as updateAdapterConfigSchema, u as DEFAULT_AGENT_RUNTIME_CONFIG_PAYLOAD, v as adminCreateTaskSchema, w as clientRegisterSchema, x as agentPinnedMessageSchema$1, y as adminUpdateTaskSchema, z as linkTaskChatSchema } from "./feishu-CRNUI05I.mjs";
 import { createRequire } from "node:module";
 import { ZodError, z } from "zod";
-import { dirname, isAbsolute, join, resolve } from "node:path";
+import { delimiter, dirname, isAbsolute, join, resolve } from "node:path";
 import { Writable } from "node:stream";
-import { homedir, hostname, platform, userInfo } from "node:os";
+import { homedir, hostname, platform, tmpdir, userInfo } from "node:os";
 import { EventEmitter } from "node:events";
 import { closeSync, copyFileSync, createReadStream, existsSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, unwatchFile, watch, watchFile, writeFileSync, writeSync } from "node:fs";
 import { createCipheriv, createDecipheriv, createHash, createHmac, randomBytes, randomUUID, timingSafeEqual } from "node:crypto";
 import WebSocket from "ws";
+import { mkdir, writeFile } from "node:fs/promises";
+import { stringify } from "yaml";
 import { query } from "@anthropic-ai/claude-agent-sdk";
 import { execFileSync, execSync, spawn, spawnSync } from "node:child_process";
-import { stringify } from "yaml";
 import * as semver from "semver";
 import bcrypt from "bcrypt";
 import { and, asc, count, desc, eq, gt, inArray, isNotNull, isNull, lt, ne, or, sql } from "drizzle-orm";
@@ -659,6 +660,11 @@ const chatParticipantSchema = z.object({
 	mode: z.string(),
 	joinedAt: z.string()
 });
+chatParticipantSchema.extend({
+	name: z.string().nullable(),
+	displayName: z.string().nullable(),
+	type: z.string()
+});
 z.object({
 	id: z.string(),
 	organizationId: z.string(),
@@ -698,6 +704,54 @@ z.object({
 	limit: z.coerce.number().int().min(1).max(100).default(20),
 	cursor: z.string().optional()
 });
+/**
+* MIME types the web + client image paths recognise. Kept in sync with
+* Claude's vision API (see packages/client/src/handlers/claude-code.ts).
+*/
+const SUPPORTED_IMAGE_MIMES$1 = [
+	"image/png",
+	"image/jpeg",
+	"image/gif",
+	"image/webp"
+];
+const supportedImageMimeSchema = z.enum(SUPPORTED_IMAGE_MIMES$1);
+const IMAGE_MIME_TO_EXT = {
+	"image/png": "png",
+	"image/jpeg": "jpg",
+	"image/gif": "gif",
+	"image/webp": "webp"
+};
+z.object({
+	data: z.string().min(1),
+	mimeType: supportedImageMimeSchema,
+	filename: z.string().min(1),
+	size: z.number().int().nonnegative().optional(),
+	imageId: z.string().uuid().optional()
+});
+z.object({
+	imageId: z.string().uuid(),
+	mimeType: supportedImageMimeSchema,
+	filename: z.string().min(1),
+	size: z.number().int().nonnegative().optional()
+});
+/**
+* Server → client WS frame carrying the full image bytes for an image
+* message. Pushed before the corresponding `new_message` notification so
+* the client has the file on disk by the time it polls the message.
+*
+* Best-effort: if the target client WS lives on a different server
+* instance (or is offline), the frame is lost and the reference message
+* will surface a "not available on this device" placeholder downstream.
+*/
+const imagePayloadFrameSchema = z.object({
+	type: z.literal("image_payload"),
+	imageId: z.string().uuid(),
+	chatId: z.string(),
+	base64: z.string().min(1),
+	mimeType: supportedImageMimeSchema,
+	filename: z.string().min(1),
+	size: z.number().int().nonnegative().optional()
+});
 const messageSourceSchema = z.enum([
 	"hub_ui",
 	"cli",
@@ -730,17 +784,7 @@ z.object({
 	replyToChat: z.string().optional(),
 	source: messageSourceSchema.optional()
 });
-/**
-* Wire format for messages routed FROM the Hub TO a client runtime.
-*
-* Adds `configVersion` so the client can compare against its locally cached
-* agent runtime config and refresh before delivering the message to the SDK.
-*
-* Step 3: this is the single shape used by `buildClientMessagePayload` —
-* never serialise a raw `messageSchema` row to a client; always go through
-* the dispatcher.
-*/
-const clientMessageSchema = z.object({
+const messageSchema = z.object({
 	id: z.string(),
 	chatId: z.string(),
 	senderId: z.string(),
@@ -752,7 +796,46 @@ const clientMessageSchema = z.object({
 	inReplyTo: z.string().nullable(),
 	source: messageSourceSchema.nullable(),
 	createdAt: z.string()
-}).extend({ configVersion: z.number().int().positive() });
+});
+/**
+* Snapshot of the `in_reply_to` target that the server materialises at
+* dispatch time so the receiving runtime can decide whether this is an
+* echo it should suppress (see proposal hub-agent-messaging-reply-and-mentions).
+*
+* `chatId` is the original message's `chat_id`; `replyToChat` is the chat
+* its sender expected replies to flow back to (often a different chat).
+* `null` when the message is not a reply, or the original could not be
+* resolved (e.g. deleted).
+*/
+const inReplyToSnapshotSchema = z.object({
+	senderId: z.string(),
+	chatId: z.string(),
+	replyToChat: z.string().nullable()
+}).nullable();
+/** Per-chat participation mode exposed to the recipient runtime. */
+const participantModeSchema = z.enum(["full", "mention_only"]);
+/**
+* Wire format for messages routed FROM the Hub TO a client runtime.
+*
+* Adds `configVersion` so the client can compare against its locally cached
+* agent runtime config and refresh before delivering the message to the SDK.
+*
+* Step 3: this is the single shape used by `buildClientMessagePayload` —
+* never serialise a raw `messageSchema` row to a client; always go through
+* the dispatcher.
+*
+* `recipientMode` is the receiving agent's own mode in the entry's chat —
+* `mention_only` participants must only start a session when they appear in
+* `metadata.mentions` (see session-manager.ts).
+*
+* `inReplyToSnapshot` is populated when `inReplyTo` resolves to an existing
+* message; runtime uses it to suppress self-reply echo on direct chats.
+*/
+const clientMessageSchema = messageSchema.extend({
+	configVersion: z.number().int().positive(),
+	recipientMode: participantModeSchema.default("full"),
+	inReplyToSnapshot: inReplyToSnapshotSchema.default(null)
+});
 z.enum([
 	"pending",
 	"delivered",
@@ -1112,6 +1195,195 @@ const serverWelcomeFrameSchema = z.object({
 	serverCommandVersion: z.string().min(1),
 	serverTimeMs: z.number().int().nonnegative()
 }).passthrough();
+/** Declare a config field with a Zod schema and optional metadata. */
+function field(schema, options) {
+	return {
+		_tag: "field",
+		_type: void 0,
+		schema,
+		options: options ?? {}
+	};
+}
+/** Mark a config group as optional — present only when at least one field has an explicit value. */
+function optional(shape) {
+	return {
+		_tag: "optional",
+		shape
+	};
+}
+/** Define a config shape. Identity function used for type inference. */
+function defineConfig(shape) {
+	return shape;
+}
+defineConfig({
+	agentId: field(z.string().min(1)),
+	runtime: field(z.string().default("claude-code")),
+	concurrency: field(z.number().int().positive().default(5)),
+	session: {
+		idle_timeout: field(z.number().int().positive().default(300)),
+		max_sessions: field(z.number().int().positive().default(10))
+	}
+});
+/**
+* Phase-dependent defaults that flip with release milestones. Kept as a plain
+* module-level constant so reviews of the beta→GA transition are a one-line
+* diff, and so tests can mock this module to exercise both branches.
+*/
+const UPDATE_POLICIES = [
+	"auto",
+	"prompt",
+	"off"
+];
+/**
+* Default value of `update.policy` on the Client config. During the beta this
+* is `"auto"` — operators rarely know to `npm i -g` weekly and we chase the
+* latest published Command by default. The GA PR flips it to `"prompt"` and
+* bumps Command to `1.0.0`.
+*/
+const UPDATE_POLICY_DEFAULT = "auto";
+const updatePolicySchema = z.enum(UPDATE_POLICIES);
+defineConfig({
+	server: { url: field(z.string(), {
+		env: "FIRST_TREE_HUB_SERVER_URL",
+		prompt: {
+			message: "Server URL:",
+			default: "http://localhost:8000"
+		}
+	}) },
+	client: { id: field(z.string().regex(/^client_[a-f0-9]{8}$/), {
+		auto: "client-id",
+		env: "FIRST_TREE_HUB_CLIENT_ID"
+	}) },
+	update: {
+		policy: field(updatePolicySchema.default(UPDATE_POLICY_DEFAULT), { env: "FIRST_TREE_HUB_UPDATE_POLICY" }),
+		restart_quiet_seconds: field(z.number().int().min(1).max(3600).default(30), { env: "FIRST_TREE_HUB_UPDATE_RESTART_QUIET_SECONDS" }),
+		restart_check_interval_seconds: field(z.number().int().min(5).max(300).default(10), { env: "FIRST_TREE_HUB_UPDATE_RESTART_CHECK_INTERVAL_SECONDS" }),
+		prompt_timeout_seconds: field(z.number().int().min(10).max(600).default(60), { env: "FIRST_TREE_HUB_UPDATE_PROMPT_TIMEOUT_SECONDS" })
+	},
+	logLevel: field(logLevelSchema.default("info"), { env: "FIRST_TREE_HUB_LOG_LEVEL" })
+});
+const DEFAULT_HOME_DIR = process.env.FIRST_TREE_HUB_HOME ?? join(homedir(), ".first-tree", "hub");
+join(DEFAULT_HOME_DIR, "config");
+const DEFAULT_DATA_DIR = join(DEFAULT_HOME_DIR, "data");
+join(homedir(), ".first-tree-hub");
+defineConfig({
+	database: {
+		url: field(z.string(), {
+			env: "FIRST_TREE_HUB_DATABASE_URL",
+			auto: "docker-pg",
+			prompt: {
+				message: "PostgreSQL:",
+				type: "select",
+				choices: [{
+					name: "Auto-provision via Docker",
+					value: "__auto__"
+				}, {
+					name: "Provide connection URL",
+					value: "__input__"
+				}]
+			}
+		}),
+		provider: field(z.enum(["docker", "external"]).default("docker"))
+	},
+	server: {
+		port: field(z.number().default(8e3), { env: "FIRST_TREE_HUB_PORT" }),
+		host: field(z.string().default("127.0.0.1"), { env: "FIRST_TREE_HUB_HOST" })
+	},
+	secrets: {
+		jwtSecret: field(z.string(), {
+			env: "FIRST_TREE_HUB_JWT_SECRET",
+			auto: "random:base64url:32",
+			secret: true
+		}),
+		encryptionKey: field(z.string(), {
+			env: "FIRST_TREE_HUB_ENCRYPTION_KEY",
+			auto: "random:hex:32",
+			secret: true
+		})
+	},
+	contextTree: optional({
+		repo: field(z.string(), {
+			env: "FIRST_TREE_HUB_CONTEXT_TREE_REPO",
+			prompt: { message: "Context Tree repo URL (e.g. https://github.com/org/first-tree):" }
+		}),
+		branch: field(z.string().default("main"))
+	}),
+	github: {
+		webhookSecret: field(z.string().optional(), {
+			env: "FIRST_TREE_HUB_GITHUB_WEBHOOK_SECRET",
+			secret: true
+		}),
+		allowedOrg: field(z.string().optional(), { env: "FIRST_TREE_HUB_GITHUB_ALLOWED_ORG" })
+	},
+	cors: optional({ origin: field(z.string(), { env: "FIRST_TREE_HUB_CORS_ORIGIN" }) }),
+	rateLimit: optional({
+		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" })
+	}),
+	kael: optional({
+		endpoint: field(z.string(), { env: "KAEL_ENDPOINT" }),
+		apiKey: field(z.string(), {
+			env: "KAEL_API_KEY",
+			secret: true
+		}),
+		hubPublicUrl: field(z.string(), { env: "FIRST_TREE_HUB_PUBLIC_URL" })
+	}),
+	observability: {
+		logging: {
+			level: field(logLevelSchema.default("info"), { env: "FIRST_TREE_HUB_LOG_LEVEL" }),
+			format: field(logFormatSchema.default(process.env.NODE_ENV === "production" ? "json" : "pretty")),
+			bridgeToSpanLevel: field(z.enum([
+				"error",
+				"warn",
+				"off"
+			]).default("error"))
+		},
+		tracing: optional({
+			endpoint: field(z.string(), { env: "FIRST_TREE_HUB_OTEL_ENDPOINT" }),
+			headers: field(z.string().default(""), {
+				env: "FIRST_TREE_HUB_OTEL_HEADERS",
+				secret: true
+			}),
+			exporter: field(z.enum(["otlp-http", "otlp-grpc"]).default("otlp-http")),
+			serviceName: field(z.string().default("first-tree-hub")),
+			environment: field(z.string().default("development"), { env: "FIRST_TREE_HUB_OTEL_ENVIRONMENT" }),
+			sampleRate: field(z.number().min(0).max(1).default(1))
+		})
+	}
+});
+/** UUIDs are the only shape we generate for imageId, but accept the same
+* loose character set as chatId sanitisers elsewhere so a malformed field
+* can never break out of the images dir. */
+function sanitize(segment) {
+	return /^[a-zA-Z0-9-]+$/.test(segment) ? segment : "unknown";
+}
+function imageDir(chatId) {
+	return join(DEFAULT_DATA_DIR, "chats", sanitize(chatId), "images");
+}
+function imagePath(chatId, imageId, mimeType) {
+	const ext = IMAGE_MIME_TO_EXT[mimeType];
+	return join(imageDir(chatId), `${sanitize(imageId)}.${ext}`);
+}
+/**
+* Locate a previously-written image file on disk. Returns null when the
+* file is missing — caller should surface the "image not available on
+* this device" placeholder in that case.
+*/
+function findImagePath(chatId, imageId, mimeType) {
+	const p = imagePath(chatId, imageId, mimeType);
+	return existsSync(p) ? p : null;
+}
+/**
+* Persist image bytes to `<dataDir>/chats/<chatId>/images/<imageId>.<ext>`.
+* Idempotent — rewriting the same imageId is a no-op overwrite.
+*/
+async function writeImage(params) {
+	await mkdir(imageDir(params.chatId), { recursive: true });
+	const path = imagePath(params.chatId, params.imageId, params.mimeType);
+	await writeFile(path, Buffer.from(params.base64, "base64"));
+	return path;
+}
 const FETCH_TIMEOUT_MS = 15e3;
 var FirstTreeHubSDK = class {
 	_baseUrl;
@@ -1185,6 +1457,13 @@ var FirstTreeHubSDK = class {
 	async listMessages(chatId, options) {
 		return this.requestJson(`/api/v1/agent/chats/${chatId}/messages${this.queryString(options)}`);
 	}
+	/**
+	* List participants of a chat with agent names/displayNames — used by the
+	* runtime to resolve `@<name>` mentions against the authoritative set.
+	*/
+	async listChatParticipants(chatId) {
+		return this.requestJson(`/api/v1/agent/chats/${chatId}/participants`);
+	}
 	queryString(options) {
 		const params = new URLSearchParams();
 		if (options?.limit !== void 0) params.set("limit", String(options.limit));
@@ -1293,6 +1572,14 @@ var ClientConnection = class extends EventEmitter {
 	/** Agents scheduled to rebind automatically on every reconnect. */
 	desiredBindings = /* @__PURE__ */ new Map();
 	pendingBinds = /* @__PURE__ */ new Map();
+	/**
+	* In-flight image writes from recent `image_payload` frames. The server
+	* pushes `image_payload` immediately before firing the `new_message`
+	* notification, but WS message handlers run through EventEmitter (sync
+	* dispatch, no await), so the disk write can still race the HTTP poll
+	* that follows. Defer `new_message` emission until these settle.
+	*/
+	pendingImageWrites = /* @__PURE__ */ new Set();
 	constructor(config) {
 		super();
 		this.clientId = config.clientId ?? process.env.FIRST_TREE_HUB_CLIENT_ID ?? `client_${randomUUID().slice(0, 8)}`;
@@ -1604,9 +1891,36 @@ var ClientConnection = class extends EventEmitter {
 			});
 			return;
 		}
+		if (type === "image_payload") {
+			const parsed = imagePayloadFrameSchema.safeParse(msg);
+			if (!parsed.success) {
+				this.wsLogger.warn({ err: parsed.error.flatten() }, "malformed image_payload frame — dropping");
+				return;
+			}
+			const { imageId, chatId, mimeType, base64 } = parsed.data;
+			const write = writeImage({
+				chatId,
+				imageId,
+				mimeType,
+				base64
+			}).then(() => {}).catch((err) => {
+				this.wsLogger.warn({
+					err,
+					imageId,
+					chatId
+				}, "image_payload write failed");
+			});
+			this.pendingImageWrites.add(write);
+			write.finally(() => this.pendingImageWrites.delete(write));
+			return;
+		}
 		if (type === "new_message") {
 			const inboxId = msg.inboxId;
-			if (inboxId) this.emit("agent:message", inboxId, msg);
+			if (!inboxId) return;
+			if (this.pendingImageWrites.size > 0) Promise.all([...this.pendingImageWrites]).finally(() => {
+				this.emit("agent:message", inboxId, msg);
+			});
+			else this.emit("agent:message", inboxId, msg);
 			return;
 		}
 		if (type === "error") {
@@ -1652,228 +1966,71 @@ var ClientConnection = class extends EventEmitter {
 			if (this.ws?.readyState === WebSocket.OPEN) this.ws.send(JSON.stringify({ type: "heartbeat" }));
 		}, HEARTBEAT_INTERVAL_MS);
 	}
-	stopHeartbeat() {
-		if (this.heartbeatTimer) {
-			clearInterval(this.heartbeatTimer);
-			this.heartbeatTimer = null;
-		}
-	}
-	rejectAllPendingBinds(reason) {
-		for (const [, pending] of this.pendingBinds) pending.reject(new Error(reason));
-		this.pendingBinds.clear();
-	}
-	clearTimers() {
-		this.stopHeartbeat();
-		if (this.wsConnectTimer) {
-			clearTimeout(this.wsConnectTimer);
-			this.wsConnectTimer = null;
-		}
-		if (this.reconnectTimer) {
-			clearTimeout(this.reconnectTimer);
-			this.reconnectTimer = null;
-		}
-		this.clearAuthRefreshTimer();
-	}
-	clearAuthRefreshTimer() {
-		if (this.authRefreshTimer) {
-			clearTimeout(this.authRefreshTimer);
-			this.authRefreshTimer = null;
-		}
-	}
-	/**
-	* Proactive JWT refresh (C5). Schedule a silent reconnect ~60s before the
-	* access token expires so `getAccessToken()` is asked for a fresh JWT
-	* before the server's scheduleAuthExpiry timer fires. Short-lived tokens
-	* (exp <= lead window) skip the proactive reconnect entirely — we let the
-	* server push `auth:expired` and handle that path.
-	*/
-	scheduleProactiveAuthRefresh(token) {
-		this.clearAuthRefreshTimer();
-		const exp = decodeJwtExp(token);
-		if (!exp) return;
-		const delay = exp * 1e3 - Date.now() - AUTH_REFRESH_LEAD_MS;
-		if (delay <= 0) return;
-		this.authLogger.debug({ delayMs: delay }, "scheduled proactive auth refresh");
-		this.authRefreshTimer = setTimeout(() => {
-			this.authRefreshTimer = null;
-			if (this.closing) return;
-			this.authLogger.info("triggering proactive auth refresh");
-			this.ws?.close(1e3, "proactive auth refresh");
-		}, delay);
-	}
-};
-/** Built-in handler registry. Populated by handler modules. */
-const HANDLER_REGISTRY = /* @__PURE__ */ new Map();
-/** Register a built-in handler type. */
-function registerHandler(type, factory) {
-	HANDLER_REGISTRY.set(type, factory);
-}
-/** Resolve a handler factory by type name. */
-function getHandlerFactory(type) {
-	const factory = HANDLER_REGISTRY.get(type);
-	if (!factory) {
-		const available = [...HANDLER_REGISTRY.keys()].join(", ") || "(none)";
-		throw new Error(`Unknown handler type "${type}". Available: ${available}`);
-	}
-	return factory;
-}
-/** Declare a config field with a Zod schema and optional metadata. */
-function field(schema, options) {
-	return {
-		_tag: "field",
-		_type: void 0,
-		schema,
-		options: options ?? {}
-	};
-}
-/** Mark a config group as optional — present only when at least one field has an explicit value. */
-function optional(shape) {
-	return {
-		_tag: "optional",
-		shape
-	};
-}
-/** Define a config shape. Identity function used for type inference. */
-function defineConfig(shape) {
-	return shape;
-}
-defineConfig({
-	agentId: field(z.string().min(1)),
-	runtime: field(z.string().default("claude-code")),
-	concurrency: field(z.number().int().positive().default(5)),
-	session: {
-		idle_timeout: field(z.number().int().positive().default(300)),
-		max_sessions: field(z.number().int().positive().default(10))
-	}
-});
-/**
-* Phase-dependent defaults that flip with release milestones. Kept as a plain
-* module-level constant so reviews of the beta→GA transition are a one-line
-* diff, and so tests can mock this module to exercise both branches.
-*/
-const UPDATE_POLICIES = [
-	"auto",
-	"prompt",
-	"off"
-];
-/**
-* Default value of `update.policy` on the Client config. During the beta this
-* is `"auto"` — operators rarely know to `npm i -g` weekly and we chase the
-* latest published Command by default. The GA PR flips it to `"prompt"` and
-* bumps Command to `1.0.0`.
-*/
-const UPDATE_POLICY_DEFAULT = "auto";
-const updatePolicySchema = z.enum(UPDATE_POLICIES);
-defineConfig({
-	server: { url: field(z.string(), {
-		env: "FIRST_TREE_HUB_SERVER_URL",
-		prompt: {
-			message: "Server URL:",
-			default: "http://localhost:8000"
-		}
-	}) },
-	client: { id: field(z.string().regex(/^client_[a-f0-9]{8}$/), {
-		auto: "client-id",
-		env: "FIRST_TREE_HUB_CLIENT_ID"
-	}) },
-	update: {
-		policy: field(updatePolicySchema.default(UPDATE_POLICY_DEFAULT), { env: "FIRST_TREE_HUB_UPDATE_POLICY" }),
-		restart_quiet_seconds: field(z.number().int().min(1).max(3600).default(30), { env: "FIRST_TREE_HUB_UPDATE_RESTART_QUIET_SECONDS" }),
-		restart_check_interval_seconds: field(z.number().int().min(5).max(300).default(10), { env: "FIRST_TREE_HUB_UPDATE_RESTART_CHECK_INTERVAL_SECONDS" }),
-		prompt_timeout_seconds: field(z.number().int().min(10).max(600).default(60), { env: "FIRST_TREE_HUB_UPDATE_PROMPT_TIMEOUT_SECONDS" })
-	},
-	logLevel: field(logLevelSchema.default("info"), { env: "FIRST_TREE_HUB_LOG_LEVEL" })
-});
-const DEFAULT_HOME_DIR = process.env.FIRST_TREE_HUB_HOME ?? join(homedir(), ".first-tree", "hub");
-join(DEFAULT_HOME_DIR, "config");
-const DEFAULT_DATA_DIR = join(DEFAULT_HOME_DIR, "data");
-join(homedir(), ".first-tree-hub");
-defineConfig({
-	database: {
-		url: field(z.string(), {
-			env: "FIRST_TREE_HUB_DATABASE_URL",
-			auto: "docker-pg",
-			prompt: {
-				message: "PostgreSQL:",
-				type: "select",
-				choices: [{
-					name: "Auto-provision via Docker",
-					value: "__auto__"
-				}, {
-					name: "Provide connection URL",
-					value: "__input__"
-				}]
-			}
-		}),
-		provider: field(z.enum(["docker", "external"]).default("docker"))
-	},
-	server: {
-		port: field(z.number().default(8e3), { env: "FIRST_TREE_HUB_PORT" }),
-		host: field(z.string().default("127.0.0.1"), { env: "FIRST_TREE_HUB_HOST" })
-	},
-	secrets: {
-		jwtSecret: field(z.string(), {
-			env: "FIRST_TREE_HUB_JWT_SECRET",
-			auto: "random:base64url:32",
-			secret: true
-		}),
-		encryptionKey: field(z.string(), {
-			env: "FIRST_TREE_HUB_ENCRYPTION_KEY",
-			auto: "random:hex:32",
-			secret: true
-		})
-	},
-	contextTree: optional({
-		repo: field(z.string(), {
-			env: "FIRST_TREE_HUB_CONTEXT_TREE_REPO",
-			prompt: { message: "Context Tree repo URL (e.g. https://github.com/org/first-tree):" }
-		}),
-		branch: field(z.string().default("main"))
-	}),
-	github: {
-		webhookSecret: field(z.string().optional(), {
-			env: "FIRST_TREE_HUB_GITHUB_WEBHOOK_SECRET",
-			secret: true
-		}),
-		allowedOrg: field(z.string().optional(), { env: "FIRST_TREE_HUB_GITHUB_ALLOWED_ORG" })
-	},
-	cors: optional({ origin: field(z.string(), { env: "FIRST_TREE_HUB_CORS_ORIGIN" }) }),
-	rateLimit: optional({
-		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" })
-	}),
-	kael: optional({
-		endpoint: field(z.string(), { env: "KAEL_ENDPOINT" }),
-		apiKey: field(z.string(), {
-			env: "KAEL_API_KEY",
-			secret: true
-		}),
-		hubPublicUrl: field(z.string(), { env: "FIRST_TREE_HUB_PUBLIC_URL" })
-	}),
-	observability: {
-		logging: {
-			level: field(logLevelSchema.default("info"), { env: "FIRST_TREE_HUB_LOG_LEVEL" }),
-			format: field(logFormatSchema.default(process.env.NODE_ENV === "production" ? "json" : "pretty")),
-			bridgeToSpanLevel: field(z.enum([
-				"error",
-				"warn",
-				"off"
-			]).default("error"))
-		},
-		tracing: optional({
-			endpoint: field(z.string(), { env: "FIRST_TREE_HUB_OTEL_ENDPOINT" }),
-			headers: field(z.string().default(""), {
-				env: "FIRST_TREE_HUB_OTEL_HEADERS",
-				secret: true
-			}),
-			exporter: field(z.enum(["otlp-http", "otlp-grpc"]).default("otlp-http")),
-			serviceName: field(z.string().default("first-tree-hub")),
-			environment: field(z.string().default("development"), { env: "FIRST_TREE_HUB_OTEL_ENVIRONMENT" }),
-			sampleRate: field(z.number().min(0).max(1).default(1))
-		})
-	}
-});
+	stopHeartbeat() {
+		if (this.heartbeatTimer) {
+			clearInterval(this.heartbeatTimer);
+			this.heartbeatTimer = null;
+		}
+	}
+	rejectAllPendingBinds(reason) {
+		for (const [, pending] of this.pendingBinds) pending.reject(new Error(reason));
+		this.pendingBinds.clear();
+	}
+	clearTimers() {
+		this.stopHeartbeat();
+		if (this.wsConnectTimer) {
+			clearTimeout(this.wsConnectTimer);
+			this.wsConnectTimer = null;
+		}
+		if (this.reconnectTimer) {
+			clearTimeout(this.reconnectTimer);
+			this.reconnectTimer = null;
+		}
+		this.clearAuthRefreshTimer();
+	}
+	clearAuthRefreshTimer() {
+		if (this.authRefreshTimer) {
+			clearTimeout(this.authRefreshTimer);
+			this.authRefreshTimer = null;
+		}
+	}
+	/**
+	* Proactive JWT refresh (C5). Schedule a silent reconnect ~60s before the
+	* access token expires so `getAccessToken()` is asked for a fresh JWT
+	* before the server's scheduleAuthExpiry timer fires. Short-lived tokens
+	* (exp <= lead window) skip the proactive reconnect entirely — we let the
+	* server push `auth:expired` and handle that path.
+	*/
+	scheduleProactiveAuthRefresh(token) {
+		this.clearAuthRefreshTimer();
+		const exp = decodeJwtExp(token);
+		if (!exp) return;
+		const delay = exp * 1e3 - Date.now() - AUTH_REFRESH_LEAD_MS;
+		if (delay <= 0) return;
+		this.authLogger.debug({ delayMs: delay }, "scheduled proactive auth refresh");
+		this.authRefreshTimer = setTimeout(() => {
+			this.authRefreshTimer = null;
+			if (this.closing) return;
+			this.authLogger.info("triggering proactive auth refresh");
+			this.ws?.close(1e3, "proactive auth refresh");
+		}, delay);
+	}
+};
+/** Built-in handler registry. Populated by handler modules. */
+const HANDLER_REGISTRY = /* @__PURE__ */ new Map();
+/** Register a built-in handler type. */
+function registerHandler(type, factory) {
+	HANDLER_REGISTRY.set(type, factory);
+}
+/** Resolve a handler factory by type name. */
+function getHandlerFactory(type) {
+	const factory = HANDLER_REGISTRY.get(type);
+	if (!factory) {
+		const available = [...HANDLER_REGISTRY.keys()].join(", ") || "(none)";
+		throw new Error(`Unknown handler type "${type}". Available: ${available}`);
+	}
+	return factory;
+}
 join(DEFAULT_DATA_DIR, "context-tree");
 /**
 * Bootstrap a workspace with .agent/ directory files.
@@ -2012,22 +2169,28 @@ Use the \`first-tree-hub agent send\` CLI — it reads the env vars above and
 attaches the \`Authorization\` + \`X-Agent-Id\` headers automatically:
 
 \`\`\`bash
-# Send to another agent (target = agent ID)
-first-tree-hub agent send <agentId> "your message"
+# Send to another agent — target is the agent NAME, NOT a uuid.
+# Names are stable (set on creation, immutable, unique in the org).
+# Run \`first-tree-hub agent list\` to see available names.
+first-tree-hub agent send <agentName> "your message"
 
-# Send to a chat (target = chat ID)
+# Send to a chat (target is a chat UUID; use this when replying into a
+# specific chat, e.g. a group where you were mentioned)
 first-tree-hub agent send --chat <chatId> "your message"
 
 # Send markdown (default format is text)
-first-tree-hub agent send <agentId> -f markdown "**bold** message"
+first-tree-hub agent send <agentName> -f markdown "**bold** message"
 
 # Reply to a specific message
-first-tree-hub agent send <agentId> --reply-to <messageId> "reply content"
+first-tree-hub agent send <agentName> --reply-to <messageId> "reply content"
 
 # Pipe long content via stdin (recommended for special characters)
-echo "long message body" | first-tree-hub agent send <agentId>
+echo "long message body" | first-tree-hub agent send <agentName>
 \`\`\`
 
+> Agent uuids appear in \`agent chats\`, chat history, and participant lists,
+> but they are NOT accepted by \`agent send\` — always use the name.
+
 For content with quotes, \`$\`, backticks, or newlines, prefer stdin to avoid shell escaping issues.
 `;
 }
@@ -2570,20 +2733,99 @@ function cleanWorkspaces(workspaceRoot, activeChatIds, ttlMs = DEFAULT_WORKSPACE
 	}
 	return removed;
 }
+/**
+* Resolve which Claude Code binary the SDK should spawn.
+*
+* Priority:
+*   1. `CLAUDE_CODE_EXECUTABLE` env var — explicit operator override
+*   2. `claude` on PATH — reuses whatever the user has already installed
+*   3. undefined — fall back to the SDK's bundled native binary
+*
+* The SDK's bundled binary ships as a per-platform **optional** npm dep
+* (`@anthropic-ai/claude-agent-sdk-<platform>-<arch>`). Any of: a proxy that
+* skips optional deps, an `.npmrc` with `omit=optional`, libc detection
+* failure, or a transient install error leaves that dep missing and the SDK
+* throws "Native CLI binary for <platform>-<arch> not found". Returning a PATH
+* hit here bypasses the missing bundle entirely.
+*/
+function resolveClaudeCodeExecutable(opts = {}) {
+	const env = opts.env ?? process.env;
+	const override = env.CLAUDE_CODE_EXECUTABLE;
+	if (override && override.length > 0 && existsSync(override)) return {
+		path: override,
+		source: "env"
+	};
+	const found = findOnPath("claude", env);
+	if (found) return {
+		path: found,
+		source: "path"
+	};
+	return {
+		path: void 0,
+		source: "default"
+	};
+}
+function findOnPath(name, env) {
+	const rawPath = env.PATH ?? env.Path ?? env.path ?? "";
+	if (!rawPath) return void 0;
+	const exts = process.platform === "win32" ? splitPathExt(env.PATHEXT) : [""];
+	for (const dir of rawPath.split(delimiter)) {
+		if (!dir) continue;
+		for (const ext of exts) {
+			const full = join(dir, name + ext);
+			if (existsSync(full)) return full;
+		}
+	}
+}
+function splitPathExt(pathext) {
+	if (!pathext) return [
+		".EXE",
+		".CMD",
+		".BAT",
+		".COM",
+		""
+	];
+	const parts = pathext.split(";").filter(Boolean);
+	return parts.length > 0 ? [...parts, ""] : [""];
+}
 const MAX_RETRIES = 2;
 const TOOL_RESULT_PREVIEW_LIMIT = 400;
 const ASSISTANT_TEXT_EVENT_LIMIT = 8e3;
-const SUPPORTED_IMAGE_MIMES = new Set([
-	"image/png",
-	"image/jpeg",
-	"image/gif",
-	"image/webp"
-]);
-function isImageFileContent(content) {
+const SUPPORTED_IMAGE_MIMES = new Set(SUPPORTED_IMAGE_MIMES$1);
+const MIME_TO_EXT = {
+	"image/png": "png",
+	"image/jpeg": "jpg",
+	"image/gif": "gif",
+	"image/webp": "webp"
+};
+function isImageRefContent(content) {
+	if (!content || typeof content !== "object") return false;
+	const c = content;
+	return typeof c.imageId === "string" && typeof c.mimeType === "string" && typeof c.filename === "string" && SUPPORTED_IMAGE_MIMES.has(c.mimeType);
+}
+function isLegacyImageFileContent(content) {
 	if (!content || typeof content !== "object") return false;
 	const c = content;
 	return typeof c.data === "string" && typeof c.mimeType === "string" && typeof c.filename === "string" && SUPPORTED_IMAGE_MIMES.has(c.mimeType);
 }
+/** chat_id values are DB-generated UUIDs; reject anything else so we never
+* traverse out of the images dir if the field is ever tampered with. */
+function sanitizeChatId(chatId) {
+	return /^[a-zA-Z0-9-]+$/.test(chatId) ? chatId : "unknown";
+}
+/**
+* Write a legacy inline-base64 image to a temp file so Claude Code's Read
+* tool can pick it up. Only the legacy path — new messages go through the
+* image_payload WS push which pre-writes to the data dir before delivery.
+*/
+async function writeLegacyImageToTempFile(content, chatId) {
+	const dir = join(tmpdir(), "first-tree-hub", "images", sanitizeChatId(chatId));
+	await mkdir(dir, { recursive: true });
+	const ext = MIME_TO_EXT[content.mimeType];
+	const path = join(dir, `${Date.now()}-${randomUUID().slice(0, 8)}.${ext}`);
+	await writeFile(path, Buffer.from(content.data, "base64"));
+	return path;
+}
 function extractContentBlocks(message) {
 	if (!message || typeof message !== "object") return [];
 	const inner = message.message;
@@ -2741,6 +2983,7 @@ const createClaudeCodeHandler = (config) => {
 	const workspaceRoot = config.workspaceRoot;
 	const agentConfigCache = config.agentConfigCache ?? null;
 	const gitMirrorManager = config.gitMirrorManager ?? null;
+	const claudeCodeExecutable = config.claudeCodeExecutable ?? resolveClaudeCodeExecutable().path;
 	let cwd = null;
 	let claudeSessionId = null;
 	let currentQuery = null;
@@ -2755,35 +2998,64 @@ const createClaudeCodeHandler = (config) => {
 	let appliedPayload = null;
 	/** Worktrees materialised for this session — each entry removed on shutdown. */
 	const ownedWorktrees = [];
-	function toSDKUserMessage(message, sessionId) {
-		if (message.format === "file" && isImageFileContent(message.content)) {
-			const { data, mimeType, filename } = message.content;
-			return {
-				type: "user",
-				message: {
-					role: "user",
-					content: [{
-						type: "text",
-						text: `${message.senderId ? `[From: ${message.senderId}]\n\n` : ""}[Attached image: ${filename}]`
-					}, {
-						type: "image",
-						source: {
-							type: "base64",
-							media_type: mimeType,
-							data
-						}
-					}]
-				},
-				parent_tool_use_id: null,
-				session_id: sessionId
-			};
+	async function toSDKUserMessage(message, sessionCtx, sessionId) {
+		if (message.format === "file") {
+			const senderLabel = message.senderId ? await sessionCtx.resolveSenderLabel(message.senderId) : "";
+			const prefix = senderLabel ? `[From: ${senderLabel}]\n\n` : "";
+			if (isImageRefContent(message.content)) {
+				const { imageId, mimeType, filename } = message.content;
+				const imagePath = findImagePath(message.chatId, imageId, mimeType);
+				if (imagePath) return {
+					type: "user",
+					message: {
+						role: "user",
+						content: `${prefix}An image was shared in this chat. Please use the Read tool to read it, then respond based on what you see.\n\nFilename: ${filename}\nPath: ${imagePath}`
+					},
+					parent_tool_use_id: null,
+					session_id: sessionId
+				};
+				return {
+					type: "user",
+					message: {
+						role: "user",
+						content: `${prefix}${`[Image "${filename}" not available on this device]`}`
+					},
+					parent_tool_use_id: null,
+					session_id: sessionId
+				};
+			}
+			if (isLegacyImageFileContent(message.content)) {
+				const { filename } = message.content;
+				try {
+					return {
+						type: "user",
+						message: {
+							role: "user",
+							content: `${prefix}An image was shared in this chat. Please use the Read tool to read it, then respond based on what you see.\n\nFilename: ${filename}\nPath: ${await writeLegacyImageToTempFile(message.content, message.chatId)}`
+						},
+						parent_tool_use_id: null,
+						session_id: sessionId
+					};
+				} catch (err) {
+					const fallbackText = `[Image attachment "${filename}" failed to materialise]`;
+					ctx?.log(`Failed to write image to temp file: ${err instanceof Error ? err.message : String(err)}`);
+					return {
+						type: "user",
+						message: {
+							role: "user",
+							content: `${prefix}${fallbackText}`
+						},
+						parent_tool_use_id: null,
+						session_id: sessionId
+					};
+				}
+			}
 		}
-		const rawContent = typeof message.content === "string" ? message.content : JSON.stringify(message.content);
 		return {
 			type: "user",
 			message: {
 				role: "user",
-				content: message.senderId ? `[From: ${message.senderId}]\n\n${rawContent}` : rawContent
+				content: await sessionCtx.formatInboundContent(message)
 			},
 			parent_tool_use_id: null,
 			session_id: sessionId
@@ -2796,8 +3068,9 @@ const createClaudeCodeHandler = (config) => {
 	* process.env contains internal markers (CLAUDECODE, CLAUDE_CODE_ENTRYPOINT,
 	* CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS, npm_lifecycle_script) that cause the
 	* child to enable Agent Teams infrastructure and use wrong init paths,
-	* resulting in ~90s cold start vs ~17s standalone. Strip these so the child
-	* starts clean; the SDK sets its own CLAUDE_CODE_ENTRYPOINT="sdk-ts".
+	* resulting in ~90s cold start vs ~17s standalone. Strip these here (Claude
+	* Code specific) then let the runtime layer add the Agent-Hub envelope via
+	* `ctx.buildAgentEnv` so all handlers expose the same vars uniformly.
 	*/
 	function buildEnv(sessionCtx) {
 		const env = { ...process.env };
@@ -2807,12 +3080,7 @@ const createClaudeCodeHandler = (config) => {
 		delete env.npm_lifecycle_script;
 		const payload = agentConfigCache?.get(sessionCtx.agent.agentId)?.payload;
 		if (payload) for (const e of payload.env) env[e.key] = e.value;
-		return {
-			...env,
-			FIRST_TREE_HUB_SERVER_URL: sessionCtx.sdk.serverUrl,
-			FIRST_TREE_HUB_AGENT_ID: sessionCtx.agent.agentId,
-			FIRST_TREE_HUB_CHAT_ID: sessionCtx.chatId
-		};
+		return sessionCtx.buildAgentEnv(env);
 	}
 	/** Create query and input controller, then start consumer loop. */
 	function spawnQuery(sessionId, sessionCtx, resume) {
@@ -2850,7 +3118,9 @@ const createClaudeCodeHandler = (config) => {
 				abortController,
 				permissionMode,
 				allowDangerouslySkipPermissions: true,
+				settingSources: ["project"],
 				env: buildEnv(sessionCtx),
+				...claudeCodeExecutable ? { pathToClaudeCodeExecutable: claudeCodeExecutable } : {},
 				...payload?.model ? { model: payload.model } : {},
 				...payload?.prompt.append ? { systemPrompt: {
 					type: "preset",
@@ -2913,10 +3183,7 @@ const createClaudeCodeHandler = (config) => {
 								if (message.result && sessionCtx.chatId) {
 									const resultText = message.result;
 									try {
-										await sessionCtx.sdk.sendMessage(sessionCtx.chatId, {
-											format: "text",
-											content: resultText
-										});
+										await sessionCtx.forwardResult(resultText);
 										sessionCtx.log("Result forwarded to chat");
 										sessionCtx.reportSessionCompletion();
 										sessionCtx.emitEvent({
@@ -3076,7 +3343,7 @@ const createClaudeCodeHandler = (config) => {
 			await prepareGitWorktrees(cwd, payload, sessionCtx);
 			sessionCtx.log(`Starting session (${claudeSessionId}), cwd=${cwd}, permissionMode=${config.permissionMode ?? "bypassPermissions"}`);
 			spawnQuery(claudeSessionId, sessionCtx);
-			const sdkMsg = toSDKUserMessage(message, claudeSessionId);
+			const sdkMsg = await toSDKUserMessage(message, sessionCtx, claudeSessionId);
 			inputController?.push(sdkMsg);
 			sessionCtx.log(`Session started (${claudeSessionId})`);
 			return claudeSessionId;
@@ -3091,7 +3358,7 @@ const createClaudeCodeHandler = (config) => {
 			await prepareGitWorktrees(cwd, payload, sessionCtx);
 			sessionCtx.log(`Resuming session (${sessionId}), cwd=${cwd}`);
 			spawnQuery(sessionId, sessionCtx, sessionId);
-			if (message) inputController?.push(toSDKUserMessage(message, sessionId));
+			if (message) inputController?.push(await toSDKUserMessage(message, sessionCtx, sessionId));
 			sessionCtx.log(`Session resumed (${sessionId})`);
 			return sessionId;
 		},
@@ -3104,8 +3371,13 @@ const createClaudeCodeHandler = (config) => {
 			const sid = claudeSessionId;
 			maybeSwitchConfig(sessionCtx).catch((err) => {
 				sessionCtx.log(`maybeSwitchConfig errored: ${err instanceof Error ? err.message : String(err)}`);
-			}).finally(() => {
-				inputController?.push(toSDKUserMessage(message, sid));
+			}).finally(async () => {
+				try {
+					const sdkMsg = await toSDKUserMessage(message, sessionCtx, sid);
+					inputController?.push(sdkMsg);
+				} catch (err) {
+					sessionCtx.log(`toSDKUserMessage errored: ${err instanceof Error ? err.message : String(err)}`);
+				}
 			});
 		},
 		async suspend() {
@@ -3190,7 +3462,13 @@ function generateClaudeMd(workspacePath, identity, contextTreePath) {
 }
 /** Register all built-in handlers. Call once at startup. */
 function registerBuiltinHandlers() {
-	registerHandler("claude-code", createClaudeCodeHandler);
+	const resolution = resolveClaudeCodeExecutable();
+	if (resolution.path) process.stderr.write(`[handlers] Claude Code executable: ${resolution.path} (source=${resolution.source})\n`);
+	else process.stderr.write("[handlers] Claude Code executable: using SDK bundled native binary (set CLAUDE_CODE_EXECUTABLE or install `claude` on PATH to override)\n");
+	registerHandler("claude-code", (config) => createClaudeCodeHandler({
+		...config,
+		claudeCodeExecutable: resolution.path
+	}));
 }
 function createAgentConfigCache(opts) {
 	const { sdk } = opts;
@@ -3269,6 +3547,84 @@ function createAgentConfigCache(opts) {
 	};
 }
 /**
+* Cross-handler plumbing for Agent Hub ↔ agent-runtime interaction.
+*
+* Every handler that shells out to the `first-tree-hub` CLI or otherwise acts
+* on behalf of the agent needs the same envelope variables (server URL, agent
+* id, inbox id, chat id). And every handler that hands inbound messages to an
+* LLM benefits from the same `[From: <name>]` attribution header so the LLM
+* can see who authored each message in human-readable terms.
+*
+* Keeping these helpers in one place means adding a second handler (Gemini,
+* Cursor Agent, custom LLM, …) does not reimplement either concern.
+*/
+/**
+* Build the env for CLI sub-processes that need to call `first-tree-hub ...`.
+* Layers the Agent-Hub envelope variables on top of the parent env. Handlers
+* that start sub-processes should call this so every one of them sees the
+* same envelope — enabling replyTo inference, access-token propagation, and
+* agent-id binding without per-handler duplication.
+*/
+function buildAgentEnv(parentEnv, ctx) {
+	return {
+		...parentEnv,
+		FIRST_TREE_HUB_SERVER_URL: ctx.sdk.serverUrl,
+		FIRST_TREE_HUB_AGENT_ID: ctx.agent.agentId,
+		FIRST_TREE_HUB_INBOX_ID: ctx.agent.inboxId,
+		FIRST_TREE_HUB_CHAT_ID: ctx.chatId
+	};
+}
+function createParticipantCache(sdk, chatId, log) {
+	let cached = null;
+	let inflight = null;
+	return { async get() {
+		if (cached) return cached;
+		if (!inflight) inflight = (async () => {
+			try {
+				const rows = await sdk.listChatParticipants(chatId);
+				cached = rows;
+				return rows;
+			} catch (err) {
+				log(`listChatParticipants failed: ${err instanceof Error ? err.message : String(err)}`);
+				return [];
+			} finally {
+				inflight = null;
+			}
+		})();
+		return inflight;
+	} };
+}
+/**
+* Resolve `senderId` → display-friendly label the LLM can actually
+* disambiguate. Prefers `name` (unique per chat, used as the `@<name>`
+* mention token), falls back to `displayName`, then to the raw id. The last
+* fallback matters for edge cases — e.g. a participant removed mid-session
+* after we cached an earlier participants snapshot.
+*/
+function resolveSenderLabel(senderId, participants) {
+	for (const p of participants) {
+		if (p.agentId !== senderId) continue;
+		if (p.name) return p.name;
+		if (p.displayName) return p.displayName;
+		return senderId;
+	}
+	return senderId;
+}
+/**
+* Produce the handler-facing string form of an inbound message. Prefixes a
+* `[From: <name>]` line when the sender is a known participant. Structured
+* content is serialised to JSON — handlers that want to feed structured
+* content some other way should opt out and format themselves.
+*
+* Async because the participant list may need a server round-trip on first
+* use; subsequent messages in the same session hit the cache.
+*/
+async function formatInboundContent(message, participants) {
+	const rawContent = typeof message.content === "string" ? message.content : JSON.stringify(message.content);
+	if (!message.senderId) return rawContent;
+	return `[From: ${resolveSenderLabel(message.senderId, await participants.get())}]\n\n${rawContent}`;
+}
+/**
 * Deduplicator — bounded set of recently seen IDs.
 *
 * Used to deduplicate at-least-once delivered messages at the dispatch layer.
@@ -3299,6 +3655,24 @@ var Deduplicator = class {
 		return this.seen.size;
 	}
 };
+function createResultSink(deps) {
+	async function buildMetadata(trigger) {
+		if (!trigger || trigger.senderId === deps.agent.agentId) return void 0;
+		if ((await deps.participants.get()).length <= 2) return void 0;
+		return { mentions: [trigger.senderId] };
+	}
+	return async function forwardResult(text) {
+		const trigger = deps.getTrigger();
+		deps.clearTrigger();
+		const metadata = await buildMetadata(trigger);
+		await deps.sdk.sendMessage(deps.chatId, {
+			format: "text",
+			content: text,
+			...trigger ? { inReplyTo: trigger.messageId } : {},
+			...metadata ? { metadata } : {}
+		});
+	};
+}
 const REGISTRY_VERSION = 1;
 /**
 * SessionRegistry — persists `chatId → claudeSessionId` mappings to disk.
@@ -3388,6 +3762,14 @@ var SessionManager = class {
 	evictedMappings = /* @__PURE__ */ new Map();
 	config;
 	deduplicator = new Deduplicator(1e3);
+	/**
+	* Current trigger (messageId + senderId) per chat — the message that kicked
+	* off the current or most-recent turn. Read by `forwardResult` (via the
+	* resultSink closure) to attach `inReplyTo` and default mentions to the
+	* outbound reply. Maintained entirely by the runtime: handlers never touch
+	* this map, which keeps adding a new handler trivial.
+	*/
+	currentTrigger = /* @__PURE__ */ new Map();
 	registry;
 	pendingQueue = [];
 	lastReportedStates = /* @__PURE__ */ new Map();
@@ -3407,11 +3789,24 @@ var SessionManager = class {
 	* Delayed ACK: messages are ACKed when the handler begins processing,
 	* not on pull. `delivered` = pulled but not yet processing,
 	* `acked` = handler has started processing (read receipt).
+	*
+	* One routing guard fires before any session lookup (see
+	* proposals/hub-agent-messaging-reply-and-mentions §3.5):
+	*
+	* - **Echo suppression** — in direct chats, a peer's reply to a message
+	*   *we* sent here but whose `replyTo` points elsewhere would otherwise
+	*   bounce our session back on. Suppress it so the reply routes only to
+	*   the external chat where we're actually waiting.
+	*
+	* The mention filter used to live here too, but it moved server-side to
+	* the fan-out step — see `services/message.ts sendMessage`. Anything
+	* reaching dispatch has already passed that check.
 	*/
 	async dispatch(entry) {
 		const chatId = entry.chatId ?? entry.message.chatId;
 		const messageId = entry.message.id;
-		if (this.deduplicator.isDuplicate(messageId)) {
+		const dedupKey = `${chatId}:${messageId}`;
+		if (this.deduplicator.isDuplicate(dedupKey)) {
 			this.config.log.debug({
 				chatId,
 				messageId
@@ -3428,6 +3823,14 @@ var SessionManager = class {
 				err
 			}, "config version mismatch — skipping refresh");
 		}
+		if (shouldSuppressEcho(entry, this.config.agentIdentity.agentId)) {
+			this.config.log.info({
+				chatId,
+				messageId
+			}, "suppressing echo — message replies to our own send whose replyTo points elsewhere");
+			await this.ackEntry(entry.id, chatId);
+			return;
+		}
 		const message = this.extractMessage(entry);
 		await this.routeMessage(chatId, message, entry.id);
 	}
@@ -3454,6 +3857,7 @@ var SessionManager = class {
 			this.evictedMappings.delete(chatId);
 			this.sessionRuntimeStates.delete(chatId);
 			this.lastReportedStates.delete(chatId);
+			this.currentTrigger.delete(chatId);
 			for (let i = this.pendingQueue.length - 1; i >= 0; i--) if (this.pendingQueue[i]?.chatId === chatId) this.pendingQueue.splice(i, 1);
 			this.recomputeRuntimeState();
 			this.persistRegistry();
@@ -3524,6 +3928,10 @@ var SessionManager = class {
 		}));
 	}
 	async routeMessage(chatId, message, entryId) {
+		if (message.id) this.currentTrigger.set(chatId, {
+			messageId: message.id,
+			senderId: message.senderId
+		});
 		const existing = this.sessions.get(chatId);
 		if (existing) switch (existing.status) {
 			case "active":
@@ -3712,6 +4120,7 @@ var SessionManager = class {
 			}
 			this.sessions.delete(candidate.key);
 			this.sessionRuntimeStates.delete(candidate.key);
+			this.currentTrigger.delete(candidate.key);
 			this.recomputeRuntimeState();
 			this.persistRegistry();
 		}
@@ -3769,10 +4178,28 @@ var SessionManager = class {
 	}
 	buildSessionContext(chatId) {
 		const sessionLog = this.config.log.child({ chatId });
+		const log = (msg) => sessionLog.info(msg);
+		const participants = createParticipantCache(this.config.sdk, chatId, log);
+		const forwardResult = createResultSink({
+			sdk: this.config.sdk,
+			agent: this.config.agentIdentity,
+			chatId,
+			getTrigger: () => this.currentTrigger.get(chatId) ?? null,
+			clearTrigger: () => {
+				this.currentTrigger.delete(chatId);
+			},
+			log,
+			participants
+		});
+		const envCtx = {
+			sdk: this.config.sdk,
+			agent: this.config.agentIdentity,
+			chatId
+		};
 		return {
 			agent: this.config.agentIdentity,
 			sdk: this.config.sdk,
-			log: (msg) => sessionLog.info(msg),
+			log,
 			chatId,
 			touch: () => {
 				const entry = this.sessions.get(chatId);
@@ -3786,7 +4213,11 @@ var SessionManager = class {
 			},
 			reportSessionCompletion: () => {
 				this.config.onSessionCompletion?.(chatId);
-			}
+			},
+			forwardResult,
+			buildAgentEnv: (parentEnv) => buildAgentEnv(parentEnv, envCtx),
+			formatInboundContent: (message) => formatInboundContent(message, participants),
+			resolveSenderLabel: async (senderId) => resolveSenderLabel(senderId, await participants.get())
 		};
 	}
 	/** Update per-session runtime state and recompute aggregate. Only active sessions may update. */
@@ -3849,6 +4280,35 @@ var SessionManager = class {
 		this.registry.save(entries);
 	}
 };
+/**
+* Core echo rule: a reply to a message *we* sent in this same chat, whose
+* original carried a `replyTo` pointing to a *different* chat, must not wake
+* our session on this side. Server-side replyTo routing already delivers a
+* second entry in the target chat, so suppressing the fan-out copy here
+* leaves exactly one path from peer's reply to our waiting session.
+*
+* The four early-returns spell out "when this is NOT an echo":
+*  - no snapshot        → just a regular message, not a reply
+*  - sender isn't us    → replying to someone else's message, clearly not an echo
+*  - original chat != this chat
+*       → the reply arrived in a chat where we never sent the original;
+*         could only happen via replyTo fan-out of a different thread, so
+*         suppressing would silence a legit cross-chat handoff
+*  - original had no replyTo → sender didn't ask replies to route away, so
+*                              the peer's reply here is the canonical path
+*
+* Only when all four are satisfied AND the replyTo target is a different
+* chat do we suppress — that's exactly proposal §3.5 Case A.
+*/
+function shouldSuppressEcho(entry, myAgentId) {
+	const snapshot = entry.message.inReplyToSnapshot;
+	if (!snapshot) return false;
+	const entryChatId = entry.chatId ?? entry.message.chatId;
+	if (snapshot.senderId !== myAgentId) return false;
+	if (snapshot.chatId !== entryChatId) return false;
+	if (snapshot.replyToChat === null) return false;
+	return snapshot.replyToChat !== entryChatId;
+}
 var AgentSlot = class {
 	sessionManager = null;
 	config;
@@ -3944,6 +4404,7 @@ var AgentSlot = class {
 			},
 			agentIdentity: {
 				agentId: agent.agentId,
+				inboxId: agent.inboxId,
 				displayName: agent.displayName,
 				type: agent.type,
 				delegateMention: agent.delegateMention,
@@ -4276,6 +4737,27 @@ const print = {
 	line
 };
 //#endregion
+//#region src/core/agent-messaging.ts
+/**
+* Resolve `replyTo` envelope fields for `agent send`. When the CLI is invoked
+* from inside a claude-code session (the handler exports
+* `FIRST_TREE_HUB_CHAT_ID` + `FIRST_TREE_HUB_INBOX_ID`), default the reply
+* target to the calling session's own chat so the peer's reply routes back
+* to the caller rather than echoing in the peer-created direct chat.
+*
+* Explicit `--reply-to-*` flags always win. See proposals/
+* hub-agent-messaging-reply-and-mentions §3.2.
+*/
+function resolveReplyToFromEnv(env, override) {
+	const envChatId = env.FIRST_TREE_HUB_CHAT_ID;
+	const envInboxId = env.FIRST_TREE_HUB_INBOX_ID;
+	const envComplete = Boolean(envChatId && envInboxId);
+	return {
+		replyToInbox: override.replyToInbox ?? (envComplete ? envInboxId : void 0),
+		replyToChat: override.replyToChat ?? (envComplete ? envChatId : void 0)
+	};
+}
+//#endregion
 //#region src/core/admin.ts
 /**
 * Check if any user exists.
@@ -5664,7 +6146,7 @@ async function onboardCreate(args) {
 	}
 	const runtimeAgent = args.type === "human" ? args.assistant : args.id;
 	if (args.feishuBotAppId && args.feishuBotAppSecret) {
-		const { bindFeishuBot } = await import("./feishu-GlaczcVf.mjs").then((n) => n.r);
+		const { bindFeishuBot } = await import("./feishu-CRNUI05I.mjs").then((n) => n.r);
 		const targetAgentUuid = args.type === "human" ? assistantUuid : primary.uuid;
 		if (!targetAgentUuid) print.line(`Warning: Cannot bind Feishu bot — no runtime agent available for "${args.id}".\n`);
 		else {
@@ -5805,7 +6287,7 @@ function setNestedByDot(obj, dotPath, value) {
 	if (lastKey !== void 0) current[lastKey] = value;
 }
 //#endregion
-//#region ../server/dist/app-Frne_Mbn.mjs
+//#region ../server/dist/app-BcAIFEPL.mjs
 var __defProp = Object.defineProperty;
 var __exportAll = (all, no_symbols) => {
 	let target = {};
@@ -7032,6 +7514,28 @@ async function deleteAgent(db, uuid) {
 	if (!agent) throw new Error("Unexpected: UPDATE RETURNING produced no row");
 	return agent;
 }
+/**
+* When a direct chat grows past 2 participants, upgrade it to `group` and
+* flip every existing non-human agent participant to `mention_only` — see
+* proposals/hub-agent-messaging-reply-and-mentions §3.3. The caller is
+* expected to insert the new participant AFTER this runs, so the "existing"
+* set excludes them.
+*
+* Idempotent: if the chat is already a group, no-op.
+*/
+async function maybeUpgradeDirectToGroup(db, chatId, existingParticipantIds, newParticipantCount) {
+	if (existingParticipantIds.length + newParticipantCount < 3) return;
+	const [chat] = await db.select({ type: chats.type }).from(chats).where(eq(chats.id, chatId)).limit(1);
+	if (!chat || chat.type !== "direct") return;
+	await db.update(chats).set({
+		type: "group",
+		updatedAt: /* @__PURE__ */ new Date()
+	}).where(eq(chats.id, chatId));
+	if (existingParticipantIds.length === 0) return;
+	const ids = (await db.select({ uuid: agents.uuid }).from(agents).where(and(inArray(agents.uuid, existingParticipantIds), ne(agents.type, "human")))).map((a) => a.uuid);
+	if (ids.length === 0) return;
+	await db.update(chatParticipants).set({ mode: "mention_only" }).where(and(eq(chatParticipants.chatId, chatId), inArray(chatParticipants.agentId, ids)));
+}
 async function createChat(db, creatorId, data) {
 	const chatId = randomUUID();
 	const allParticipantIds = new Set([creatorId, ...data.participantIds]);
@@ -7099,17 +7603,38 @@ async function listChats(db, agentId, limit, cursor) {
 		nextCursor: hasMore && last ? last.updatedAt.toISOString() : null
 	};
 }
+/**
+* List participants of a chat with their agent names — used by the client
+* runtime to resolve `@<name>` mentions against the authoritative participant
+* set (see proposals/hub-agent-messaging-reply-and-mentions §4).
+*/
+async function listChatParticipantsWithNames(db, chatId) {
+	return await db.select({
+		agentId: chatParticipants.agentId,
+		role: chatParticipants.role,
+		mode: chatParticipants.mode,
+		joinedAt: chatParticipants.joinedAt,
+		name: agents.name,
+		displayName: agents.displayName,
+		type: agents.type
+	}).from(chatParticipants).innerJoin(agents, eq(chatParticipants.agentId, agents.uuid)).where(eq(chatParticipants.chatId, chatId));
+}
 async function assertParticipant(db, chatId, agentId) {
 	const [row] = await db.select({ chatId: chatParticipants.chatId }).from(chatParticipants).where(and(eq(chatParticipants.chatId, chatId), eq(chatParticipants.agentId, agentId))).limit(1);
 	if (!row) throw new ForbiddenError("Not a participant of this chat");
 }
 /** Ensure an agent is a participant of a chat. Silently adds them if not already. */
 async function ensureParticipant(db, chatId, agentId) {
-	await db.insert(chatParticipants).values({
-		chatId,
-		agentId,
-		mode: "full"
-	}).onConflictDoNothing({ target: [chatParticipants.chatId, chatParticipants.agentId] });
+	const [existing] = await db.select({ agentId: chatParticipants.agentId }).from(chatParticipants).where(and(eq(chatParticipants.chatId, chatId), eq(chatParticipants.agentId, agentId))).limit(1);
+	if (existing) return;
+	await db.transaction(async (tx) => {
+		await maybeUpgradeDirectToGroup(tx, chatId, (await tx.select({ agentId: chatParticipants.agentId }).from(chatParticipants).where(eq(chatParticipants.chatId, chatId))).map((p) => p.agentId), 1);
+		await tx.insert(chatParticipants).values({
+			chatId,
+			agentId,
+			mode: "full"
+		}).onConflictDoNothing({ target: [chatParticipants.chatId, chatParticipants.agentId] });
+	});
 }
 async function addParticipant(db, chatId, requesterId, data) {
 	const chat = await getChat(db, chatId);
@@ -7122,10 +7647,13 @@ async function addParticipant(db, chatId, requesterId, data) {
 	if (targetAgent.organizationId !== chat.organizationId) throw new BadRequestError("Cannot add agent from different organization");
 	const [existing] = await db.select({ chatId: chatParticipants.chatId }).from(chatParticipants).where(and(eq(chatParticipants.chatId, chatId), eq(chatParticipants.agentId, data.agentId))).limit(1);
 	if (existing) throw new ConflictError(`Agent "${data.agentId}" is already a participant`);
-	await db.insert(chatParticipants).values({
-		chatId,
-		agentId: data.agentId,
-		mode: data.mode ?? "full"
+	await db.transaction(async (tx) => {
+		await maybeUpgradeDirectToGroup(tx, chatId, (await tx.select({ agentId: chatParticipants.agentId }).from(chatParticipants).where(eq(chatParticipants.chatId, chatId))).map((p) => p.agentId), 1);
+		await tx.insert(chatParticipants).values({
+			chatId,
+			agentId: data.agentId,
+			mode: data.mode ?? "full"
+		});
 	});
 	return db.select().from(chatParticipants).where(eq(chatParticipants.chatId, chatId));
 }
@@ -7224,11 +7752,14 @@ async function joinChat(db, chatId, memberId, humanAgentId) {
 	if ((await db.select({ uuid: agents.uuid }).from(agents).where(and(inArray(agents.uuid, participantAgentIds), eq(agents.managerId, memberId)))).length === 0) throw new ForbiddenError("You can only join chats where you manage at least one participant");
 	const [humanAgent] = await db.select({ organizationId: agents.organizationId }).from(agents).where(eq(agents.uuid, humanAgentId)).limit(1);
 	if (!humanAgent || humanAgent.organizationId !== chat.organizationId) throw new BadRequestError("Agent does not belong to the same organization as the chat");
-	await db.insert(chatParticipants).values({
-		chatId,
-		agentId: humanAgentId,
-		role: "member",
-		mode: "full"
+	await db.transaction(async (tx) => {
+		await maybeUpgradeDirectToGroup(tx, chatId, participantAgentIds, 1);
+		await tx.insert(chatParticipants).values({
+			chatId,
+			agentId: humanAgentId,
+			role: "member",
+			mode: "full"
+		});
 	});
 	return db.select().from(chatParticipants).where(eq(chatParticipants.chatId, chatId));
 }
@@ -7723,6 +8254,26 @@ async function sendMessage(db, chatId, senderId, data) {
 }
 async function sendMessageInner(db, chatId, senderId, data) {
 	return db.transaction(async (tx) => {
+		const participants = await tx.select({
+			agentId: chatParticipants.agentId,
+			inboxId: agents.inboxId,
+			mode: chatParticipants.mode,
+			name: agents.name
+		}).from(chatParticipants).innerJoin(agents, eq(chatParticipants.agentId, agents.uuid)).where(eq(chatParticipants.chatId, chatId));
+		if (data.replyToInbox !== void 0 && data.replyToInbox !== null) {
+			const [senderRow] = await tx.select({ inboxId: agents.inboxId }).from(agents).where(eq(agents.uuid, senderId)).limit(1);
+			if (!senderRow || senderRow.inboxId !== data.replyToInbox) throw new BadRequestError("replyToInbox must reference the sender's own inbox");
+		}
+		const incomingMeta = data.metadata ?? {};
+		const explicitMentionsRaw = incomingMeta.mentions;
+		const explicitMentions = Array.isArray(explicitMentionsRaw) ? explicitMentionsRaw.filter((m) => typeof m === "string") : [];
+		const contentText = typeof data.content === "string" ? data.content : "";
+		const resolved = contentText ? extractMentions(contentText, participants) : [];
+		const mergedMentions = [...new Set([...explicitMentions, ...resolved])];
+		const metadataToStore = mergedMentions.length > 0 ? {
+			...incomingMeta,
+			mentions: mergedMentions
+		} : incomingMeta;
 		const messageId = randomUUID();
 		const [msg] = await tx.insert(messages).values({
 			id: messageId,
@@ -7730,16 +8281,14 @@ async function sendMessageInner(db, chatId, senderId, data) {
 			senderId,
 			format: data.format,
 			content: data.content,
-			metadata: data.metadata ?? {},
+			metadata: metadataToStore,
 			replyToInbox: data.replyToInbox ?? null,
 			replyToChat: data.replyToChat ?? null,
 			inReplyTo: data.inReplyTo ?? null,
 			source: data.source ?? null
 		}).returning();
-		const entries = (await tx.select({
-			agentId: chatParticipants.agentId,
-			inboxId: agents.inboxId
-		}).from(chatParticipants).innerJoin(agents, eq(chatParticipants.agentId, agents.uuid)).where(eq(chatParticipants.chatId, chatId))).filter((p) => p.agentId !== senderId).map((p) => ({
+		const mentionSet = new Set(mergedMentions);
+		const entries = participants.filter((p) => p.agentId !== senderId).filter((p) => p.mode !== "mention_only" || mentionSet.has(p.agentId)).map((p) => ({
 			inboxId: p.inboxId,
 			messageId,
 			chatId
@@ -7775,7 +8324,7 @@ async function sendToAgent(db, senderUuid, targetName, data) {
 	}).from(agents).where(eq(agents.uuid, senderUuid)).limit(1);
 	if (!sender) throw new NotFoundError(`Agent "${senderUuid}" not found`);
 	const [target] = await db.select({ uuid: agents.uuid }).from(agents).where(and(eq(agents.organizationId, sender.organizationId), eq(agents.name, targetName), ne(agents.status, "deleted"))).limit(1);
-	if (!target) throw new NotFoundError(`Agent "${targetName}" not found`);
+	if (!target) throw new NotFoundError(`Agent "${targetName}" not found${/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(targetName) ? " — `agent send` expects an agent NAME, not a uuid. Run `first-tree-hub agent list` to see available names." : ""}`);
 	return sendMessage(db, (await findOrCreateDirectChat(db, senderUuid, target.uuid)).id, senderUuid, {
 		format: data.format,
 		content: data.content,
@@ -7874,6 +8423,23 @@ function createNotifier(listenClient) {
 				await listenClient`SELECT pg_notify(${RUNTIME_STATE_CHANNEL}, ${`${agentId}:${state}:${organizationId}`})`;
 			} catch {}
 		},
+		async pushFrameToInbox(inboxId, frame) {
+			const sockets = subscriptions.get(inboxId);
+			if (!sockets) return 0;
+			let queued = 0;
+			const pending = [];
+			for (const ws of sockets) {
+				if (ws.readyState !== ws.OPEN) continue;
+				pending.push(new Promise((resolve) => {
+					ws.send(frame, (err) => {
+						if (!err) queued += 1;
+						resolve();
+					});
+				}));
+			}
+			await Promise.all(pending);
+			return queued;
+		},
 		onConfigChange(handler) {
 			configChangeHandlers.push(handler);
 		},
@@ -8250,6 +8816,73 @@ function requireAdminRoleHook() {
 		if (request.member?.role !== "admin") throw new ForbiddenError("Admin role required");
 	};
 }
+/**
+* Intercepts outbound image messages. If `data.content` carries an inline
+* base64 image (legacy-style payload from the web), we:
+*
+*   1. Generate / adopt an `imageId`
+*   2. Push the bytes as an `image_payload` WS frame to every participant
+*      agent's inbox — plus the reply-to inbox when this is a cross-chat
+*      reply (matches sendMessage's extra fan-out). Best-effort, local
+*      instance only, no PG NOTIFY.
+*   3. Return a copy of `data` whose `content` is just the reference
+*      {imageId, mimeType, filename, size}
+*
+* The push is fire-and-forget: `ws.send()` queues the frame into the socket's
+* send buffer synchronously, which is the only ordering guarantee we need
+* — the subsequent `new_message` notification travels a strictly slower PG
+* NOTIFY round trip, so the image lands first on the wire. Awaiting the TCP
+* flush here would put a slow subscriber's backpressure on the sender's
+* HTTP response for a feature that is already best-effort.
+*
+* Non-image messages are returned unchanged. Missing-subscriber / wrong-
+* instance cases are acceptable loss per the image-out-of-messages design
+* (the reference-only message still lands in the DB; clients that missed
+* the bytes surface a "not available on this device" placeholder).
+*/
+async function prepareImageOutbound(db, notifier, chatId, data) {
+	if (data.format !== "file") return data;
+	const parsed = imageInlineContentSchema.safeParse(data.content);
+	if (!parsed.success) return data;
+	const inline = parsed.data;
+	const imageId = inline.imageId ?? randomUUID();
+	const frame = {
+		type: "image_payload",
+		imageId,
+		chatId,
+		base64: inline.data,
+		mimeType: inline.mimeType,
+		filename: inline.filename,
+		...inline.size !== void 0 ? { size: inline.size } : {}
+	};
+	const serialised = JSON.stringify(frame);
+	const inboxIds = await collectTargetInboxes(db, chatId, data.inReplyTo);
+	for (const inboxId of inboxIds) notifier.pushFrameToInbox(inboxId, serialised).catch(() => {});
+	const ref = {
+		imageId,
+		mimeType: inline.mimeType,
+		filename: inline.filename,
+		...inline.size !== void 0 ? { size: inline.size } : {}
+	};
+	return {
+		...data,
+		content: ref
+	};
+}
+/**
+* Mirror `sendMessage`'s fan-out set: every participant of the current
+* chat, plus the original requester's inbox when this message is a cross-
+* chat reply (see `services/message.ts` replyTo routing).
+*/
+async function collectTargetInboxes(db, chatId, inReplyTo) {
+	const participants = await db.select({ inboxId: agents.inboxId }).from(chatParticipants).innerJoin(agents, eq(chatParticipants.agentId, agents.uuid)).where(eq(chatParticipants.chatId, chatId));
+	const set = new Set(participants.map((p) => p.inboxId));
+	if (inReplyTo) {
+		const [original] = await db.select({ replyToInbox: messages.replyToInbox }).from(messages).where(eq(messages.id, inReplyTo)).limit(1);
+		if (original?.replyToInbox) set.add(original.replyToInbox);
+	}
+	return [...set];
+}
 async function adminChatRoutes(app) {
 	/** List all chats in org (admin-only, for audit). Members should use GET /mine. */
 	app.get("/", { preHandler: requireAdminRoleHook() }, async (request) => {
@@ -8427,10 +9060,11 @@ async function adminChatRoutes(app) {
 		const body = sendMessageSchema.parse(request.body);
 		await assertChatAccess(app.db, scope, chatId);
 		await ensureParticipant(app.db, chatId, member.agentId);
-		const result = await sendMessage(app.db, chatId, member.agentId, {
+		const prepared = await prepareImageOutbound(app.db, app.notifier, chatId, {
 			...body,
 			source: "hub_ui"
 		});
+		const result = await sendMessage(app.db, chatId, member.agentId, prepared);
 		notifyRecipients(app.notifier, result.recipients, result.message.id);
 		return reply.status(201).send({
 			id: result.message.id,
@@ -8453,15 +9087,19 @@ const agentChatSessions = pgTable("agent_chat_sessions", {
 /**
 * Upsert session state + refresh presence aggregates + NOTIFY.
 *
-* Revival defense: an admin-terminated (`evicted`) row is immutable; a client
-* report for the same chatId is silently dropped after the FOR UPDATE check.
+* `agent_chat_sessions.(agent_id, chat_id)` is a single-row "current session
+* state" cache, not a session history log. A new runtime session starting on
+* the same (agent, chat) pair MUST overwrite whatever ended before — including
+* an `evicted` row left by a previous terminate. The previous "revival
+* defense" conflated two concerns: "this runtime session ended" (which is
+* what `evicted` actually means) and "this chat is permanently archived for
+* this agent" (a chat-level decision that should live on `chats`, not here).
+* See proposals/hub-agent-messaging-reply-and-mentions §M2-session-lifecycle.
 */
 async function upsertSessionState(db, agentId, chatId, state, organizationId, notifier) {
 	const now = /* @__PURE__ */ new Date();
 	let wrote = false;
 	await db.transaction(async (tx) => {
-		const [existing] = await tx.select({ state: agentChatSessions.state }).from(agentChatSessions).where(and(eq(agentChatSessions.agentId, agentId), eq(agentChatSessions.chatId, chatId))).for("update");
-		if (existing?.state === "evicted") return;
 		await tx.insert(agentChatSessions).values({
 			agentId,
 			chatId,
@@ -8986,7 +9624,8 @@ function extractSummary(content, maxLen = SUMMARY_MAX_LENGTH) {
 	let text = "";
 	if (typeof content === "object" && content !== null && "text" in content) text = String(content.text ?? "");
 	else if (typeof content === "string") text = content;
-	return text ? text.slice(0, maxLen) : null;
+	if (!text) return null;
+	return Array.from(text).slice(0, maxLen).join("");
 }
 /** List sessions for a specific agent, with optional state filters. */
 async function listAgentSessions(db, agentId, filters) {
@@ -9071,7 +9710,8 @@ async function listAllSessions(db, limit, cursor, filters) {
 		chatId: agentChatSessions.chatId,
 		state: agentChatSessions.state,
 		updatedAt: agentChatSessions.updatedAt,
-		chatCreatedAt: chats.createdAt
+		chatCreatedAt: chats.createdAt,
+		chatTopic: chats.topic
 	}).from(agentChatSessions).innerJoin(chats, eq(agentChatSessions.chatId, chats.id)).innerJoin(agents, eq(agentChatSessions.agentId, agents.uuid)).where(conditions.length > 0 ? and(...conditions) : void 0).orderBy(desc(agentChatSessions.updatedAt)).limit(limit + 1);
 	const hasMore = rows.length > limit;
 	const items = hasMore ? rows.slice(0, limit) : rows;
@@ -9081,6 +9721,16 @@ async function listAllSessions(db, limit, cursor, filters) {
 		runtimeState: agentPresence.runtimeState
 	}).from(agentPresence).where(inArray(agentPresence.agentId, agentIds)) : [];
 	const runtimeMap = new Map(presenceRows.map((r) => [r.agentId, r.runtimeState]));
+	const chatIds = [...new Set(items.map((r) => r.chatId))];
+	const firstMessages = chatIds.length > 0 ? await db.selectDistinctOn([messages.chatId], {
+		chatId: messages.chatId,
+		content: messages.content
+	}).from(messages).where(inArray(messages.chatId, chatIds)).orderBy(messages.chatId, messages.createdAt) : [];
+	const summaryMap = /* @__PURE__ */ new Map();
+	for (const row of firstMessages) {
+		const summary = extractSummary(row.content);
+		if (summary) summaryMap.set(row.chatId, summary);
+	}
 	const last = items[items.length - 1];
 	const nextCursor = hasMore && last ? last.updatedAt.toISOString() : null;
 	return {
@@ -9092,8 +9742,8 @@ async function listAllSessions(db, limit, cursor, filters) {
 			startedAt: r.chatCreatedAt.toISOString(),
 			lastActivityAt: r.updatedAt.toISOString(),
 			messageCount: 0,
-			summary: null,
-			topic: null
+			summary: summaryMap.get(r.chatId) ?? null,
+			topic: r.chatTopic ?? null
 		})),
 		nextCursor
 	};
@@ -10055,6 +10705,24 @@ async function agentChatRoutes(app) {
 			}))
 		};
 	});
+	/**
+	* List chat participants with agent names/displayNames. Used by the client
+	* runtime to resolve `@<name>` mentions against the authoritative participant
+	* set (see proposals/hub-agent-messaging-reply-and-mentions §4).
+	*/
+	app.get("/:chatId/participants", async (request) => {
+		const identity = requireAgent(request);
+		await assertParticipant(app.db, request.params.chatId, identity.uuid);
+		return (await listChatParticipantsWithNames(app.db, request.params.chatId)).map((r) => ({
+			agentId: r.agentId,
+			role: r.role,
+			mode: r.mode,
+			name: r.name,
+			displayName: r.displayName,
+			type: r.type,
+			joinedAt: r.joinedAt.toISOString()
+		}));
+	});
 	app.post("/:chatId/participants", async (request, reply) => {
 		const identity = requireAgent(request);
 		const body = addParticipantSchema.parse(request.body);
@@ -10180,19 +10848,46 @@ function normaliseSource(source) {
 	const parsed = messageSourceSchema$1.safeParse(source);
 	return parsed.success ? parsed.data : null;
 }
+function normaliseMode(mode) {
+	return mode === "mention_only" ? "mention_only" : "full";
+}
 /**
-* Batch variant — builds all payloads with a single DB lookup per agent.
-* Use this from `pollInbox` to avoid an N+1 against `agent_configs`.
+* Batch variant — builds all payloads with a single DB lookup per agent plus
+* batched lookups for participant modes and inReplyTo snapshots.
 */
-async function buildClientMessagePayloadsForInbox(db, inboxId, messages) {
-	if (messages.length === 0) return [];
+async function buildClientMessagePayloadsForInbox(db, inboxId, items) {
+	if (items.length === 0) return [];
 	const agentId = await resolveAgentId(db, {
 		kind: "inboxId",
 		inboxId
 	});
 	const [cfg] = await db.select({ version: agentConfigs.version }).from(agentConfigs).where(eq(agentConfigs.agentId, agentId)).limit(1);
 	const version = cfg?.version ?? 1;
-	return messages.map((m) => ({
+	const chatIds = [...new Set(items.map((it) => it.entryChatId ?? it.message.chatId).filter((id) => id !== null))];
+	const modeByChat = /* @__PURE__ */ new Map();
+	if (chatIds.length > 0) {
+		const rows = await db.select({
+			chatId: chatParticipants.chatId,
+			mode: chatParticipants.mode
+		}).from(chatParticipants).where(and(eq(chatParticipants.agentId, agentId), inArray(chatParticipants.chatId, chatIds)));
+		for (const r of rows) modeByChat.set(r.chatId, normaliseMode(r.mode));
+	}
+	const inReplyToIds = [...new Set(items.map((it) => it.message.inReplyTo).filter((id) => id !== null))];
+	const snapshotById = /* @__PURE__ */ new Map();
+	if (inReplyToIds.length > 0) {
+		const origs = await db.select({
+			id: messages.id,
+			senderId: messages.senderId,
+			chatId: messages.chatId,
+			replyToChat: messages.replyToChat
+		}).from(messages).where(inArray(messages.id, inReplyToIds));
+		for (const o of origs) snapshotById.set(o.id, {
+			senderId: o.senderId,
+			chatId: o.chatId,
+			replyToChat: o.replyToChat
+		});
+	}
+	return items.map(({ entryChatId, message: m }) => ({
 		id: m.id,
 		chatId: m.chatId,
 		senderId: m.senderId,
@@ -10204,7 +10899,9 @@ async function buildClientMessagePayloadsForInbox(db, inboxId, messages) {
 		inReplyTo: m.inReplyTo,
 		source: normaliseSource(m.source),
 		createdAt: m.createdAt,
-		configVersion: version
+		configVersion: version,
+		recipientMode: modeByChat.get(entryChatId ?? m.chatId) ?? "full",
+		inReplyToSnapshot: m.inReplyTo ? snapshotById.get(m.inReplyTo) ?? null : null
 	}));
 }
 async function resolveAgentId(db, source) {
@@ -10243,23 +10940,25 @@ async function pollInboxInner(db, inboxId, limit) {
 			const msg = msgMap.get(entry.message_id);
 			if (!msg) throw new Error(`Unexpected: message ${entry.message_id} not found`);
 			return {
-				id: msg.id,
-				chatId: msg.chatId,
-				senderId: msg.senderId,
-				format: msg.format,
-				content: msg.content,
-				metadata: msg.metadata,
-				replyToInbox: msg.replyToInbox,
-				replyToChat: msg.replyToChat,
-				inReplyTo: msg.inReplyTo,
-				source: msg.source,
-				createdAt: msg.createdAt.toISOString()
+				entryChatId: entry.chat_id,
+				message: {
+					id: msg.id,
+					chatId: msg.chatId,
+					senderId: msg.senderId,
+					format: msg.format,
+					content: msg.content,
+					metadata: msg.metadata,
+					replyToInbox: msg.replyToInbox,
+					replyToChat: msg.replyToChat,
+					inReplyTo: msg.inReplyTo,
+					source: msg.source,
+					createdAt: msg.createdAt.toISOString()
+				}
 			};
 		}));
-		const payloadByMessageId = new Map(payloads.map((p) => [p.id, p]));
-		return claimed.map((entry) => {
-			const payload = payloadByMessageId.get(entry.message_id);
-			if (!payload) throw new Error(`Unexpected: payload for ${entry.message_id} not built`);
+		return claimed.map((entry, idx) => {
+			const payload = payloads[idx];
+			if (!payload) throw new Error(`Unexpected: payload for entry ${entry.id} not built`);
 			return {
 				id: entry.id,
 				inboxId: entry.inbox_id,
@@ -10359,7 +11058,8 @@ async function agentMessageRoutes(app) {
 		const identity = requireAgent(request);
 		await assertParticipant(app.db, request.params.chatId, identity.uuid);
 		const body = sendMessageSchema.parse(request.body);
-		const { message: msg, recipients } = await sendMessage(app.db, request.params.chatId, identity.uuid, body);
+		const prepared = await prepareImageOutbound(app.db, app.notifier, request.params.chatId, body);
+		const { message: msg, recipients } = await sendMessage(app.db, request.params.chatId, identity.uuid, prepared);
 		notifyRecipients(app.notifier, recipients, msg.id);
 		return reply.status(201).send({
 			...msg,
@@ -11385,7 +12085,7 @@ function isRecord(value) {
 }
 /** Extract unique @mentions from text. Returns lowercase usernames.
 * Excludes email patterns (user@example.com) and team mentions (@org/team). */
-function extractMentions(text) {
+function extractMentions$1(text) {
 	if (!text) return [];
 	const re = /(?<!\w)@([a-zA-Z0-9][\w-]*)(\/)?/g;
 	const names = /* @__PURE__ */ new Set();
@@ -11679,7 +12379,7 @@ function extractEventContext(eventType, payload) {
 * Only called after action gating confirms this is a "new content" event.
 */
 async function handleMentionDelegation(app, eventType, payload) {
-	const mentions = extractMentions(extractEventText(eventType, payload));
+	const mentions = extractMentions$1(extractEventText(eventType, payload));
 	const mentionCtx = extractEventContext(eventType, payload);
 	if (mentions.length > 0 && mentionCtx) return routeMentionDelegations(app, mentions, mentionCtx);
 	return 0;
@@ -13726,4 +14426,4 @@ function createExecuteUpdate({ managed }) {
 	};
 }
 //#endregion
-export { checkServerHealth as A, blank as B, runMigrations as C, checkDocker as D, checkDatabase as E, isDockerAvailable as F, SdkError as G, setJsonMode as H, stopPostgres as I, applyClientLoggerConfig as J, SessionRegistry as K, ClientRuntime as L, checkWebSocket as M, printResults as N, checkNodeVersion as O, ensurePostgres as P, createOwner as R, uninstallClientService as S, checkClientConfig as T, status as U, print as V, FirstTreeHubSDK as W, configureClientLoggerForService as Y, runHomeMigration as _, showServiceLogs as a, isServiceSupported as b, COMMAND_VERSION as c, promptMissingFields as d, formatCheckReport as f, saveOnboardState as g, onboardCreate as h, parseDuration as i, checkServerReachable as j, checkServerConfig as k, isInteractive as l, onboardCheck as m, declineUpdate as n, validateLevel as o, loadOnboardState as p, cleanWorkspaces as q, promptUpdate as r, startServer as s, createExecuteUpdate as t, promptAddAgent as u, getClientServiceStatus as v, checkAgentConfigs as w, resolveCliInvocation as x, installClientService as y, hasUser as z };
+export { checkServerHealth as A, resolveReplyToFromEnv as B, runMigrations as C, checkDocker as D, checkDatabase as E, isDockerAvailable as F, FirstTreeHubSDK as G, print as H, stopPostgres as I, cleanWorkspaces as J, SdkError as K, ClientRuntime as L, checkWebSocket as M, printResults as N, checkNodeVersion as O, ensurePostgres as P, createOwner as R, uninstallClientService as S, checkClientConfig as T, setJsonMode as U, blank as V, status as W, configureClientLoggerForService as X, applyClientLoggerConfig as Y, runHomeMigration as _, showServiceLogs as a, isServiceSupported as b, COMMAND_VERSION as c, promptMissingFields as d, formatCheckReport as f, saveOnboardState as g, onboardCreate as h, parseDuration as i, checkServerReachable as j, checkServerConfig as k, isInteractive as l, onboardCheck as m, declineUpdate as n, validateLevel as o, loadOnboardState as p, SessionRegistry as q, promptUpdate as r, startServer as s, createExecuteUpdate as t, promptAddAgent as u, getClientServiceStatus as v, checkAgentConfigs as w, resolveCliInvocation as x, installClientService as y, hasUser as z };