lark-remote 0.1.5 → 0.1.6

package/dist/bridge/index.js

@@ -12,6 +12,7 @@ import { enforceCardBudget } from '../card/card-budget.js';
 import { normalizeResultUsage } from '../runner/common/usage.js';
 import { BashProcessRunner } from '../runner/index.js';
 import { QueueManager, } from './queue-manager.js';
+import { ApprovalCoordinator, decisionToApprovalAction } from './approval-coordinator.js';
 /**
  * Max events to read for the completion notification card (mirror router's
  * AUTO_RESUME_MAX_EVENTS = 5). Without a cap, readSessionContent returns every
@@ -19,6 +20,8 @@ import { QueueManager, } from './queue-manager.js';
  * budget (review §P1-21).
  */
 const COMPLETION_NOTIFICATION_MAX_EVENTS = 5;
+/** Approval request timeout (ms) — pending approval expires after this. */
+const APPROVAL_TIMEOUT_MS = 5 * 60 * 1000;
 /**
  * Max idle time (no stdout events) before a claude run is considered hung
  * (§9.12). When this fires the bridge calls `runner.stop()` to unblock the
@@ -80,6 +83,13 @@ export class Bridge {
     queueManager;
     /** Active runs per workspace (cwd). Multiple workspaces can run in parallel. */
     activeRuns = new Map();
