lark-remote 0.1.5 → 0.1.7

package/dist/card/run-renderer.js

@@ -1,10 +1,10 @@
-import { terminalToColor, terminalToLabel, newSessionButton, stopButton, agentDisplayName, } from './card-shared.js';
+import { terminalToColor, terminalToLabel, newSessionButton, stopButton, compactButton, agentDisplayName, } from './card-shared.js';
 import { collapsibleMarkdownPanel, markdownDiv } from './collapsible.js';
 import { toolBodyMd, toolHeaderText } from './tool-render.js';
-import { truncateUtf8, truncateMarkdownTables } from './text-truncate.js';
+import { truncateUtf8, truncateMarkdownTables, CARD_BUDGET_BYTES } from './text-truncate.js';
 import { formatTimestamp } from './time.js';
-import { formatUsageStats } from '../router/index.js';
-const CARD_BUDGET_BYTES = 28_000;
+import { formatUsageStats } from '../router/utils.js';
+import { renderApprovalArea } from './approval-render.js';
 const REASONING_BYTES = 4_500;
 const TEXT_BYTES = 10_000;
 const DEGRADED_THINKING_KEEP = 2;
@@ -24,6 +24,20 @@ function measureJson(obj) {
 }
 /** markdownDiv('', 'notation') 的序列化字节（空内容 div 的常量开销，估算时复用）。 */
 const EMPTY_MD_DIV_BYTES = measureJson(markdownDiv('', 'notation'));
