pikiloop 0.4.0

package/dist/channels/feishu/bot.js

@@ -0,0 +1,1275 @@
+/**
+ * bot-feishu.ts — Feishu bot orchestration: commands, streaming, artifacts, lifecycle.
+ *
+ * Follows the same pattern as bot-telegram.ts:
+ *   - Commands use shared data layer (bot-commands.ts) + Feishu renderer
+ *   - Messages flow through the streaming pipeline
+ *   - LivePreview provides real-time streaming updates via card edits
+ */
+import os from 'node:os';
+import fs from 'node:fs';
+import path from 'node:path';
+import { Bot, normalizeAgent, fmtTokens, buildPrompt, parseAllowedChatIds, } from '../../bot/bot.js';
+import { BOT_SHUTDOWN_FORCE_EXIT_MS, SessionMessageRegistry, buildBotMenuState, buildKnownChatEnv, buildSessionTaskId, } from '../../bot/orchestration.js';
+import { stageSessionFiles, } from '../../agent/index.js';
+import { shutdownAllDrivers } from '../../agent/driver.js';
+import { expandTilde } from '../../core/platform.js';
+import { SKILL_CMD_PREFIX, } from '../../bot/menu.js';
+import { getStartData, getSessionsPageData, getModelsListData, getSessionTurnPreviewData, getStatusDataAsync, getHostDataSync, getWorkspacesData, resolveSkillPrompt, handleGoalCommand, } from '../../bot/commands.js';
+import { buildAgentsCommandView, buildModelsCommandView, buildModeCommandView, buildSessionsCommandView, buildSkillsCommandView, decodeCommandAction, executeCommandAction, } from '../../bot/command-ui.js';
+import { LivePreview } from '../telegram/live-preview.js';
+import { registerProcessRuntime, requestProcessRestart, } from '../../core/process-control.js';
+import { feishuPreviewRenderer, buildInitialPreviewMarkdown, buildHumanLoopPromptMarkdown, buildAnsweredHumanLoopPromptMarkdown, buildFinalReplyRender, dispatchImageBlocks, renderCommandNotice, renderCommandSelectionCard, renderSessionTurnMarkdown, renderStart, renderStatus, renderHost, buildSwitchWorkdirCard, buildWorkspacesCard, resolveFeishuRegisteredPath, } from './render.js';
+import { currentHumanLoopQuestion, humanLoopOptionSelected } from '../../bot/human-loop.js';
+import { FeishuChannel } from './channel.js';
+import { splitText, supportsChannelCapability } from '../base.js';
+import { getActiveUserConfig, loadKnownChatIds } from '../../core/config/user-config.js';
+import { FEISHU_BOT_CARD_MAX } from '../../core/constants.js';
+const SHUTDOWN_EXIT_CODE = {
+    SIGINT: 130,
+    SIGTERM: 143,
+};
+const FEISHU_FILE_STAGE_REACTION = 'Get';
+function describeError(err) {
+    if (!(err instanceof Error))
+        return String(err ?? 'unknown error');
+    const parts = [`${err.name}: ${err.message}`];
+    for (const key of ['code', 'errno', 'syscall', 'address', 'port', 'host', 'hostname', 'path']) {
+        const value = err?.[key];
+        if (value != null && value !== '')
+            parts.push(`${key}=${value}`);
+    }
+    const cause = err?.cause;
+    if (cause && cause !== err)
+        parts.push(`cause=${describeError(cause)}`);
+    return parts.join(' | ');
+}
+/**
+ * Decision echo rendered as a separate Feishu message after a human-loop
+ * prompt resolves — so the answer becomes part of the conversation history
+ * rather than living only inside the now-closed card.
+ */
+function buildInteractionEchoMarkdown(summary) {
+    if (summary.status === 'cancelled')
+        return '*⊘ Prompt cancelled.*';
+    if (!summary.rows.length)
+        return null;
+    if (summary.rows.length === 1) {
+        return `**✓ Answered** · ${summary.rows[0].display}`;
+    }
+    const lines = ['**✓ Answered**'];
+    for (const row of summary.rows) {
+        lines.push(`• ${row.label}: ${row.display}`);
+    }
+    return lines.join('\n');
+}
+function formatToolLog(activity) {
+    const lines = String(activity || '')
+        .split('\n')
+        .map(line => line.trim())
+        .filter(Boolean)
+        .filter(line => (/^Read\b/.test(line)
+        || /^Edit\b/.test(line)
+        || /^Write\b/.test(line)
+        || /^List files\b/.test(line)
+        || /^Search text\b/.test(line)
+        || /^Fetch\b/.test(line)
+        || /^Search web\b/.test(line)
+        || /^Update plan\b/.test(line)
+        || /^Run task\b/.test(line)
+        || /^Run shell\b/.test(line)
+        || /^Use\b/.test(line)
+        || /^Using\b/.test(line)
+        || /^Updated\b/.test(line)
+        || /^Inspect image\b/.test(line)
+        || /^Request user input\b/.test(line)
+        || /^Run multiple tools\b/.test(line)
+        || /\bdone\b/.test(line)
+        || /\bfailed\b/.test(line)));
+    const deduped = [];
+    const seen = new Set();
+    for (const line of lines) {
+        if (seen.has(line))
+            continue;
+        seen.add(line);
+        deduped.push(line);
+    }
+    if (!deduped.length)
+        return '-';
+    const summary = deduped.slice(0, 6).join(' | ');
+    return summary.length <= 240 ? summary : `${summary.slice(0, 237).trimEnd()}...`;
+}
+// ---------------------------------------------------------------------------
+// FeishuBot
+// ---------------------------------------------------------------------------
+export class FeishuBot extends Bot {
+    appId;
+    appSecret;
+    domain;
+    channel;
+    /** Maps chatId → (messageId → sessionKey) for reply-chain session tracking. */
+    sessionMessages = new SessionMessageRegistry();
+    nextTaskId = 1;
+    shutdownInFlight = false;
+    shutdownExitCode = null;
+    shutdownForceExitTimer = null;
+    signalHandlers = {};
+    processRuntimeCleanup = null;
+    constructor() {
+        super();
+        const config = getActiveUserConfig();
+        // Merge Feishu-specific allowed IDs into base
+        if (process.env.FEISHU_ALLOWED_CHAT_IDS) {
+            for (const id of parseAllowedChatIds(process.env.FEISHU_ALLOWED_CHAT_IDS))
+                this.allowedChatIds.add(id);
+        }
+        // NOTE: persisted known chats are restored into channel.knownChats in run()
+        // (for the startup greeting / per-chat menu) — deliberately NOT into
+        // allowedChatIds. allowedChatIds is the explicit allowlist; folding known
+        // chats into it flips _isAllowed() from allow-all into allowlist-only and
+        // silently drops every new chat.
+        this.appId = String(config.feishuAppId || process.env.FEISHU_APP_ID || '').trim();
+        this.appSecret = String(config.feishuAppSecret || process.env.FEISHU_APP_SECRET || '').trim();
+        this.domain = (process.env.FEISHU_DOMAIN || 'https://open.feishu.cn').trim();
+        if (!this.appId || !this.appSecret) {
+            throw new Error('Missing Feishu credentials. Set FEISHU_APP_ID and FEISHU_APP_SECRET');
+        }
+    }
+    requestStop() {
+        super.requestStop();
+        try {
+            this.channel?.disconnect();
+        }
+        catch { }
+    }
+    onManagedConfigChange(config, opts = {}) {
+        const nextAppId = String(config.feishuAppId || process.env.FEISHU_APP_ID || '').trim();
+        const nextAppSecret = String(config.feishuAppSecret || process.env.FEISHU_APP_SECRET || '').trim();
+        if (nextAppId && nextAppId !== this.appId) {
+            this.appId = nextAppId;
+            if (!opts.initial)
+                this.log('feishu appId reloaded from setting.json');
+        }
+        if (nextAppSecret && nextAppSecret !== this.appSecret) {
+            this.appSecret = nextAppSecret;
+            if (!opts.initial)
+                this.log('feishu appSecret reloaded from setting.json');
+        }
+    }
+    static SKILL_CMD_PREFIX = SKILL_CMD_PREFIX;
+    async setupMenu() {
+        if (!supportsChannelCapability(this.channel, 'commandMenu'))
+            return;
+        const { commands, skillCount } = buildBotMenuState(this);
+        await this.channel.setMenu(commands);
+        this.log(`menu: ${commands.length} commands (${skillCount} skills)`);
+    }
+    afterSwitchWorkdir(_oldPath, _newPath) {
+        if (!this.channel)
+            return;
+        void this.setupMenu().catch(err => this.log(`menu refresh failed: ${err}`));
+    }
+    // ---- signal handling ------------------------------------------------------
+    installSignalHandlers() {
+        this.removeSignalHandlers();
+        const onSigint = () => this.beginShutdown('SIGINT');
+        const onSigterm = () => this.beginShutdown('SIGTERM');
+        this.signalHandlers = { SIGINT: onSigint, SIGTERM: onSigterm };
+        process.once('SIGINT', onSigint);
+        process.once('SIGTERM', onSigterm);
+    }
+    removeSignalHandlers() {
+        for (const sig of Object.keys(this.signalHandlers)) {
+            const handler = this.signalHandlers[sig];
+            if (handler)
+                process.off(sig, handler);
+        }
+        this.signalHandlers = {};
+    }
+    beginShutdown(sig) {
+        if (this.shutdownInFlight)
+            return;
+        this.shutdownInFlight = true;
+        this.shutdownExitCode = SHUTDOWN_EXIT_CODE[sig];
+        this.log(`${sig}, shutting down...`);
+        this.cleanupRuntimeForExit();
+        if (this.shutdownForceExitTimer)
+            clearTimeout(this.shutdownForceExitTimer);
+        this.shutdownForceExitTimer = setTimeout(() => {
+            this.log(`shutdown still pending after ${Math.floor(BOT_SHUTDOWN_FORCE_EXIT_MS / 1000)}s, forcing exit`);
+            process.exit(this.shutdownExitCode ?? 1);
+        }, BOT_SHUTDOWN_FORCE_EXIT_MS);
+        this.shutdownForceExitTimer.unref?.();
+    }
+    cleanupRuntimeForExit() {
+        try {
+            this.channel.disconnect();
+        }
+        catch { }
+        this.stopKeepAlive();
+        shutdownAllDrivers();
+    }
+    buildRestartEnv() {
+        // Hand off only the explicit allowlist. Known chats persist to setting.json
+        // (recordKnownChatId) and are restored via loadKnownChatIds, so they must NOT
+        // ride along in the allowlist env — that would re-pollute allowedChatIds on
+        // the next boot and lock out new chats.
+        return buildKnownChatEnv(this.allowedChatIds, [], 'FEISHU_ALLOWED_CHAT_IDS');
+    }
+    // ---- session tracking -----------------------------------------------------
+    createTaskId(session) {
+        return buildSessionTaskId(session, this.nextTaskId++);
+    }
+    registerSessionMessage(chatId, messageId, session) {
+        this.sessionMessages.register(chatId, messageId, session, session.workdir);
+    }
+    registerSessionMessages(chatId, messageIds, session) {
+        this.sessionMessages.registerMany(chatId, messageIds, session, session.workdir);
+    }
+    sessionFromMessage(chatId, messageId) {
+        const sessionRef = this.sessionMessages.resolve(chatId, messageId);
+        if (!sessionRef)
+            return null;
+        return this.getSessionRuntimeByKey(sessionRef.key, { allowAnyWorkdir: true })
+            || this.hydrateSessionRuntime(sessionRef);
+    }
+    ensureSession(chatId, title, files) {
+        return this.ensureSessionForChat(chatId, title, files);
+    }
+    resolveIncomingSession(ctx, text, files) {
+        const cs = this.chat(ctx.chatId);
+        const replyMessageId = ctx.replyToMessageId || null;
+        const repliedSession = this.sessionFromMessage(ctx.chatId, replyMessageId);
+        if (repliedSession) {
+            this.log(`[resolveSession] reply matched session=${repliedSession.sessionId} chat=${ctx.chatId}`);
+            this.applySessionSelection(cs, repliedSession);
+            return repliedSession;
+        }
+        const selected = this.getSelectedSession(cs);
+        if (selected)
+            return selected;
+        return this.ensureSession(ctx.chatId, text, files);
+    }
+    // ---- commands -------------------------------------------------------------
+    async cmdStart(ctx) {
+        const d = getStartData(this, ctx.chatId);
+        await ctx.reply(renderStart(d));
+    }
+    async cmdSkills(ctx) {
+        await this.sendCommandView(ctx, buildSkillsCommandView(this, ctx.chatId));
+    }
+    async sendCommandView(ctx, view) {
+        await ctx.channel.sendCard(ctx.chatId, renderCommandSelectionCard(view));
+    }
+    async replyCommandResult(ctx, result) {
+        if (result.kind === 'view') {
+            await this.sendCommandView(ctx, result.view);
+            return;
+        }
+        if (result.kind === 'skill') {
+            await this.handleMessage({ text: result.prompt, files: [] }, ctx);
+            return;
+        }
+        if (result.kind === 'notice') {
+            const sent = await ctx.reply(renderCommandNotice(result.notice));
+            if (result.session && sent)
+                this.registerSessionMessage(ctx.chatId, sent, result.session);
+            if (result.previewSession) {
+                await this.previewCurrentSessionTurn(ctx.chatId, result.previewSession.agent, result.previewSession.sessionId);
+            }
+            return;
+        }
+        await ctx.reply(result.message);
+    }
+    async applyCommandCallbackResult(ctx, result) {
+        if (result.kind === 'noop')
+            return;
+        if (result.kind === 'view') {
+            await ctx.channel.editCard(ctx.chatId, ctx.messageId, renderCommandSelectionCard(result.view));
+            return;
+        }
+        if (result.kind === 'skill') {
+            await this.handleMessage({ text: result.prompt, files: [] }, this.callbackToMessageContext(ctx));
+            return;
+        }
+        await ctx.editReply(ctx.messageId, renderCommandNotice(result.notice));
+        if (result.session)
+            this.registerSessionMessage(ctx.chatId, ctx.messageId, result.session);
+        if (result.previewSession) {
+            await this.previewCurrentSessionTurn(ctx.chatId, result.previewSession.agent, result.previewSession.sessionId);
+        }
+    }
+    sessionsPageSize = 5;
+    buildStopKeyboard(actionId, opts) {
+        if (!actionId)
+            return undefined;
+        if (opts?.queued) {
+            return {
+                rows: [{
+                        actions: [
+                            {
+                                tag: 'button',
+                                text: { tag: 'plain_text', content: 'Recall' },
+                                value: { action: `tsk:stop:${actionId}` },
+                            },
+                            {
+                                tag: 'button',
+                                text: { tag: 'plain_text', content: 'Steer' },
+                                value: { action: `tsk:steer:${actionId}` },
+                            },
+                        ],
+                    }],
+            };
+        }
+        return {
+            rows: [{
+                    actions: [{
+                            tag: 'button',
+                            text: { tag: 'plain_text', content: 'Stop' },
+                            value: { action: `tsk:stop:${actionId}` },
+                        }],
+                }],
+        };
+    }
+    async cmdSessions(ctx, args) {
+        const arg = args.trim().toLowerCase();
+        if (arg === 'new') {
+            await this.replyCommandResult(ctx, await executeCommandAction(this, ctx.chatId, { kind: 'session.new' }, { sessionsPageSize: this.sessionsPageSize }));
+            return;
+        }
+        const pageMatch = arg.match(/^p(\d+)$/);
+        if (pageMatch) {
+            await this.replyCommandResult(ctx, await executeCommandAction(this, ctx.chatId, { kind: 'sessions.page', page: parseInt(pageMatch[1], 10) - 1 }, { sessionsPageSize: this.sessionsPageSize }));
+            return;
+        }
+        const idx = parseInt(arg, 10);
+        if (!isNaN(idx) && idx >= 1) {
+            const d = await getSessionsPageData(this, ctx.chatId, 0, 100);
+            const target = d.sessions[idx - 1];
+            if (target) {
+                await this.replyCommandResult(ctx, await executeCommandAction(this, ctx.chatId, { kind: 'session.switch', sessionId: target.key }));
+                return;
+            }
+            await ctx.reply(`Session #${idx} not found.`);
+            return;
+        }
+        await this.sendCommandView(ctx, await buildSessionsCommandView(this, ctx.chatId, 0, this.sessionsPageSize));
+    }
+    async cmdStatus(ctx) {
+        const d = await getStatusDataAsync(this, ctx.chatId);
+        await ctx.reply(renderStatus(d));
+    }
+    async cmdHost(ctx) {
+        const d = getHostDataSync(this);
+        await ctx.reply(renderHost(d));
+    }
+    async cmdAgents(ctx, args) {
+        const arg = args.trim().toLowerCase();
+        if (arg) {
+            try {
+                const agent = normalizeAgent(arg);
+                await this.replyCommandResult(ctx, await executeCommandAction(this, ctx.chatId, { kind: 'agent.switch', agent }));
+                return;
+            }
+            catch {
+                // Not a valid agent name — show list
+            }
+        }
+        await this.sendCommandView(ctx, buildAgentsCommandView(this, ctx.chatId));
+    }
+    async cmdModels(ctx, args) {
+        const arg = args.trim();
+        if (arg) {
+            const d = await getModelsListData(this, ctx.chatId);
+            const idx = parseInt(arg, 10);
+            let modelId = null;
+            if (!isNaN(idx) && idx >= 1 && idx <= d.models.length) {
+                modelId = d.models[idx - 1].id;
+            }
+            else {
+                const match = d.models.find(m => m.id === arg || m.alias === arg);
+                if (match)
+                    modelId = match.id;
+            }
+            if (modelId) {
+                await this.replyCommandResult(ctx, await executeCommandAction(this, ctx.chatId, { kind: 'model.switch', modelId }));
+                return;
+            }
+        }
+        await this.sendCommandView(ctx, await buildModelsCommandView(this, ctx.chatId));
+    }
+    async cmdMode(ctx) {
+        await this.sendCommandView(ctx, buildModeCommandView(this, ctx.chatId));
+    }
+    async cmdSwitch(ctx, args) {
+        const arg = args.trim();
+        if (arg) {
+            const resolvedPath = path.resolve(expandTilde(arg));
+            if (!fs.existsSync(resolvedPath) || !fs.statSync(resolvedPath).isDirectory()) {
+                await ctx.reply(`Not a valid directory: \`${resolvedPath}\``);
+                return;
+            }
+            const oldPath = this.switchWorkdir(resolvedPath);
+            await ctx.reply(`**Workdir switched**\n\n\`${oldPath}\`\n↓\n\`${resolvedPath}\``);
+            return;
+        }
+        const wd = this.chatWorkdir(ctx.chatId);
+        const browsePath = path.dirname(wd);
+        const savedCount = getWorkspacesData(this, ctx.chatId).workspaces.length;
+        const view = buildSwitchWorkdirCard(wd, browsePath, 0, { savedWorkspaceCount: savedCount });
+        await ctx.channel.sendCard(ctx.chatId, view);
+    }
+    async cmdWorkspaces(ctx) {
+        const data = getWorkspacesData(this, ctx.chatId);
+        const view = buildWorkspacesCard(data);
+        await ctx.channel.sendCard(ctx.chatId, view);
+    }
+    async cmdRestart(ctx) {
+        await ctx.reply('**Restarting pikiloop...**\n\nPulling latest version. The bot will be back shortly.');
+        void requestProcessRestart({ log: msg => this.log(msg) });
+    }
+    async cmdGoal(ctx, args) {
+        const reply = await handleGoalCommand(this, ctx.chatId, args);
+        if (reply == null) {
+            await ctx.reply('No session selected. Use /sessions to pick one first.');
+            return;
+        }
+        await ctx.reply(reply);
+    }
+    async cmdStop(ctx) {
+        const session = this.selectedSession(ctx.chatId);
+        if (!session) {
+            await ctx.reply('No active session to stop.');
+            return;
+        }
+        const { interrupted, cancelledQueued } = this.stopTasksForSession(session.key);
+        if (!interrupted && cancelledQueued === 0) {
+            await ctx.reply('No running or queued work for the current session.');
+            return;
+        }
+        const parts = [];
+        if (interrupted)
+            parts.push('interrupted the current run');
+        if (cancelledQueued > 0)
+            parts.push(`cancelled ${cancelledQueued} queued ${cancelledQueued === 1 ? 'task' : 'tasks'}`);
+        await ctx.reply(`Stopped current session: ${parts.join(', ')}.`);
+    }
+    buildHumanLoopKeyboard(promptId) {
+        const prompt = this.humanLoopPrompt(promptId);
+        const question = prompt ? currentHumanLoopQuestion(prompt) : null;
+        const rows = [];
+        for (let index = 0; index < (question?.options?.length || 0); index++) {
+            const option = question.options[index];
+            rows.push({
+                actions: [{
+                        tag: 'button',
+                        text: { tag: 'plain_text', content: `${humanLoopOptionSelected(prompt, option.value) ? '●' : '○'} ${option.label}`.slice(0, 32) },
+                        value: { action: `hl:o:${promptId}:${index}` },
+                    }],
+            });
+        }
+        if (question?.options?.length && question.allowFreeform) {
+            rows.push({
+                actions: [{
+                        tag: 'button',
+                        text: { tag: 'plain_text', content: 'Other...' },
+                        value: { action: `hl:other:${promptId}` },
+                    }],
+            });
+        }
+        if (question?.allowEmpty) {
+            rows.push({
+                actions: [{
+                        tag: 'button',
+                        text: { tag: 'plain_text', content: 'Skip' },
+                        value: { action: `hl:skip:${promptId}` },
+                    }],
+            });
+        }
+        rows.push({
+            actions: [{
+                    tag: 'button',
+                    text: { tag: 'plain_text', content: 'Cancel' },
+                    value: { action: `hl:cancel:${promptId}` },
+                }],
+        });
+        return { rows };
+    }
+    async refreshHumanLoopPrompt(chatId, promptId) {
+        const prompt = this.humanLoopPrompt(promptId);
+        if (!prompt)
+            return;
+        const messageId = prompt.messageIds[0];
+        if (!messageId)
+            return;
+        await this.channel.editMessage(chatId, String(messageId), buildHumanLoopPromptMarkdown(prompt), {
+            keyboard: this.buildHumanLoopKeyboard(promptId),
+        }).catch(err => this.debug(`[human-loop] refresh edit failed chat=${chatId} prompt=${promptId}: ${err?.message || err}`));
+    }
+    async onInteractionAnswered(prompt, summary) {
+        const messageId = prompt.messageIds[0];
+        const chatId = prompt.chatId;
+        const closedMarkdown = buildAnsweredHumanLoopPromptMarkdown(prompt, summary);
+        if (messageId) {
+            try {
+                await this.channel.editMessage(chatId, String(messageId), closedMarkdown, {
+                    keyboard: { rows: [] },
+                });
+            }
+            catch (err) {
+                this.debug(`[human-loop] close-card edit failed chat=${chatId} prompt=${prompt.promptId}: ${err?.message || err}`);
+            }
+        }
+        const echoText = buildInteractionEchoMarkdown(summary);
+        if (!echoText)
+            return;
+        try {
+            await this.channel.send(chatId, echoText);
+        }
+        catch (err) {
+            this.debug(`[human-loop] echo send failed chat=${chatId} prompt=${prompt.promptId}: ${err?.message || err}`);
+        }
+    }
+    /**
+     * IM presenter for programmatic submissions (e.g. /goal-driven turns) so
+     * they stream to Feishu the same way a typed message does. Without this,
+     * /goal just emits a confirmation reply and the rest of the turn is
+     * invisible to the IM user.
+     */
+    async createImTaskPresenter(opts) {
+        if (typeof opts.chatId !== 'string')
+            return null;
+        const chatId = opts.chatId;
+        const startTimeMs = Date.now();
+        const startConfig = this.resolveSessionStreamConfig(opts.session);
+        const canEditMessages = supportsChannelCapability(this.channel, 'editMessages');
+        let placeholderId = null;
+        try {
+            placeholderId = await this.channel.send(chatId, buildInitialPreviewMarkdown(opts.agent, startConfig.model, startConfig.effort, false));
+            if (placeholderId)
+                this.registerSessionMessage(chatId, placeholderId, opts.session);
+        }
+        catch (e) {
+            this.debug(`[im-presenter feishu] placeholder send failed chat=${chatId}: ${e?.message || e}`);
+        }
+        this.registerTaskPlaceholders(opts.taskId, [placeholderId]);
+        let livePreview = null;
+        if (placeholderId) {
+            livePreview = new LivePreview({
+                agent: opts.agent,
+                chatId,
+                placeholderMessageId: placeholderId,
+                channel: this.channel,
+                renderer: feishuPreviewRenderer,
+                streamEditIntervalMs: 700,
+                startTimeMs,
+                canEditMessages,
+                canSendTyping: false,
+                parseMode: 'Markdown',
+                model: startConfig.model,
+                effort: startConfig.effort,
+                log: (msg) => this.debug(`[live-preview task=${opts.taskId}] ${msg}`),
+            });
+            livePreview.start();
+        }
+        const session = opts.session;
+        return {
+            onText: (text, thinking, activity, meta, plan) => {
+                livePreview?.update(text, thinking, activity, meta, plan);
+            },
+            onSuccess: async (result) => {
+                try {
+                    await livePreview?.settle();
+                }
+                catch { }
+                const effectivePlaceholderId = livePreview?.isPlaceholderAbandoned() ? null : placeholderId;
+                const finalReplyIds = await this.sendFinalReply({ chatId }, effectivePlaceholderId, opts.agent, result);
+                this.registerSessionMessages(chatId, finalReplyIds, session);
+            },
+            onFailure: async (error) => {
+                try {
+                    await livePreview?.settle();
+                }
+                catch { }
+                const fallbackPlaceholderId = livePreview?.isPlaceholderAbandoned() ? null : placeholderId;
+                const errorText = `**Error**\n\n\`${error.slice(0, 500)}\``;
+                await this.editOrSendFresh(chatId, fallbackPlaceholderId, errorText, { logTag: 'im-presenter-error' })
+                    .catch(err => this.debug(`[im-presenter feishu] error send failed chat=${chatId}: ${err?.message || err}`));
+            },
+            dispose: () => {
+                livePreview?.dispose();
+            },
+        };
+    }
+    async renderInteractionPrompt(prompt, chatId) {
+        const sent = await this.channel.send(chatId, buildHumanLoopPromptMarkdown(prompt), {
+            keyboard: this.buildHumanLoopKeyboard(prompt.promptId),
+        });
+        if (sent)
+            this.registerHumanLoopMessage(prompt.promptId, sent);
+    }
+    async safeSetMessageReaction(chatId, messageId, reactions) {
+        if (!supportsChannelCapability(this.channel, 'messageReactions'))
+            return;
+        const setReaction = this.channel?.setMessageReaction;
+        if (typeof setReaction !== 'function')
+            return;
+        try {
+            await setReaction.call(this.channel, chatId, messageId, reactions);
+        }
+        catch { }
+    }
+    // ---- streaming bridge -----------------------------------------------------
+    async handleMessage(msg, ctx) {
+        const text = msg.text.trim();
+        if (!text && !msg.files.length)
+            return;
+        const pendingPrompt = this.pendingHumanLoopPrompt(ctx.chatId);
+        if (pendingPrompt && text && !msg.files.length && !text.startsWith('/')) {
+            const result = this.humanLoopSubmitText(ctx.chatId, text);
+            if (!result) {
+                await ctx.reply('Please answer the active prompt using the buttons above.');
+                return;
+            }
+            // Completed prompts close themselves via onInteractionAnswered.
+            if (!result.completed)
+                await this.refreshHumanLoopPrompt(ctx.chatId, result.prompt.promptId);
+            return;
+        }
+        const session = this.resolveIncomingSession(ctx, text, msg.files);
+        const cs = this.chat(ctx.chatId);
+        this.applySessionSelection(cs, session);
+        // Tie the user's own message to its session so a future Feishu reply to it
+        // (their own message, or a quote-chain rooted at it) resolves back to this
+        // session instead of falling through to the chat's current default.
+        this.registerSessionMessage(ctx.chatId, ctx.messageId, session);
+        // File-only message: stage files
+        if (!text && msg.files.length) {
+            const hadPendingWork = this.sessionHasPendingWork(session);
+            const stageTask = this.queueSessionTask(session, async () => {
+                try {
+                    if (this.isSourceMessageWithdrawn(ctx.chatId, ctx.messageId)) {
+                        this.debug(`[handleMessage] skipped withdrawn file stage chat=${ctx.chatId} msg=${ctx.messageId}`);
+                        return;
+                    }
+                    const staged = stageSessionFiles({
+                        agent: session.agent,
+                        workdir: session.workdir,
+                        files: msg.files,
+                        sessionId: session.sessionId,
+                        title: undefined,
+                        threadId: session.threadId,
+                    });
+                    session.workspacePath = staged.workspacePath;
+                    session.threadId = staged.threadId;
+                    this.syncSelectedChats(session);
+                    if (!staged.importedFiles.length)
+                        throw new Error('no files persisted');
+                    this.debug(`[handleMessage] staged files chat=${ctx.chatId} session=${staged.sessionId} files=${staged.importedFiles.length}`);
+                    this.registerSessionMessage(ctx.chatId, ctx.messageId, session);
+                    await this.safeSetMessageReaction(ctx.chatId, ctx.messageId, [FEISHU_FILE_STAGE_REACTION]);
+                }
+                catch (e) {
+                    this.warn(`[handleMessage] stage files failed: ${e?.message || e}`);
+                }
+            });
+            if (hadPendingWork) {
+                void stageTask.catch(e => this.warn(`[handleMessage] stage queue failed: ${e}`));
+            }
+            else {
+                await stageTask.catch(e => this.warn(`[handleMessage] stage queue failed: ${e}`));
+            }
+            return;
+        }
+        const files = msg.files;
+        const prompt = buildPrompt(text, files);
+        const start = Date.now();
+        this.debug(`[handleMessage] start chat=${ctx.chatId} agent=${session.agent} session=${session.sessionId || '(new)'} ` +
+            `files=${files.length} prompt="${prompt.slice(0, 100)}"`);
+        const waiting = this.sessionHasPendingWork(session);
+        const taskId = this.createTaskId(session);
+        this.beginTask({
+            taskId,
+            chatId: ctx.chatId,
+            agent: session.agent,
+            sessionKey: session.key,
+            prompt,
+            attachments: files,
+            startedAt: start,
+            sourceMessageId: ctx.messageId,
+        });
+        this.emitStreamQueued(session.key, taskId);
+        const queuePosition = waiting ? this.getQueuePosition(session.key, taskId) : 0;
+        const placeholderKeyboard = this.buildStopKeyboard(this.actionIdForTask(taskId), { queued: waiting });
+        // Use the canonical resolver so the labels in the IM card match what
+        // runStream actually invokes the agent with (and what the dashboard's
+        // `start` event reports).
+        const startConfig = this.resolveSessionStreamConfig(session);
+        const model = startConfig.model;
+        const effort = startConfig.effort;
+        const placeholderId = await this.channel.send(ctx.chatId, buildInitialPreviewMarkdown(session.agent, model, effort, waiting, queuePosition), {
+            replyTo: ctx.messageId || undefined,
+            keyboard: placeholderKeyboard,
+        });
+        if (placeholderId) {
+            this.registerSessionMessage(ctx.chatId, placeholderId, session);
+        }
+        this.registerTaskPlaceholders(taskId, [placeholderId]);
+        void this.queueSessionTask(session, async () => {
+            let livePreview = null;
+            let task = null;
+            const abortController = new AbortController();
+            try {
+                task = this.markTaskRunning(taskId, () => abortController.abort());
+                if (!task || task.cancelled) {
+                    this.emitStreamCancelled(taskId, session.key);
+                    if (placeholderId) {
+                        try {
+                            await this.channel.deleteMessage(ctx.chatId, placeholderId);
+                        }
+                        catch { }
+                    }
+                    this.debug(`[handleMessage] skipped cancelled queued task chat=${ctx.chatId} msg=${ctx.messageId}`);
+                    return;
+                }
+                this.emitStreamStart(taskId, session);
+                // Task is now running — update keyboard from Recall/Steer to Stop
+                const runningKeyboard = this.buildStopKeyboard(this.actionIdForTask(taskId));
+                if (placeholderId && waiting) {
+                    try {
+                        await this.channel.editMessage(ctx.chatId, placeholderId, buildInitialPreviewMarkdown(session.agent, model, effort, false), { keyboard: runningKeyboard });
+                    }
+                    catch (e) {
+                        this.debug(`[handleMessage] queued→running keyboard refresh failed task=${taskId} placeholder=${placeholderId}: ${e?.message || e}`);
+                    }
+                }
+                if (placeholderId) {
+                    livePreview = new LivePreview({
+                        agent: session.agent,
+                        chatId: ctx.chatId,
+                        placeholderMessageId: placeholderId,
+                        channel: this.channel,
+                        renderer: feishuPreviewRenderer,
+                        streamEditIntervalMs: 700,
+                        startTimeMs: start,
+                        canEditMessages: supportsChannelCapability(this.channel, 'editMessages'),
+                        canSendTyping: false,
+                        parseMode: 'Markdown',
+                        keyboard: runningKeyboard,
+                        model,
+                        effort,
+                        log: (message) => this.debug(`[live-preview task=${taskId} placeholder=${placeholderId}] ${message}`),
+                    });
+                    livePreview.start();
+                }
+                // MCP sendFile callback: sends files to IM in real-time during the stream
+                const mcpSendFile = this.createMcpSendFileCallback(ctx);
+                const result = await this.runStream(prompt, session, files, (nextText, nextThinking, nextActivity = '', meta, plan) => {
+                    livePreview?.update(nextText, nextThinking, nextActivity, meta, plan);
+                    this.emitStreamText(taskId, session.key, nextText, nextThinking, nextActivity, meta, plan);
+                }, undefined, mcpSendFile, abortController.signal, this.createInteractionHandler(ctx.chatId, taskId), (steer) => {
+                    const currentTask = this.activeTasks.get(taskId);
+                    if (!currentTask || currentTask.cancelled || currentTask.status !== 'running')
+                        return;
+                    currentTask.steer = steer;
+                });
+                await livePreview?.settle();
+                if (task?.freezePreviewOnAbort && result.stopReason === 'interrupted') {
+                    this.emitStreamDone(taskId, session.key, {
+                        sessionId: result.sessionId || session.sessionId,
+                        incomplete: true,
+                    });
+                    const freezePlaceholderId = livePreview?.isPlaceholderAbandoned() ? null : placeholderId;
+                    const frozenMessageIds = await this.freezeSteerHandoffPreview(ctx, freezePlaceholderId, livePreview);
+                    this.registerSessionMessages(ctx.chatId, frozenMessageIds, session);
+                    this.debug(`[handleMessage] steer handoff preserved previous preview chat=${ctx.chatId} task=${taskId}`);
+                    return;
+                }
+                this.emitStreamDone(taskId, session.key, {
+                    sessionId: result.sessionId || session.sessionId,
+                    incomplete: !!result.incomplete,
+                    ...(result.ok ? {} : { error: result.error || result.message }),
+                });
+                // If LivePreview already gave up on the placeholder (Feishu rejected too
+                // many consecutive edits) skip the doomed edit attempt and send fresh.
+                const effectivePlaceholderId = livePreview?.isPlaceholderAbandoned() ? null : placeholderId;
+                const finalReplyIds = await this.sendFinalReply({ chatId: ctx.chatId }, effectivePlaceholderId, session.agent, result);
+                this.registerSessionMessages(ctx.chatId, finalReplyIds, session);
+                this.debug(`[handleMessage] end chat=${ctx.chatId} agent=${session.agent} ok=${result.ok} session=${result.sessionId || session.sessionId || '(new)'} ` +
+                    `elapsed=${result.elapsedS.toFixed(1)}s tokens=in:${fmtTokens(result.inputTokens)}/out:${fmtTokens(result.outputTokens)} ` +
+                    `tools=${formatToolLog(result.activity)}`);
+            }
+            catch (e) {
+                const fallbackPlaceholderId = livePreview?.isPlaceholderAbandoned() ? null : placeholderId;
+                if (task?.freezePreviewOnAbort && abortController.signal.aborted) {
+                    this.emitStreamDone(taskId, session.key, {
+                        sessionId: session.sessionId,
+                        incomplete: true,
+                    });
+                    const frozenMessageIds = await this.freezeSteerHandoffPreview(ctx, fallbackPlaceholderId, livePreview);
+                    this.registerSessionMessages(ctx.chatId, frozenMessageIds, session);
+                    this.debug(`[handleMessage] steer handoff preserved preview after abort chat=${ctx.chatId} task=${taskId}`);
+                    return;
+                }
+                const msgText = String(e?.message || e || 'Unknown error');
+                this.emitStreamDone(taskId, session.key, {
+                    sessionId: session.sessionId,
+                    incomplete: true,
+                    error: msgText,
+                });
+                this.warn(`[handleMessage] end chat=${ctx.chatId} agent=${session.agent} ok=false session=${session.sessionId || '(new)'} ` +
+                    `elapsed=${((Date.now() - start) / 1000).toFixed(1)}s error="${msgText.slice(0, 240)}" tools=-`);
+                const errorText = `**Error**\n\n\`${msgText.slice(0, 500)}\``;
+                await this.editOrSendFresh(ctx.chatId, fallbackPlaceholderId, errorText, { logTag: 'final-error' })
+                    .catch(err => this.debug(`[handleMessage] error reply send failed chat=${ctx.chatId}: ${err?.message || err}`));
+            }
+            finally {
+                livePreview?.dispose();
+                this.finishTask(taskId);
+                this.syncSelectedChats(session);
+            }
+        }, taskId).catch(e => {
+            this.warn(`[handleMessage] queue execution failed: ${e}`);
+            this.finishTask(taskId);
+        });
+    }
+    /** Edit the placeholder if possible; otherwise send `text` as a fresh card
+     *  anchored to the placeholder so the user always sees the result. Returns
+     *  the message id that now carries `text` (the placeholder id if the edit
+     *  succeeded, or a newly-created id on fallback). */
+    async editOrSendFresh(chatId, placeholderId, text, opts = {}) {
+        const tag = opts.logTag || 'editOrSendFresh';
+        if (placeholderId) {
+            try {
+                await this.channel.editMessage(chatId, placeholderId, text, opts.keyboard ? { keyboard: opts.keyboard } : undefined);
+                return placeholderId;
+            }
+            catch (e) {
+                this.debug(`[${tag}] placeholder edit failed, falling back to send chat=${chatId} placeholder=${placeholderId}: ${e?.message || e}`);
+            }
+            // Try anchoring the fresh send to the placeholder so the result stays in
+            // the same visual thread.
+            try {
+                const sent = await this.channel.send(chatId, text, {
+                    replyTo: placeholderId,
+                    keyboard: opts.keyboard,
+                });
+                if (sent)
+                    return sent;
+            }
+            catch (e) {
+                this.debug(`[${tag}] reply send failed, dropping reply anchor chat=${chatId} placeholder=${placeholderId}: ${e?.message || e}`);
+            }
+        }
+        // Last resort: standalone fresh card.
+        try {
+            return await this.channel.send(chatId, text, { keyboard: opts.keyboard });
+        }
+        catch (e) {
+            this.warn(`[${tag}] all send paths failed chat=${chatId}: ${e?.message || e}`);
+            return null;
+        }
+    }
+    async freezeSteerHandoffPreview(ctx, placeholderId, livePreview) {
+        if (!placeholderId)
+            return [];
+        const previewMarkdown = livePreview?.getRenderedPreview()?.trim() || '';
+        if (!previewMarkdown)
+            return [placeholderId];
+        const finalId = await this.editOrSendFresh(ctx.chatId, placeholderId, previewMarkdown, {
+            keyboard: { rows: [] },
+            logTag: 'freeze-steer',
+        });
+        return finalId ? [finalId] : [];
+    }
+    async sendFinalReply(anchor, placeholderId, agent, result) {
+        const rendered = buildFinalReplyRender(agent, result);
+        const messageIds = [];
+        const MAX_CARD = FEISHU_BOT_CARD_MAX;
+        if (rendered.fullText.length <= MAX_CARD) {
+            // Fits in one card — try to edit the placeholder, fall back to a fresh
+            // card if Feishu rejected the patch (message too old, recalled, ...).
+            const finalId = await this.editOrSendFresh(anchor.chatId, placeholderId, rendered.fullText, { logTag: 'final-reply' });
+            if (finalId)
+                messageIds.push(finalId);
+        }
+        else {
+            // Split: first card has header + truncated body + footer, continuation as separate cards
+            const maxFirst = MAX_CARD - rendered.headerText.length - rendered.footerText.length;
+            let firstBody;
+            let remaining;
+            if (maxFirst > 200) {
+                let cut = rendered.bodyText.lastIndexOf('\n', maxFirst);
+                if (cut < maxFirst * 0.3)
+                    cut = maxFirst;
+                firstBody = rendered.bodyText.slice(0, cut);
+                remaining = rendered.bodyText.slice(cut);
+            }
+            else {
+                firstBody = '';
+                remaining = rendered.bodyText;
+            }
+            const firstText = `${rendered.headerText}${firstBody}${rendered.footerText}`;
+            const firstId = await this.editOrSendFresh(anchor.chatId, placeholderId, firstText, { logTag: 'final-reply-head' });
+            if (firstId)
+                messageIds.push(firstId);
+            if (remaining.trim()) {
+                const chunks = splitText(remaining, MAX_CARD);
+                for (const chunk of chunks) {
+                    const sent = await this.channel.send(anchor.chatId, chunk);
+                    if (sent)
+                        messageIds.push(sent);
+                }
+            }
+        }
+        // Dispatch any image MessageBlocks the agent produced this turn.
+        const lastId = messageIds[messageIds.length - 1];
+        const dispatched = await dispatchImageBlocks(this.channel, result.assistantBlocks, {
+            chatId: anchor.chatId,
+            replyTo: lastId,
+            log: (message) => this.debug(message),
+        });
+        for (const entry of dispatched) {
+            if (typeof entry.messageId === 'string')
+                messageIds.push(entry.messageId);
+        }
+        return messageIds;
+    }
+    /** Create an MCP sendFile callback bound to a Feishu chat context. */
+    createMcpSendFileCallback(ctx) {
+        return async (filePath, opts) => {
+            try {
+                await this.channel.sendFile(ctx.chatId, filePath, {
+                    caption: opts?.caption,
+                    replyTo: ctx.messageId,
+                    asPhoto: opts?.kind === 'photo',
+                });
+                return { ok: true };
+            }
+            catch (e) {
+                this.log(`[mcp] sendFile failed: ${filePath} error=${e?.message || e}`);
+                return { ok: false, error: e?.message || 'send failed' };
+            }
+        };
+    }
+    // ---- command router -------------------------------------------------------
+    async handleCommand(cmd, args, ctx) {
+        try {
+            switch (cmd) {
+                case 'start':
+                    await this.cmdStart(ctx);
+                    return;
+                case 'sessions':
+                    await this.cmdSessions(ctx, args);
+                    return;
+                case 'agents':
+                    await this.cmdAgents(ctx, args);
+                    return;
+                case 'models':
+                    await this.cmdModels(ctx, args);
+                    return;
+                case 'mode':
+                    await this.cmdMode(ctx);
+                    return;
+                case 'skills':
+                    await this.cmdSkills(ctx);
+                    return;
+                case 'goal':
+                    await this.cmdGoal(ctx, args);
+                    return;
+                case 'stop':
+                    await this.cmdStop(ctx);
+                    return;
+                case 'status':
+                    await this.cmdStatus(ctx);
+                    return;
+                case 'host':
+                    await this.cmdHost(ctx);
+                    return;
+                case 'switch':
+                    await this.cmdSwitch(ctx, args);
+                    return;
+                case 'workspaces':
+                    await this.cmdWorkspaces(ctx);
+                    return;
+                case 'restart':
+                    await this.cmdRestart(ctx);
+                    return;
+                default:
+                    // Skill commands
+                    if (cmd.startsWith(FeishuBot.SKILL_CMD_PREFIX)) {
+                        await this.cmdSkill(cmd, args, ctx);
+                        return;
+                    }
+                    // Unknown command — treat as message
+                    await this.handleMessage({ text: `/${cmd}${args ? ' ' + args : ''}`, files: [] }, ctx);
+            }
+        }
+        catch (e) {
+            this.log(`cmd error: ${e}`);
+            await ctx.reply(`Error: ${String(e).slice(0, 200)}`);
+        }
+    }
+    async cmdSkill(cmd, args, ctx) {
+        const resolved = resolveSkillPrompt(this, ctx.chatId, cmd, args);
+        if (!resolved) {
+            await ctx.reply(`Skill not found for command /${cmd} in:\n\`${this.chatWorkdir(ctx.chatId)}\``);
+            return;
+        }
+        this.log(`skill: ${resolved.skillName} agent=${this.chat(ctx.chatId).agent}${args.trim() ? ` args="${args.trim()}"` : ''}`);
+        await this.handleMessage({ text: resolved.prompt, files: [] }, ctx);
+    }
+    callbackToMessageContext(ctx) {
+        return {
+            chatId: ctx.chatId,
+            messageId: ctx.messageId,
+            from: ctx.from,
+            chatType: 'p2p',
+            replyToMessageId: null,
+            reply: (text, opts) => ctx.channel.send(ctx.chatId, text, opts),
+            editReply: (msgId, text, opts) => ctx.channel.editMessage(ctx.chatId, msgId, text, opts),
+            channel: ctx.channel,
+            raw: ctx.raw,
+        };
+    }
+    // ---- callback handlers ----------------------------------------------------
+    async handleCallback(data, ctx) {
+        try {
+            if (await this.handleHumanLoopCallback(data, ctx))
+                return;
+            if (await this.handleTaskStopCallback(data, ctx))
+                return;
+            if (await this.handleTaskSteerCallback(data, ctx))
+                return;
+            if (await this.handleSwitchNavigateCallback(data, ctx))
+                return;
+            if (await this.handleSwitchSelectCallback(data, ctx))
+                return;
+            if (await this.handleWorkspacesCallback(data, ctx))
+                return;
+            const action = decodeCommandAction(data);
+            if (!action)
+                return;
+            const result = await executeCommandAction(this, ctx.chatId, action, {
+                sessionsPageSize: this.sessionsPageSize,
+            });
+            await this.applyCommandCallbackResult(ctx, result);
+        }
+        catch (e) {
+            this.log(`callback error: ${e}`);
+        }
+    }
+    async handleHumanLoopCallback(data, ctx) {
+        if (!data.startsWith('hl:'))
+            return false;
+        const [, action, promptId, rawIndex] = data.split(':');
+        const prompt = this.humanLoopPrompt(promptId);
+        if (!prompt)
+            return true;
+        if (action === 'cancel') {
+            this.humanLoopCancel(promptId, 'Prompt cancelled from Feishu.');
+            return true;
+        }
+        if (action === 'skip') {
+            const result = this.humanLoopSkip(promptId);
+            if (!result)
+                return true;
+            if (!result.completed)
+                await this.refreshHumanLoopPrompt(ctx.chatId, promptId);
+            return true;
+        }
+        if (action === 'other') {
+            const result = this.humanLoopSelectOption(promptId, '__other__', { requestFreeform: true });
+            if (!result)
+                return true;
+            await this.refreshHumanLoopPrompt(ctx.chatId, promptId);
+            return true;
+        }
+        if (action === 'o') {
+            const index = Number.parseInt(rawIndex || '', 10);
+            const question = this.humanLoopCurrentQuestion(promptId);
+            const option = Number.isFinite(index) ? question?.options?.[index] : null;
+            if (!option)
+                return true;
+            const result = this.humanLoopSelectOption(promptId, option.value);
+            if (!result)
+                return true;
+            if (!result.completed)
+                await this.refreshHumanLoopPrompt(ctx.chatId, promptId);
+            return true;
+        }
+        return true;
+    }
+    async handleTaskStopCallback(data, ctx) {
+        if (!data.startsWith('tsk:stop:'))
+            return false;
+        const actionId = data.slice('tsk:stop:'.length).trim();
+        const result = this.stopTaskByActionId(actionId);
+        if (!result.task)
+            return true;
+        if (result.cancelled) {
+            try {
+                await this.channel.deleteMessage(ctx.chatId, ctx.messageId);
+            }
+            catch { }
+        }
+        return true;
+    }
+    async handleTaskSteerCallback(data, ctx) {
+        if (!data.startsWith('tsk:steer:'))
+            return false;
+        const actionId = data.slice('tsk:steer:'.length).trim();
+        const result = await this.steerTaskByActionId(actionId);
+        if (!result.task)
+            return true;
+        // The queued task will naturally run next after the running task is interrupted
+        return true;
+    }
+    async handleSwitchNavigateCallback(data, ctx) {
+        if (!data.startsWith('sw:n:'))
+            return false;
+        const [pathId, pageRaw] = data.slice(5).split(':');
+        const browsePath = resolveFeishuRegisteredPath(parseInt(pathId, 10));
+        if (!browsePath)
+            return true;
+        const wd = this.chatWorkdir(ctx.chatId);
+        const view = buildSwitchWorkdirCard(wd, browsePath, parseInt(pageRaw, 10) || 0);
+        await ctx.channel.editCard(ctx.chatId, ctx.messageId, view);
+        return true;
+    }
+    async handleSwitchSelectCallback(data, ctx) {
+        if (!data.startsWith('sw:s:'))
+            return false;
+        const dirPath = resolveFeishuRegisteredPath(parseInt(data.slice(5), 10));
+        if (!dirPath || !fs.existsSync(dirPath) || !fs.statSync(dirPath).isDirectory())
+            return true;
+        const oldPath = this.switchWorkdir(dirPath);
+        await ctx.editReply(ctx.messageId, `**Workdir**\n● \`${oldPath}\`\n→ \`${dirPath}\``);
+        return true;
+    }
+    async handleWorkspacesCallback(data, ctx) {
+        if (data.startsWith('wsp:p:')) {
+            const page = parseInt(data.slice('wsp:p:'.length), 10) || 0;
+            const view = buildWorkspacesCard(getWorkspacesData(this, ctx.chatId), page);
+            await ctx.channel.editCard(ctx.chatId, ctx.messageId, view);
+            return true;
+        }
+        if (data.startsWith('wsp:s:')) {
+            const dirPath = resolveFeishuRegisteredPath(parseInt(data.slice('wsp:s:'.length), 10));
+            if (!dirPath || !fs.existsSync(dirPath) || !fs.statSync(dirPath).isDirectory())
+                return true;
+            const oldPath = this.switchWorkdir(dirPath);
+            await ctx.editReply(ctx.messageId, `**Workdir**\n● \`${oldPath}\`\n→ \`${dirPath}\``);
+            return true;
+        }
+        return false;
+    }
+    async previewCurrentSessionTurn(chatId, agent, sessionId) {
+        try {
+            const preview = await getSessionTurnPreviewData(this, agent, sessionId, 50, this.chatWorkdir(chatId));
+            if (!preview)
+                return;
+            const previewMarkdown = renderSessionTurnMarkdown(preview.userText, preview.assistantText);
+            if (!previewMarkdown)
+                return;
+            const sent = await this.channel.send(chatId, previewMarkdown);
+            if (sessionId) {
+                const runtime = this.getSessionRuntimeByKey(this.sessionKey(agent, sessionId));
+                if (runtime && sent)
+                    this.registerSessionMessage(chatId, sent, runtime);
+            }
+        }
+        catch {
+            // non-critical
+        }
+    }
+    async handleMessageRecalled(messageId, chatId) {
+        const task = this.withdrawQueuedTaskBySourceMessage(chatId, messageId);
+        if (!task)
+            return;
+        for (const placeholderId of task.placeholderMessageIds || []) {
+            try {
+                await this.channel.deleteMessage(chatId, String(placeholderId));
+            }
+            catch { }
+        }
+        this.log(`[message-recalled] cancelled queued task chat=${chatId} msg=${messageId} session=${task.sessionKey}`);
+    }
+    // ---- lifecycle ------------------------------------------------------------
+    async run() {
+        const tmpDir = path.join(os.tmpdir(), 'pikiloop');
+        fs.mkdirSync(tmpDir, { recursive: true });
+        this.channel = new FeishuChannel({
+            appId: this.appId,
+            appSecret: this.appSecret,
+            domain: this.domain,
+            workdir: tmpDir,
+            allowedChatIds: this.allowedChatIds.size
+                ? this.allowedChatIds
+                : undefined,
+        });
+        // Restore persisted known chats into the channel so the startup greeting and
+        // per-chat menu can address them — without polluting the allowlist.
+        for (const id of loadKnownChatIds('feishu'))
+            this.channel.knownChats.add(id);
+        this.processRuntimeCleanup?.();
+        this.processRuntimeCleanup = registerProcessRuntime({
+            label: 'feishu',
+            getActiveTaskCount: () => this.activeTasks.size,
+            prepareForRestart: () => this.cleanupRuntimeForExit(),
+            buildRestartEnv: () => this.buildRestartEnv(),
+        });
+        this.installSignalHandlers();
+        try {
+            const bot = await this.channel.connect();
+            this.connected = true;
+            this.log(`bot: ${bot.displayName} (id=${bot.id})`);
+            for (const ag of this.fetchAgents().agents) {
+                this.log(`agent ${ag.agent}: ${ag.path || 'NOT FOUND'}`);
+            }
+            this.log(`config: agent=${this.defaultAgent} workdir=${this.workdir} timeout=${this.runTimeout}s`);
+            this.channel.onCommand((cmd, args, ctx) => this.handleCommand(cmd, args, ctx));
+            this.channel.onMessage((msg, ctx) => this.handleMessage(msg, ctx));
+            this.channel.onCallback((data, ctx) => this.handleCallback(data, ctx));
+            this.channel.onMessageRecalled((messageId, chatId) => this.handleMessageRecalled(messageId, chatId));
+            this.channel.onError(err => this.log(`error: ${err}`));
+            this.startKeepAlive();
+            void this.setupMenu().catch(err => this.log(`menu setup failed: ${err}`));
+            void this.sendStartupNotice().catch(err => this.log(`startup notice failed: ${err}`));
+            this.log('✓ Feishu connected, WebSocket listening — ready to receive messages');
+            await this.channel.listen();
+            this.stopKeepAlive();
+            this.log('stopped');
+        }
+        finally {
+            this.stopKeepAlive();
+            if (this.shutdownForceExitTimer)
+                clearTimeout(this.shutdownForceExitTimer);
+            this.removeSignalHandlers();
+            this.processRuntimeCleanup?.();
+            this.processRuntimeCleanup = null;
+            if (this.shutdownInFlight)
+                process.exit(this.shutdownExitCode ?? 1);
+        }
+    }
+    async sendStartupNotice() {
+        const targets = new Set(this.allowedChatIds);
+        for (const cid of this.channel.knownChats)
+            targets.add(cid);
+        if (!targets.size) {
+            this.log('no known chats for startup notice');
+            return;
+        }
+        for (const cid of targets) {
+            try {
+                const d = getStartData(this, cid);
+                const text = renderStart(d);
+                await this.channel.send(cid, text);
+                this.log(`startup notice sent to chat=${cid}`);
+            }
+            catch (e) {
+                this.log(`startup notice failed for chat=${cid}: ${e}`);
+            }
+        }
+    }
+}