@rivus/gateway 0.16.2 → 0.17.0

package/dist/bootstrap/herdr-feishu.js

@@ -0,0 +1,856 @@
+import { isAbsolute, join, resolve } from "node:path";
+import { Array as Array$1, Effect, Schema } from "effect";
+import { lstat, mkdir, open, readFile, readdir, unlink } from "node:fs/promises";
+import { createHash, randomBytes, randomUUID } from "node:crypto";
+import { createConnection } from "node:net";
+import { Client, EventDispatcher, LoggerLevel, WSClient } from "@larksuiteoapi/node-sdk";
+import { stripVTControlCharacters } from "node:util";
+//#region src/core/application/terminal-session/terminal-session-bridge.ts
+function createTerminalSessionBridge(options) {
+	if (!options.actors.length || !options.chats.length) throw new Error("Explicit actor and chat allowlists required");
+	const bindings = /* @__PURE__ */ new Map();
+	const watches = /* @__PURE__ */ new Map();
+	const allowed = (actor, chat) => options.actors.includes(actor) && options.chats.includes(chat);
+	const bindingFor = (handle, message, refresh = false) => {
+		const binding = bindings.get(handle);
+		if (!binding || binding.expires + (refresh ? 18e5 : 0) <= options.now() || binding.actorId !== message.actorId || binding.chatId !== message.chatId) throw new Error("Target expired; run /herdr list again");
+		return binding;
+	};
+	const reply = (message, text) => ({
+		chatId: message.chatId,
+		text
+	});
+	const watchKey = (message, agent) => JSON.stringify([
+		message.actorId,
+		message.chatId,
+		agent.session,
+		agent.pane,
+		agent.identity
+	]);
+	const bind = (message, agent, form = false) => {
+		for (const [handle, binding] of bindings) if (binding.expires + 18e5 <= options.now()) bindings.delete(handle);
+		if (bindings.size >= 1e3) bindings.clear();
+		const handle = options.newHandle();
+		bindings.set(handle, {
+			agent,
+			actorId: message.actorId,
+			chatId: message.chatId,
+			form,
+			expires: options.now() + 6e5
+		});
+		return handle;
+	};
+	const detail = (message, agent, handle, text) => ({
+		chatId: message.chatId,
+		text: `${agent.session} / ${agent.name} | ${agent.status}\n${text}`,
+		menu: {
+			kind: "detail",
+			agents: [{
+				...agent,
+				handle
+			}],
+			writable: options.writable,
+			notice: text
+		}
+	});
+	const recovery = (message) => {
+		const handle = message.text.trim().split(/\s+/)[2] ?? "";
+		let agents = [];
+		try {
+			agents = [{
+				...bindingFor(handle, message, true).agent,
+				handle
+			}];
+		} catch {}
+		return {
+			...reply(message, "会话已过期、离线或目标已变化（target changed）。刷新原会话不会重发指令；目标已替换时请重新选择。"),
+			menu: {
+				kind: "recovery",
+				writable: false,
+				agents
+			}
+		};
+	};
+	const execute = (message) => Effect.gen(function* () {
+		const match = /^\/herdr(?:\s+(\S+))?(?:\s+([\s\S]*))?$/.exec(message.text.trim());
+		if (!match) return null;
+		const command = match[1] ?? "help";
+		const argument = match[2]?.trim() ?? "";
+		if (command === "list" || command === "menu") {
+			const { agents, unavailableSessions } = yield* options.sessions.list();
+			const page = Math.max(0, Math.min(Math.floor(Number(argument) || 0), Math.max(0, Math.ceil(agents.length / 20) - 1)));
+			const choices = (command === "menu" ? agents.slice(page * 20, (page + 1) * 20) : agents).map((agent) => ({
+				...agent,
+				handle: bind(message, agent)
+			}));
+			const warning = unavailableSessions.length ? `\nUnavailable sessions: ${unavailableSessions.join(", ")}; inventory is incomplete.` : "";
+			const lines = choices.map((agent) => `${agent.handle} | ${agent.session} | ${agent.name} | ${agent.status}`);
+			return {
+				...reply(message, `${new Date(options.now()).toISOString()}\n${lines.join("\n") || "No panels"}${warning}`),
+				...command === "menu" ? { menu: {
+					kind: "list",
+					agents: choices,
+					unavailableSessions,
+					page,
+					pages: Math.max(1, Math.ceil(agents.length / 20)),
+					writable: options.writable
+				} } : {}
+			};
+		}
+		if (command === "help") return reply(message, "/herdr menu\n/herdr list\n/herdr read HANDLE\n/herdr screen HANDLE\n/herdr send HANDLE -- TEXT\n/herdr watch HANDLE\n/herdr unwatch HANDLE");
+		const parts = ["send", "submit"].includes(command) ? /^(\S+)\s+--\s+([\s\S]+)$/.exec(argument) : null;
+		const handle = parts?.[1] ?? argument;
+		const binding = yield* Effect.try(() => bindingFor(handle, message, command === "refresh" || command === "unwatch"));
+		if (command === "unwatch") {
+			const removed = watches.delete(watchKey(message, binding.agent));
+			return detail(message, binding.agent, handle, removed ? "已取消关注；agent 仍在运行。" : "当前没有关注此会话。");
+		}
+		if (command === "open" || command === "compose" || command === "refresh") {
+			const current = yield* options.sessions.inspect(binding.agent);
+			if (command === "compose" && (!options.writable || current.kind !== "agent" || !current.ready || !["idle", "done"].includes(current.status))) return detail(message, current, handle, "当前不可发送指令，请先查看输出或刷新状态。");
+			const selected = command === "open" ? handle : bind(message, current, command === "compose");
+			return {
+				...reply(message, `${current.name} | ${current.status}`),
+				menu: {
+					kind: command === "compose" ? "form" : "detail",
+					agents: [{
+						...current,
+						handle: selected
+					}],
+					writable: options.writable
+				}
+			};
+		}
+		if (command === "read" || command === "screen") {
+			const read = yield* options.sessions.read(binding.agent, command === "screen");
+			const title = `${handle} | ${binding.agent.name}`;
+			const at = options.now();
+			return command === "screen" ? {
+				...reply(message, `${title} — terminal text rendering`),
+				screen: {
+					title,
+					at,
+					...read
+				}
+			} : reply(message, `${title} | ${new Date(at).toISOString()}${read.truncated || read.text.length > 12e3 ? " | truncated（已截断）" : ""}\n${read.text.slice(-12e3)}`);
+		}
+		if (command === "send" || command === "submit") {
+			if (command === "submit") {
+				if (!binding.form || !(yield* options.claim({
+					...message,
+					id: `form:${handle}`
+				}))) return detail(message, binding.agent, handle, "此表单已提交或失效，请查看输出；新指令请重新打开输入框。");
+			}
+			if (!options.writable) return reply(message, "Terminal input is disabled for this deployment.");
+			const text = parts?.[2];
+			if (!text?.trim() || text.length > (command === "submit" ? 1e3 : 8e3) || Array.from(text).some((char) => {
+				const code = char.charCodeAt(0);
+				return code < 32 && code !== 9 && code !== 10 || code === 127;
+			})) return reply(message, "Use /herdr send HANDLE -- TEXT (1–8000 characters, no terminal control characters).");
+			const current = yield* options.sessions.inspect(binding.agent);
+			if (current.kind !== "agent" || !current.ready || !["idle", "done"].includes(current.status)) return detail(message, current, handle, `Input rejected: agent is ${current.status} or not ready. 请刷新状态后重新打开输入框。`);
+			return yield* options.sessions.prompt(binding.agent, text).pipe(Effect.as(detail(message, {
+				...current,
+				ready: false
+			}, handle, "指令已提交一次；尚未确认 agent 已处理或完成，请查看输出。")), Effect.catchAll(() => Effect.succeed(detail(message, {
+				...current,
+				ready: false
+			}, handle, "提交结果不确定（uncertain），不会自动重试。请先查看输出，确认后再发送新指令。"))));
+		}
+		if (command === "watch") {
+			for (const [key, watch] of watches) if (watch.expires <= options.now()) watches.delete(key);
+			const key = watchKey(message, binding.agent);
+			if (!watches.has(key) && watches.size >= 8) return detail(message, binding.agent, handle, "已达到 8 个关注目标，请先取消其他关注。");
+			const current = yield* options.sessions.inspect(binding.agent);
+			watches.set(key, {
+				chatId: message.chatId,
+				actorId: message.actorId,
+				binding,
+				expires: options.now() + 6e5,
+				status: current.status
+			});
+			return detail(message, current, handle, "已关注此会话 10 分钟；重复关注会续期，不增加名额。");
+		}
+		return reply(message, "Unknown command; use /herdr help.");
+	});
+	return {
+		handle: (message) => Effect.gen(function* () {
+			if (!allowed(message.actorId, message.chatId) || !message.text.trim().startsWith("/herdr")) return null;
+			const age = options.now() - message.sentAt;
+			if (!Number.isFinite(age) || age < -3e4 || age > 12e4) return null;
+			if (!(yield* options.claim(message))) return null;
+			return yield* execute(message).pipe(Effect.catchAll(() => Effect.succeed(recovery(message))));
+		}),
+		tick: () => Effect.gen(function* () {
+			const results = [];
+			for (const [key, watch] of watches) {
+				if (watch.expires <= options.now() || !allowed(watch.actorId, watch.chatId)) {
+					watches.delete(key);
+					continue;
+				}
+				const current = yield* options.sessions.inspect(watch.binding.agent).pipe(Effect.map((agent) => agent.status), Effect.catchAll(() => Effect.succeed("unavailable")));
+				if (current === watch.status) continue;
+				const handle = bind(watch, watch.binding.agent);
+				results.push({
+					reply: detail(watch, {
+						...watch.binding.agent,
+						status: current,
+						ready: false
+					}, handle, `状态有变化 · ${new Date(options.now()).toISOString()}。这是观察结果，不代表任务成功；操作前请刷新状态。`),
+					acknowledge: () => {
+						if (watches.get(key) === watch) watch.status = current;
+					}
+				});
+			}
+			return results;
+		})
+	};
+}
+//#endregion
+//#region src/adapters/herdr/session/herdr-socket-client.ts
+function createHerdrSocketClient(sessions, timeoutMs = 5e3, discoverSessionsIn) {
+	if (!sessions.length && !discoverSessionsIn || new Set(sessions.map((s) => s.name)).size !== sessions.length) throw new Error("Herdr requires unique configured session names");
+	if (discoverSessionsIn && !isAbsolute(discoverSessionsIn)) throw new Error("Herdr discovery root must be absolute");
+	let configs = new Map(sessions.map((session) => [session.name, session]));
+	const refresh = () => Effect.tryPromise({
+		try: async () => {
+			const discovered = discoverSessionsIn ? await discoverSessions(discoverSessionsIn) : [];
+			const next = /* @__PURE__ */ new Map();
+			const paths = /* @__PURE__ */ new Set();
+			for (const config of [...sessions, ...discovered]) {
+				const path = resolve(config.socketPath);
+				if (paths.has(path)) continue;
+				if (next.has(config.name)) throw new Error("Herdr session aliases collide");
+				next.set(config.name, {
+					...config,
+					socketPath: path
+				});
+				paths.add(path);
+			}
+			configs = next;
+			return [...next.keys()];
+		},
+		catch: (error) => error
+	});
+	const invoke = (session, method, params) => Effect.tryPromise({
+		try: async (signal) => {
+			const config = configs.get(session);
+			if (!config) throw new Error("Unknown Herdr session");
+			const socket = await lstat(config.socketPath);
+			if (!socket.isSocket() || (socket.mode & 63) !== 0 || socket.uid !== process.getuid?.()) throw new Error("Herdr socket must be private and owned by the current user");
+			return {
+				result: await request(config.socketPath, method, params, timeoutMs, signal),
+				generation: `${socket.dev}:${socket.ino}:${socket.birthtimeMs}`
+			};
+		},
+		catch: (error) => error
+	});
+	const listSession = (session) => invoke(session, "session.snapshot", {}).pipe(Effect.flatMap(({ result, generation }) => Effect.try(() => {
+		const snapshot = object(result.snapshot);
+		if (snapshot.protocol !== 22 || !Array.isArray(snapshot.panes) || !Array.isArray(snapshot.agents)) throw new Error("Herdr protocol 22 session snapshot required");
+		const agents = snapshot.agents.map(object);
+		const labels = (values, key) => new Map((Array.isArray(values) ? values : []).map((item) => {
+			const entry = object(item);
+			return [string(entry[key]), string(entry.label)];
+		}));
+		const workspaces = labels(snapshot.workspaces, "workspace_id");
+		const tabs = labels(snapshot.tabs, "tab_id");
+		return snapshot.panes.map((entry) => {
+			const value = object(entry);
+			const pane = string(value.pane_id);
+			const terminal = string(value.terminal_id);
+			const agent = agents.find((item) => item.pane_id === pane && item.terminal_id === terminal);
+			const kind = typeof value.agent === "string" && value.agent ? value.agent : "terminal";
+			const workspace = string(value.workspace_id);
+			const tab = string(value.tab_id);
+			const title = [
+				agent?.name,
+				value.label,
+				value.terminal_title_stripped,
+				value.title
+			].find((item) => typeof item === "string" && item.length > 0) ?? kind;
+			return {
+				session,
+				pane,
+				identity: createHash("sha256").update(JSON.stringify([
+					generation,
+					session,
+					pane,
+					terminal,
+					kind,
+					value.agent_session ?? null
+				])).digest("hex"),
+				kind: kind === "terminal" ? "terminal" : "agent",
+				name: `${pane} / ${workspaces.get(workspace) ?? workspace} / ${tabs.get(tab) ?? tab} / ${title}`,
+				workspace: workspaces.get(workspace) ?? workspace,
+				tab: tabs.get(tab) ?? tab,
+				title,
+				status: string(value.agent_status),
+				ready: kind !== "terminal" && agent?.interactive_ready === true
+			};
+		});
+	})));
+	const resolve$1 = (agent) => listSession(agent.session).pipe(Effect.flatMap((agents) => {
+		const current = agents.find((item) => item.pane === agent.pane && item.identity === agent.identity);
+		return current ? Effect.succeed(current) : Effect.fail(/* @__PURE__ */ new Error("Target changed; list agents again"));
+	}));
+	return {
+		list: () => refresh().pipe(Effect.flatMap((names) => Effect.all(names.map((name) => listSession(name).pipe(Effect.map((agents) => ({
+			agents,
+			unavailableSessions: []
+		})), Effect.catchAll(() => Effect.succeed({
+			agents: [],
+			unavailableSessions: [name]
+		})))), { concurrency: 4 })), Effect.map((results) => ({
+			agents: results.flatMap((result) => result.agents),
+			unavailableSessions: results.flatMap((result) => result.unavailableSessions)
+		}))),
+		inspect: resolve$1,
+		read: (agent, visible) => resolve$1(agent).pipe(Effect.flatMap(() => invoke(agent.session, "pane.read", {
+			pane_id: agent.pane,
+			source: visible ? "visible" : "recent_unwrapped",
+			format: "text",
+			lines: visible ? 80 : 120
+		})), Effect.flatMap(({ result }) => Effect.try(() => {
+			const read = object(result.read);
+			return {
+				text: string(read.text),
+				truncated: read.truncated === true
+			};
+		}))),
+		prompt: (agent, text) => resolve$1(agent).pipe(Effect.flatMap((current) => {
+			if (current.kind !== "agent" || !current.ready || !["idle", "done"].includes(current.status)) return Effect.fail(/* @__PURE__ */ new Error("Agent is not ready for a prompt"));
+			return invoke(agent.session, "agent.prompt", {
+				target: agent.pane,
+				text
+			}).pipe(Effect.asVoid);
+		}))
+	};
+}
+async function discoverSessions(root) {
+	const directory = await lstat(root);
+	if (!directory.isDirectory() || directory.uid !== process.getuid?.() || (directory.mode & 18) !== 0) throw new Error("Herdr discovery root must be an owned, non-writable directory");
+	const candidates = [{
+		name: "default",
+		socketPath: join(root, "herdr.sock")
+	}];
+	const named = join(root, "sessions");
+	const info = await lstat(named).catch((error) => {
+		if (error.code === "ENOENT") return null;
+		throw error;
+	});
+	if (info) {
+		if (!info.isDirectory() || info.uid !== process.getuid?.() || (info.mode & 18) !== 0) throw new Error("Invalid Herdr sessions directory");
+		for (const entry of (await readdir(named, { withFileTypes: true })).sort((a, b) => a.name.localeCompare(b.name))) if (entry.isDirectory()) candidates.push({
+			name: entry.name,
+			socketPath: join(named, entry.name, "herdr.sock")
+		});
+	}
+	const found = [];
+	for (const candidate of candidates) if (await lstat(candidate.socketPath).catch((error) => {
+		if (error.code === "ENOENT") return null;
+		throw error;
+	})) found.push(candidate);
+	return found;
+}
+function object(value) {
+	if (!value || typeof value !== "object" || Array.isArray(value)) throw new Error("Invalid Herdr response");
+	return value;
+}
+function string(value) {
+	if (typeof value !== "string") throw new Error("Invalid Herdr response field");
+	return value;
+}
+function request(path, method, params, timeoutMs, signal) {
+	return new Promise((resolve, reject) => {
+		const id = randomUUID();
+		const socket = createConnection({ path });
+		let settled = false;
+		let bytes = 0;
+		let buffer = "";
+		const finish = (error, result) => {
+			if (settled) return;
+			settled = true;
+			clearTimeout(timer);
+			signal.removeEventListener("abort", abort);
+			socket.destroy();
+			if (error) reject(error);
+			else resolve(result);
+		};
+		const abort = () => finish(/* @__PURE__ */ new Error("Herdr request aborted; input may have been submitted"));
+		const timer = setTimeout(() => finish(/* @__PURE__ */ new Error("Herdr request timed out; input may have been submitted")), timeoutMs);
+		signal.addEventListener("abort", abort, { once: true });
+		socket.setEncoding("utf8");
+		socket.on("connect", () => socket.write(`${JSON.stringify({
+			id,
+			method,
+			params
+		})}\n`));
+		socket.on("error", (error) => finish(error));
+		socket.on("end", () => finish(/* @__PURE__ */ new Error("Herdr closed without a response; outcome unknown")));
+		socket.on("data", (chunk) => {
+			bytes += Buffer.byteLength(chunk);
+			if (bytes > 1048576) return finish(/* @__PURE__ */ new Error("Herdr response exceeds one MiB"));
+			buffer += chunk;
+			const newline = buffer.indexOf("\n");
+			if (newline < 0) return;
+			try {
+				const response = object(JSON.parse(buffer.slice(0, newline)));
+				if (response.id !== id) throw new Error("Herdr response identity mismatch");
+				if (response.error) throw new Error(`Herdr error: ${string(object(response.error).code)}`);
+				finish(void 0, object(response.result));
+			} catch (error) {
+				finish(error);
+			}
+		});
+		if (signal.aborted) abort();
+	});
+}
+//#endregion
+//#region src/adapters/herdr/rendering/terminal-text-image.ts
+async function renderTerminalTextImage(screen, fontFiles) {
+	const { renderAsync } = await import("@resvg/resvg-js");
+	const allLines = stripVTControlCharacters(screen.text).replace(/[^\P{Cc}\n\t]/gu, "").split("\n");
+	const expanded = allLines.map((line) => Array.from(line.replaceAll("	", "    ")));
+	const lines = expanded.slice(0, 80).map((line) => line.slice(0, 90).join(""));
+	const clipped = screen.truncated || allLines.length > 80 || expanded.some((line) => line.length > 90);
+	const title = Array.from(stripVTControlCharacters(screen.title).replace(/\p{Cc}/gu, "")).slice(0, 90).join("");
+	const width = 1800;
+	const height = 100 + Math.max(1, lines.length) * 24;
+	const label = `Terminal text rendering | ${new Date(screen.at).toISOString()}${clipped ? " | truncated" : ""}`;
+	const body = lines.map((line, i) => `<text x="24" y="${96 + i * 24}">${escapeXml(line)}</text>`).join("");
+	return (await renderAsync(`<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}"><rect width="100%" height="100%" fill="#101827"/><g fill="#e5e7eb" font-family="monospace" font-size="18" xml:space="preserve"><text x="24" y="30">${escapeXml(title)}</text><text x="24" y="58" fill="#94a3b8">${escapeXml(label)}</text>${body}</g></svg>`, { font: {
+		loadSystemFonts: !fontFiles?.length,
+		...fontFiles ? { fontFiles: [...fontFiles] } : {},
+		defaultFontFamily: "monospace"
+	} })).asPng();
+}
+function escapeXml(text) {
+	return text.replace(/[&<>"']/g, (char) => ({
+		"&": "&amp;",
+		"<": "&lt;",
+		">": "&gt;",
+		"\"": "&quot;",
+		"'": "&apos;"
+	})[char]);
+}
+//#endregion
+//#region src/adapters/outbound/persistence/terminal-session/terminal-message-claims.ts
+async function openTerminalMessageClaims(directory, appId) {
+	await mkdir(directory, {
+		recursive: true,
+		mode: 448
+	});
+	const lockPath = join(directory, "bridge.lock");
+	const lock = await open(lockPath, "wx", 384);
+	await lock.writeFile(JSON.stringify({
+		pid: process.pid,
+		appId
+	}));
+	const claims = join(directory, "claims");
+	try {
+		await mkdir(claims, {
+			recursive: true,
+			mode: 448
+		});
+	} catch (error) {
+		await lock.close();
+		await unlink(lockPath);
+		throw error;
+	}
+	return {
+		claim: (message) => Effect.tryPromise({
+			try: async () => {
+				const digest = createHash("sha256").update(JSON.stringify([appId, message.id])).digest("hex");
+				let file;
+				try {
+					file = await open(join(claims, digest), "wx", 384);
+				} catch (error) {
+					if (error.code === "EEXIST") return false;
+					throw error;
+				}
+				try {
+					await file.writeFile(JSON.stringify({
+						state: "claimed",
+						at: Date.now()
+					}));
+					await file.sync();
+					const folder = await open(claims, "r");
+					try {
+						await folder.sync();
+					} finally {
+						await folder.close();
+					}
+					return true;
+				} finally {
+					await file.close();
+				}
+			},
+			catch: (error) => error
+		}),
+		close: async () => {
+			await lock.close();
+			if (JSON.parse(await readFile(lockPath, "utf8")).pid === process.pid) await unlink(lockPath);
+		}
+	};
+}
+//#endregion
+//#region src/adapters/feishu/terminal-session/feishu-terminal-session.ts
+function parseFeishuTerminalMessage(event) {
+	if (!event || typeof event !== "object") return null;
+	const value = event;
+	const message = value.message;
+	if (value.sender?.sender_type !== "user" || !value.sender.sender_id?.open_id || !message?.message_id || !message.chat_id || message.message_type !== "text") return null;
+	try {
+		const content = JSON.parse(message.content ?? "{}");
+		if (!content || typeof content !== "object" || !("text" in content) || typeof content.text !== "string") return null;
+		return {
+			id: message.message_id,
+			actorId: value.sender.sender_id.open_id,
+			chatId: message.chat_id,
+			sentAt: Number(message.create_time),
+			text: content.text.replace(/^@_user_\d+\s*/, "")
+		};
+	} catch {
+		return null;
+	}
+}
+async function deliverTerminalBridgeReply(reply, delivery, render) {
+	if (reply.menu && delivery.sendCard) return delivery.sendCard(reply.chatId, renderTerminalMenu({
+		...reply.menu,
+		...reply.menu.kind === "recovery" ? { notice: reply.text } : {}
+	}));
+	if (!reply.screen) return delivery.sendText(reply.chatId, reply.text);
+	try {
+		await delivery.sendImage(reply.chatId, await render(reply.screen));
+	} catch {
+		await delivery.sendText(reply.chatId, `${reply.text} | ${new Date(reply.screen.at).toISOString()}${reply.screen.truncated || reply.screen.text.length > 12e3 ? " | truncated（已截断）" : ""}\n图片暂不可用，以下是终端文字：\n${reply.screen.text.slice(-12e3)}`);
+	}
+}
+function parseFeishuTerminalAction(event, menuChats) {
+	if (!event || typeof event !== "object") return null;
+	const value = event;
+	const actorId = value.operator?.open_id ?? value.operator?.operator_id?.open_id;
+	if (!actorId || !value.event_id || !value.create_time) return null;
+	let text;
+	let chatId;
+	if (value.event_key) {
+		if (!["herdr_list", "herdr_help"].includes(value.event_key)) return null;
+		chatId = menuChats[actorId];
+		text = value.event_key === "herdr_list" ? "/herdr menu" : "/herdr help";
+	} else {
+		chatId = value.context?.open_chat_id;
+		const action = value.action;
+		if (action?.tag !== "button") return null;
+		const form = /^herdr_submit_([a-f0-9]{12})$/.exec(action.name ?? "");
+		if (form) {
+			if (typeof action.form_value?.prompt !== "string") return null;
+			text = `/herdr submit ${form[1]} -- ${action.form_value.prompt}`;
+		} else {
+			const command = action.value?.command;
+			if (command === "menu") {
+				const page = action.value?.page ?? 0;
+				if (!Number.isSafeInteger(page) || page < 0) return null;
+				text = `/herdr menu ${page}`;
+			} else {
+				if (!command || ![
+					"open",
+					"refresh",
+					"compose",
+					"read",
+					"screen",
+					"watch",
+					"unwatch"
+				].includes(command)) return null;
+				const handle = action.value?.handle;
+				if (typeof handle !== "string" || !/^[a-f0-9]{12}$/.test(handle)) return null;
+				text = `/herdr ${command} ${handle}`;
+			}
+		}
+	}
+	return chatId ? {
+		id: `action:${value.event_id}`,
+		actorId,
+		chatId,
+		sentAt: Number(value.create_time) / (value.event_key ? 1 : 1e3),
+		text
+	} : null;
+}
+function renderTerminalMenu(menu) {
+	const plain = (content) => ({
+		tag: "plain_text",
+		content
+	});
+	const button = (label, command, handle, page) => ({
+		tag: "button",
+		text: plain(label),
+		type: "default",
+		behaviors: [{
+			type: "callback",
+			value: {
+				command,
+				handle,
+				page
+			}
+		}]
+	});
+	const status = (agent) => {
+		if (agent.status === "unavailable") return "离线／暂不可用";
+		if (agent.kind === "terminal") return "终端只读";
+		if (agent.ready && ["idle", "done"].includes(agent.status)) return "等待输入";
+		return {
+			working: "执行中",
+			blocked: "等待处理",
+			idle: "空闲，尚未确认可输入",
+			done: "运行已结束，请刷新确认",
+			unknown: "状态未知"
+		}[agent.status] ?? "暂不可输入";
+	};
+	const elements = [];
+	if (menu.notice) elements.push({
+		tag: "div",
+		text: plain(menu.notice)
+	});
+	if (menu.kind === "list") {
+		elements.push({
+			tag: "markdown",
+			content: `**选择会话** · 第 ${(menu.page ?? 0) + 1}/${menu.pages ?? 1} 页`
+		});
+		const groups = Array$1.groupBy(menu.agents, (agent) => `${agent.session} / ${agent.workspace ?? "会话"}`);
+		for (const [group, agents] of Object.entries(groups)) {
+			elements.push({
+				tag: "div",
+				text: plain(group)
+			});
+			for (const agent of agents) elements.push(button(`${agent.pane} · ${agent.tab ? agent.tab + " / " : ""}${agent.title ?? agent.name} · ${status(agent)}`.slice(0, 100), "open", agent.handle));
+		}
+		if (menu.unavailableSessions?.length) elements.push({
+			tag: "div",
+			text: plain(`以下 session 无法读取，列表不完整：${menu.unavailableSessions.join(", ")}`)
+		});
+		if (!menu.agents.length) elements.push({
+			tag: "markdown",
+			content: "当前没有可用会话。"
+		});
+		if ((menu.page ?? 0) > 0) elements.push(button("上一页", "menu", void 0, menu.page - 1));
+		if ((menu.page ?? 0) + 1 < (menu.pages ?? 1)) elements.push(button("下一页", "menu", void 0, menu.page + 1));
+	} else if (menu.kind === "recovery") {
+		if (menu.agents[0]) elements.push(button("刷新原会话", "refresh", menu.agents[0].handle));
+	} else {
+		const agent = menu.agents[0];
+		elements.push({
+			tag: "div",
+			text: plain(`目标：${agent.session} / ${agent.name}\n状态：${status(agent)}`)
+		});
+		if (menu.kind === "form") {
+			elements.push({
+				tag: "form",
+				name: "herdr_prompt",
+				elements: [{
+					tag: "input",
+					name: "prompt",
+					required: true,
+					input_type: "multiline_text",
+					max_length: 1e3,
+					placeholder: plain("输入要交给此 agent 的指令"),
+					label: plain("指令内容")
+				}, {
+					tag: "button",
+					name: `herdr_submit_${agent.handle}`,
+					text: plain("发送"),
+					type: "primary_filled",
+					form_action_type: "submit"
+				}]
+			});
+			elements.push({
+				tag: "markdown",
+				content: "每个表单只提交一次；提交后可通过“看输出”核对执行结果。"
+			});
+		} else {
+			if (menu.writable && agent.kind === "agent" && agent.ready && ["idle", "done"].includes(agent.status)) elements.push(button("发指令", "compose", agent.handle));
+			else elements.push({
+				tag: "div",
+				text: plain(menu.writable && agent.kind === "agent" ? "当前不可发送指令。请查看输出，或刷新状态后再试。" : "此会话为只读模式。")
+			});
+			elements.push(button("关注状态", "watch", agent.handle), button("取消关注", "unwatch", agent.handle));
+		}
+		elements.push(button("看画面", "screen", agent.handle), button("看输出", "read", agent.handle), button("刷新当前会话", "refresh", agent.handle));
+	}
+	elements.push(button("刷新会话列表", "menu"));
+	return {
+		schema: "2.0",
+		config: {
+			width_mode: "default",
+			enable_forward: false
+		},
+		header: {
+			title: plain(menu.kind === "form" ? "向会话发送指令" : "Herdr 会话"),
+			template: "blue"
+		},
+		body: { elements }
+	};
+}
+function createFeishuTerminalDelivery(client) {
+	return {
+		sendCard: async (chatId, card) => {
+			if ((await client.im.message.create({
+				params: { receive_id_type: "chat_id" },
+				data: {
+					receive_id: chatId,
+					msg_type: "interactive",
+					content: JSON.stringify(card)
+				}
+			})).code !== 0) throw new Error("Feishu card delivery failed");
+		},
+		sendText: async (chatId, text) => {
+			if ((await client.im.message.create({
+				params: { receive_id_type: "chat_id" },
+				data: {
+					receive_id: chatId,
+					msg_type: "text",
+					content: JSON.stringify({ text })
+				}
+			})).code !== 0) throw new Error("Feishu text delivery failed");
+		},
+		sendImage: async (chatId, bytes) => {
+			const value = await client.im.image.create({ data: {
+				image_type: "message",
+				image: Buffer.from(bytes)
+			} });
+			const imageKey = value?.image_key ?? value?.data?.image_key;
+			if (!imageKey) throw new Error("Feishu image upload failed");
+			if ((await client.im.message.create({
+				params: { receive_id_type: "chat_id" },
+				data: {
+					receive_id: chatId,
+					msg_type: "image",
+					content: JSON.stringify({ image_key: imageKey })
+				}
+			})).code !== 0) throw new Error("Feishu image delivery failed");
+		}
+	};
+}
+//#endregion
+//#region src/bootstrap/herdr-feishu.ts
+const configSchema = Schema.Struct({
+	appId: Schema.NonEmptyTrimmedString,
+	appSecret: Schema.NonEmptyTrimmedString,
+	sessions: Schema.optional(Schema.Array(Schema.Struct({
+		name: Schema.NonEmptyTrimmedString,
+		socketPath: Schema.String.pipe(Schema.filter(isAbsolute))
+	}))),
+	discoverSessionsIn: Schema.optional(Schema.String.pipe(Schema.filter(isAbsolute))),
+	allowedActors: Schema.NonEmptyArray(Schema.NonEmptyTrimmedString),
+	allowedChats: Schema.NonEmptyArray(Schema.NonEmptyTrimmedString),
+	menuChats: Schema.optional(Schema.Record({
+		key: Schema.String,
+		value: Schema.NonEmptyTrimmedString
+	})),
+	stateDirectory: Schema.String.pipe(Schema.filter(isAbsolute)),
+	writable: Schema.optional(Schema.Boolean),
+	fontFiles: Schema.optional(Schema.Array(Schema.String.pipe(Schema.filter(isAbsolute))))
+});
+function configuredSessions(options) {
+	if (!Schema.is(configSchema)(options)) throw new Error("Invalid bridge configuration: check credentials, nonempty actor/chat lists, absolute paths and option types");
+	for (const [actor, chat] of Object.entries(options.menuChats ?? {})) if (!options.allowedActors.includes(actor) || !options.allowedChats.includes(chat)) throw new Error("Menu destinations must be allowlisted");
+	return createHerdrSocketClient(options.sessions ?? [], 5e3, options.discoverSessionsIn);
+}
+async function checkHerdrFeishuBridge(options) {
+	const inventory = await Effect.runPromise(configuredSessions(options).list());
+	return {
+		panels: inventory.agents.length,
+		sessionsWithPanels: new Set(inventory.agents.map((agent) => agent.session)).size,
+		unavailableSessions: inventory.unavailableSessions,
+		writable: options.writable === true,
+		feishuVerified: false
+	};
+}
+async function startHerdrFeishuBridge(options) {
+	const sessions = configuredSessions(options);
+	const claims = await openTerminalMessageClaims(options.stateDirectory, options.appId);
+	const bridge = createTerminalSessionBridge({
+		sessions,
+		actors: options.allowedActors,
+		chats: options.allowedChats,
+		writable: options.writable === true,
+		now: Date.now,
+		newHandle: () => randomBytes(6).toString("hex"),
+		claim: claims.claim
+	});
+	const client = new Client({
+		appId: options.appId,
+		appSecret: options.appSecret,
+		loggerLevel: LoggerLevel.error
+	});
+	const ws = new WSClient({
+		appId: options.appId,
+		appSecret: options.appSecret,
+		loggerLevel: LoggerLevel.error
+	});
+	const delivery = createFeishuTerminalDelivery(client);
+	let stopped = false;
+	let pending = 0;
+	let tail = Promise.resolve();
+	const enqueue = (run) => {
+		if (stopped || pending >= 32) return false;
+		pending++;
+		tail = tail.then(run).catch(() => options.onObservation?.({ type: "operation_failed" })).finally(() => {
+			pending--;
+		});
+		return true;
+	};
+	const receive = async (message) => {
+		if (!message) return;
+		options.onObservation?.({
+			type: "received",
+			messageId: message.id
+		});
+		if (!enqueue(async () => {
+			const response = await Effect.runPromise(bridge.handle(message));
+			if (response) {
+				await deliverTerminalBridgeReply(response, delivery, (screen) => renderTerminalTextImage(screen, options.fontFiles));
+				options.onObservation?.({
+					type: "replied",
+					messageId: message.id
+				});
+			}
+		})) throw new Error("Herdr bridge queue is full or stopped");
+	};
+	const dispatcher = new EventDispatcher({}).register({
+		"im.message.receive_v1": (event) => receive(parseFeishuTerminalMessage(event)),
+		"application.bot.menu_v6": (event) => receive(parseFeishuTerminalAction(event, options.menuChats ?? {})),
+		"card.action.trigger": async (event) => {
+			await receive(parseFeishuTerminalAction(event, options.menuChats ?? {}));
+			return {};
+		}
+	});
+	try {
+		await ws.start({ eventDispatcher: dispatcher });
+	} catch (error) {
+		ws.close({ force: true });
+		await claims.close();
+		throw error;
+	}
+	const timer = setInterval(() => {
+		if (pending) return;
+		enqueue(async () => {
+			for (const notification of await Effect.runPromise(bridge.tick())) try {
+				await deliverTerminalBridgeReply(notification.reply, delivery, (screen) => renderTerminalTextImage(screen, options.fontFiles));
+				notification.acknowledge();
+			} catch {
+				options.onObservation?.({ type: "notification_failed" });
+			}
+		});
+	}, 5e3);
+	return { stop: async () => {
+		if (stopped) return;
+		stopped = true;
+		clearInterval(timer);
+		ws.close({ force: true });
+		await tail;
+		await claims.close();
+	} };
+}
+//#endregion
+export { checkHerdrFeishuBridge, startHerdrFeishuBridge };
+