pikiclaw 0.2.35

package/dist/bot-feishu.js

@@ -0,0 +1,752 @@
+/**
+ * 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, VERSION, normalizeAgent, fmtTokens, buildPrompt, parseAllowedChatIds, } from './bot.js';
+import { stageSessionFiles, } from './code-agent.js';
+import { shutdownAllDrivers } from './agent-driver.js';
+import { buildDefaultMenuCommands, SKILL_CMD_PREFIX, } from './bot-menu.js';
+import { getStartData, getSessionsPageData, getModelsListData, getSessionTurnPreviewData, getStatusDataAsync, getHostDataSync, resolveSkillPrompt, } from './bot-commands.js';
+import { buildAgentsCommandView, buildModelsCommandView, buildSessionsCommandView, buildSkillsCommandView, decodeCommandAction, executeCommandAction, } from './bot-command-ui.js';
+import { LivePreview } from './bot-telegram-live-preview.js';
+import { formatActiveTaskRestartError, getActiveTaskCount, registerProcessRuntime, requestProcessRestart, } from './process-control.js';
+import { feishuPreviewRenderer, buildInitialPreviewMarkdown, buildFinalReplyRender, renderCommandNotice, renderCommandSelectionCard, renderSessionTurnMarkdown, renderStart, renderStatus, renderHost, buildSwitchWorkdirCard, resolveFeishuRegisteredPath, } from './bot-feishu-render.js';
+import { FeishuChannel } from './channel-feishu.js';
+import { splitText, supportsChannelCapability } from './channel-base.js';
+import { getActiveUserConfig } from './user-config.js';
+const SHUTDOWN_EXIT_CODE = {
+    SIGINT: 130,
+    SIGTERM: 143,
+};
+const SHUTDOWN_FORCE_EXIT_MS = 3_000;
+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(' | ');
+}
+// ---------------------------------------------------------------------------
+// FeishuBot
+// ---------------------------------------------------------------------------
+export class FeishuBot extends Bot {
+    appId;
+    appSecret;
+    domain;
+    channel;
+    /** Maps chatId → (messageId → sessionKey) for reply-chain session tracking. */
+    sessionMessages = new Map();
+    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);
+        }
+        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');
+        }
+    }
+    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 res = this.fetchAgents();
+        const installedCount = res.agents.filter(a => a.installed).length;
+        const skillRes = this.fetchSkills();
+        const commands = buildDefaultMenuCommands(installedCount, skillRes.skills);
+        await this.channel.setMenu(commands);
+        this.log(`menu: ${commands.length} commands (${skillRes.skills.length} skills)`);
+    }
+    afterSwitchWorkdir(_oldPath, _newPath) {
+        this.sessionMessages.clear();
+        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(SHUTDOWN_FORCE_EXIT_MS / 1000)}s, forcing exit`);
+            process.exit(this.shutdownExitCode ?? 1);
+        }, SHUTDOWN_FORCE_EXIT_MS);
+        this.shutdownForceExitTimer.unref?.();
+    }
+    cleanupRuntimeForExit() {
+        try {
+            this.channel.disconnect();
+        }
+        catch { }
+        this.stopKeepAlive();
+        shutdownAllDrivers();
+    }
+    buildRestartEnv() {
+        const knownIds = new Set(this.allowedChatIds);
+        for (const cid of this.channel.knownChats)
+            knownIds.add(cid);
+        return knownIds.size ? { FEISHU_ALLOWED_CHAT_IDS: [...knownIds].join(',') } : {};
+    }
+    // ---- session tracking -----------------------------------------------------
+    createTaskId(session) {
+        const seq = this.nextTaskId++;
+        return `${session.key}:${Date.now().toString(36)}:${seq.toString(36)}`;
+    }
+    registerSessionMessage(chatId, messageId, session) {
+        if (session.workdir !== this.workdir)
+            return;
+        if (!messageId)
+            return;
+        let messages = this.sessionMessages.get(chatId);
+        if (!messages) {
+            messages = new Map();
+            this.sessionMessages.set(chatId, messages);
+        }
+        messages.set(messageId, session.key);
+        // Cap size
+        while (messages.size > 1024) {
+            const oldest = messages.keys().next();
+            if (oldest.done)
+                break;
+            messages.delete(oldest.value);
+        }
+    }
+    registerSessionMessages(chatId, messageIds, session) {
+        for (const messageId of messageIds)
+            this.registerSessionMessage(chatId, messageId, session);
+    }
+    sessionFromMessage(chatId, messageId) {
+        if (!messageId)
+            return null;
+        const sessionKey = this.sessionMessages.get(chatId)?.get(messageId) || null;
+        return this.getSessionRuntimeByKey(sessionKey);
+    }
+    ensureSession(chatId, title, files) {
+        const cs = this.chat(chatId);
+        const selected = this.getSelectedSession(cs);
+        if (selected)
+            return selected;
+        const staged = stageSessionFiles({
+            agent: cs.agent,
+            workdir: this.workdir,
+            files: [],
+            sessionId: null,
+            title: title || files[0] || 'New session',
+        });
+        const runtime = this.upsertSessionRuntime({
+            agent: cs.agent,
+            sessionId: staged.sessionId,
+            workspacePath: staged.workspacePath,
+            modelId: this.modelForAgent(cs.agent),
+        });
+        this.applySessionSelection(cs, runtime);
+        return runtime;
+    }
+    resolveIncomingSession(ctx, text, files) {
+        const cs = this.chat(ctx.chatId);
+        // TODO: Feishu doesn't expose reply_to in the event easily; for now use active session
+        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;
+    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 cmdSwitch(ctx, args) {
+        const arg = args.trim();
+        if (arg) {
+            const resolvedPath = path.resolve(arg.replace(/^~/, process.env.HOME || ''));
+            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 browsePath = path.dirname(this.workdir);
+        const view = buildSwitchWorkdirCard(this.workdir, browsePath);
+        await ctx.channel.sendCard(ctx.chatId, view);
+    }
+    async cmdRestart(ctx) {
+        const activeTasks = getActiveTaskCount();
+        if (activeTasks > 0) {
+            await ctx.reply(`⚠ ${formatActiveTaskRestartError(activeTasks)}`);
+            return;
+        }
+        await ctx.reply('**Restarting pikiclaw...**\n\nPulling latest version. The bot will be back shortly.');
+        void requestProcessRestart({ log: msg => this.log(msg) });
+    }
+    // ---- streaming bridge -----------------------------------------------------
+    async handleMessage(msg, ctx) {
+        const text = msg.text.trim();
+        if (!text && !msg.files.length)
+            return;
+        const session = this.resolveIncomingSession(ctx, text, msg.files);
+        const cs = this.chat(ctx.chatId);
+        this.applySessionSelection(cs, session);
+        // File-only message: stage files
+        if (!text && msg.files.length) {
+            const hadPendingWork = this.sessionHasPendingWork(session);
+            const stageTask = this.queueSessionTask(session, async () => {
+                try {
+                    const staged = stageSessionFiles({
+                        agent: session.agent,
+                        workdir: this.workdir,
+                        files: msg.files,
+                        sessionId: session.sessionId,
+                        title: msg.files[0],
+                    });
+                    session.workspacePath = staged.workspacePath;
+                    this.syncSelectedChats(session);
+                    if (!staged.importedFiles.length)
+                        throw new Error('no files persisted');
+                    this.log(`[handleMessage] staged files chat=${ctx.chatId} session=${staged.sessionId} files=${staged.importedFiles.length}`);
+                    this.registerSessionMessage(ctx.chatId, ctx.messageId, session);
+                }
+                catch (e) {
+                    this.log(`[handleMessage] stage files failed: ${e?.message || e}`);
+                }
+            });
+            if (hadPendingWork) {
+                void stageTask.catch(e => this.log(`[handleMessage] stage queue failed: ${e}`));
+            }
+            else {
+                await stageTask.catch(e => this.log(`[handleMessage] stage queue failed: ${e}`));
+            }
+            return;
+        }
+        const files = msg.files;
+        const prompt = buildPrompt(text, files);
+        const start = Date.now();
+        this.log(`[handleMessage] queued chat=${ctx.chatId} agent=${session.agent} session=${session.sessionId || '(new)'} prompt="${prompt.slice(0, 100)}" files=${files.length}`);
+        // Send streaming card (CardKit typewriter effect) or fall back to regular card
+        const placeholderId = await this.channel.sendStreamingCard(ctx.chatId, buildInitialPreviewMarkdown(session.agent), { replyTo: ctx.messageId || undefined });
+        if (placeholderId) {
+            this.registerSessionMessage(ctx.chatId, placeholderId, session);
+            this.log(`[handleMessage] streaming card sent msg_id=${placeholderId}`);
+        }
+        const taskId = this.createTaskId(session);
+        this.beginTask({
+            taskId,
+            chatId: ctx.chatId,
+            agent: session.agent,
+            sessionKey: session.key,
+            prompt,
+            startedAt: start,
+            sourceMessageId: ctx.messageId,
+        });
+        void this.queueSessionTask(session, async () => {
+            let livePreview = null;
+            try {
+                if (placeholderId) {
+                    livePreview = new LivePreview({
+                        agent: session.agent,
+                        chatId: ctx.chatId,
+                        placeholderMessageId: placeholderId,
+                        channel: this.channel,
+                        renderer: feishuPreviewRenderer,
+                        streamEditIntervalMs: 300, // CardKit streaming cards handle frequent updates well
+                        startTimeMs: start,
+                        canEditMessages: supportsChannelCapability(this.channel, 'editMessages'),
+                        canSendTyping: false,
+                        parseMode: 'Markdown',
+                        log: (message) => this.log(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);
+                }, undefined, mcpSendFile);
+                await livePreview?.settle();
+                // End streaming mode — finalize the card before sending final reply
+                if (placeholderId) {
+                    const summary = result.message.slice(0, 80).replace(/\s+/g, ' ').trim() || 'Response complete.';
+                    await this.channel.endStreaming(placeholderId, summary);
+                }
+                this.log(`[handleMessage] done agent=${session.agent} ok=${result.ok} elapsed=${result.elapsedS.toFixed(1)}s ` +
+                    `tokens=in:${fmtTokens(result.inputTokens)}/out:${fmtTokens(result.outputTokens)}`);
+                const finalReplyIds = await this.sendFinalReply(ctx, placeholderId, session.agent, result);
+                this.registerSessionMessages(ctx.chatId, finalReplyIds, session);
+                this.log(`[handleMessage] final reply sent to chat=${ctx.chatId}`);
+            }
+            catch (e) {
+                const msgText = String(e?.message || e || 'Unknown error');
+                this.log(`[handleMessage] task failed chat=${ctx.chatId} error=${msgText}`);
+                const errorText = `**Error**\n\n\`${msgText.slice(0, 500)}\``;
+                if (placeholderId) {
+                    try {
+                        await this.channel.editMessage(ctx.chatId, placeholderId, errorText);
+                    }
+                    catch {
+                        await this.channel.send(ctx.chatId, errorText).catch(() => null);
+                    }
+                }
+                else {
+                    await this.channel.send(ctx.chatId, errorText).catch(() => null);
+                }
+            }
+            finally {
+                livePreview?.dispose();
+                this.finishTask(taskId);
+                this.syncSelectedChats(session);
+            }
+        }).catch(e => {
+            this.log(`[handleMessage] queue execution failed: ${e}`);
+            this.finishTask(taskId);
+        });
+    }
+    async sendFinalReply(ctx, placeholderId, agent, result) {
+        const rendered = buildFinalReplyRender(agent, result);
+        const messageIds = [];
+        const MAX_CARD = 25_000;
+        if (rendered.fullText.length <= MAX_CARD) {
+            // Fits in one card — edit the placeholder
+            if (placeholderId) {
+                try {
+                    await this.channel.editMessage(ctx.chatId, placeholderId, rendered.fullText);
+                    messageIds.push(placeholderId);
+                    return messageIds;
+                }
+                catch { }
+            }
+            const sent = await this.channel.send(ctx.chatId, rendered.fullText);
+            if (sent)
+                messageIds.push(sent);
+        }
+        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}`;
+            if (placeholderId) {
+                try {
+                    await this.channel.editMessage(ctx.chatId, placeholderId, firstText);
+                    messageIds.push(placeholderId);
+                }
+                catch {
+                    const sent = await this.channel.send(ctx.chatId, firstText);
+                    if (sent)
+                        messageIds.push(sent);
+                }
+            }
+            else {
+                const sent = await this.channel.send(ctx.chatId, firstText);
+                if (sent)
+                    messageIds.push(sent);
+            }
+            if (remaining.trim()) {
+                const chunks = splitText(remaining, MAX_CARD);
+                for (const chunk of chunks) {
+                    const sent = await this.channel.send(ctx.chatId, chunk);
+                    if (sent)
+                        messageIds.push(sent);
+                }
+            }
+        }
+        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,
+                    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 'skills':
+                    await this.cmdSkills(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 '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.workdir}\``);
+            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',
+            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.handleSwitchNavigateCallback(data, ctx))
+                return;
+            if (await this.handleSwitchSelectCallback(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 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 view = buildSwitchWorkdirCard(this.workdir, 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 previewCurrentSessionTurn(chatId, agent, sessionId) {
+        try {
+            const preview = await getSessionTurnPreviewData(this, agent, sessionId, 50);
+            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
+        }
+    }
+    // ---- lifecycle ------------------------------------------------------------
+    async run() {
+        const tmpDir = path.join(os.tmpdir(), 'pikiclaw');
+        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,
+        });
+        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.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;
+        }
+        const text = `**${VERSION}** pikiclaw is online.\nSend /start to get started.`;
+        for (const cid of targets) {
+            try {
+                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}`);
+            }
+        }
+    }
+}