+    /** Approval coordinators keyed by runId. */
+    approvalCoordinators = new Map();
+    /**
+     * 最近一次已完成的 codex app-server run（按 cwd）。run 结束后 activeRuns
+     * 已清空，Compact 需要它来校验 runId 并提供 sessionId。
+     */
+    lastCompactableCodexRun = new Map();
     /**
      * Active `!` bash runs, keyed by runId (NOT cwd). Bash runs bypass the serial
      * queue and may run in parallel with claude runs / other bash runs in the same
@@ -182,6 +192,11 @@ export class Bridge {
         if (evicted && typeof evicted.unregisterExitHandlers === 'function') {
             evicted.unregisterExitHandlers();
         }
+        // App-server runner owns a persistent connection — dispose it so the
+        // `codex app-server` child process does not leak across runs/evictions.
+        if (evicted && typeof evicted.dispose === 'function') {
+            void evicted.dispose();
+        }
         workspaceMap.delete(kind);
         if (workspaceMap.size === 0) {
             this.runners.delete(cwd);
@@ -483,6 +498,15 @@ export class Bridge {
         }
         catch (err) {
             getLogger().error('[bridge] failed to send result:', err);
+            // 不静默：向用户发送一条纯文本消息，告知具体错误（如飞书 11310 element exceeds
+            // the limit）。如果用户看到空白无反馈，无法判断是命令无效还是卡片发送失败。
+            try {
+                const errMsg = err.message ?? String(err);
+                await this.connector.sendWithRetry(ctx.chatId, { text: `⚠️ 卡片发送失败：${errMsg}` }, { replyTo: ctx.messageId });
+            }
+            catch (fallbackErr) {
+                getLogger().error('[bridge] fallback text send also failed:', fallbackErr);
+            }
             return false;
         }
     }
@@ -511,7 +535,10 @@ export class Bridge {
             return true;
         }
         catch (err) {
-            getLogger().warn(`[bridge] updateCardInPlace failed, falling back to sendResult: ${err.message}`);
+            const errMsg = err.message ?? String(err);
+            getLogger().warn(`[bridge] updateCardInPlace failed, falling back to sendResult: ${errMsg}`);
+            // 先尝试 fallback 发卡片；若卡片本身有问题（如 11310），
+            // sendResult 内部 catch 会发纯文本通知用户。
             await this.sendResult({ card }, ctx);
             return false;
         }
@@ -641,6 +668,10 @@ export class Bridge {
      * Handles idle watchdog, event processing, session sync, and state transitions.
      */
     async runAgentStreamToEnd(runner, cardSession, sessionId, sessionEpochAtStart, ctx, cwd, runId, message, agentKind = this.config.defaultAgent) {
+        // Runner 声明的 usage 权威来源（review P3-7）：codex exec = 'jsonl'，
+        // codex app-server = 'live'（turn/started 的 tokenUsage.last 是本 turn 增量）。
+        // 其余 runner 未声明，回退到 agentKind 推断（仅 codex 视为 jsonl-first）。
+        const usageAuthority = runner.getUsageAuthority?.();
         // P2-1: idle watchdog 用单 interval + lastEventTs 截止时间判定，而非每事件
         // clearTimeout + setTimeout 重建 timer。高频事件流下 timer 重建次数与事件数
         // 成正比（N 事件 = N 次 setTimeout + N 个闭包/秒）；interval 方案只建一个
@@ -650,7 +681,7 @@ export class Bridge {
         let idleInterval = null;
         let sawResult = false;
         // 记录 result 是否为 error: error 时跳过 jsonl usage 读取 (见 stream end 处说明)
-        let resultWasError = false;
+        let resultNotSuccess = false;
         // Final usage read from jsonl after the run completes. live stream-json does
         // not emit compact_boundary, so the live contextLength is unreliable.
         let finalContextLength;
@@ -664,6 +695,10 @@ export class Bridge {
         // done card shows real values instead of the 10% estimate.
         let liveInputTokens;
         let liveOutputTokens;
+        // Real context window limit from the live result event (codex app-server
+        // carries it in ResultEvent.usage.context_limit). jsonl wins when present;
+        // live is the fallback (app-server error runs / jsonl 未落盘时).
+        let liveContextLimit;
         // Final input/output for the done card: live value wins (codex/opencode
         // carry per-run usage in the result event); jsonl is the fallback for
         // agents whose live stream has no usage (kimi).
@@ -746,7 +781,7 @@ export class Bridge {
                     // 代际守卫：run 在途时 /new（或 new-session 卡片、/cd、/resume、
                     // /config 切换）移动了 session 指针，此 init 的写回是 stale 的——
                     // 跳过，否则 /new 的清空会被在途 run 静默撤销（2026-08-09 事故：
-                    // task-notification 注入触发 Claude 重发 init，e8defc46 复活）。
+                    // task-notification 注入触发 Claude 重发 init，已终止的 run 被复活）。
                     const pointerMoved = this.sessionStore.getSessionEpoch(ctx.userId, agentKind) !== sessionEpochAtStart;
                     if (pointerMoved) {
                         getLogger().info(`[bridge] system.init write-back skipped: session pointer moved since run start runId=${runId} sessionId=${event.session_id}`);
@@ -773,6 +808,20 @@ export class Bridge {
                     }
                     getLogger().info(`[bridge] system.init received runId=${runId} sessionId=${event.session_id} cwd=${event.cwd}`);
                 }
+                if (event.type === 'turn_started') {
+                    // app-server runner 在 turn setup 成功后补发 synthetic system.init
+                    // （§9.22 守卫前提），此处 turn_started 写回保留为双保险：两者都用
+                    // threadId 写回 sessionId（代际守卫一致），幂等。缺失会导致每次消息
+                    // 都新建线程（thread/start 而非 thread/resume），会话无法延续。
+                    const pointerMoved = this.sessionStore.getSessionEpoch(ctx.userId, agentKind) !== sessionEpochAtStart;
+                    if (!pointerMoved) {
+                        this.sessionStore.setSessionIdAndCwd(ctx.userId, agentKind, event.threadId, cwd);
+                        getLogger().info(`[bridge] turn_started session write-back runId=${runId} sessionId=${event.threadId}`);
+                    }
+                    else {
+                        getLogger().info(`[bridge] turn_started write-back skipped: session pointer moved since run start runId=${runId} sessionId=${event.threadId}`);
+                    }
+                }
                 // Track context length from compaction events
                 if (event.type === 'system' &&
                     event.subtype === 'compact_boundary' &&
@@ -786,7 +835,14 @@ export class Bridge {
                     // also guards on sessionId === undefined) from transitioning to
                     // finalizing too early. The real result for this run arrives after
                     // system.init.
-                    if (!sawInit) {
+                    //
+                    // Exception: app-server runners (usageAuthority === 'live') 的 init
+                    // 是 runner 补发的 synthetic init（2026-08-13 修复）。此分支保留为
+                    // 防御性兜底：任何 live runner 若在无 init 时发出 result（如旧构建、
+                    // 其它 live runner），session 写回仍执行，但 sawResult 保持 false，
+                    // 卡片不会把半初始化的 run 当作已收尾。
+                    const preInitResult = !sawInit;
+                    if (preInitResult && usageAuthority !== 'live') {
                         getLogger().info(`[bridge] pre-init result ignored (resume replay) runId=${runId}`);
                         // Still reset idle timer — the CLI is alive and producing events.
                         resetIdle();
@@ -795,9 +851,24 @@ export class Bridge {
                         // layer avoids the push + render overhead for a no-op event.
                         continue;
                     }
-                    sawResult = true;
-                    resultWasError = event.subtype === 'error';
-                    getLogger().info(`[bridge] result event received runId=${runId}`);
+                    if (!preInitResult) {
+                        sawResult = true;
+                    }
+                    resultNotSuccess = event.subtype !== 'success';
+                    getLogger().info(preInitResult
+                        ? `[bridge] pre-init result from live runner (app-server setup failure) runId=${runId}`
+                        : `[bridge] result event received runId=${runId}`);
+                    // app-server 模式 setup 失败路径（thread/start 成功后 turn/start 失败）
+                    // 不会有 turn_started 事件，store 不会写回新线程 id；runner 已在 result
+                    // 里兜底上报（review P3-10）。此处仅当 runner 声明 live usage（app-server）
+                    // 且会话指针未动时写回，避免下条消息再开一个孤儿线程。exec 模式与其
+                    // 余 agent 不在此列（它们各自有 system.init / turn_started 写回）。
+                    if (usageAuthority === 'live' &&
+                        event.session_id &&
+                        this.sessionStore.getSessionEpoch(ctx.userId, agentKind) === sessionEpochAtStart) {
+                        this.sessionStore.setSessionIdAndCwd(ctx.userId, agentKind, event.session_id, cwd);
+                        getLogger().info(`[bridge] result session write-back runId=${runId} sessionId=${event.session_id}`);
+                    }
                     // result 后进入 finalizing 非终态（暂存 subtype/errorMsg），由 for-await
                     // 自然结束后在 finally 转 done/error。提取 usage 信息。
                     if (event.usage) {
@@ -814,6 +885,7 @@ export class Bridge {
                         // Input/Output 是本 run、Cache/Total 是 session 累计的混 scope 问题。
                         liveInputTokens = u.inputTokens;
                         liveOutputTokens = u.outputTokens;
+                        liveContextLimit = u.contextLimit;
                         if (u.cacheReadTokens !== undefined) {
                             finalCacheReadTokens = u.cacheReadTokens;
                         }
@@ -825,6 +897,59 @@ export class Bridge {
                         }
                     }
                 }
+                // Approval events (Codex app-server mode)
+                if (event.type === 'approval_requested') {
+                    // 审批请求到达：撤回 Typing 表情再重发，让飞书重新触发提醒，把用户
+                    // 注意力拉回待审批的卡片（run 在等待人工决策，Typing 应重新闪烁）。
+                    void (async () => {
+                        try {
+                            await this.connector.removeReactionByEmoji(ctx.messageId, 'Typing');
+                        }
+                        catch (err) {
+                            getLogger().warn(`[bridge] remove Typing reaction failed runId=${runId}: ${errorMessage(err)}`);
+                        }
+                        try {
+                            await this.connector.addReaction(ctx.messageId, 'Typing');
+                        }
+                        catch (err) {
+                            getLogger().warn(`[bridge] re-add Typing reaction failed runId=${runId}: ${errorMessage(err)}`);
+                        }
+                    })();
+                    let coordinator = this.approvalCoordinators.get(runId);
+                    if (!coordinator) {
+                        coordinator = new ApprovalCoordinator({
+                            runId,
+                            userId: ctx.userId,
+                            chatId: ctx.chatId,
+                            workspace: cwd,
+                            approvalTimeoutMs: APPROVAL_TIMEOUT_MS,
+                            responder: async (requestId, response) => {
+                                const r = runner;
+                                if (typeof r.respondApproval === 'function') {
+                                    await r.respondApproval(requestId, response);
+                                }
+                            },
+                            interruptTurn: () => runner.stop(),
+                            pushToCard: async (events) => {
+                                for (const ev of events)
+                                    await cardSession.push(ev);
+                            },
+                        });
+                        this.approvalCoordinators.set(runId, coordinator);
+                        getLogger().info(`[bridge] approval coordinator created runId=${runId.slice(0, 8)} requestId=${event.requestId}`);
+                    }
+                    coordinator.onRequested(event);
+                }
+                else if (event.type === 'approval_resolved') {
+                    const coordinator = this.approvalCoordinators.get(runId);
+                    coordinator?.onResolved(event.requestId);
+                }
+                else if (event.type === 'approval_view_updated') {
+                    // 乱序流：审批先到、item/started 后到，补全审批卡内容。coordinator
+                    // 仅在 pending 时更新（已响应/过期不复活）。
+                    const coordinator = this.approvalCoordinators.get(runId);
+                    coordinator?.updateView(event.requestId, event.view);
+                }
                 // §9.12 红线（§P1-2 方案 A）：每个事件（含 result）无条件刷新
                 // lastEventTs 重新武装看门狗。result 后 CLI 进程做 jsonl flush/清理（finalizing
                 // 过渡）期间，宽限期恢复为完整的 idleTimeoutMs，避免已产出结果的 turn 被误标
@@ -846,11 +971,11 @@ export class Bridge {
             // 立即 exit=1), 此时 jsonl 里是上一次成功 turn 的历史 usage, 会被误当作本次 usage 显示,
             // 误导用户以为本次出错的请求也消耗了 token。error 时只用 live 捕获的 usage (若有)。
             const finalSessionId = this.sessionStore.getSessionId(ctx.userId, agentKind);
-            const finalUsage = resultWasError
+            const finalUsage = resultNotSuccess
                 ? undefined
                 : this.resolveFinalUsage(finalSessionId, cwd, agentKind);
             finalContextLength = finalUsage?.contextLength ?? contextLength;
-            finalContextLimit = finalUsage?.contextLimit;
+            finalContextLimit = finalUsage?.contextLimit ?? liveContextLimit;
             finalCompactCount = finalUsage?.compactCount;
             finalCumulativeTotalTokens = finalUsage?.cumulativeTotalTokens;
             finalCumulativeInputTokens = finalUsage?.cumulativeInputTokens;
@@ -867,7 +992,7 @@ export class Bridge {
             // 值必须被忽略，flow 字段一律取 jsonl 主线程文件的 per-turn 值；
             // jsonl 缺失（老版本无 token_count）时才回退 live。
             // contextLength/compactCount 保持 jsonl 优先（它们是水位/历史计数）。
-            const codexJsonlFirst = agentKind === 'codex';
+            const codexJsonlFirst = usageAuthority === 'jsonl' || (usageAuthority === undefined && agentKind === 'codex');
             if (!codexJsonlFirst && liveInputTokens !== undefined && liveOutputTokens !== undefined) {
                 // 非 codex 且 live 有 input/output → 所有 flow 字段用 live scope
                 finalInputTokens = liveInputTokens;
@@ -892,9 +1017,13 @@ export class Bridge {
             // 3) 已终态 + sawResult -> 补充 usage meta（不改 terminal）
             const finalState = cardSession.currentState;
             if (finalState.terminal === 'finalizing') {
-                const isError = finalState.resultSubtype === 'error' || !!finalState.errorMsg;
-                await cardSession.finish(isError ? 'error' : 'done', {
-                    resultSubtype: finalState.resultSubtype,
+                // 三态终态映射（2026-08-14）：interrupted（审批超时/取消、/stop）是独立
+                // 终态，不再归因于 Agent 错误；error 保持「运行出错」；其余为 done。
+                const subtype = finalState.resultSubtype;
+                const isError = subtype === 'error' || !!finalState.errorMsg;
+                const terminal = isError ? 'error' : subtype === 'interrupted' ? 'interrupted' : 'done';
+                await cardSession.finish(terminal, {
+                    resultSubtype: subtype,
                     errorMsg: finalState.errorMsg,
                     contextLength: finalContextLength,
                     contextLimit: finalContextLimit,
@@ -1003,6 +1132,11 @@ export class Bridge {
         finally {
             if (idleInterval)
                 clearInterval(idleInterval);
+            const coordinator = this.approvalCoordinators.get(runId);
+            if (coordinator) {
+                coordinator.onTurnEnded();
+                this.approvalCoordinators.delete(runId);
+            }
         }
     }
     /**
@@ -1047,14 +1181,35 @@ export class Bridge {
             // (every later message busy-dropped until a manual /stop).
             if (this.activeRuns.get(cwd) === activeRun) {
                 this.activeRuns.delete(cwd);
-                // Also clean up the runner to prevent memory leak
-                // Fix 4: Clean up this specific (cwd, agentKind) runner slot.
-                // (P1-1: eviction must also unregister the runner from the exit dispatcher)
-                // P2-3: evict by the run's captured agentKind, not the live
-                // defaultAgent — switching agent mid-run (via /config, whose
-                // clearRunners skips the active cwd) would otherwise delete the new
-                // agent's slot (no-op) and leave the original runner lingering.
-                this.evictRunnerSlot(cwd, activeRun.agentKind);
+                // Workspace-lifetime runners (codex app-server) keep their persistent
+                // connection across runs: evicting here would kill the connection after
+                // EVERY run, defeating lifetime='workspace' + idle TTL. They are still
+                // evicted+disposed by clearRunners (/config) and interruptCurrentRun
+                // (/stop). Spawn-per-message runners are evicted as before to prevent
+                // stale process references accumulating.
+                if (activeRun.runner.lifetime !== 'workspace') {
+                    this.evictRunnerSlot(cwd, activeRun.agentKind);
+                }
+                // Compact 卡片需要 runId + sessionId；record 供终态卡上的 Compact 按钮
+                // 校验与取参（activeRuns 已清空，无法再查到）。异常退出（error/
+                // interrupted/idle_timeout）同样记录——上下文往往更大，压缩后再续。
+                const runTerminal = cardSession.currentState.terminal;
+                if (activeRun.agentKind === 'codex' &&
+                    activeRun.runner.lifetime === 'workspace' &&
+                    (runTerminal === 'done' ||
+                        runTerminal === 'error' ||
+                        runTerminal === 'interrupted' ||
+                        runTerminal === 'idle_timeout')) {
+                    const compactSessionId = cardSession.currentState.sessionId ??
+                        this.sessionStore.getSessionId(ctx.userId, 'codex');
+                    if (compactSessionId) {
+                        this.lastCompactableCodexRun.set(cwd, {
+                            runId: activeRun.runId,
+                            sessionId: compactSessionId,
+                            agentKind: activeRun.agentKind,
+                        });
+                    }
+                }
                 getLogger().info(`[bridge] activeRuns.delete cwd=${cwd} runId=${runId}`);
             }
         }
@@ -1081,6 +1236,7 @@ export class Bridge {
                     contextLength: content.usage.contextLength,
                     contextLimit: content.usage.contextLimit,
                     compactCount: content.usage.compactCount,
+                    compactPreContextLength: content.usage.compactPreContextLength,
                     cacheReadTokens: content.usage.cacheReadTokens,
                     cacheCreationTokens: content.usage.cacheCreationTokens,
                     totalTokens: content.usage.totalTokens,
@@ -1165,6 +1321,231 @@ export class Bridge {
             getLogger().warn(`[bridge] failed to send completion notification card:`, err);
         }
     }
+    // =============================================================================
+    // Approval action handlers
+    // =============================================================================
+    /**
+     * Handle an approval response from a card button click.
+     * Routes to the ApprovalCoordinator for the given run.
+     */
+    async handleApprovalRespond(opts) {
+        const log = getLogger();
+        log.info(`[bridge] handleApprovalRespond runId=${opts.runId.slice(0, 8)}... requestId=${opts.requestId} decision=${opts.decision}`);
+        const coordinator = this.approvalCoordinators.get(opts.runId);
+        if (!coordinator) {
+            // P2-7: run 已结束（coordinator 已释放）时点击审批按钮必须给用户明确反馈，
+            // 不能静默。router 会把该异常转成 error toast。
+            log.warn(`[bridge] no approval coordinator for runId=${opts.runId.slice(0, 8)}`);
+            throw new Error('任务已结束，审批无法响应');
+        }
+        // Build ApprovalAction from the decision string
+        const action = decisionToApprovalAction(opts.decision);
+        await coordinator.submit(action, { requestId: opts.requestId, nonce: opts.nonce });
+    }
+    /**
+     * Handle a permission toggle from a card button click.
+     * Routes to the ApprovalCoordinator for the given run.
+     */
+    async handleApprovalToggle(opts) {
+        const log = getLogger();
+        log.info(`[bridge] handleApprovalToggle runId=${opts.runId.slice(0, 8)}... requestId=${opts.requestId} permId=${opts.permId}`);
+        const coordinator = this.approvalCoordinators.get(opts.runId);
+        if (!coordinator) {
+            log.warn(`[bridge] no approval coordinator for runId=${opts.runId.slice(0, 8)}`);
+            throw new Error('任务已结束，审批无法响应');
+        }
+        // selected 由卡片根据当前渲染状态传回（取反），不再硬编码只授不撤。
+        const toggleAction = {
+            permId: opts.permId,
+            selected: opts.selected ?? true,
+        };
+        await coordinator.togglePerm(toggleAction, { requestId: opts.requestId });
+    }
+    /**
+     * Handle codex.compact card action — trigger a Codex compaction request.
+     * Validates the run exists and is in a terminal state, then calls
+     * the app-server runner's runCompact().
+     */
+    async handleCodexCompact(value, ctx) {
+        const log = getLogger();
+        log.info(`[bridge] handleCodexCompact userId=${ctx.userId} runId=${value.runId?.slice(0, 8)}...`);
+        const { runId } = value;
+        if (!runId) {
+            await this.sendResult({ text: '⚠️ 无效的 Compact 请求，缺少 runId' }, ctx);
+            return;
+        }
+        const cwd = this.resolveCwd(ctx.userId);
+        if (!cwd) {
+            await this.sendResult({ text: '⚠️ 未设置工作目录' }, ctx);
+            return;
+        }
+        // 校验：run 结束后 activeRuns 已清空，用 lastCompactableCodexRun 对照 runId。
+        const last = this.lastCompactableCodexRun.get(cwd);
+        if (!last || last.runId !== runId) {
+            await this.sendResult({ text: '⚠️ 该任务已结束或不属于当前会话' }, ctx);
+            return;
+        }
+        if (!last.sessionId) {
+            await this.sendResult({ text: '⚠️ 未找到可压缩的会话' }, ctx);
+            return;
+        }
+        // Check that the runner has runCompact method
+        const runner = this.getRunner(cwd, last.agentKind);
+        if (!('runCompact' in runner) ||
+            typeof runner.runCompact !== 'function') {
+            await this.sendResult({ text: '⚠️ 当前运行模式不支持 Compact' }, ctx);
+            return;
+        }
+        log.info(`[bridge] handleCodexCompact executing runCompact for runId=${runId} cwd=${cwd}`);
+        await this.streamCodexCompact({
+            sessionId: last.sessionId,
+            cwd,
+            agentKind: last.agentKind,
+            runner,
+            ctx,
+        });
+    }
+    /**
+     * Stream a Codex compaction to a card: start a RunCardSession with
+     * operationKind='compaction' (no recursive Compact button), consume
+     * runner.runCompact() events, read authoritative jsonl usage, and finish
+     * the card. Shared by handleCodexCompact (run card button) and
+     * handleResumeCompact (resume cards) so both flows stay in sync.
+     *
+     * Precondition: callers have already validated that `runner` implements
+     * runCompact and that the session exists in `cwd`.
+     */
+    async streamCodexCompact(opts) {
+        const log = getLogger();
+        const { sessionId, cwd, agentKind, runner, ctx } = opts;
+        log.info(`[bridge] streamCodexCompact sessionId=${sessionId} cwd=${cwd}`);
+        // 防御性能力检查：调用方已校验（runId / resume 两条路径），此处双保险并
+        // 让 TS 收窄 runner 类型（'runCompact' in runner 之后的 cast 才合法）。
+        if (!('runCompact' in runner) ||
+            typeof runner.runCompact !== 'function') {
+            await this.sendResult({ text: '⚠️ 当前运行模式不支持 Compact' }, ctx);
+            return;
+        }
+        await this.sendResult({ text: '🗜 Compact 已触发，正在压缩会话…' }, ctx);
+        const compactRunId = randomUUID();
+        const cardSession = new RunCardSession({
+            connector: this.connector,
+            chatId: ctx.chatId,
+            replyTo: ctx.messageId,
+            runId: compactRunId,
+            renderOptions: {
+                showThinking: this.config.output.showThinking,
+                showToolUse: this.config.output.showToolUse,
+                showToolResult: this.config.output.showToolResult,
+                agentKind,
+            },
+        });
+        try {
+            await cardSession.start();
+            // operationKind=compaction：卡片不渲染 Compact 按钮（防递归 Compact）。
+            await cardSession.push({
+                type: 'turn_started',
+                threadId: sessionId,
+                turnId: '',
+                operationKind: 'compaction',
+            });
+            let sawResult = false;
+            for await (const event of runner.runCompact('', { cwd, sessionId })) {
+                if (event.type === 'result')
+                    sawResult = true;
+                await cardSession.push(event);
+            }
+            // 压缩结束后从会话 jsonl 读权威统计（压缩后上下文、压缩次数、本次压缩
+            // token 消耗与会话累计）。thread/compacted 通知与 jsonl 落盘几乎同时
+            // （实测差 ~9ms），compactCount 未读到则短重试，仍失败优雅降级（无统计）。
+            let finalUsage = this.resolveFinalUsage(sessionId, cwd, agentKind);
+            for (let attempt = 0; !finalUsage?.compactCount && attempt < 2; attempt++) {
+                await new Promise((r) => setTimeout(r, 150));
+                finalUsage = this.resolveFinalUsage(sessionId, cwd, agentKind);
+            }
+            await cardSession.finish(sawResult ? 'done' : 'error', {
+                resultSubtype: sawResult ? 'success' : 'error',
+                errorMsg: sawResult ? undefined : '未收到压缩结果',
+                contextLength: finalUsage?.contextLength,
+                contextLimit: finalUsage?.contextLimit,
+                compactPreContextLength: finalUsage?.compactPreContextLength,
+                compactCount: finalUsage?.compactCount,
+                cacheReadTokens: finalUsage?.cacheReadTokens,
+                cacheCreationTokens: finalUsage?.cacheCreationTokens,
+                totalTokens: finalUsage?.totalTokens,
+                inputTokens: finalUsage?.inputTokens,
+                outputTokens: finalUsage?.outputTokens,
+                cumulativeTotalTokens: finalUsage?.cumulativeTotalTokens,
+                cumulativeInputTokens: finalUsage?.cumulativeInputTokens,
+                cumulativeOutputTokens: finalUsage?.cumulativeOutputTokens,
+                cumulativeCacheReadTokens: finalUsage?.cumulativeCacheReadTokens,
+                cumulativeCacheCreationTokens: finalUsage?.cumulativeCacheCreationTokens,
+            });
+            log.info(`[bridge] streamCodexCompact finished sessionId=${sessionId} sawResult=${sawResult}`);
+        }
+        catch (err) {
+            log.error(`[bridge] streamCodexCompact failed: ${errorMessage(err)}`);
+            await cardSession.finish('error', { errorMsg: errorMessage(err) });
+        }
+    }
+    /**
+     * Handle resume.compact card action — compact a session directly from a
+     * resume card (auto-resume / `/resume <id>`), without a runId.
+     *
+     * Unlike handleCodexCompact (which validates against the last finished run's
+     * runId), the resume card carries the sessionId + agent it was rendered for.
+     * Validation: the session must exist in the current cwd (same rule as
+     * cmdResume / resume.use) and the runner must implement runCompact.
+     */
+    async handleResumeCompact(value, ctx) {
+        const log = getLogger();
+        log.info(`[bridge] handleResumeCompact userId=${ctx.userId} sessionId=${value.sessionId?.slice(0, 16)} agent=${value.agent ?? 'default'}`);
+        const { sessionId } = value;
+        if (!sessionId) {
+            await this.sendResult({ text: '⚠️ 无效的 Compact 请求，缺少 sessionId' }, ctx);
+            return;
+        }
+        const cwd = this.resolveCwd(ctx.userId);
+        if (!cwd) {
+            await this.sendResult({ text: '⚠️ 未设置工作目录' }, ctx);
+            return;
+        }
+        // Resolve agent kind the same way resume.use does: card value wins,
+        // otherwise fall back to defaultAgent.
+        const validAgents = ['claude', 'codex', 'opencode', 'pi', 'kimi'];
+        const agentKind = value.agent && validAgents.includes(value.agent)
+            ? value.agent
+            : this.config.defaultAgent;
+        // Session must exist in the current cwd (same rule as cmdResume /
+        // resume.use): reject ghosts so a stale card cannot compact a session
+        // from another cwd. Read failures get visible feedback (card click
+        // 红线：不许静默失败)。
+        let content;
+        try {
+            content = this.sessionReaderRegistry.get(agentKind).readSessionContent(sessionId, cwd);
+        }
+        catch (err) {
+            await this.sendResult({ text: `⚠️ 读取 session ${sessionId} 失败: ${errorMessage(err)}` }, ctx);
+            return;
+        }
+        if (content.events.length === 0 &&
+            !content.usage &&
+            !content.aiTitle &&
+            !content.recap &&
+            !content.displayTitle) {
+            await this.sendResult({ text: `⚠️ 未找到 session ${sessionId}（当前目录: ${cwd}）` }, ctx);
+            return;
+        }
+        // Check that the runner has runCompact (codex app-server only).
+        const runner = this.getRunner(cwd, agentKind);
+        if (!('runCompact' in runner) ||
+            typeof runner.runCompact !== 'function') {
+            await this.sendResult({ text: '⚠️ 当前运行模式不支持 Compact' }, ctx);
+            return;
+        }
+        log.info(`[bridge] handleResumeCompact executing runCompact sessionId=${sessionId} cwd=${cwd}`);
+        await this.streamCodexCompact({ sessionId, cwd, agentKind, runner, ctx });
+    }
     /**
      * Execute a bash command and stream output to a card.
      * `!` commands bypass the serial queue entirely (see body comment + §9.6):

package/dist/bridge/queue-manager.d.ts

@@ -29,6 +29,13 @@ export interface QueuedTask {
     workspace: string;
     timestamp: number;
     messagePreview: string;
+    /**
+     * Whether the queued task's message is editable from the queue card.
+     * Card actions like Compact are one-shot operations — editing their
+     * preview is meaningless, so they enqueue with `editable: false` and the
+     * queue card omits the ✏️ 编辑 button.
+     */
+    editable?: boolean;
     /**
      * Edited message content. Set by `updateQueuedTaskMessage` when the user
      * edits a queued message. The original closure captured at enqueue time
@@ -54,6 +61,8 @@ export interface EnqueueOptions {
          * real Feishu id and doubles as the reply target.
          */
         feishuReplyTo?: string;
+        /** Whether the queued task is editable (queue card ✏️ 编辑 button). Defaults to true. */
+        editable?: boolean;
         /** 入队时刻捕获的 agent+session 绑定（方案 D4）。 */
         binding?: AgentBinding;
     };

package/dist/bridge/queue-manager.js

@@ -138,6 +138,7 @@ export class QueueManager {
                 workspace,
                 timestamp: Date.now(),
                 messagePreview,
+                editable: taskMeta.editable,
                 binding: taskMeta.binding,
             };
             // Check if there are tasks waiting BEFORE adding this one
@@ -395,22 +396,29 @@ export class QueueManager {
             },
             { tag: 'hr' },
         ];
-        // Show message preview with edit button (only if not executing)
+        // Show message preview with edit button (only if not executing AND the
+        // task is editable). One-shot card actions like Compact enqueue with
+        // editable=false: their preview is not user-editable text, so the ✏️ 编辑
+        // button must not appear (queue card is still shown — only editing is
+        // meaningless for them).
         if (messagePreview) {
             elements.push({
                 tag: 'div',
                 text: { tag: 'lark_md', content: `📝 \`${messagePreview}\`` },
             });
-            // Edit button: a pending (queued) task is always editable. The
-            // executing/cancelled states render via dedicated card builders that
-            // hard-disable all buttons, so this builder only serves pending cards.
-            elements.push({
-                tag: 'button',
-                text: { tag: 'plain_text', content: '✏️ 编辑' },
-                type: 'default',
-                size: 'small',
-                behaviors: [{ type: 'callback', value: { cmd: 'queue.edit', workspace, messageId } }],
-            });
+            const task = this.indexGet(workspace, messageId);
+            if (task?.editable !== false) {
+                // Edit button: a pending (queued) task is editable by default. The
+                // executing/cancelled states render via dedicated card builders that
+                // hard-disable all buttons, so this builder only serves pending cards.
+                elements.push({
+                    tag: 'button',
+                    text: { tag: 'plain_text', content: '✏️ 编辑' },
+                    type: 'default',
+                    size: 'small',
+                    behaviors: [{ type: 'callback', value: { cmd: 'queue.edit', workspace, messageId } }],
+                });
+            }
             elements.push({ tag: 'hr' });
         }
         // Action buttons