+/**
+ * Compact 按钮可见性：普通 run（operationKind='turn'）到达任意终态即可压缩。
+ * 异常退出（error/interrupted/idle_timeout）时上下文往往更大，更需要压缩后
+ * 再继续，因此不再要求 resultSubtype==='success'。compaction 卡
+ * （operationKind='compaction'）永不显示，防止递归 Compact。
+ */
+function shouldShowCompactButton(state) {
+    if (state.operationKind !== 'turn')
+        return false;
+    return (state.terminal === 'done' ||
+        state.terminal === 'error' ||
+        state.terminal === 'interrupted' ||
+        state.terminal === 'idle_timeout');
+}
 /**
  * Wrap text block in a collapsible panel with timestamp in the header.
  * This unifies timestamp position across all block types (thinking/plan/file_change/tool/text).
@@ -174,92 +188,35 @@ function toolTitle(tool) {
     const title = toolHeaderText(tool);
     return ts ? `${title} (${ts})` : title;
 }
-/**
- * Build degraded elements when full card exceeds 28KB budget.
- * Strategy: text fully preserved, thinking keeps last 2, tools keep last N (compressed).
- *
- * 性能优化：单遍遍历 state.blocks 按 kind 分桶（thinking/tool/other），替代原先
- * 多次 state.blocks.filter() 扫描。分桶时保持原相对顺序，后续用 groupBlocks
- * 渲染时序不变。
- */
-function buildDegradedElements(state, options) {
-    const elements = [];
-    elements.push(statusRow(state));
-    // 单遍分桶：thinking / tool / other（保持原相对顺序）
-    const { thinking: allThinkingBlocks, tool: allToolBlocks } = bucketThinkingAndTool(state.blocks);
-    if (allThinkingBlocks.length > DEGRADED_THINKING_KEEP) {
-        const omitted = allThinkingBlocks.length - DEGRADED_THINKING_KEEP;
-        elements.push(markdownDiv(`_💡 ${omitted} 个早期思考已省略_`));
-    }
-    // Keep only the last N thinking blocks for display
-    const thinkingBlocksToShow = allThinkingBlocks.slice(-DEGRADED_THINKING_KEEP);
-    const toolsToShow = allToolBlocks.slice(-DEGRADED_TOOL_KEEP);
-    const toolsOmitted = allToolBlocks.length - DEGRADED_TOOL_KEEP;
-    // Add omit hint for tools if any were omitted
-    if (toolsOmitted > 0) {
-        elements.push(markdownDiv(`_💡 另外 ${toolsOmitted} 个工具调用已省略_`));
-    }
-    // Build a filtered blocks list that only includes the thinking blocks we want to show
-    // and the tool blocks we want to show.
-    // P2-6: use object references (like the extreme path) instead of timestamps.
-    // RunBlock.timestamp has millisecond precision; ≥2 thinking blocks sharing a
-    // timestamp collapse to one Set entry, so `has(block.timestamp)` lets ALL
-    // same-timestamp blocks (including ones meant to be omitted) pass through —
-    // inflating the degraded card past 28KB and contradicting the "N omitted"
-    // hint. `thinkingBlocksToShow` is a slice of `allThinkingBlocks`, so the
-    // blocks retain stable references and the Set membership check is exact.
-    const thinkingSetToShow = new Set(thinkingBlocksToShow);
-    const toolIdsToShow = new Set(toolsToShow.map((b) => b.tool.id));
-    const filteredBlocks = state.blocks.filter((block) => {
-        if (block.kind === 'thinking') {
-            return thinkingSetToShow.has(block);
-        }
-        if (block.kind === 'tool') {
-            return toolIdsToShow.has(block.tool.id);
-        }
-        return true; // keep all non-thinking, non-tool blocks
-    });
-    // Render thinking/text/tool in chronological order using groupBlocks
-    for (const group of groupBlocks(filteredBlocks)) {
-        if (group.kind === 'thinking') {
-            if (options.showThinking === false)
-                continue;
-            const ts = formatTimestamp(group.timestamp);
-            const title = '💭 **思考完成**';
-            const content = truncateUtf8(group.content, REASONING_BYTES);
-            const header = ts ? `${title} (${ts})` : title;
-            elements.push(collapsibleMarkdownPanel({
-                title: header,
-                expanded: false,
-                border: 'grey',
-                content,
-                textSize: 'notation',
-            }));
-        }
-        else if (group.kind === 'text') {
-            const content = truncateUtf8(group.content, TEXT_BYTES, true, '…（已截断）\n');
-            const ts = formatTimestamp(group.timestamp);
-            const els = renderTextBlock(content, ts, true);
-            elements.push(...els);
-        }
-        else if (group.kind === 'tool') {
-            // Degraded: show tool individually (each tool is independent now)
-            if (options.showToolUse === false)
-                continue;
-            elements.push(renderTool(group.tool, true, options.showToolResult !== false)); // finalized=true
-        }
-    }
-    elements.push(...buildSummaryContent(state));
-    // Bottom action row: stop (if running) + new session (always)
+const DEGRADED_TIER = {
+    thinkingKeep: DEGRADED_THINKING_KEEP,
+    thinkingBytes: REASONING_BYTES,
+    toolKeep: DEGRADED_TOOL_KEEP,
+    textBytes: TEXT_BYTES,
+};
+const EXTREME_TIER = {
+    thinkingKeep: 1,
+    thinkingBytes: DEGRADED_THINKING_BYTES,
+    toolKeep: EXTREME_TOOL_KEEP,
+    textBytes: DEGRADED_TEXT_BYTES,
+};
+/** Bottom action row: stop (if running) + compact (if applicable) + new session (always). */
+function actionRow(state) {
     const actionButtons = [];
     // finalizing 也显示停止按钮（进程未退出，用户可 /stop）
     const showStop = state.terminal === 'running' || state.terminal === 'finalizing';
     if (showStop) {
         actionButtons.push(stopButton(state.runId));
     }
+    // Compact 按钮：普通 turn 到达任意终态即可压缩（含异常退出），compaction 卡除外
+    if (shouldShowCompactButton(state)) {
+        actionButtons.push(compactButton(state.runId));
+    }
     actionButtons.push(newSessionButton());
-    if (actionButtons.length > 0) {
-        elements.push({ tag: 'div', text: { content: '‎', tag: 'lark_md' } }, // spacer
+    if (actionButtons.length === 0)
+        return [];
+    return [
+        { tag: 'div', text: { content: '‎', tag: 'lark_md' } }, // spacer
         {
             tag: 'column_set',
             columns: actionButtons.map((btn) => ({
@@ -267,53 +224,80 @@ function buildDegradedElements(state, options) {
                 width: 'auto',
                 elements: [btn],
             })),
-        });
+        },
+    ];
+}
+/** 审批区位于 body 最底部（底部操作行之后）：待审批时决策按钮不遮挡内容流。 */
+function approvalArea(state) {
+    const elements = [];
+    for (const slot of state.approvals ?? []) {
+        elements.push(...renderApprovalArea(slot.view, {
+            expired: slot.expired,
+            runId: state.runId,
+            terminal: state.terminal,
+        }));
     }
     return elements;
 }
+/** Assemble the card shell (schema/config/header) around body elements. */
+function assembleRunCard(state, options, elements) {
+    return {
+        schema: '2.0',
+        config: { wide_screen_mode: true, update_multi: true },
+        header: {
+            template: headerTemplate2(state),
+            title: { content: headerTitle2(state, options), tag: 'plain_text' },
+        },
+        body: { elements },
+    };
+}
 /**
- * Extreme fallback when even degraded card exceeds 28KB.
- * Strategy: text truncated to 5KB tail, thinking only last 1 truncated to 1KB,
- * tools keep last N (more aggressive than degraded).
- *
- * 性能优化：单遍分桶替代多次 state.blocks.filter()。
+ * Build a budget-fallback tier (degraded or extreme): keep the last N thinking
+ * blocks and last N tools, truncate text/thinking per tier, then render in
+ * chronological order. Shared by buildDegradedElements / buildExtremeFallback.
  */
-function buildExtremeFallbackElements(state, options) {
+function buildFallbackElements(state, options, tier) {
     const elements = [];
     elements.push(statusRow(state));
-    // 单遍分桶：thinking / tool
+    // 单遍分桶：thinking / tool（保持原相对顺序）
     const { thinking: allThinkingBlocks, tool: allToolBlocks } = bucketThinkingAndTool(state.blocks);
-    // Thinking: only keep last 1 for extreme fallback
-    if (allThinkingBlocks.length > 1) {
-        const omitted = allThinkingBlocks.length - 1;
+    if (allThinkingBlocks.length > tier.thinkingKeep) {
+        const omitted = allThinkingBlocks.length - tier.thinkingKeep;
         elements.push(markdownDiv(`_💡 ${omitted} 个早期思考已省略_`));
     }
-    const thinkingBlockToShow = allThinkingBlocks.length > 0 ? allThinkingBlocks[allThinkingBlocks.length - 1] : null;
-    const toolsToShow = allToolBlocks.slice(-EXTREME_TOOL_KEEP);
-    const toolsOmitted = allToolBlocks.length - EXTREME_TOOL_KEEP;
+    const thinkingBlocksToShow = allThinkingBlocks.slice(-tier.thinkingKeep);
+    const toolsToShow = allToolBlocks.slice(-tier.toolKeep);
+    const toolsOmitted = allToolBlocks.length - tier.toolKeep;
     // Add omit hint for tools if any were omitted
     if (toolsOmitted > 0) {
         elements.push(markdownDiv(`_💡 另外 ${toolsOmitted} 个工具调用已省略_`));
     }
-    // Build filtered blocks: only last thinking, last N tools, all text
+    // P2-6: use object references (like the extreme path) instead of timestamps.
+    // RunBlock.timestamp has millisecond precision; ≥2 thinking blocks sharing a
+    // timestamp collapse to one Set entry, so `has(block.timestamp)` lets ALL
+    // same-timestamp blocks (including ones meant to be omitted) pass through —
+    // inflating the card past 28KB and contradicting the "N omitted" hint.
+    // `thinkingBlocksToShow` is a slice of `allThinkingBlocks`, so the blocks
+    // retain stable references and the Set membership check is exact.
+    const thinkingSetToShow = new Set(thinkingBlocksToShow);
     const toolIdsToShow = new Set(toolsToShow.map((b) => b.tool.id));
     const filteredBlocks = state.blocks.filter((block) => {
         if (block.kind === 'thinking') {
-            return block === thinkingBlockToShow;
+            return thinkingSetToShow.has(block);
         }
         if (block.kind === 'tool') {
             return toolIdsToShow.has(block.tool.id);
         }
-        return true; // keep all text and other blocks
+        return true; // keep all non-thinking, non-tool blocks
     });
-    // Render in chronological order
+    // Render thinking/text/tool in chronological order using groupBlocks
     for (const group of groupBlocks(filteredBlocks)) {
         if (group.kind === 'thinking') {
             if (options.showThinking === false)
                 continue;
             const ts = formatTimestamp(group.timestamp);
             const title = '💭 **思考完成**';
-            const content = truncateUtf8(group.content, DEGRADED_THINKING_BYTES);
+            const content = truncateUtf8(group.content, tier.thinkingBytes);
             const header = ts ? `${title} (${ts})` : title;
             elements.push(collapsibleMarkdownPanel({
                 title: header,
@@ -324,43 +308,40 @@ function buildExtremeFallbackElements(state, options) {
             }));
         }
         else if (group.kind === 'text') {
-            const content = truncateUtf8(group.content, DEGRADED_TEXT_BYTES, true, '…（已截断）\n');
+            const content = truncateUtf8(group.content, tier.textBytes, true, '…（已截断）\n');
             const ts = formatTimestamp(group.timestamp);
-            const els = renderTextBlock(content, ts, true);
-            elements.push(...els);
+            elements.push(...renderTextBlock(content, ts, true));
         }
         else if (group.kind === 'tool') {
-            // Extreme fallback: show tool individually
+            // Show tool individually (each tool is independent now)
             if (options.showToolUse === false)
                 continue;
-            elements.push(renderTool(group.tool, true, options.showToolResult !== false));
+            elements.push(renderTool(group.tool, true, options.showToolResult !== false)); // finalized=true
         }
     }
-    if (elements.length === 0) {
+    if (elements.length === 0 && tier === EXTREME_TIER) {
         elements.push(markdownDiv('_暂无输出_'));
     }
     elements.push(...buildSummaryContent(state));
-    // Bottom action row: stop (if running) + new session (always)
-    const actionButtons = [];
-    // finalizing 也显示停止按钮（进程未退出，用户可 /stop）
-    const showStop = state.terminal === 'running' || state.terminal === 'finalizing';
-    if (showStop) {
-        actionButtons.push(stopButton(state.runId));
-    }
-    actionButtons.push(newSessionButton());
-    if (actionButtons.length > 0) {
-        elements.push({ tag: 'div', text: { content: '‎', tag: 'lark_md' } }, // spacer
-        {
-            tag: 'column_set',
-            columns: actionButtons.map((btn) => ({
-                tag: 'column',
-                width: 'auto',
-                elements: [btn],
-            })),
-        });
-    }
+    elements.push(...actionRow(state));
+    elements.push(...approvalArea(state));
     return elements;
 }
+/**
+ * Build degraded elements when full card exceeds 28KB budget.
+ * Strategy: text fully preserved, thinking keeps last 2, tools keep last N (compressed).
+ */
+function buildDegradedElements(state, options) {
+    return buildFallbackElements(state, options, DEGRADED_TIER);
+}
+/**
+ * Extreme fallback when even degraded card exceeds 28KB.
+ * Strategy: text truncated to 5KB tail, thinking only last 1 truncated to 1KB,
+ * tools keep last N (more aggressive than degraded).
+ */
+function buildExtremeFallbackElements(state, options) {
+    return buildFallbackElements(state, options, EXTREME_TIER);
+}
 /** Build the status row element (shared across full/degraded/extreme). */
 function statusRow(state) {
     const statusLabel = statusTagLabel(state.terminal);
@@ -399,23 +380,9 @@ function buildSkeletonElements(state) {
     elements.push(markdownDiv('_⚠️ 输出过大且含大量转义字符，已省略全部内容以避免超限；完整内容请查日志_'));
     // Summary (token stats etc.) — static, bounded size
     elements.push(...buildSummaryContent(state));
-    // Bottom action row: stop (if running/finalizing) + new session (always).
+    // Bottom action row: stop (if running/finalizing) + compact (if applicable) + new session (always).
     // Degraded paths must keep the action buttons reachable (design constraint).
-    const actionButtons = [];
-    const showStop = state.terminal === 'running' || state.terminal === 'finalizing';
-    if (showStop) {
-        actionButtons.push(stopButton(state.runId));
-    }
-    actionButtons.push(newSessionButton());
-    elements.push({ tag: 'div', text: { content: '‎', tag: 'lark_md' } }, // spacer
-    {
-        tag: 'column_set',
-        columns: actionButtons.map((btn) => ({
-            tag: 'column',
-            width: 'auto',
-            elements: [btn],
-        })),
-    });
+    elements.push(...actionRow(state));
     return elements;
 }
 /**
@@ -572,93 +539,41 @@ function measurePanelBytes(title, expanded, border, content) {
  * CardKit 2.0 renderer - simplified for streaming (no tabs)
  */
 export function renderRunCard(state, options = {}) {
-    const { terminal, runId } = state;
     // 先估后建：用廉价估算预测是否超 28KB 预算，明显超预算直接跳过完整卡构建走
     // degraded。P1-2：groups/prepared 只算一次，测量与正式渲染共用同一份截断结果，
     // 避免影子测量 + 正式渲染对每个超限块双倍截断。
     const groups = groupBlocks(state.blocks);
     const prepared = prepareGroupContent(groups);
     const estimate = estimateCardBytes(state, options, { groups, prepared });
-    // Stop button: show when running or finalizing (process not yet exited)
-    const showStop = terminal === 'running' || terminal === 'finalizing';
     // 构建完整卡（仅在估算低于阈值时，避免大 state 浪费 render + stringify）
     if (estimate < DEGRADED_THRESHOLD) {
         const elements = [
             statusRow(state),
             ...buildChronologicalContent(state, options, prepared, groups),
             ...buildSummaryContent(state),
+            ...actionRow(state),
+            ...approvalArea(state),
         ];
-        // Bottom action row: stop (if running) + new session (always)
-        const actionButtons = [];
-        if (showStop) {
-            actionButtons.push(stopButton(runId));
-        }
-        actionButtons.push(newSessionButton());
-        if (actionButtons.length > 0) {
-            elements.push({ tag: 'div', text: { content: '‎', tag: 'lark_md' } }, // spacer
-            {
-                tag: 'column_set',
-                columns: actionButtons.map((btn) => ({
-                    tag: 'column',
-                    width: 'auto',
-                    elements: [btn],
-                })),
-            });
-        }
-        const card = {
-            schema: '2.0',
-            config: { wide_screen_mode: true, update_multi: true },
-            header: {
-                template: headerTemplate2(state),
-                title: { content: headerTitle2(state, options), tag: 'plain_text' },
-            },
-            body: { elements },
-        };
+        const card = assembleRunCard(state, options, elements);
         // Check budget — stringify 兜底（估算可能低估，仍保留安全网）
         if (Buffer.byteLength(JSON.stringify(card), 'utf8') <= CARD_BUDGET_BYTES)
             return card;
         // 超预算 → 继续走 degraded（不 return，fallthrough）
     }
     // 估算 ≥ 阈值 或 完整卡 stringify 超预算 — 走 degraded 渲染
-    const degradedElements = buildDegradedElements(state, options);
-    const degradedCard = {
-        schema: '2.0',
-        config: { wide_screen_mode: true, update_multi: true },
-        header: {
-            template: headerTemplate2(state),
-            title: { content: headerTitle2(state, options), tag: 'plain_text' },
-        },
-        body: { elements: degradedElements },
-    };
+    const degradedCard = assembleRunCard(state, options, buildDegradedElements(state, options));
     if (Buffer.byteLength(JSON.stringify(degradedCard), 'utf8') <= CARD_BUDGET_BYTES) {
         return degradedCard;
     }
     // Extreme fallback: even degraded exceeds budget
-    const extremeElements = buildExtremeFallbackElements(state, options);
-    const extremeCard = {
-        schema: '2.0',
-        config: { wide_screen_mode: true, update_multi: true },
-        header: {
-            template: headerTemplate2(state),
-            title: { content: headerTitle2(state, options), tag: 'plain_text' },
-        },
-        body: { elements: extremeElements },
-    };
+    const extremeCard = assembleRunCard(state, options, buildExtremeFallbackElements(state, options));
     // Final safety net: extreme fallback 是最后一层，但高转义内容（反斜杠 4× 膨胀）
     // 可能让 extreme 产物本身 >28KB。补上 stringify 兜底（与 normal/degraded 对称）：
     // 超预算则降级到结构性保证 ≤28KB 的 skeleton 卡，避免飞书 11310 整卡不可用。
     if (Buffer.byteLength(JSON.stringify(extremeCard), 'utf8') <= CARD_BUDGET_BYTES) {
         return extremeCard;
     }
-    const skeletonCard = {
-        schema: '2.0',
-        config: { wide_screen_mode: true, update_multi: true },
-        header: {
-            template: headerTemplate2(state),
-            title: { content: headerTitle2(state, options), tag: 'plain_text' },
-        },
-        body: { elements: buildSkeletonElements(state) },
-    };
+    const skeletonCard = assembleRunCard(state, options, buildSkeletonElements(state));
     // skeleton 卡是静态结构，理论上必 ≤28KB；保留兜底断言以防未来结构膨胀
     if (Buffer.byteLength(JSON.stringify(skeletonCard), 'utf8') <= CARD_BUDGET_BYTES) {
         return skeletonCard;
@@ -765,7 +680,18 @@ function buildSummaryContent(state) {
         elements.push(markdownDiv(`⚠️ **运行出错**\n\n${state.errorMsg ?? '未知错误'}`));
     }
     else if (state.terminal === 'interrupted') {
-        elements.push(markdownDiv('⏹ **已被用户终止**'));
+        // 审批超时（approval_expired 已标记）是「无人响应被自动取消」，不是用户
+        // 主动终止；如实展示原因，避免用户误判为 Agent 出错或自己操作过。
+        // 顶层 approvalExpired 优先：approval_resolved 会移除审批条目，但标记
+        // 必须活到终态渲染（2026-08-15 事故回归）。
+        const expiredApproval = state.interruptedReason === 'approval_timeout' ||
+            state.approvalExpired === true ||
+            (state.approvals ?? []).some((a) => a.expired);
+        elements.push(markdownDiv(expiredApproval
+            ? '⏰ **审批超时未响应，已自动取消**'
+            : state.interruptedReason === 'approval_cancelled'
+                ? '⏹ **已取消审批，任务终止**'
+                : '⏹ **已被用户终止**'));
     }
     else if (state.terminal === 'idle_timeout') {
         elements.push(markdownDiv(`⏱ **已超时**\n\n${state.idleTimeoutMinutes ?? 0} 分钟无响应，已自动终止`));
@@ -778,6 +704,7 @@ function buildSummaryContent(state) {
             contextLength: state.contextLength,
             contextLimit: state.contextLimit,
             compactCount: state.compactCount,
+            compactPreContextLength: state.compactPreContextLength,
             cacheReadTokens: state.cacheReadTokens,
             cacheCreationTokens: state.cacheCreationTokens,
             totalTokens: state.totalTokens,
@@ -801,6 +728,9 @@ function buildDurationInfo(state) {
         state.terminal === 'idle_timeout') {
         return `⏱ ${state.footer || '已完成'}`;
     }
+    // 与标题一致：审批等待期间状态行显示「等待审批中」，而不是「工具调用中」。
+    if (hasPendingApproval(state))
+        return '✋ 等待审批中';
     return footerText2(state.footer);
 }
 function footerText2(footer) {
@@ -827,6 +757,10 @@ function headerTitle2(state, options = {}) {
         return `⏱ ${agent} · 已超时`;
     if (state.terminal === 'finalizing')
         return `⏳ ${agent} · 完成中`;
+    // 审批等待期间 server 暂停 turn，命令工具停在 tool_running——标题必须提示
+    // 正在等人工决策，而不是「调用工具」（2026-08-14 UX）。
+    if (hasPendingApproval(state))
+        return `✋ ${agent} · 等待审批`;
     if (state.footer === 'thinking')
         return `💭 ${agent} · 思考中`;
     if (state.footer === 'streaming')
@@ -835,6 +769,10 @@ function headerTitle2(state, options = {}) {
         return `🔧 ${agent} · 调用工具`;
     return `🔴 ${agent} · 运行中`;
 }
+/** 是否有未过期（仍可操作）的待审批请求。 */
+function hasPendingApproval(state) {
+    return (state.approvals ?? []).some((a) => !a.expired);
+}
 /** CardKit 2.0 header template color */
 function headerTemplate2(state) {
     return terminalToColor(state.terminal);

package/dist/card/run-state.d.ts

@@ -1,6 +1,8 @@
-import type { AgentEvent } from '../runner/index.js';
+import type { AgentEvent, ApprovalView } from '../runner/index.js';
 export type RunTerminal = 'running' | 'finalizing' | 'done' | 'error' | 'interrupted' | 'idle_timeout';
 export type RunFooter = 'thinking' | 'tool_running' | 'streaming' | null;
+/** 中断来源（interrupted 终态的原因），供卡片如实归因。 */
+export type InterruptedReason = 'approval_timeout' | 'user_stop' | 'approval_cancelled';
 type ToolStatus = 'running' | 'ok' | 'error';
 export interface ToolEntry {
     id: string;
@@ -23,27 +25,36 @@ export interface ToolEntry {
 }
 export type RunBlock = {
     kind: 'thinking';
+    /** app-server item id; exec-mode blocks leave it undefined. */
+    itemId?: string;
     content: string;
     active: boolean;
     timestamp?: string;
+    completedAt?: string;
 } | {
     kind: 'text';
+    itemId?: string;
     content: string;
     timestamp?: string;
+    completedAt?: string;
 } | {
     kind: 'tool';
     tool: ToolEntry;
 } | {
     kind: 'plan';
+    itemId?: string;
     content: string;
     active: boolean;
     timestamp?: string;
+    completedAt?: string;
 } | {
     kind: 'file_change';
+    itemId?: string;
     path: string;
     operation: 'create' | 'edit' | 'delete' | 'read';
     diff?: string;
     timestamp?: string;
+    completedAt?: string;
 };
 export interface RunState {
     runId: string;
@@ -51,7 +62,9 @@ export interface RunState {
     footer: RunFooter;
     blocks: RunBlock[];
     sessionId?: string;
-    resultSubtype?: 'success' | 'error';
+    resultSubtype?: 'success' | 'error' | 'interrupted';
+    /** interrupted 终态的中断来源；undefined = 未归类（渲染默认文案）。 */
+    interruptedReason?: InterruptedReason;
     contextLength?: number;
     /** 当前模型 context window 上限（codex jsonl 提供）；卡片据此渲染百分比。 */
     contextLimit?: number;
@@ -77,15 +90,37 @@ export interface RunState {
     /** 会话累计 cache creation token（所有 run 之和）。 */
     cumulativeCacheCreationTokens?: number;
     plan?: string;
+    /** Codex 操作类型：'turn' 表示普通 run，'compaction' 表示 compact 运行。 */
+    operationKind?: 'turn' | 'compaction';
+    /** 压缩前上下文水位（codex compact 卡展示「压缩前 X → 压缩后 Y」）。 */
+    compactPreContextLength?: number;
+    /**
+     * 待审批请求列表（app-server 模式，review P2-3）。同一 turn 内并发多个审批
+     * 时全部渲染，避免后到者顶掉先到者的按钮（单槽会丢 UI，只能等超时 cancel）。
+     */
+    approvals?: Array<{
+        view: ApprovalView;
+        expired?: boolean;
+    }>;
+    /**
+     * 审批是否曾过期（桥侧 timer 触发，approval_expired 事件置位）。
+     * 独立于 approvals 数组持久保存：cancel 送达后 server 会回
+     * approval_resolved，把对应审批条目从数组移除，但过期原因必须活到
+     * 终态渲染（2026-08-15 事故：标记被消费后卡片误报「已被用户终止」）。
+     */
+    approvalExpired?: boolean;
 }
 export interface FinishMeta {
-    resultSubtype?: 'success' | 'error';
+    resultSubtype?: 'success' | 'error' | 'interrupted';
+    /** 中断来源：由桥侧在 finish 时显式传入（/stop → user_stop、审批卡取消 → approval_cancelled）。 */
+    interruptedReason?: InterruptedReason;
     contextLength?: number;
     /** 当前模型 context window 上限；透传到 RunState 供 done 卡片显示百分比。 */
     contextLimit?: number;
     errorMsg?: string;
     idleTimeoutMinutes?: number;
     compactCount?: number;
+    compactPreContextLength?: number;
     cacheReadTokens?: number;
     cacheCreationTokens?: number;
     /** Agent-declared total; threaded to RunState for the done card. */