@rynx-ai/plugin-channel-lark 0.1.9

package/dist/lark.js

@@ -0,0 +1,2010 @@
+import { execFile } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+import { CodexRuntimeError, collectLiveRun, } from "@rynx-ai/core";
+const execFileAsync = promisify(execFile);
+import { LarkSessionCardController, } from "./lark-card-stream.js";
+import { buildLarkCardReplyPrompt, chunkLarkReplyText, extractLarkTextPrompt, isLarkNewSessionCommand, isLarkStopCommand, parseLarkCommand, } from "./lark-content.js";
+import { deriveConversationShortId, MemoryLarkConversationDirectory, } from "./lark-conversation-directory.js";
+import { buildDiffCardJson } from "./lark-diff-card.js";
+import { buildForkTranscript } from "./lark-fork-transcript.js";
+import { buildChatApplink, buildOpenChatCardJson, buildResumeCardJson, } from "./lark-resume-card.js";
+import { LarkClientProvider, LarkSdkMessageSender } from "./lark-sender.js";
+import { buildSettingsCard, buildSettingsCardJson, buildSettingsResultCard, SETTINGS_DEFAULT_VALUE, SETTINGS_EFFORT_VALUES, } from "./lark-settings-card.js";
+import { getRuntimeProfile, isAgentRuntimeId, RUNTIME_PROFILES, } from "@rynx-ai/core";
+import { SteerController } from "@rynx-ai/core";
+import { toErrorMessage } from "@rynx-ai/core";
+import { findInnermostAllowedRoot } from "@rynx-ai/core";
+export { chunkLarkReplyText, extractLarkTextPrompt, isLarkNewSessionCommand, isLarkStopCommand, };
+export { LarkClientProvider, LarkSdkMessageSender };
+const DEFAULT_UNSUPPORTED_MESSAGE = "暂时只支持文本消息，请发送文本内容。";
+const DEFAULT_EMPTY_MESSAGE = "请发送文本内容。";
+const DEFAULT_EMPTY_RESPONSE = "抱歉，我暂时没有生成回复。";
+const DEFAULT_NEW_SESSION_RESPONSE = "已开启新会话。";
+const DEFAULT_STOP_NO_INFLIGHT_RESPONSE = "当前没有正在进行的任务。";
+const DEFAULT_STOP_ACK_RESPONSE = "已停止当前任务。";
+const LARK_WORK_STARTED_REACTION = "Get";
+const LARK_WORK_COMPLETED_REACTION = "DONE";
+/** Reaction added to a message whose text was steered into the running turn. */
+const LARK_STEER_ACK_REACTION = "Get";
+const LARK_COMMANDS = [
+    { name: "new", help: "/new — 开启新会话", category: "takeover" },
+    { name: "stop", help: "/stop 或 /cancel — 停止当前正在进行的任务", category: "other" },
+    { name: "runtime", help: "/runtime — 卡片切换运行时（codex/traex/claude）/ 模型 / 思考强度", category: "other" },
+    { name: "model", help: "/model — 卡片切换当前运行时的模型 / 思考强度", category: "other" },
+    { name: "agent", help: "/agent [名称] — 列出/切换声明式 agent（运行时+模型+提示+权限的预设）", category: "other" },
+    { name: "models", help: "/models — 列出当前运行时可用模型", category: "info" },
+    { name: "resume", help: "/resume [短id] — 列出最近会话/跳转或转发到指定会话", category: "takeover" },
+    { name: "fork", help: "/fork — 把当前会话 fork 到新群/新话题（带上下文+历史记录）", category: "takeover" },
+    { name: "cwd", help: "/cwd [目录] — 查看/绑定当前会话的工作目录（不存在则新建）", category: "takeover" },
+    { name: "goal", help: "/goal [目标|clear] — 查看/设置/清除当前会话目标", category: "action" },
+    { name: "diff", help: "/diff — 显示当前工作区 git 改动（含未跟踪文件）", category: "action" },
+    { name: "help", help: "/help — 显示本帮助", category: "info" },
+];
+function larkCommandNames(category) {
+    return new Set(LARK_COMMANDS.filter((c) => c.category === category).map((c) => c.name));
+}
+const LARK_TAKEOVER_COMMANDS = larkCommandNames("takeover");
+const LARK_INFO_COMMANDS = larkCommandNames("info");
+const LARK_ACTION_COMMANDS = larkCommandNames("action");
+const LARK_HELP_TEXT = ["可用命令：", ...LARK_COMMANDS.map((c) => c.help)].join("\n");
+const LARK_BACKEND_UNSUPPORTED = "当前后端不支持该命令（仅 app_server 后端可用）。";
+const LARK_NO_ACTIVE_SESSION = "请先发一条消息开始会话，再使用该命令。";
+const DIFF_REPLY_MAX_BYTES = 60 * 1024;
+/** Max diff body embedded in the `/diff` card (kept under Feishu's card size limit). */
+const DIFF_CARD_MAX_BYTES = 16 * 1024;
+const defaultLogger = {
+    log(entry) {
+        console.log(JSON.stringify({
+            level: "info",
+            type: "lark",
+            ...entry,
+        }));
+    },
+};
+/** Route SDK diagnostics through the runner logger instead of stdout, which is
+ * reserved for the NDJSON RPC transport in an out-of-process plugin. */
+function larkSdkLogger(logger) {
+    const write = (level, messages) => {
+        const text = messages
+            .map((message) => (message instanceof Error ? message.message : String(message)))
+            .join(" ")
+            .replace(/[A-Za-z0-9_-]{30,}/g, "***");
+        logger.log({ event: `sdk.${level}`, error: text });
+    };
+    return {
+        error: (...messages) => write("error", messages),
+        warn: (...messages) => write("warn", messages),
+        info: () => undefined,
+        debug: () => undefined,
+        trace: () => undefined,
+    };
+}
+export class LarkConversationKeyResolver {
+    resolve(event) {
+        const tenantKey = event.tenant_key ?? event.sender.tenant_key ?? "unknown-tenant";
+        const threadId = event.message.thread_id?.trim();
+        if (threadId) {
+            return `lark:${tenantKey}:thread:${threadId}`;
+        }
+        return `lark:${tenantKey}:chat:${event.message.chat_id}`;
+    }
+}
+export class PerThreadQueue {
+    tails = new Map();
+    enqueue(key, task) {
+        const previous = this.tails.get(key) ?? Promise.resolve();
+        const next = previous
+            .catch(() => undefined)
+            .then(task);
+        const tracked = next.finally(() => {
+            if (this.tails.get(key) === tracked) {
+                this.tails.delete(key);
+            }
+        });
+        this.tails.set(key, tracked);
+        return tracked;
+    }
+}
+export class LarkMessageDeduper {
+    ttlMs;
+    entries = new Map();
+    constructor(ttlMs = 60 * 60 * 1000) {
+        this.ttlMs = ttlMs;
+    }
+    markIfNew(messageId, now = Date.now()) {
+        this.prune(now);
+        const expiresAt = this.entries.get(messageId);
+        if (expiresAt && expiresAt > now) {
+            return false;
+        }
+        this.entries.set(messageId, now + this.ttlMs);
+        return true;
+    }
+    prune(now) {
+        for (const [messageId, expiresAt] of this.entries) {
+            if (expiresAt <= now) {
+                this.entries.delete(messageId);
+            }
+        }
+    }
+}
+/** One-line title for a session's registry row: collapse whitespace, trim, cap
+ *  at 60 chars + ellipsis. Empty prompt ⇒ undefined (no title). */
+function larkSessionTitle(prompt) {
+    const text = prompt.replace(/\s+/g, " ").trim();
+    if (!text)
+        return undefined;
+    return text.length <= 60 ? text : `${text.slice(0, 59)}…`;
+}
+/**
+ * Pull a model's supported reasoning efforts from a `model/list` entry,
+ * tolerating both the App Server camelCase (`supportedReasoningEfforts`) and the
+ * cache/snake (`supported_reasoning_levels`) spellings. Empty when unknown.
+ */
+function extractSupportedEfforts(model) {
+    const raw = model.supportedReasoningEfforts ??
+        model.supported_reasoning_levels ??
+        model.supportedReasoningLevels;
+    if (!Array.isArray(raw)) {
+        return [];
+    }
+    const efforts = [];
+    const seen = new Set();
+    for (const item of raw) {
+        const record = item && typeof item === "object" && !Array.isArray(item)
+            ? item
+            : undefined;
+        const effort = typeof item === "string"
+            ? item.trim()
+            : typeof record?.reasoningEffort === "string"
+                ? record.reasoningEffort.trim()
+                : typeof record?.effort === "string"
+                    ? record.effort.trim()
+                    : "";
+        if (!/^[a-zA-Z0-9_-]{1,64}$/.test(effort) || seen.has(effort))
+            continue;
+        seen.add(effort);
+        efforts.push(effort);
+    }
+    return efforts;
+}
+export class LarkMessageIngestor {
+    conversationRuntime;
+    messageSender;
+    /** Default runtime for this bot; per-conversation choices override it. */
+    provider;
+    /** Default declarative agent for this bot; per-conversation `/agent` overrides it. */
+    defaultAgent;
+    /** Host-backed agent catalog for `/agent` and execution freezing. */
+    agentCatalog;
+    /** Transient per-conversation settings-card selections, keyed by sessionKey. */
+    pendingSettings = new Map();
+    cwd;
+    activeSessionStore;
+    conversationKeyResolver;
+    deduper;
+    queue;
+    logger;
+    cardThrottleMs;
+    capabilities;
+    conversationDirectory;
+    allowedRoots;
+    botOpenId;
+    disableP2p;
+    groupAllowlistEnabled;
+    groupAllowlist;
+    mirror;
+    sessionTitleWriter;
+    sessionProvisioner;
+    inFlight = new Map();
+    constructor({ conversationRuntime, messageSender, cwd, defaultRuntime = "codex", defaultAgent, agentCatalog, activeSessionStore, conversationKeyResolver = new LarkConversationKeyResolver(), deduper = new LarkMessageDeduper(), queue = new PerThreadQueue(), logger = defaultLogger, cardThrottleMs = 250, capabilities, conversationDirectory = new MemoryLarkConversationDirectory(), allowedRoots = [], botOpenId = null, disableP2p = false, groupAllowlistEnabled = false, groupAllowlist = [], mirror, sessionTitleWriter, sessionProvisioner, }) {
+        this.conversationRuntime = conversationRuntime;
+        this.messageSender = messageSender;
+        this.provider = defaultRuntime;
+        this.defaultAgent = defaultAgent;
+        this.agentCatalog = agentCatalog;
+        this.cwd = cwd;
+        this.activeSessionStore = activeSessionStore;
+        this.conversationKeyResolver = conversationKeyResolver;
+        this.deduper = deduper;
+        this.queue = queue;
+        this.logger = logger;
+        this.cardThrottleMs = cardThrottleMs;
+        this.capabilities = capabilities;
+        this.conversationDirectory = conversationDirectory;
+        this.allowedRoots = allowedRoots;
+        this.botOpenId = botOpenId ?? null;
+        this.disableP2p = disableP2p;
+        this.groupAllowlistEnabled = groupAllowlistEnabled;
+        this.groupAllowlist = new Set(groupAllowlist);
+        this.mirror = mirror;
+        this.sessionTitleWriter = sessionTitleWriter;
+        this.sessionProvisioner = sessionProvisioner;
+    }
+    /** Best-effort title update for the daemon-owned machine-session record. */
+    registerSession(sessionId, prompt) {
+        const title = larkSessionTitle(prompt);
+        if (!this.sessionTitleWriter || !title)
+            return;
+        void this.sessionTitleWriter(sessionId, title).catch((error) => {
+            this.logger.log({
+                event: "session_meta.title_failed",
+                session_id: sessionId,
+                error: toErrorMessage(error),
+            });
+        });
+    }
+    /**
+     * Set this bot's own `open_id` once it has been resolved asynchronously
+     * (the runtime fetches it from the bot info API at startup).
+     */
+    setBotOpenId(openId) {
+        this.botOpenId = openId ?? null;
+    }
+    /** Whether a bridge-driven turn is currently running for `sessionKey`. The
+     *  CLI mirror reads this to skip turns already shown live in Feishu. */
+    isInFlight(sessionKey) {
+        return this.inFlight.has(sessionKey);
+    }
+    /**
+     * Whether a group message is addressed to *this* bot. With a known
+     * `botOpenId`, that means one of the `@`-mentions carries our `open_id` —
+     * so in a group hosting several bots, only the one actually mentioned runs.
+     * When `botOpenId` is unknown, fall back to "any mention" (legacy single-bot
+     * behavior) rather than going silent.
+     */
+    isAddressedToBot(event) {
+        const mentions = event.message.mentions ?? [];
+        if (!this.botOpenId) {
+            return mentions.length > 0;
+        }
+        return mentions.some((mention) => mention.id?.open_id === this.botOpenId);
+    }
+    /**
+     * Handle a Feishu CardKit button click. Supported actions:
+     * - `{ kind: "stop_turn", sessionKey }` — the in-card "停止" button.
+     * - `{ kind: "resume_forward", threadId, chatId }` — forward a topic thread
+     *   into `chatId` (from the `/resume` card).
+     * Anything else is logged and ignored.
+     */
+    async ingestCardAction(event) {
+        const value = event.value;
+        const kind = typeof value?.kind === "string" ? value.kind : null;
+        if (kind === "resume_forward") {
+            return this.handleResumeForwardAction(event);
+        }
+        if (kind === "settings_select") {
+            return this.handleSettingsSelect(event);
+        }
+        if (kind === "settings_apply") {
+            return this.handleSettingsApply(event);
+        }
+        if (kind === "settings_cancel") {
+            return this.handleSettingsCancel(event);
+        }
+        if (kind !== "stop_turn") {
+            this.logger.log({
+                event: "card.action.unknown",
+                kind,
+                message_id: event.messageId,
+            });
+            return {};
+        }
+        const sessionKey = typeof value?.sessionKey === "string" ? value.sessionKey : null;
+        if (!sessionKey) {
+            this.logger.log({
+                event: "card.action.missing_session_key",
+                message_id: event.messageId,
+            });
+            return {};
+        }
+        const aborted = this.interruptSession(sessionKey);
+        this.logger.log({
+            event: aborted ? "session.stopped" : "session.stop_noop",
+            message_id: event.messageId,
+            session_key: sessionKey,
+            provider: this.provider,
+            source: "card_button",
+        });
+        // No toast — the cancellation appears as a grey blockquote at the bottom
+        // of the card via the executor's CodexRuntimeError → finalize path.
+        return {};
+    }
+    async handleResumeForwardAction(event) {
+        const value = event.value;
+        const sourceThreadId = typeof value?.sourceThreadId === "string" ? value.sourceThreadId : null;
+        const targetChatId = typeof value?.targetChatId === "string" ? value.targetChatId : null;
+        const targetThreadId = typeof value?.targetThreadId === "string" ? value.targetThreadId : null;
+        if (!sourceThreadId || !this.messageSender.forwardThread) {
+            return { toast: { type: "error", content: "无法转发该话题。" } };
+        }
+        // Forward into the current thread when /resume was invoked inside one, so
+        // it lands in-place instead of spawning a new thread in the topic group.
+        const receiveIdType = targetThreadId ? "thread_id" : "chat_id";
+        const receiveId = targetThreadId ?? targetChatId;
+        if (!receiveId) {
+            return { toast: { type: "error", content: "无法转发该话题。" } };
+        }
+        try {
+            await this.messageSender.forwardThread({
+                threadId: sourceThreadId,
+                receiveId,
+                receiveIdType,
+                uuid: randomUUID(),
+            });
+            this.logger.log({
+                event: "resume.forwarded",
+                message_id: event.messageId,
+                thread_id: sourceThreadId,
+                chat_id: receiveId,
+            });
+            return { toast: { type: "success", content: "已转发到当前会话" } };
+        }
+        catch (error) {
+            return { toast: { type: "error", content: `转发失败：${toErrorMessage(error)}` } };
+        }
+    }
+    /** Where a forward should land for the conversation `event` arrived in:
+     *  inside the current topic thread when present, else the chat. */
+    forwardTargetOf(event) {
+        if (event.message.thread_id) {
+            return { receiveId: event.message.thread_id, receiveIdType: "thread_id" };
+        }
+        return { receiveId: event.message.chat_id, receiveIdType: "chat_id" };
+    }
+    /**
+     * Cancel the in-flight turn for `sessionKey`, if any. Returns true if a
+     * turn was actually aborted. Safe to call from outside the per-session
+     * queue (that's the whole point — the queue is serialized but interrupt
+     * must bypass it).
+     */
+    interruptSession(sessionKey) {
+        const turn = this.inFlight.get(sessionKey);
+        if (!turn) {
+            return false;
+        }
+        turn.abort.abort();
+        return true;
+    }
+    registerInFlight(sessionKey) {
+        const existing = this.inFlight.get(sessionKey);
+        if (existing) {
+            // Per-session queue should prevent overlap, but be defensive: abort
+            // any prior controller so it doesn't leak.
+            existing.abort.abort();
+        }
+        const turn = {
+            abort: new AbortController(),
+            steer: new SteerController(),
+        };
+        this.inFlight.set(sessionKey, turn);
+        return turn;
+    }
+    clearInFlight(sessionKey, turn) {
+        if (this.inFlight.get(sessionKey) === turn) {
+            this.inFlight.delete(sessionKey);
+        }
+    }
+    async ingest(event) {
+        const sessionKey = this.conversationKeyResolver.resolve(event);
+        const prompt = ["text", "post"].includes(event.message.message_type)
+            ? extractLarkTextPrompt(event)
+            : "";
+        if (!this.deduper.markIfNew(event.message.message_id)) {
+            this.logger.log({
+                event: "message.duplicate",
+                tenant_key: event.tenant_key ?? event.sender.tenant_key,
+                chat_id: event.message.chat_id,
+                thread_id: event.message.thread_id,
+                message_id: event.message.message_id,
+                session_key: sessionKey,
+            });
+            return;
+        }
+        // Access control: optionally forbid private (p2p) chats so the bot is
+        // group-only. p2p chats are always "addressed" to the bot, so a notice is
+        // sent back rather than going silently dark.
+        if (event.message.chat_type !== "group" && this.disableP2p) {
+            this.logger.log({
+                event: "message.access_denied",
+                tenant_key: event.tenant_key ?? event.sender.tenant_key,
+                chat_id: event.message.chat_id,
+                thread_id: event.message.thread_id,
+                message_id: event.message.message_id,
+                session_key: sessionKey,
+                reason: "p2p_disabled",
+            });
+            await this.sendReplyText(event, "私聊已被管理员禁用，请在授权的群聊中使用本机器人。").catch(() => { });
+            return;
+        }
+        // In a group, only run when *this* bot is the one `@`-mentioned. A group can
+        // host several bots, and every bot receives the message event — without this
+        // check, an `@` aimed at one bot would make all of them reply.
+        if (event.message.chat_type === "group" && !this.isAddressedToBot(event)) {
+            this.logger.log({
+                event: "message.ignored",
+                tenant_key: event.tenant_key ?? event.sender.tenant_key,
+                chat_id: event.message.chat_id,
+                thread_id: event.message.thread_id,
+                message_id: event.message.message_id,
+                session_key: sessionKey,
+                reason: (event.message.mentions?.length ?? 0) === 0
+                    ? "group_message_without_mention"
+                    : "group_message_not_addressed_to_bot",
+            });
+            return;
+        }
+        // Access control: when the group allowlist is enabled, only run in groups
+        // whose chat_id is listed. Checked after the mention gate above, so we only
+        // reply to messages actually addressed to this bot (not every group chatter).
+        if (event.message.chat_type === "group" &&
+            this.groupAllowlistEnabled &&
+            !this.groupAllowlist.has(event.message.chat_id)) {
+            this.logger.log({
+                event: "message.access_denied",
+                tenant_key: event.tenant_key ?? event.sender.tenant_key,
+                chat_id: event.message.chat_id,
+                thread_id: event.message.thread_id,
+                message_id: event.message.message_id,
+                session_key: sessionKey,
+                reason: "group_not_allowlisted",
+            });
+            await this.sendReplyText(event, "本群未在机器人白名单内，暂不可使用。").catch(() => { });
+            return;
+        }
+        // /stop bypasses the per-session queue on purpose — the in-flight turn
+        // is what we want to abort, and that turn is currently holding the queue.
+        if (isLarkStopCommand(prompt)) {
+            await this.handleStopCommand(event, sessionKey);
+            return;
+        }
+        const command = parseLarkCommand(prompt);
+        // While a turn is already running for this session, a new message acts on
+        // that turn instead of queueing behind it:
+        //   - a takeover command (/new /cwd /fork /resume) stops the running turn,
+        //     then executes via its handler below (/stop is handled above);
+        //   - plain text is injected into the running turn via `turn/steer`.
+        const inflight = this.inFlight.get(sessionKey);
+        if (inflight) {
+            if (command && LARK_TAKEOVER_COMMANDS.has(command.name)) {
+                if (this.interruptSession(sessionKey)) {
+                    this.logger.log({
+                        event: "session.stopped",
+                        tenant_key: event.tenant_key ?? event.sender.tenant_key,
+                        chat_id: event.message.chat_id,
+                        thread_id: event.message.thread_id,
+                        message_id: event.message.message_id,
+                        session_key: sessionKey,
+                        provider: this.provider,
+                        source: "command_takeover",
+                        command: command.name,
+                    });
+                }
+            }
+            else if (!command && prompt) {
+                if (inflight.steer.send(prompt)) {
+                    await this.tryCreateReaction(event, sessionKey, LARK_STEER_ACK_REACTION);
+                    this.logger.log({
+                        event: "session.steered",
+                        tenant_key: event.tenant_key ?? event.sender.tenant_key,
+                        chat_id: event.message.chat_id,
+                        thread_id: event.message.thread_id,
+                        message_id: event.message.message_id,
+                        session_key: sessionKey,
+                        provider: this.provider,
+                    });
+                    return;
+                }
+                // Backend can't steer (e.g. the `codex exec` fallback never subscribes)
+                // → fall through to the queue so the message runs as the next turn.
+            }
+        }
+        // Informational commands (/help, /models, /search) answer instantly and
+        // also bypass the queue so they respond even while a turn is running.
+        if (command && LARK_INFO_COMMANDS.has(command.name)) {
+            await this.handleInfoCommand(event, sessionKey, command);
+            return;
+        }
+        // Action commands (/goal, /diff) operate on the current session / working
+        // tree without running a Codex turn; also bypass the queue.
+        if (command && LARK_ACTION_COMMANDS.has(command.name)) {
+            await this.handleActionCommand(event, sessionKey, command);
+            return;
+        }
+        // /resume lists / navigates the user's recent conversations; bypasses queue.
+        if (command && command.name === "resume") {
+            await this.handleResumeCommand(event, sessionKey, command);
+            return;
+        }
+        // /fork spins the conversation off into a new group/thread; bypasses queue.
+        if (command && command.name === "fork") {
+            await this.handleForkCommand(event, sessionKey);
+            return;
+        }
+        // /cwd binds the conversation's working directory; bypasses queue.
+        if (command && command.name === "cwd") {
+            await this.handleCwdCommand(event, sessionKey, command);
+            return;
+        }
+        // /runtime and /model open the interactive settings card; bypass queue.
+        if (command && (command.name === "runtime" || command.name === "model")) {
+            await this.handleSettingsCommand(event, sessionKey, command.name === "runtime");
+            return;
+        }
+        // /agent lists declarative agents or selects one for this conversation.
+        if (command && command.name === "agent") {
+            await this.handleAgentCommand(event, sessionKey, command);
+            return;
+        }
+        await this.queue.enqueue(sessionKey, async () => {
+            if (isLarkNewSessionCommand(prompt)) {
+                await this.handleNewSessionCommand(event, sessionKey);
+                return;
+            }
+            // Best-effort, off the turn's critical path: the directory only feeds
+            // /resume, so a lagging or failed write must never delay the reply.
+            void this.recordConversation(event, sessionKey, prompt);
+            const session = await this.activeSessionStore.ensure(sessionKey);
+            if (session.source !== "existing") {
+                this.logger.log({
+                    event: "session.started",
+                    tenant_key: event.tenant_key ?? event.sender.tenant_key,
+                    chat_id: event.message.chat_id,
+                    thread_id: event.message.thread_id,
+                    message_id: event.message.message_id,
+                    session_key: sessionKey,
+                    session_id: session.sessionId,
+                    provider: this.provider,
+                });
+            }
+            // Register the session's identity row (idempotent): the first turn fixes
+            // its source + title; rotated (`/new`) and forked sessions land here on
+            // their first turn too, so the control plane lists every Lark session.
+            this.registerSession(session.sessionId, prompt);
+            this.logMessageReceived(event, sessionKey, session.sessionId);
+            const startedReactionId = await this.tryCreateReaction(event, sessionKey, LARK_WORK_STARTED_REACTION, session.sessionId);
+            const reply = await this.buildReply(event, sessionKey, session.sessionId, prompt, session.cwd ?? this.cwd, await this.resolveTurnExecution(sessionKey, session));
+            if (reply.text) {
+                const sent = await this.sendReplyText(event, reply.text);
+                if (sent) {
+                    this.logger.log({
+                        event: "message.completed",
+                        tenant_key: event.tenant_key ?? event.sender.tenant_key,
+                        chat_id: event.message.chat_id,
+                        thread_id: event.message.thread_id,
+                        message_id: event.message.message_id,
+                        session_key: sessionKey,
+                        session_id: session.sessionId,
+                        provider: reply.provider,
+                        model: reply.model,
+                    });
+                }
+            }
+            await this.tryCreateReaction(event, sessionKey, LARK_WORK_COMPLETED_REACTION, session.sessionId);
+            await this.tryDeleteReaction(event, sessionKey, startedReactionId, LARK_WORK_STARTED_REACTION, session.sessionId);
+        });
+    }
+    async handleStopCommand(event, sessionKey) {
+        const aborted = this.interruptSession(sessionKey);
+        this.logger.log({
+            event: aborted ? "session.stopped" : "session.stop_noop",
+            tenant_key: event.tenant_key ?? event.sender.tenant_key,
+            chat_id: event.message.chat_id,
+            thread_id: event.message.thread_id,
+            message_id: event.message.message_id,
+            session_key: sessionKey,
+            provider: this.provider,
+        });
+        await this.sendReplyText(event, aborted ? DEFAULT_STOP_ACK_RESPONSE : DEFAULT_STOP_NO_INFLIGHT_RESPONSE);
+    }
+    async handleInfoCommand(event, sessionKey, command) {
+        const session = await this.activeSessionStore.get(sessionKey);
+        const runtime = session?.runtime ?? this.provider;
+        let text;
+        switch (command.name) {
+            case "models":
+                text = await this.renderModelsReply(runtime);
+                break;
+            case "help":
+            default:
+                text = LARK_HELP_TEXT;
+                break;
+        }
+        await this.sendReplyText(event, text);
+        this.logger.log({
+            event: "command.handled",
+            tenant_key: event.tenant_key ?? event.sender.tenant_key,
+            chat_id: event.message.chat_id,
+            thread_id: event.message.thread_id,
+            message_id: event.message.message_id,
+            session_key: sessionKey,
+            command: command.name,
+            provider: this.provider,
+        });
+    }
+    async handleActionCommand(event, sessionKey, command) {
+        if (command.name === "diff") {
+            await this.handleDiffCommand(event, sessionKey);
+        }
+        else {
+            const text = command.name === "goal"
+                ? await this.renderGoalReply(sessionKey, command.args)
+                : LARK_HELP_TEXT;
+            await this.sendReplyText(event, text);
+        }
+        this.logger.log({
+            event: "command.handled",
+            tenant_key: event.tenant_key ?? event.sender.tenant_key,
+            chat_id: event.message.chat_id,
+            thread_id: event.message.thread_id,
+            message_id: event.message.message_id,
+            session_key: sessionKey,
+            command: command.name,
+            provider: this.provider,
+        });
+    }
+    /**
+     * Render the working-tree diff as a CardKit card (summary + per-file stats +
+     * a collapsed full diff). Falls back to a plain-text reply when the sender
+     * has no card capability or the card send fails.
+     */
+    async handleDiffCommand(event, sessionKey) {
+        const result = await this.collectGitDiff();
+        if (result.kind === "error") {
+            await this.sendReplyText(event, `git diff 失败：${result.message}`);
+            return;
+        }
+        if (result.kind === "clean") {
+            await this.sendReplyText(event, "工作区干净，没有改动。");
+            return;
+        }
+        if (this.messageSender.createCard) {
+            try {
+                await this.sendStandaloneCard(event, buildDiffCardJson(result.input));
+                return;
+            }
+            catch (error) {
+                this.logger.log({
+                    event: "command.diff_card_failed",
+                    chat_id: event.message.chat_id,
+                    thread_id: event.message.thread_id,
+                    message_id: event.message.message_id,
+                    session_key: sessionKey,
+                    error: toErrorMessage(error),
+                });
+            }
+        }
+        await this.sendReplyText(event, result.fallbackText);
+    }
+    async collectGitDiff() {
+        const cwd = this.cwd ?? process.cwd();
+        try {
+            const [{ stdout: diff }, { stdout: numstat }, { stdout: untracked }] = await Promise.all([
+                execFileAsync("git", ["-C", cwd, "diff"], { maxBuffer: 8 * 1024 * 1024 }),
+                execFileAsync("git", ["-C", cwd, "diff", "--numstat"], { maxBuffer: 8 * 1024 * 1024 }),
+                execFileAsync("git", ["-C", cwd, "ls-files", "--others", "--exclude-standard"], {
+                    maxBuffer: 8 * 1024 * 1024,
+                }),
+            ]);
+            const files = [];
+            let totalAdditions = 0;
+            let totalDeletions = 0;
+            for (const line of numstat.split("\n")) {
+                if (!line.trim()) {
+                    continue;
+                }
+                const [addRaw, delRaw, ...rest] = line.split("\t");
+                const filePath = rest.join("\t").trim();
+                if (!filePath) {
+                    continue;
+                }
+                const additions = addRaw === "-" ? null : Number(addRaw);
+                const deletions = delRaw === "-" ? null : Number(delRaw);
+                if (additions != null && Number.isFinite(additions)) {
+                    totalAdditions += additions;
+                }
+                if (deletions != null && Number.isFinite(deletions)) {
+                    totalDeletions += deletions;
+                }
+                files.push({ path: filePath, additions, deletions });
+            }
+            const untrackedFiles = untracked
+                .split("\n")
+                .map((file) => file.trim())
+                .filter(Boolean);
+            for (const filePath of untrackedFiles) {
+                files.push({ path: filePath, additions: null, deletions: null, untracked: true });
+            }
+            if (files.length === 0 && !diff.trim()) {
+                return { kind: "clean" };
+            }
+            const overCardLimit = Buffer.byteLength(diff, "utf8") > DIFF_CARD_MAX_BYTES;
+            const diffBody = overCardLimit ? diff.slice(0, DIFF_CARD_MAX_BYTES) : diff.trimEnd();
+            // Plain-text fallback mirrors the previous /diff output.
+            let body = diff.trimEnd();
+            if (untrackedFiles.length) {
+                const list = untrackedFiles.map((file) => `?? ${file}`).join("\n");
+                body = body ? `${body}\n\n未跟踪文件：\n${list}` : `未跟踪文件：\n${list}`;
+            }
+            const fallbackText = Buffer.byteLength(body, "utf8") > DIFF_REPLY_MAX_BYTES
+                ? `${body.slice(0, DIFF_REPLY_MAX_BYTES)}\n… (diff 过长已截断)`
+                : body;
+            return {
+                kind: "diff",
+                input: { files, totalAdditions, totalDeletions, diffBody, truncated: overCardLimit },
+                fallbackText,
+            };
+        }
+        catch (error) {
+            return { kind: "error", message: toErrorMessage(error) };
+        }
+    }
+    async renderGoalReply(sessionKey, args) {
+        if (!this.capabilities) {
+            return LARK_BACKEND_UNSUPPORTED;
+        }
+        const session = await this.activeSessionStore.get(sessionKey);
+        if (!session) {
+            return LARK_NO_ACTIVE_SESSION;
+        }
+        const sub = args.trim();
+        if (!sub) {
+            const result = await this.capabilities.getGoal(session.sessionId);
+            if (!result.ok) {
+                return this.capabilityErrorText(result);
+            }
+            const goal = result.data;
+            if (!goal?.objective) {
+                return "当前没有设置目标。用 `/goal <目标>` 设置。";
+            }
+            const status = goal.status ? `（${goal.status}）` : "";
+            return `当前目标：${goal.objective}${status}`;
+        }
+        if (sub === "clear") {
+            const result = await this.capabilities.clearGoal(session.sessionId);
+            return result.ok ? "已清除当前会话目标。" : this.capabilityErrorText(result);
+        }
+        const result = await this.capabilities.setGoal(session.sessionId, sub);
+        return result.ok ? `已设置目标：${sub}` : this.capabilityErrorText(result);
+    }
+    capabilityErrorText(result) {
+        switch (result.reason) {
+            case "no_active_thread":
+                return LARK_NO_ACTIVE_SESSION;
+            case "unsupported":
+                return LARK_BACKEND_UNSUPPORTED;
+            default:
+                return `操作失败：${result.message ?? "未知错误"}`;
+        }
+    }
+    conversationKindOf(event) {
+        if (event.message.thread_id) {
+            return "thread";
+        }
+        return event.message.chat_type === "group" ? "group" : "p2p";
+    }
+    async recordConversation(event, sessionKey, prompt) {
+        const title = prompt.trim();
+        if (!title) {
+            return;
+        }
+        try {
+            await this.conversationDirectory.record({
+                conversationKey: sessionKey,
+                chatId: event.message.chat_id,
+                threadId: event.message.thread_id,
+                kind: this.conversationKindOf(event),
+                title,
+                participantOpenId: event.sender.sender_id?.open_id,
+            });
+        }
+        catch (error) {
+            this.logger.log({
+                event: "conversation.record_failed",
+                session_key: sessionKey,
+                message_id: event.message.message_id,
+                error: toErrorMessage(error),
+            });
+        }
+    }
+    async handleCwdCommand(event, sessionKey, command) {
+        const session = await this.activeSessionStore.get(sessionKey);
+        const currentCwd = session?.cwd ?? this.cwd;
+        const arg = command.args.trim();
+        if (!arg) {
+            await this.sendReplyText(event, currentCwd ? `当前工作目录：${currentCwd}` : "当前使用默认工作目录。");
+            return;
+        }
+        const base = currentCwd ?? this.allowedRoots[0] ?? process.cwd();
+        const resolved = path.isAbsolute(arg) ? path.resolve(arg) : path.resolve(base, arg);
+        if (!findInnermostAllowedRoot(resolved, this.allowedRoots)) {
+            await this.sendReplyText(event, `目录不在允许范围内（需位于 AGENT_ALLOWED_DIRS 内）：${resolved}`);
+            return;
+        }
+        try {
+            await mkdir(resolved, { recursive: true });
+        }
+        catch (error) {
+            await this.sendReplyText(event, `创建目录失败：${toErrorMessage(error)}`);
+            return;
+        }
+        await this.activeSessionStore.bindCwd(sessionKey, resolved);
+        await this.sendReplyText(event, `已绑定工作目录：${resolved}，并开启新会话。`);
+        this.logger.log({
+            event: "command.handled",
+            tenant_key: event.tenant_key ?? event.sender.tenant_key,
+            chat_id: event.message.chat_id,
+            thread_id: event.message.thread_id,
+            message_id: event.message.message_id,
+            session_key: sessionKey,
+            command: "cwd",
+            provider: this.provider,
+        });
+    }
+    async handleResumeCommand(event, sessionKey, command) {
+        const arg = command.args.trim();
+        if (arg) {
+            await this.resumeByShortId(event, arg);
+        }
+        else {
+            await this.resumeList(event);
+        }
+        this.logger.log({
+            event: "command.handled",
+            tenant_key: event.tenant_key ?? event.sender.tenant_key,
+            chat_id: event.message.chat_id,
+            thread_id: event.message.thread_id,
+            message_id: event.message.message_id,
+            session_key: sessionKey,
+            command: "resume",
+            provider: this.provider,
+        });
+    }
+    async resumeList(event) {
+        const openId = event.sender.sender_id?.open_id;
+        if (!openId) {
+            await this.sendReplyText(event, "无法识别你的身份，暂时无法列出历史会话。");
+            return;
+        }
+        const records = await this.conversationDirectory.listForUser(openId, 5);
+        if (records.length === 0) {
+            await this.sendReplyText(event, "你还没有可恢复的历史会话。");
+            return;
+        }
+        if (this.canUseCardSender()) {
+            try {
+                await this.sendStandaloneCard(event, buildResumeCardJson(records, {
+                    chatId: event.message.chat_id,
+                    threadId: event.message.thread_id,
+                }));
+                return;
+            }
+            catch (error) {
+                this.logger.log({
+                    event: "resume.card_failed",
+                    message_id: event.message.message_id,
+                    error: toErrorMessage(error),
+                });
+                // fall through to text
+            }
+        }
+        const lines = records.map((record, index) => {
+            if (record.kind === "thread") {
+                return `${index + 1}. ${record.title}  \`${record.shortId}\`（话题，发送 /resume ${record.shortId} 转发到此）`;
+            }
+            return `${index + 1}. ${record.title}  \`${record.shortId}\`  ${buildChatApplink(record.chatId)}`;
+        });
+        await this.sendReplyText(event, ["最近会话：", ...lines].join("\n"));
+    }
+    async resumeByShortId(event, shortId) {
+        const record = await this.conversationDirectory.getByShortId(shortId);
+        if (!record) {
+            await this.sendReplyText(event, `没有找到 id 为 \`${shortId}\` 的会话。`);
+            return;
+        }
+        if (record.kind === "thread" && record.threadId) {
+            if (!this.messageSender.forwardThread) {
+                await this.sendReplyText(event, "当前不支持转发话题。");
+                return;
+            }
+            const target = this.forwardTargetOf(event);
+            try {
+                await this.messageSender.forwardThread({
+                    threadId: record.threadId,
+                    receiveId: target.receiveId,
+                    receiveIdType: target.receiveIdType,
+                    uuid: randomUUID(),
+                });
+                await this.sendReplyText(event, `已把话题「${record.title}」转发到当前会话。`);
+            }
+            catch (error) {
+                await this.sendReplyText(event, `转发失败：${toErrorMessage(error)}`);
+            }
+            return;
+        }
+        await this.sendReplyText(event, `会话「${record.title}」：${buildChatApplink(record.chatId)}`);
+    }
+    async sendStandaloneCard(event, cardJson) {
+        const sender = this.messageSender;
+        if (!sender.createCard) {
+            throw new Error("card sender unavailable");
+        }
+        const { cardId } = await sender.createCard({ cardJson });
+        const uuid = randomUUID();
+        if (event.message.thread_id && sender.replyInteractive) {
+            const { messageId } = await sender.replyInteractive({
+                messageId: event.message.message_id,
+                cardId,
+                uuid,
+                replyInThread: true,
+            });
+            return { cardId, messageId };
+        }
+        if (sender.sendInteractive) {
+            const { messageId } = await sender.sendInteractive({
+                chatId: event.message.chat_id,
+                cardId,
+                uuid,
+            });
+            return { cardId, messageId };
+        }
+        return { cardId };
+    }
+    async handleForkCommand(event, sessionKey) {
+        const sender = this.messageSender;
+        if (!this.capabilities?.forkSession ||
+            !sender.sendText ||
+            !sender.listMessages ||
+            !sender.listChatMembers) {
+            await this.sendReplyText(event, "当前不支持 /fork（仅 app_server 后端 + 飞书机器人能力）。");
+            return;
+        }
+        const session = await this.activeSessionStore.get(sessionKey);
+        if (!session) {
+            await this.sendReplyText(event, LARK_NO_ACTIVE_SESSION);
+            return;
+        }
+        const tenantKey = event.tenant_key ?? event.sender.tenant_key ?? "unknown-tenant";
+        const isThread = Boolean(event.message.thread_id);
+        const directoryRecord = await this.conversationDirectory.get(sessionKey);
+        // Prefer the real Feishu chat name; fall back to the last user message, then
+        // a sensible default. (p2p chats have no name, so the fallback applies.)
+        let chatName = "";
+        if (sender.getChat) {
+            try {
+                chatName = (await sender.getChat({ chatId: event.message.chat_id })).name;
+            }
+            catch (error) {
+                this.logger.log({ event: "fork.get_chat_failed", error: toErrorMessage(error), message_id: event.message.message_id });
+            }
+        }
+        const baseName = chatName.trim() || directoryRecord?.title?.trim() || "Codex 会话";
+        // Members serve both the transcript (id → name) and, for the group case,
+        // the new group's member list. Fetch once, best-effort.
+        let members = [];
+        try {
+            members = await sender.listChatMembers({ chatId: event.message.chat_id });
+        }
+        catch (error) {
+            this.logger.log({ event: "fork.members_failed", error: toErrorMessage(error), message_id: event.message.message_id });
+        }
+        const nameById = new Map(members.map((m) => [m.memberId, m.name]));
+        let transcript = "";
+        try {
+            const messages = await sender.listMessages({
+                containerIdType: isThread ? "thread" : "chat",
+                containerId: isThread ? event.message.thread_id : event.message.chat_id,
+                pageSize: 50,
+            });
+            transcript = buildForkTranscript(messages, nameById);
+        }
+        catch (error) {
+            this.logger.log({ event: "fork.transcript_failed", error: toErrorMessage(error), message_id: event.message.message_id });
+        }
+        const header = `📋 原会话「${baseName}」记录（fork）：`;
+        const body = transcript ? `${header}\n${transcript}` : header;
+        let newSessionKey;
+        let newChatId = null;
+        try {
+            if (isThread) {
+                const sent = await sender.sendText({
+                    chatId: event.message.chat_id,
+                    text: body,
+                    uuid: randomUUID(),
+                });
+                if (!sent.threadId) {
+                    await this.sendReplyText(event, "fork 失败：未能创建新话题。");
+                    return;
+                }
+                newSessionKey = `lark:${tenantKey}:thread:${sent.threadId}`;
+            }
+            else {
+                if (!sender.createChat) {
+                    await this.sendReplyText(event, "当前不支持建群。");
+                    return;
+                }
+                const userIdList = members.map((m) => m.memberId).filter(Boolean);
+                const created = await sender.createChat({
+                    name: `${baseName} - fork`,
+                    userIdList,
+                    uuid: randomUUID(),
+                });
+                await sender.sendText({ chatId: created.chatId, text: body, uuid: randomUUID() });
+                newSessionKey = `lark:${tenantKey}:chat:${created.chatId}`;
+                newChatId = created.chatId;
+            }
+        }
+        catch (error) {
+            await this.sendReplyText(event, `fork 失败：${toErrorMessage(error)}`);
+            return;
+        }
+        // Bind the new conversation to a forked Codex thread carrying context.
+        // Carry the source cwd so the forked thread's working dir stays consistent.
+        // The session id is opaque (no routing baked in); newSessionKey is the
+        // routing key the store maps to it.
+        if (!this.sessionProvisioner) {
+            await this.sendReplyText(event, LARK_BACKEND_UNSUPPORTED);
+            return;
+        }
+        let newLocalThreadId;
+        let forkResult;
+        try {
+            newLocalThreadId = await this.sessionProvisioner({
+                sessionKey: newSessionKey,
+                fromSessionId: session.sessionId,
+            });
+            await this.activeSessionStore.set(newSessionKey, newLocalThreadId, session.cwd);
+            forkResult = await this.capabilities.forkSession(session.sessionId, newLocalThreadId);
+        }
+        catch (error) {
+            await this.sendReplyText(event, `fork 会话创建失败：${toErrorMessage(error)}`);
+            return;
+        }
+        const contextNote = forkResult.ok
+            ? "已带上当前会话上下文。"
+            : `但未能带上上下文：${this.capabilityErrorText(forkResult)}`;
+        // Surface a one-tap entry into the new conversation in the current chat.
+        if (newChatId) {
+            const entryCardJson = buildOpenChatCardJson(newChatId, `${baseName} - fork`);
+            let sentCard = false;
+            if (this.canUseCardSender()) {
+                try {
+                    await this.sendStandaloneCard(event, entryCardJson);
+                    sentCard = true;
+                }
+                catch (error) {
+                    this.logger.log({ event: "fork.entry_card_failed", error: toErrorMessage(error), message_id: event.message.message_id });
+                }
+            }
+            if (!sentCard) {
+                await this.sendReplyText(event, `已 fork 到新群「${baseName} - fork」，点此进入：${buildChatApplink(newChatId)}（${contextNote}）`);
+            }
+            else if (!forkResult.ok) {
+                await this.sendReplyText(event, `提示：${contextNote}`);
+            }
+        }
+        else {
+            // Topic thread: the root message is already visible in this group.
+            await this.sendReplyText(event, `已在本群新建话题（见上方新消息），可在其中继续对话。${contextNote}`);
+        }
+        this.logger.log({
+            event: "command.handled",
+            tenant_key: tenantKey,
+            chat_id: event.message.chat_id,
+            thread_id: event.message.thread_id,
+            message_id: event.message.message_id,
+            session_key: sessionKey,
+            command: "fork",
+            provider: this.provider,
+        });
+    }
+    /**
+     * Send the `/runtime` (or `/model`) settings card and seed the pending
+     * selection state with the conversation's current settings.
+     */
+    async handleSettingsCommand(event, sessionKey, includeRuntime) {
+        const session = await this.activeSessionStore.get(sessionKey);
+        const currentRuntime = session?.runtime ?? this.provider;
+        const currentModel = session?.model;
+        const currentEffort = session?.reasoningEffort;
+        if (!this.canUseCardSender()) {
+            await this.sendReplyText(event, this.renderSettingsSummary(currentRuntime, currentModel, currentEffort));
+            return;
+        }
+        const models = await this.fetchModelOptions(currentRuntime);
+        const pending = {
+            includeRuntime,
+            currentRuntime,
+            currentModel,
+            runtime: currentRuntime,
+            model: currentModel ?? SETTINGS_DEFAULT_VALUE,
+            effort: currentEffort ?? SETTINGS_DEFAULT_VALUE,
+            models,
+        };
+        this.pendingSettings.set(sessionKey, pending);
+        const cardJson = buildSettingsCardJson(this.settingsCardInput(sessionKey, pending));
+        try {
+            await this.sendStandaloneCard(event, cardJson);
+        }
+        catch (error) {
+            this.pendingSettings.delete(sessionKey);
+            await this.sendReplyText(event, `发送设置卡片失败：${toErrorMessage(error)}`);
+            return;
+        }
+        this.logger.log({
+            event: "command.handled",
+            tenant_key: event.tenant_key ?? event.sender.tenant_key,
+            chat_id: event.message.chat_id,
+            thread_id: event.message.thread_id,
+            message_id: event.message.message_id,
+            session_key: sessionKey,
+            command: includeRuntime ? "runtime" : "model",
+            provider: currentRuntime,
+        });
+    }
+    /**
+     * `/agent` — list declarative agents, or select one for this conversation.
+     * Selecting rotates to a fresh session (so sandbox/persona/tools don't change
+     * mid-thread) and drops explicit runtime/model overrides so the agent drives them.
+     */
+    async handleAgentCommand(event, sessionKey, command) {
+        const name = command.args.trim();
+        const session = await this.activeSessionStore.get(sessionKey);
+        const current = session?.agent;
+        if (!name) {
+            if (!this.agentCatalog) {
+                await this.sendReplyText(event, "当前运行环境不支持 agent 目录。");
+                return;
+            }
+            let specs;
+            try {
+                specs = await this.agentCatalog.list();
+            }
+            catch (error) {
+                await this.sendReplyText(event, `读取 agent 失败：${toErrorMessage(error)}`);
+                return;
+            }
+            const lines = ["可用 agent："];
+            if (specs.length === 0) {
+                lines.push("  （暂无；用 `rynx agent add <名称>` 创建）");
+            }
+            else {
+                for (const spec of specs) {
+                    const marker = spec.id === current ? "✓" : "·";
+                    const runtime = spec.runtime ?? "默认";
+                    const model = spec.model ?? "默认";
+                    const display = spec.name && spec.name !== spec.id ? `${spec.name} · ` : "";
+                    lines.push(`  ${marker} ${spec.id}（${display}${runtime} / ${model}）`);
+                }
+            }
+            lines.push(current ? `\n当前：${current}` : "\n当前：未选择（用全局默认）");
+            lines.push("用 `/agent <名称>` 切换。");
+            await this.sendReplyText(event, lines.join("\n"));
+            return;
+        }
+        if (!this.agentCatalog) {
+            await this.sendReplyText(event, "当前运行环境不支持 agent 目录。");
+            return;
+        }
+        let spec;
+        try {
+            spec = await this.agentCatalog.get(name);
+        }
+        catch (error) {
+            await this.sendReplyText(event, `agent「${name}」配置无效：${toErrorMessage(error)}`);
+            return;
+        }
+        if (!spec) {
+            await this.sendReplyText(event, `未找到 agent「${name}」。用 /agent 查看可用列表。`);
+            return;
+        }
+        await this.activeSessionStore.setAgent(sessionKey, name);
+        const runtime = spec.runtime ?? "默认运行时";
+        const model = spec.model ?? "默认模型";
+        await this.sendReplyText(event, `已切换到 agent「${name}」（${runtime} / ${model}），并开启新会话。`);
+        this.logger.log({
+            event: "command.handled",
+            tenant_key: event.tenant_key ?? event.sender.tenant_key,
+            chat_id: event.message.chat_id,
+            thread_id: event.message.thread_id,
+            message_id: event.message.message_id,
+            session_key: sessionKey,
+            command: "agent",
+            provider: spec.runtime ?? this.provider,
+        });
+    }
+    /**
+     * Label shown for the model in the turn card. An empty model means the
+     * runtime follows its own configured default (e.g. traex with no
+     * `TRAEX_MODEL`); show a placeholder so the status row isn't blank (the
+     * runtime itself is shown separately).
+     */
+    displayModel(model) {
+        return model?.trim() || "默认模型";
+    }
+    renderSettingsSummary(runtime, model, effort) {
+        return [
+            "当前会话设置：",
+            `• 运行时：${getRuntimeProfile(runtime).displayName}`,
+            `• 模型：${model ?? "（运行时默认）"}`,
+            `• 思考强度：${effort ?? "（默认）"}`,
+            "（当前环境不支持交互卡片，无法在此切换。）",
+        ].join("\n");
+    }
+    /** Assemble the settings-card input from the current pending selection. */
+    settingsCardInput(sessionKey, pending) {
+        return {
+            sessionKey,
+            includeRuntime: pending.includeRuntime,
+            runtimeOptions: Object.keys(RUNTIME_PROFILES).map((id) => ({
+                value: id,
+                label: RUNTIME_PROFILES[id].displayName,
+            })),
+            models: pending.models,
+            selectedRuntime: isAgentRuntimeId(pending.runtime) ? pending.runtime : pending.currentRuntime,
+            selectedModel: pending.model,
+            selectedEffort: pending.effort,
+        };
+    }
+    async fetchModelOptions(runtime) {
+        if (!this.capabilities) {
+            return [];
+        }
+        try {
+            const response = await this.capabilities.listModels(runtime);
+            const models = (response?.data ?? []).filter((model) => !model.hidden);
+            return models.map((model) => ({
+                value: String(model.model || model.id),
+                label: String(model.displayName || model.model || model.id),
+                isDefault: Boolean(model.isDefault),
+                supportedEfforts: extractSupportedEfforts(model),
+            }));
+        }
+        catch (error) {
+            this.logger.log({ event: "settings.models_failed", error: toErrorMessage(error) });
+            return [];
+        }
+    }
+    /**
+     * Handle a settings-card dropdown change. A runtime change re-scopes the
+     * model list (and resets model/effort); a model change re-scopes the effort
+     * list — both re-render the card in place via the callback response so the
+     * dependent dropdowns update. Effort changes just update pending state.
+     */
+    async handleSettingsSelect(event) {
+        const value = event.value;
+        const sessionKey = typeof value?.sessionKey === "string" ? value.sessionKey : null;
+        const field = typeof value?.field === "string" ? value.field : null;
+        const option = typeof event.option === "string" ? event.option : null;
+        if (!sessionKey || !field || option === null) {
+            return {};
+        }
+        const pending = this.pendingSettings.get(sessionKey);
+        if (!pending) {
+            return {};
+        }
+        if (field === "runtime") {
+            if (!isAgentRuntimeId(option) || option === pending.runtime) {
+                return {};
+            }
+            pending.runtime = option;
+            pending.models = await this.fetchModelOptions(option);
+            // A model from the old runtime can't carry over → reset model + effort.
+            pending.model = SETTINGS_DEFAULT_VALUE;
+            pending.effort = SETTINGS_DEFAULT_VALUE;
+            return this.settingsCardResponse(sessionKey, pending);
+        }
+        if (field === "model") {
+            if (option === pending.model) {
+                return {};
+            }
+            pending.model = option;
+            // Available efforts depend on the model → reset the effort selection.
+            pending.effort = SETTINGS_DEFAULT_VALUE;
+            return this.settingsCardResponse(sessionKey, pending);
+        }
+        if (field === "effort") {
+            pending.effort = option;
+        }
+        return {};
+    }
+    /** Card-action response that re-renders the open settings card in place. */
+    settingsCardResponse(sessionKey, pending) {
+        return {
+            card: { type: "raw", data: buildSettingsCard(this.settingsCardInput(sessionKey, pending)) },
+        };
+    }
+    /** Apply the pending settings-card selections to the conversation. */
+    async handleSettingsApply(event) {
+        const value = event.value;
+        const sessionKey = typeof value?.sessionKey === "string" ? value.sessionKey : null;
+        if (!sessionKey) {
+            return { toast: { type: "error", content: "无法识别会话。" } };
+        }
+        const pending = this.pendingSettings.get(sessionKey);
+        if (!pending) {
+            return { toast: { type: "warning", content: "设置已过期，请重新发送 /runtime。" } };
+        }
+        // Pending state is the source of truth — the dropdowns re-render it on each
+        // change, so the selected model is always valid for the selected runtime.
+        const runtime = pending.includeRuntime && isAgentRuntimeId(pending.runtime)
+            ? pending.runtime
+            : pending.currentRuntime;
+        const runtimeChanged = runtime !== pending.currentRuntime;
+        const model = pending.model === SETTINGS_DEFAULT_VALUE ? undefined : pending.model;
+        const selectedModel = pending.models.find((candidate) => candidate.value === pending.model);
+        const allowedEfforts = selectedModel?.supportedEfforts?.length
+            ? selectedModel.supportedEfforts
+            : SETTINGS_EFFORT_VALUES;
+        const effort = pending.effort !== SETTINGS_DEFAULT_VALUE && allowedEfforts.includes(pending.effort)
+            ? pending.effort
+            : undefined;
+        // Only a runtime change rotates to a fresh session (its rollout/transcript
+        // store is runtime-specific). model / effort switch on the SAME thread —
+        // both lineages take them per-turn — so the conversation keeps its context.
+        const rotate = runtimeChanged;
+        await this.activeSessionStore.applySettings(sessionKey, {
+            runtime,
+            model,
+            reasoningEffort: effort,
+            rotate,
+        });
+        this.pendingSettings.delete(sessionKey);
+        const summary = [
+            `运行时：${getRuntimeProfile(runtime).displayName}`,
+            `模型：${model ?? "运行时默认"}`,
+            `思考强度：${effort ?? "默认"}`,
+        ].join(" · ");
+        this.logger.log({
+            event: "settings.applied",
+            session_key: sessionKey,
+            message_id: event.messageId,
+            provider: runtime,
+            model: model ?? undefined,
+            reasoning_effort: effort ?? null,
+            rotated: rotate,
+        });
+        const headline = rotate ? `已应用并开启新会话 — ${summary}` : `已更新 — ${summary}`;
+        // Replace the card via the callback response (atomic — no flash/revert).
+        return this.settingsResultCard(pending.includeRuntime, "green", `✅ ${headline}`);
+    }
+    /** Cancel an open settings card without changing anything. */
+    handleSettingsCancel(event) {
+        const value = event.value;
+        const sessionKey = typeof value?.sessionKey === "string" ? value.sessionKey : null;
+        if (!sessionKey) {
+            return {};
+        }
+        const pending = this.pendingSettings.get(sessionKey);
+        if (!pending) {
+            return {};
+        }
+        const includeRuntime = pending.includeRuntime;
+        this.pendingSettings.delete(sessionKey);
+        return this.settingsResultCard(includeRuntime, "grey", "已取消，设置未改动。");
+    }
+    /**
+     * Build a card-action response that swaps the settings card for a static
+     * result card. Returning the card in the callback response replaces it
+     * atomically; an out-of-band `card.update` would briefly show the result and
+     * then revert to the form.
+     */
+    settingsResultCard(includeRuntime, template, content) {
+        return {
+            card: {
+                type: "raw",
+                data: buildSettingsResultCard({ includeRuntime, template, content }),
+            },
+        };
+    }
+    async renderModelsReply(runtime) {
+        if (!this.capabilities) {
+            return LARK_BACKEND_UNSUPPORTED;
+        }
+        try {
+            const response = await this.capabilities.listModels(runtime);
+            if (!response) {
+                return LARK_BACKEND_UNSUPPORTED;
+            }
+            const models = (response.data ?? []).filter((model) => !model.hidden);
+            if (models.length === 0) {
+                return "未获取到可用模型。";
+            }
+            const lines = models.map((model) => {
+                const label = model.displayName || model.model || model.id;
+                return `• ${label}${model.isDefault ? " ⭐️" : ""}`;
+            });
+            return ["可用模型：", ...lines].join("\n");
+        }
+        catch (error) {
+            return `获取模型列表失败：${toErrorMessage(error)}`;
+        }
+    }
+    async handleNewSessionCommand(event, sessionKey) {
+        const currentSession = await this.activeSessionStore.get(sessionKey);
+        this.logMessageReceived(event, sessionKey, currentSession?.sessionId);
+        const rotated = await this.activeSessionStore.rotate(sessionKey);
+        this.logger.log({
+            event: "session.rotated",
+            tenant_key: event.tenant_key ?? event.sender.tenant_key,
+            chat_id: event.message.chat_id,
+            thread_id: event.message.thread_id,
+            message_id: event.message.message_id,
+            session_key: sessionKey,
+            session_id: rotated.sessionId,
+            previous_session_id: rotated.previousSessionId,
+            provider: this.provider,
+        });
+        const sent = await this.sendReplyText(event, DEFAULT_NEW_SESSION_RESPONSE);
+        if (sent) {
+            this.logger.log({
+                event: "message.completed",
+                tenant_key: event.tenant_key ?? event.sender.tenant_key,
+                chat_id: event.message.chat_id,
+                thread_id: event.message.thread_id,
+                message_id: event.message.message_id,
+                session_key: sessionKey,
+                session_id: rotated.sessionId,
+                provider: this.provider,
+            });
+        }
+    }
+    logMessageReceived(event, sessionKey, sessionId) {
+        this.logger.log({
+            event: "message.received",
+            tenant_key: event.tenant_key ?? event.sender.tenant_key,
+            chat_id: event.message.chat_id,
+            thread_id: event.message.thread_id,
+            message_id: event.message.message_id,
+            session_key: sessionKey,
+            session_id: sessionId,
+            provider: this.provider,
+        });
+    }
+    async tryCreateReaction(event, sessionKey, emojiType, sessionId) {
+        try {
+            return await this.messageSender.createReaction({
+                messageId: event.message.message_id,
+                emojiType,
+            });
+        }
+        catch (error) {
+            this.logger.log({
+                event: "message.reaction_failed",
+                tenant_key: event.tenant_key ?? event.sender.tenant_key,
+                chat_id: event.message.chat_id,
+                thread_id: event.message.thread_id,
+                message_id: event.message.message_id,
+                session_key: sessionKey,
+                session_id: sessionId,
+                emoji_type: emojiType,
+                error: toErrorMessage(error),
+            });
+            return undefined;
+        }
+    }
+    async tryDeleteReaction(event, sessionKey, reactionId, emojiType, sessionId) {
+        if (!reactionId) {
+            return;
+        }
+        try {
+            await this.messageSender.deleteReaction({
+                messageId: event.message.message_id,
+                reactionId,
+            });
+        }
+        catch (error) {
+            this.logger.log({
+                event: "message.reaction_delete_failed",
+                tenant_key: event.tenant_key ?? event.sender.tenant_key,
+                chat_id: event.message.chat_id,
+                thread_id: event.message.thread_id,
+                message_id: event.message.message_id,
+                session_key: sessionKey,
+                session_id: sessionId,
+                emoji_type: emojiType,
+                error: toErrorMessage(error),
+            });
+        }
+    }
+    /**
+     * If this turn replies to a Lark message card, fetch the parent card and wrap
+     * the prompt so the agent receives the card content as context. Generic: it
+     * forwards any interactive (card) parent and names no specific skill — the
+     * agent decides how to act on the card. Returns null when the parent is not a
+     * card (or cannot be fetched), so the caller falls back to the raw prompt.
+     */
+    async tryBuildCardReplyPrompt(event, sessionKey, sessionId, prompt) {
+        const parentMessageId = event.message.parent_id?.trim();
+        if (!parentMessageId || !this.messageSender.getMessage) {
+            return null;
+        }
+        try {
+            const parentMessage = await this.messageSender.getMessage({ messageId: parentMessageId });
+            const content = parentMessage?.body?.content ?? parentMessage?.content;
+            const parentContent = typeof content === "string" && content.trim() ? content : null;
+            if (parentMessage?.msgType !== "interactive" || !parentContent) {
+                return null;
+            }
+            this.logger.log({
+                event: "message.card_reply_detected",
+                tenant_key: event.tenant_key ?? event.sender.tenant_key,
+                chat_id: event.message.chat_id,
+                thread_id: event.message.thread_id,
+                message_id: event.message.message_id,
+                session_key: sessionKey,
+                session_id: sessionId,
+                provider: this.provider,
+            });
+            return buildLarkCardReplyPrompt({
+                userPrompt: prompt,
+                cardContent: parentContent,
+            });
+        }
+        catch (error) {
+            this.logger.log({
+                event: "message.parent_lookup_failed",
+                tenant_key: event.tenant_key ?? event.sender.tenant_key,
+                chat_id: event.message.chat_id,
+                thread_id: event.message.thread_id,
+                message_id: event.message.message_id,
+                session_key: sessionKey,
+                session_id: sessionId,
+                provider: this.provider,
+                error: toErrorMessage(error),
+            });
+            return null;
+        }
+    }
+    /**
+     * Map a session to the {@link TurnSettings} a turn runs with. Already-frozen
+     * sessions are resolved locally; first-turn defaults and named-agent lookup
+     * are delegated to the capability-gated host and then persisted exactly once.
+     */
+    async resolveTurnExecution(sessionKey, session) {
+        if (session.runtime) {
+            return {
+                provider: session.runtime,
+                providerExplicit: true,
+                model: session.model,
+                reasoningEffort: session.reasoningEffort,
+                agentName: session.agent,
+            };
+        }
+        // Lightweight unit-test/custom embeddings may omit the host resolver.
+        if (!this.agentCatalog) {
+            return {
+                provider: session.runtime ?? this.provider,
+                providerExplicit: session.runtime != null,
+                model: session.model,
+                reasoningEffort: session.reasoningEffort,
+                agentName: session.agent ?? this.defaultAgent,
+            };
+        }
+        const plan = await this.agentCatalog.resolveExecution({
+            ...(this.defaultAgent ? { defaultAgent: this.defaultAgent } : {}),
+            session: {
+                ...(session.runtime ? { runtime: session.runtime } : {}),
+                ...(session.model ? { model: session.model } : {}),
+                ...(session.reasoningEffort ? { reasoningEffort: session.reasoningEffort } : {}),
+                ...(session.agent ? { agent: session.agent } : {}),
+            },
+        });
+        // Freshly resolved (not yet frozen) → persist it so it can't drift later.
+        if (!plan.alreadyFrozen) {
+            await this.activeSessionStore.freeze(sessionKey, {
+                runtime: plan.runtime,
+                model: plan.model,
+                reasoningEffort: plan.reasoningEffort,
+                agent: plan.agent,
+            });
+        }
+        return {
+            provider: plan.runtime,
+            providerExplicit: true,
+            model: plan.model,
+            reasoningEffort: plan.reasoningEffort,
+            agentName: plan.agent,
+        };
+    }
+    async buildReply(event, sessionKey, sessionId, prompt, cwd, settings) {
+        if (!["text", "post"].includes(event.message.message_type)) {
+            return {
+                text: DEFAULT_UNSUPPORTED_MESSAGE,
+                provider: settings.provider,
+            };
+        }
+        const runtimePrompt = (await this.tryBuildCardReplyPrompt(event, sessionKey, sessionId, prompt)) ?? prompt;
+        if (!runtimePrompt) {
+            return {
+                text: DEFAULT_EMPTY_MESSAGE,
+                provider: settings.provider,
+            };
+        }
+        const turn = this.registerInFlight(sessionKey);
+        try {
+            if (this.canUseCardSender()) {
+                const streamed = await this.tryBuildReplyWithCard(event, sessionKey, sessionId, runtimePrompt, cwd, turn, settings);
+                if (streamed) {
+                    return streamed;
+                }
+            }
+            return await this.buildReplyDrain(event, sessionKey, sessionId, runtimePrompt, cwd, turn, settings);
+        }
+        finally {
+            // Claim the bridge's own rollout lines before releasing the in-flight
+            // gate, so the CLI mirror's cursor sits past them and they're not
+            // mirrored back into Feishu (they were already shown live).
+            if (this.mirror && turn.codexSessionId) {
+                try {
+                    await this.mirror.claimToEof(turn.codexSessionId);
+                }
+                catch (error) {
+                    this.logger.log({
+                        event: "mirror.claim_failed",
+                        session_key: sessionKey,
+                        session_id: sessionId,
+                        error: toErrorMessage(error),
+                    });
+                }
+            }
+            this.clearInFlight(sessionKey, turn);
+        }
+    }
+    canUseCardSender() {
+        return Boolean(this.messageSender.createCard &&
+            this.messageSender.batchUpdateCard &&
+            (this.messageSender.sendInteractive || this.messageSender.replyInteractive));
+    }
+    async tryBuildReplyWithCard(event, sessionKey, sessionId, runtimePrompt, cwd, turn, settings) {
+        let started;
+        try {
+            started = await this.conversationRuntime.runLive({
+                message: runtimePrompt,
+                threadId: sessionId,
+                // When an agent is selected but the user hasn't pinned a runtime, pass
+                // undefined so the agent spec's `executor.runtime` decides the backend.
+                provider: settings.providerExplicit || !settings.agentName ? settings.provider : undefined,
+                model: settings.model,
+                reasoningEffort: settings.reasoningEffort,
+                agentName: settings.agentName,
+                cwd,
+                signal: turn.abort.signal,
+                steer: turn.steer,
+            });
+        }
+        catch (error) {
+            const errorMessage = toErrorMessage(error);
+            this.logger.log({
+                event: "message.failed",
+                tenant_key: event.tenant_key ?? event.sender.tenant_key,
+                chat_id: event.message.chat_id,
+                thread_id: event.message.thread_id,
+                message_id: event.message.message_id,
+                session_key: sessionKey,
+                session_id: sessionId,
+                provider: settings.provider,
+                error: errorMessage,
+            });
+            return {
+                text: `处理失败：${errorMessage}`,
+                provider: settings.provider,
+            };
+        }
+        const orchestrator = new LarkSessionCardController({
+            sender: this.messageSender,
+            session: {
+                chatId: event.message.chat_id,
+                messageId: event.message.message_id,
+                threadId: event.message.thread_id,
+            },
+            meta: {
+                runtime: getRuntimeProfile(started.provider).shortLabel,
+                model: this.displayModel(started.model),
+                effort: settings.reasoningEffort ?? null,
+                // Same stable id the conversation directory keys on, so the footer id is
+                // exactly what `/resume <id>` accepts (conversationKey === sessionKey).
+                resumeShortId: deriveConversationShortId(sessionKey),
+            },
+            throttleMs: this.cardThrottleMs,
+            logger: { log: (entry) => this.logger.log({ event: "card.update", ...entry }) },
+            stopButton: { sessionKey },
+            onRuntimeSession: (runtimeSessionId) => this.noteRuntimeSession(turn, runtimeSessionId),
+        });
+        try {
+            // Live co-drive single-writer: `runLive` yields THIS turn's canonical events
+            // off the session bus (the forwarder mirrors them). The server's `onMirror`
+            // already persisted them — do NOT persist again here (that was the double
+            // write). Only render the card. Lark shows the user message inline from the
+            // chat, so keep `session.input.consumed` out of the card render.
+            for await (const sessionEvent of started.generator) {
+                if (sessionEvent.type !== "session.input.consumed") {
+                    await orchestrator.ingest(sessionEvent);
+                }
+            }
+            await orchestrator.finalizeAll("completed");
+        }
+        catch (error) {
+            const errorMessage = toErrorMessage(error);
+            const cancelled = error instanceof CodexRuntimeError && error.code === "codex_cancelled";
+            this.logger.log({
+                event: cancelled ? "message.cancelled" : "message.failed",
+                tenant_key: event.tenant_key ?? event.sender.tenant_key,
+                chat_id: event.message.chat_id,
+                thread_id: event.message.thread_id,
+                message_id: event.message.message_id,
+                session_key: sessionKey,
+                session_id: sessionId,
+                provider: this.provider,
+                error: errorMessage,
+            });
+            // The normalizer already emitted `response.failed` (so the card shows the
+            // error); this finalizeAll is a safety net for any still-open card.
+            await orchestrator.finalizeAll(cancelled ? "cancelled" : "failed");
+            return {
+                // A user-triggered cancel needs no redundant chat reply (the card carries it).
+                text: cancelled ? "" : `处理失败：${errorMessage}`,
+                provider: started.provider,
+                model: started.model,
+            };
+        }
+        // The card carries the answer; only emit a plain-text reply when no card
+        // could be posted (e.g. the card API failed), so the chat isn't left empty.
+        return {
+            text: orchestrator.cardStarted ? "" : orchestrator.fallbackText.trim() || DEFAULT_EMPTY_RESPONSE,
+            provider: started.provider,
+            model: started.model,
+        };
+    }
+    /**
+     * On the turn's first `session.status` carrying a runtime session id, bind it
+     * to the in-flight turn and register it with the CLI mirror (so the mirror
+     * watches that rollout file, and the bridge's own lines are later claimed).
+     */
+    noteRuntimeSession(turn, runtimeSessionId) {
+        if (turn.codexSessionId || !runtimeSessionId) {
+            return;
+        }
+        turn.codexSessionId = runtimeSessionId;
+        if (this.mirror) {
+            void this.mirror.noteBoundSession(runtimeSessionId).catch((error) => {
+                this.logger.log({
+                    event: "mirror.note_failed",
+                    session_key: runtimeSessionId,
+                    error: toErrorMessage(error),
+                });
+            });
+        }
+    }
+    async buildReplyDrain(event, sessionKey, sessionId, runtimePrompt, cwd, turn, settings) {
+        try {
+            // Live co-drive: inject the turn and collect the reply text from the turn's
+            // mirrored bus events (the server's onMirror persists them — we only read).
+            const started = await this.conversationRuntime.runLive({
+                message: runtimePrompt,
+                threadId: sessionId,
+                provider: settings.providerExplicit || !settings.agentName ? settings.provider : undefined,
+                model: settings.model,
+                reasoningEffort: settings.reasoningEffort,
+                agentName: settings.agentName,
+                cwd,
+                signal: turn.abort.signal,
+                steer: turn.steer,
+            });
+            const answer = await collectLiveRun(started.generator);
+            return {
+                text: answer.trim() || DEFAULT_EMPTY_RESPONSE,
+                provider: started.provider,
+                model: started.model,
+            };
+        }
+        catch (error) {
+            const errorMessage = toErrorMessage(error);
+            this.logger.log({
+                event: "message.failed",
+                tenant_key: event.tenant_key ?? event.sender.tenant_key,
+                chat_id: event.message.chat_id,
+                thread_id: event.message.thread_id,
+                message_id: event.message.message_id,
+                session_key: sessionKey,
+                session_id: sessionId,
+                provider: settings.provider,
+                error: errorMessage,
+            });
+            return {
+                text: `处理失败：${errorMessage}`,
+                provider: settings.provider,
+            };
+        }
+    }
+    async sendReplyText(event, text) {
+        const chunks = chunkLarkReplyText(text);
+        if (chunks.length === 0) {
+            return false;
+        }
+        for (const [index, chunk] of chunks.entries()) {
+            const uuid = `lark-reply:${event.message.message_id}:${index}`;
+            if (event.message.thread_id) {
+                await this.messageSender.replyText({
+                    messageId: event.message.message_id,
+                    text: chunk,
+                    uuid,
+                    replyInThread: true,
+                });
+            }
+            else {
+                await this.messageSender.createText({
+                    chatId: event.message.chat_id,
+                    text: chunk,
+                    uuid,
+                });
+            }
+        }
+        return true;
+    }
+}
+/** Per-instance option readers: parse raw `channels.<id>.options` values
+ *  (strings from JSON) into the typed shapes the ingestor expects; `undefined`
+ *  ⇒ "not set for this instance" so the caller falls back to global config. */
+function larkStringOption(options, key) {
+    const value = options?.[key];
+    return typeof value === "string" && value.trim() ? value.trim() : undefined;
+}
+function larkBoolOption(options, key) {
+    const value = options?.[key];
+    if (typeof value === "boolean")
+        return value;
+    if (typeof value === "string" && value.trim())
+        return value.trim().toLowerCase() === "true";
+    return undefined;
+}
+function larkListOption(options, key) {
+    const value = options?.[key];
+    if (Array.isArray(value))
+        return value.map(String).map((entry) => entry.trim()).filter(Boolean);
+    if (typeof value === "string" && value.trim()) {
+        return value.split(",").map((entry) => entry.trim()).filter(Boolean);
+    }
+    return undefined;
+}
+export class LocalLarkBotRuntime {
+    clientProvider;
+    messageIngestor;
+    logger;
+    connected = false;
+    lastEventAt = null;
+    lastError = null;
+    constructor({ executionDefaults, agentCatalog, conversationRuntime, options, defaultAgent, logger = defaultLogger, clientProvider = new LarkClientProvider(options, larkSdkLogger(logger)), messageIngestor, capabilities, activeSessionStore: injectedActiveSessionStore, conversationDirectory: injectedConversationDirectory, sessionTitleWriter, sessionProvisioner, }) {
+        this.clientProvider = clientProvider;
+        this.logger = logger;
+        if (messageIngestor) {
+            this.messageIngestor = messageIngestor;
+            return;
+        }
+        if (!clientProvider) {
+            return;
+        }
+        if (!injectedConversationDirectory || !injectedActiveSessionStore) {
+            throw new Error("LocalLarkBotRuntime requires explicit plugin-scoped state stores");
+        }
+        const conversationDirectory = injectedConversationDirectory;
+        // The conversation → current-session routing map is plugin-owned state.
+        const activeSessionStore = injectedActiveSessionStore;
+        const messageSender = clientProvider.getMessageSender();
+        const larkCwd = larkStringOption(options, "LARK_CWD");
+        if (!executionDefaults || !agentCatalog) {
+            throw new Error("LocalLarkBotRuntime requires host execution defaults and an agent catalog adapter");
+        }
+        const allowedRoots = [...new Set([
+                ...executionDefaults.allowedRoots.map((root) => path.resolve(root)),
+                ...(larkCwd ? [path.resolve(larkCwd)] : []),
+            ])];
+        const ingestor = new LarkMessageIngestor({
+            conversationRuntime,
+            messageSender,
+            cwd: larkCwd,
+            defaultRuntime: executionDefaults.runtime,
+            defaultAgent: defaultAgent ?? executionDefaults.defaultAgent,
+            agentCatalog,
+            activeSessionStore,
+            conversationDirectory,
+            logger,
+            capabilities,
+            allowedRoots,
+            disableP2p: larkBoolOption(options, "LARK_DISABLE_P2P") ?? false,
+            groupAllowlistEnabled: larkBoolOption(options, "LARK_GROUP_ALLOWLIST_ENABLED") ?? false,
+            groupAllowlist: larkListOption(options, "LARK_GROUP_ALLOWLIST") ?? [],
+            sessionTitleWriter,
+            sessionProvisioner,
+        });
+        this.messageIngestor = ingestor;
+    }
+    getStatus() {
+        return {
+            connected: this.connected,
+            mode: "ws",
+            last_event_at: this.lastEventAt,
+            last_error: this.lastError,
+        };
+    }
+    async start() {
+        if (!this.clientProvider || !this.messageIngestor) {
+            return;
+        }
+        // Resolve our own open_id before connecting so group `@`-mention routing is
+        // in effect for the very first message. Best-effort: on failure the
+        // ingestor keeps its legacy "any mention triggers" behavior.
+        if (this.clientProvider.getBotOpenId) {
+            const botOpenId = await this.clientProvider.getBotOpenId().catch(() => null);
+            this.messageIngestor.setBotOpenId(botOpenId);
+            this.logger.log({
+                event: botOpenId ? "runtime.bot_identity_resolved" : "runtime.bot_identity_unresolved",
+            });
+        }
+        try {
+            await this.clientProvider.start({
+                onMessage: (event) => {
+                    this.lastEventAt = new Date().toISOString();
+                    void this.messageIngestor?.ingest(event).catch((error) => {
+                        this.lastError = toErrorMessage(error);
+                        this.logger.log({
+                            event: "runtime.ingest_failed",
+                            error: this.lastError,
+                            tenant_key: event.tenant_key ?? event.sender.tenant_key,
+                            chat_id: event.message.chat_id,
+                            thread_id: event.message.thread_id,
+                            message_id: event.message.message_id,
+                        });
+                    });
+                },
+                onCardAction: async (cardEvent) => {
+                    this.lastEventAt = new Date().toISOString();
+                    try {
+                        return await this.messageIngestor.ingestCardAction(cardEvent);
+                    }
+                    catch (error) {
+                        this.lastError = toErrorMessage(error);
+                        this.logger.log({
+                            event: "runtime.card_action_failed",
+                            error: this.lastError,
+                            message_id: cardEvent.messageId,
+                        });
+                        return {
+                            toast: {
+                                type: "error",
+                                content: `卡片操作失败：${this.lastError}`,
+                            },
+                        };
+                    }
+                },
+            });
+            this.connected = true;
+            this.lastError = null;
+            this.logger.log({
+                event: "runtime.connected",
+            });
+        }
+        catch (error) {
+            this.connected = false;
+            this.lastError = toErrorMessage(error);
+            this.logger.log({
+                event: "runtime.connection_failed",
+                error: this.lastError,
+            });
+            throw error;
+        }
+    }
+    async stop() {
+        if (!this.clientProvider) {
+            return;
+        }
+        await this.clientProvider.stop();
+        this.connected = false;
+        this.logger.log({
+            event: "runtime.disconnected",
+        });
+    }
+}