lark-remote 0.5.12 → 0.5.14

package/CHANGELOG.md

@@ -5,6 +5,32 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.5.14] - 2026-10-28
+
+### 修复
+
+- **卡片停止刷新不再查不到原因**：飞书拒收一次卡片更新后，这张卡会被永久剔除、此后不再原地刷新（用户侧表现为「卡片卡在最后一步」）。这条失败此前只记 debug 级日志，在默认 `info` 级别下看不到；现在按 warn 记录，带上下原因
+- **自重启的前实例信息读取失败不再被误归因**：`/restart` 读旧实例的 startup-contact 时，只有「从未写过」（首次运行）算正常；解析失败或权限问题现在会留痕，否则排查时被当成「旧 owner 没有条目」而走错方向
+
+### 维护
+
+- **agent 名单、会话读取契约、用量字段与模型别名各自单源**：新增 `src/agent-kinds.ts`、`src/session-contract.ts`、`src/model-catalog.ts`。用量字段清单原先手抄了 5 份、加一个字段要同时改三处，现在统一从一处派生。无行为变化
+- **模块归位，依赖方向只剩单向**：`card-helpers` / `usage-format` 从 router 移入 card，DSH 的协议、类型与 home 解析从 runner 提到 `src/dsh/`；地基层（配置、会话、卡片）不再反向 import 上层，并加了依赖方向守卫用例守住这条边。无行为变化
+- **`/config` 卡片删掉从未被任何字段使用的开关控件形态**，同时加「控件 ↔ 处理端」一致性守卫：渲染得出的按钮必定有对应处理分支，也不会漏进即时动作名单——「按钮点下去没人处理」这类状态从此被测出来
+- **审批动作与排队管理从 bridge 拆成独立模块**，入口装配线（进程级异常处理器、ConfigDir 派生路径、agent 工厂闭包）收拢为单文件静态守卫；顺带清掉死代码、重复实现与静默吞错的分支。无行为变化
+- **单元测试纳入类型检查**：`tsconfig.test-infra.json` 不再排除 `src/**/*.test.ts`，`bun run typecheck` 现在会检查测试文件的类型，测试夹具里的陈旧键当场可见
+
+## [0.5.13] - 2026-10-26
+
+### 修复
+
+- **长回合的最终回答不再被进度内容挤掉**：工具输出、思考、通知此前与最终回答共用同一份卡片预算，回合越长越容易把回答截断甚至整段挤没。现在最终回答独立保存，不受进度文本窗口和工具块上限淘汰；终态渲染先排状态、审批与操作控件，再放完整回答，剩余空间才从新到旧回填进度内容。协议带 `final_answer` 标记的（Codex app-server）直接采用，没有标记的 agent 在收尾时把最后一条非空 assistant 文本提升为最终回答，Claude、opencode、Kimi、Pi、DSH 共用同一套保护
+- **回答放不下时随后补发完整文本**：单张卡片连「最终回答 + 必要控件」都装不下时，原卡提示「最终回答较长，完整内容已随后发送」，完整回答按 UTF-8 字节边界拆成多条纯文本消息补发（优先落在换行处，单条上限 20000 字节），拼接后与原文逐字一致，不再静默截断；补发失败会在原卡给出「完整回答补发失败」的可见回执
+
+### 维护
+
+- **入口与路由/桥接层拆分为独立模块**：消息入站装配、命令实现（`ls` / `order` / `resume` / `ws`）、分页与路径校验、审批转发、用量聚合、会话回写、DSH 多路复用流各自成模块，`src/index.ts`、`src/bridge/index.ts`、`src/router/index.ts` 只保留编排职责；同时为拆分中暴露的状态竞争（中断与自然结束并发写同一张卡的终态、审批重投递、bash 卡片收尾）补上回归用例。无行为变化
+
 ## [0.5.12] - 2026-10-24
 
 ### 修复
@@ -562,8 +588,8 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### 修复
 
 - `displayTitle`/`summary` 跳过 task-notification 注入
-- 修复 `scanClaudeSessions` 对迁移到其他目录的会话的遗漏（S2）
-- 修复 probe 生命周期、工厂回退、卡片回调等评审发现的问题（F1-F8）
+- 修复 `scanClaudeSessions` 对迁移到其他目录的会话的遗漏
+- 修复 probe 生命周期、工厂回退、卡片回调等问题
 
 ### 变更
 

package/README.en.md

@@ -14,19 +14,6 @@ Designed for a single-user, peer-to-peer private chat. The agent's system prompt
 
 > **New here? Start with [docs/en/getting-started.md](docs/en/getting-started.md).**
 
-## ⚠️ Security Warning (read first)
-
-This tool turns Feishu messages directly into local agent executions. **Out of the box, agents run without approval prompts**: Claude defaults to `bypassPermissions` (no approval card), but that permission mode is **configurable** — set it to anything other than `bypassPermissions` (`default` / `acceptEdits` / `auto` / `dontAsk` / `plan`) to enable interactive approval, where high-risk actions wait for your confirmation on the Feishu card. Codex uses the **app-server approval mode** (default `approvalPolicy=on-request` — command execution requires your confirmation on the Feishu card, sandbox defaults to `workspace-write`); Kimi defaults to `manual` (per-action approval; note that since kimi 0.40, `yolo` means Ask-When-Needed rather than allow-everything — use `auto` for fully unattended, no-approval execution); other agents run with their CLI defaults. **In any mode**, agents can read and write the local directories you specify. You MUST:
-
-- **Use it only in your own private (p2p) chat.** Never add the bot to any group chat; never let anyone else talk to it.
-- Restrict the app's visibility to **yourself only** in the Feishu Open Platform.
-- Don't run it on a machine holding data you can't afford to lose; prefer a dedicated user / machine / container.
-- Keep credentials such as `appSecret` in your local `config.yaml` only — **never commit them anywhere**.
-
-In approval mode (Claude, Codex, Kimi), an approval card arrives before a command runs — approve or reject it right in Feishu:
-
-![Command approval card example](docs/images/approval-card.png)
-
 ## Prerequisites
 
 - OS: macOS / Linux / Windows 10+ (native Windows support is verified on real hardware, with behavior matching macOS/Linux)
@@ -70,7 +57,7 @@ defaultAgent: claude
 claude:
   model: claude-opus-4-8
   effort: medium            # low | medium | high | xhigh | max
-  permissionMode: bypassPermissions  # Claude official --permission-mode: default | acceptEdits | auto | bypassPermissions | manual | dontAsk | plan (switchable via /config card; anything other than bypassPermissions enables approval)
+  permissionMode: auto  # Claude official --permission-mode: default | acceptEdits | auto | bypassPermissions | manual | dontAsk | plan (switchable via /config card; auto is the default: low-risk actions run, high-risk actions ask)
   stopGraceMs: 5000
 
 logging:

package/README.md

@@ -14,19 +14,6 @@
 
 > **第一次接触本项目？先看 [docs/zh/getting-started.md](docs/zh/getting-started.md)。**
 
-## ⚠️ 安全警告（必读）
-
-本工具会把飞书消息直接转为本地 agent 执行。**开箱默认是不弹审批的**：Claude 默认以 `bypassPermissions` 运行（无审批卡），但该权限模式**可配置**——把它改成 `bypassPermissions` 以外的值（`default` / `acceptEdits` / `auto` / `dontAsk` / `plan`）即启用交互式审批，高风险操作会在飞书卡片上等你确认；Codex 采用 **app-server 审批模式**（默认 `approvalPolicy=on-request`，执行命令需在飞书卡片上确认，沙箱默认 `workspace-write`）；Kimi 默认 `manual`（逐条审批；注意 kimi 0.40+ 起 `yolo` 已改为「必要时询问」而非全部放行，要完全不弹审批需选 `auto`）；其他 agent 以各自 CLI 的默认权限运行。**无论哪种模式**，agent 都能读写你指定的本地目录，请务必：
-
-- **仅限你自己的私聊（p2p）使用**。不要把机器人拉进任何群聊，不要让任何其他人能与它对话。
-- 在飞书开放平台把应用可见范围限制到**只有你自己**。
-- 运行本工具的机器上不要存放与损失承受力不符的数据；建议在独立用户/机器/容器里运行。
-- `appSecret` 等凭据只在本地 `config.yaml`，**不要提交到任何仓库**。
-
-审批模式下（Claude、Codex、Kimi），执行命令前会收到审批卡片，可直接在飞书里允许或拒绝：
-
-![命令审批卡片示例](docs/images/approval-card.png)
-
 ## 前置条件
 
 - 操作系统：macOS / Linux / Windows 10+（原生 Windows 支持已完成真机验证，行为与 macOS/Linux 对齐）
@@ -70,7 +57,7 @@ defaultAgent: claude
 claude:
   model: claude-opus-4-8
   effort: medium            # low | medium | high | xhigh | max
-  permissionMode: bypassPermissions  # Claude 官方 --permission-mode：default | acceptEdits | auto | bypassPermissions | manual | dontAsk | plan（`/config` 卡片可切换；非 bypassPermissions 会启用审批）
+  permissionMode: auto  # Claude 官方 --permission-mode：default | acceptEdits | auto | bypassPermissions | manual | dontAsk | plan（`/config` 卡片可切换；auto 为默认：低风险放行、高风险审批）
   stopGraceMs: 5000
 
 logging:

package/dist/agent-kinds.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Agent 名单单源（运行时数组 + 类型同源，二者不可能漂移）。
+ *
+ * 中立层：config（校验 defaultAgent）、session（按 agent 存 sessionId）、card
+ * （显示名）、router（解析用户输入）、runner（实现各家 runner）都要用这个名字，
+ * 谁都不该为了拿它去 import 别层的模块 —— 名单原先住在 runner/types.ts 时，
+ * 地基层 config 就得反向 import 上层 runner。
+ *
+ * 历史上这份名单被手抄成多份（router 的 VALID_AGENTS、bridge 的 resume.compact
+ * 校验、各 agent 的 config builder…），漂移过：dsh 加入后 bridge 的
+ * resume.compact 仍只有 5 个，带 dsh 的 resume 卡片会静默退回 defaultAgent。
+ * 新增 agent 只改这里。
+ */
+export declare const AGENT_KINDS: readonly ["claude", "codex", "opencode", "pi", "kimi", "dsh"];
+export type AgentKind = (typeof AGENT_KINDS)[number];
+/** 用户可见 agent 显示名单源：启动注册与无 registry 的回退路径共用。 */
+export declare const AGENT_DISPLAY_NAMES: Record<AgentKind, string>;
+/** 任意输入（卡片 payload / 命令行参数）是否是一个已知 agent 名。 */
+export declare function isAgentKind(value: unknown): value is AgentKind;
+/**
+ * 解析用户给出的 agent 名，未知/缺省时回退 `fallback`。
+ *
+ * 判定此前抄了三份（router 的两处 resume 分支 + commands/resume.ts）；名单与
+ * 判定同源才有意义——`resume.compact` 曾因手抄名单漏掉 dsh 而静默退回
+ * defaultAgent（见 `AGENT_KINDS` 头注）。
+ */
+export declare function resolveAgentKind(value: unknown, fallback: AgentKind): AgentKind;

package/dist/agent-kinds.js

@@ -0,0 +1,38 @@
+/**
+ * Agent 名单单源（运行时数组 + 类型同源，二者不可能漂移）。
+ *
+ * 中立层：config（校验 defaultAgent）、session（按 agent 存 sessionId）、card
+ * （显示名）、router（解析用户输入）、runner（实现各家 runner）都要用这个名字，
+ * 谁都不该为了拿它去 import 别层的模块 —— 名单原先住在 runner/types.ts 时，
+ * 地基层 config 就得反向 import 上层 runner。
+ *
+ * 历史上这份名单被手抄成多份（router 的 VALID_AGENTS、bridge 的 resume.compact
+ * 校验、各 agent 的 config builder…），漂移过：dsh 加入后 bridge 的
+ * resume.compact 仍只有 5 个，带 dsh 的 resume 卡片会静默退回 defaultAgent。
+ * 新增 agent 只改这里。
+ */
+export const AGENT_KINDS = ['claude', 'codex', 'opencode', 'pi', 'kimi', 'dsh'];
+/** 用户可见 agent 显示名单源：启动注册与无 registry 的回退路径共用。 */
+export const AGENT_DISPLAY_NAMES = {
+    claude: 'Claude',
+    codex: 'Codex',
+    opencode: 'Opencode',
+    pi: 'Pi',
+    kimi: 'Kimi',
+    dsh: 'DSH',
+};
+/** 任意输入（卡片 payload / 命令行参数）是否是一个已知 agent 名。 */
+export function isAgentKind(value) {
+    return AGENT_KINDS.includes(value);
+}
+/**
+ * 解析用户给出的 agent 名，未知/缺省时回退 `fallback`。
+ *
+ * 判定此前抄了三份（router 的两处 resume 分支 + commands/resume.ts）；名单与
+ * 判定同源才有意义——`resume.compact` 曾因手抄名单漏掉 dsh 而静默退回
+ * defaultAgent（见 `AGENT_KINDS` 头注）。
+ */
+export function resolveAgentKind(value, fallback) {
+    return isAgentKind(value) ? value : fallback;
+}
+//# sourceMappingURL=agent-kinds.js.map

package/dist/bridge/approval-actions.d.ts

@@ -0,0 +1,95 @@
+/**
+ * 审批卡动作分发（Bridge 的终态卡动作侧，审计 #32 的一刀）。
+ *
+ * 每个方法只做一件事：按 runId 找到那次 run 的 `ApprovalCoordinator`，把卡片
+ * payload 翻成一次 coordinator 调用。原先这 7 个 handler 连同「找不到
+ * coordinator 怎么回答」的公共前缀平铺在 Bridge 里，占了 160 行却不碰任何
+ * Bridge 状态——只碰 `approvalCoordinators` 这一张表。
+ *
+ * 语义红线（保留原位，别在调用方重新实现）：
+ * - run 已结束（coordinator 已释放）时点审批按钮必须给用户明确反馈，不能静默；
+ *   router 把这个异常转成 error toast。
+ * - `nonce` 原样透传给 coordinator：飞书会重投递同一个按钮回调，去重靠它
+ *   （见 approval-coordinator.ts 的状态机注释）。
+ */
+import type { ApprovalCoordinator } from './approval-coordinator.js';
+export interface ApprovalActionDeps {
+    /** 按 runId 取该 run 的 coordinator；已结束返回 undefined。 */
+    coordinatorFor(runId: string): ApprovalCoordinator | undefined;
+}
+/** 所有 handler 共用的入参形状。 */
+interface RunScopedOpts {
+    runId: string;
+    requestId: number | string;
+}
+export declare class ApprovalActions {
+    private deps;
+    constructor(deps: ApprovalActionDeps);
+    /**
+     * Resolve the ApprovalCoordinator for a run, or throw the standard
+     * "已结束" error. Shared preamble of all approval card-action handlers.
+     */
+    private withCoordinator;
+    private dispatchQuestionAction;
+    /**
+     * Handle an approval response from a card button click.
+     * Routes to the ApprovalCoordinator for the given run.
+     */
+    handleApprovalRespond(opts: RunScopedOpts & {
+        decision: string;
+        nonce: string;
+    }): Promise<void>;
+    /**
+     * 计划审批修改意见（ExitPlanMode 输入框）：记录到 coordinator 并回流卡片。
+     * 「拒绝并附意见」/「批准并采纳修改」按钮复用该文本。
+     */
+    handleApprovalPlanFeedback(opts: RunScopedOpts & {
+        text: string;
+        nonce: string;
+    }): Promise<void>;
+    /**
+     * Handle a permission toggle from a card button click.
+     * Routes to the ApprovalCoordinator for the given run.
+     */
+    handleApprovalToggle(opts: RunScopedOpts & {
+        permId: string;
+        selected?: boolean;
+    }): Promise<void>;
+    /**
+     * Claude AskUserQuestion 选项点击（单选即时提交 / 多选切换勾选）。
+     * 路由到 ApprovalCoordinator.toggleAnswer。
+     */
+    handleApprovalAnswer(opts: RunScopedOpts & {
+        questionIndex: number;
+        option: string;
+        nonce: string;
+    }): Promise<void>;
+    /**
+     * Claude AskUserQuestion 多选问题的「提交答案」按钮。
+     * 路由到 ApprovalCoordinator.submitAnswers。
+     */
+    handleApprovalAnswerSubmit(opts: RunScopedOpts & {
+        questionIndex: number;
+        nonce: string;
+    }): Promise<void>;
+    /**
+     * Claude AskUserQuestion 自定义答案（Other）：自由文本直接
+     * 作为该单选问题的答案提交。路由到 ApprovalCoordinator.answerCustom。
+     */
+    handleApprovalAnswerCustom(opts: RunScopedOpts & {
+        questionIndex: number;
+        text: string;
+        nonce: string;
+    }): Promise<void>;
+    /**
+     * Codex AskUserQuestion 补充说明（user_note，2026-08-18 live 验证模型理解
+     * "user_note: <text>" 条目）：记录到 coordinator，随答案一起提交。
+     * 路由到 ApprovalCoordinator.answerNote。
+     */
+    handleApprovalAnswerNote(opts: RunScopedOpts & {
+        questionIndex: number;
+        text: string;
+        nonce: string;
+    }): Promise<void>;
+}
+export {};

package/dist/bridge/approval-actions.js

@@ -0,0 +1,104 @@
+/**
+ * 审批卡动作分发（Bridge 的终态卡动作侧，审计 #32 的一刀）。
+ *
+ * 每个方法只做一件事：按 runId 找到那次 run 的 `ApprovalCoordinator`，把卡片
+ * payload 翻成一次 coordinator 调用。原先这 7 个 handler 连同「找不到
+ * coordinator 怎么回答」的公共前缀平铺在 Bridge 里，占了 160 行却不碰任何
+ * Bridge 状态——只碰 `approvalCoordinators` 这一张表。
+ *
+ * 语义红线（保留原位，别在调用方重新实现）：
+ * - run 已结束（coordinator 已释放）时点审批按钮必须给用户明确反馈，不能静默；
+ *   router 把这个异常转成 error toast。
+ * - `nonce` 原样透传给 coordinator：飞书会重投递同一个按钮回调，去重靠它
+ *   （见 approval-coordinator.ts 的状态机注释）。
+ */
+import { getLogger } from '../logger/index.js';
+import { decisionToApprovalAction } from './approval-coordinator.js';
+export class ApprovalActions {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Resolve the ApprovalCoordinator for a run, or throw the standard
+     * "已结束" error. Shared preamble of all approval card-action handlers.
+     */
+    withCoordinator(runId, fn) {
+        const coordinator = this.deps.coordinatorFor(runId);
+        if (!coordinator) {
+            getLogger().warn(`[lark-remote] no approval coordinator for runId=${runId.slice(0, 8)}`);
+            throw new Error('任务已结束，审批无法响应');
+        }
+        return fn(coordinator);
+    }
+    dispatchQuestionAction(opts, action, invoke) {
+        getLogger().info(`[lark-remote] ${action} runId=${opts.runId.slice(0, 8)}... requestId=${opts.requestId} question=${opts.questionIndex}`);
+        return this.withCoordinator(opts.runId, invoke);
+    }
+    /**
+     * Handle an approval response from a card button click.
+     * Routes to the ApprovalCoordinator for the given run.
+     */
+    async handleApprovalRespond(opts) {
+        getLogger().info(`[lark-remote] handleApprovalRespond runId=${opts.runId.slice(0, 8)}... requestId=${opts.requestId} decision=${opts.decision}`);
+        return this.withCoordinator(opts.runId, async (coordinator) => {
+            // Build ApprovalAction from the decision string
+            const action = decisionToApprovalAction(opts.decision);
+            await coordinator.submit(action, { requestId: opts.requestId, nonce: opts.nonce });
+        });
+    }
+    /**
+     * 计划审批修改意见（ExitPlanMode 输入框）：记录到 coordinator 并回流卡片。
+     * 「拒绝并附意见」/「批准并采纳修改」按钮复用该文本。
+     */
+    async handleApprovalPlanFeedback(opts) {
+        return this.withCoordinator(opts.runId, async (coordinator) => {
+            await coordinator.planFeedback({ text: opts.text }, { 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) {
+        getLogger().info(`[lark-remote] handleApprovalToggle runId=${opts.runId.slice(0, 8)}... requestId=${opts.requestId} permId=${opts.permId}`);
+        return this.withCoordinator(opts.runId, async (coordinator) => {
+            // selected 由卡片根据当前渲染状态传回（取反），不再硬编码只授不撤。
+            const toggleAction = {
+                permId: opts.permId,
+                selected: opts.selected ?? true,
+            };
+            await coordinator.togglePerm(toggleAction, { requestId: opts.requestId });
+        });
+    }
+    /**
+     * Claude AskUserQuestion 选项点击（单选即时提交 / 多选切换勾选）。
+     * 路由到 ApprovalCoordinator.toggleAnswer。
+     */
+    async handleApprovalAnswer(opts) {
+        return this.dispatchQuestionAction(opts, 'handleApprovalAnswer', (coordinator) => coordinator.toggleAnswer({ questionIndex: opts.questionIndex, option: opts.option }, { requestId: opts.requestId, nonce: opts.nonce }));
+    }
+    /**
+     * Claude AskUserQuestion 多选问题的「提交答案」按钮。
+     * 路由到 ApprovalCoordinator.submitAnswers。
+     */
+    async handleApprovalAnswerSubmit(opts) {
+        return this.dispatchQuestionAction(opts, 'handleApprovalAnswerSubmit', (coordinator) => coordinator.submitAnswers({ questionIndex: opts.questionIndex }, { requestId: opts.requestId, nonce: opts.nonce }));
+    }
+    /**
+     * Claude AskUserQuestion 自定义答案（Other）：自由文本直接
+     * 作为该单选问题的答案提交。路由到 ApprovalCoordinator.answerCustom。
+     */
+    async handleApprovalAnswerCustom(opts) {
+        return this.dispatchQuestionAction(opts, 'handleApprovalAnswerCustom', (coordinator) => coordinator.answerCustom({ questionIndex: opts.questionIndex, text: opts.text }, { requestId: opts.requestId, nonce: opts.nonce }));
+    }
+    /**
+     * Codex AskUserQuestion 补充说明（user_note，2026-08-18 live 验证模型理解
+     * "user_note: <text>" 条目）：记录到 coordinator，随答案一起提交。
+     * 路由到 ApprovalCoordinator.answerNote。
+     */
+    async handleApprovalAnswerNote(opts) {
+        return this.dispatchQuestionAction(opts, 'handleApprovalAnswerNote', (coordinator) => coordinator.answerNote({ questionIndex: opts.questionIndex, text: opts.text }, { requestId: opts.requestId, nonce: opts.nonce }));
+    }
+}
+//# sourceMappingURL=approval-actions.js.map

package/dist/bridge/approval-coordinator.d.ts

@@ -179,6 +179,7 @@ export declare class ApprovalCoordinator {
     /** 记录问题答案到 tracked.answers（懒初始化 Map）。 */
     private recordAnswer;
     private getPendingQuestion;
+    private getPendingQuestionAt;
     private allQuestionsAnswered;
     /** 推送审批卡视图更新（approval_view_updated 重渲染；失败仅记日志）。 */
     private pushApprovalViewUpdate;

package/dist/bridge/approval-coordinator.js

@@ -178,12 +178,7 @@ export class ApprovalCoordinator {
      *   submitAnswers() 显式提交。
      */
     async toggleAnswer(action, ctx) {
-        const tracked = this.getPendingQuestion(ctx.requestId);
-        const questions = tracked.view.questions;
-        const q = questions[action.questionIndex];
-        if (!q) {
-            throw new Error(`Question ${action.questionIndex} not found in request ${ctx.requestId}`);
-        }
+        const { tracked, question: q } = this.getPendingQuestionAt(ctx.requestId, action.questionIndex);
         const option = q.options.find((o) => o.label === action.option);
         if (!option) {
             throw new Error(`Option "${action.option}" not found in question ${action.questionIndex}`);
@@ -217,12 +212,7 @@ export class ApprovalCoordinator {
      * 提交该问题当前勾选的选项；全部问题答完时通过 responder 提交。
      */
     async submitAnswers(action, ctx) {
-        const tracked = this.getPendingQuestion(ctx.requestId);
-        const questions = tracked.view.questions;
-        const q = questions[action.questionIndex];
-        if (!q) {
-            throw new Error(`Question ${action.questionIndex} not found in request ${ctx.requestId}`);
-        }
+        const { tracked, question: q } = this.getPendingQuestionAt(ctx.requestId, action.questionIndex);
         if (!q.multiSelect) {
             throw new Error('该问题为单选，请直接点击选项');
         }
@@ -240,12 +230,7 @@ export class ApprovalCoordinator {
      * 单选问题的答案。与单选 toggle 同语义：全部问题答完自动提交。
      */
     async answerCustom(action, ctx) {
-        const tracked = this.getPendingQuestion(ctx.requestId);
-        const questions = tracked.view.questions;
-        const q = questions[action.questionIndex];
-        if (!q) {
-            throw new Error(`Question ${action.questionIndex} not found in request ${ctx.requestId}`);
-        }
+        const { tracked, question: q } = this.getPendingQuestionAt(ctx.requestId, action.questionIndex);
         if (q.multiSelect) {
             throw new Error('自定义答案仅支持单选');
         }
@@ -266,12 +251,7 @@ export class ApprovalCoordinator {
      * 后回流视图（卡片回显），同一请求可多次修改（新 nonce 来自新渲染）。
      */
     async answerNote(action, ctx) {
-        const tracked = this.getPendingQuestion(ctx.requestId);
-        const questions = tracked.view.questions;
-        const q = questions[action.questionIndex];
-        if (!q) {
-            throw new Error(`Question ${action.questionIndex} not found in request ${ctx.requestId}`);
-        }
+        const { tracked, question: q } = this.getPendingQuestionAt(ctx.requestId, action.questionIndex);
         const text = action.text.trim();
         if (!text) {
             throw new Error('请输入补充说明');
@@ -443,6 +423,14 @@ export class ApprovalCoordinator {
         }
         return tracked;
     }
+    getPendingQuestionAt(requestId, questionIndex) {
+        const tracked = this.getPendingQuestion(requestId);
+        const question = tracked.view.questions?.[questionIndex];
+        if (!question) {
+            throw new Error(`Question ${questionIndex} not found in request ${requestId}`);
+        }
+        return { tracked, question };
+    }
     allQuestionsAnswered(tracked) {
         const questions = tracked.view.questions ?? [];
         if (questions.length === 0)

package/dist/bridge/final-usage.d.ts

@@ -1,22 +1,13 @@
 import type { SessionReaderRegistry } from '../session/index.js';
-import type { AgentKind } from '../runner/index.js';
+import type { AgentKind } from '../agent-kinds.js';
+import type { AgentSessionUsage } from '../session-contract.js';
 export declare function errorMessage(error: unknown): string;
-export type FinalUsageSnapshot = {
-    contextLength?: number;
-    contextLimit?: number;
-    compactCount?: number;
-    compactPreContextLength?: number;
-    cacheReadTokens?: number;
-    cacheCreationTokens?: number;
-    totalTokens?: number;
-    inputTokens?: number;
-    outputTokens?: number;
-    cumulativeTotalTokens?: number;
-    cumulativeInputTokens?: number;
-    cumulativeOutputTokens?: number;
-    cumulativeCacheReadTokens?: number;
-    cumulativeCacheCreationTokens?: number;
-};
+/**
+ * jsonl 侧的最终用量快照。就是 `AgentSessionUsage` 的可选形态：reader 保证
+ * input/output/contextLength 有值，这里允许「读不到」，字段清单不再手抄第二份
+ * （§9.21 的口径一致要求靠这个单源维持）。
+ */
+export type FinalUsageSnapshot = Partial<AgentSessionUsage>;
 /**
  * Read final usage (contextLength + compactCount + cache tokens) from the
  * session jsonl. Called after a run finishes.

package/dist/bridge/final-usage.js

@@ -28,24 +28,7 @@ export function resolveFinalUsage(registry, defaultAgent, sessionId, cwd, agentK
             // fallback to per-run live usage is visible in logs, not silent.
             getLogger().warn(`[lark-remote] resolveFinalUsage: no usage from jsonl sessionId=${sessionId} cwd=${cwd} agent=${agentKind}, card falls back to per-run live usage`);
         }
-        return content.usage
-            ? {
-                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,
-                inputTokens: content.usage.inputTokens,
-                outputTokens: content.usage.outputTokens,
-                cumulativeTotalTokens: content.usage.cumulativeTotalTokens,
-                cumulativeInputTokens: content.usage.cumulativeInputTokens,
-                cumulativeOutputTokens: content.usage.cumulativeOutputTokens,
-                cumulativeCacheReadTokens: content.usage.cumulativeCacheReadTokens,
-                cumulativeCacheCreationTokens: content.usage.cumulativeCacheCreationTokens,
-            }
-            : undefined;
+        return content.usage ? { ...content.usage } : undefined;
     }
     catch (err) {
         getLogger().warn(`[lark-remote] resolveFinalUsage failed sessionId=${sessionId}: ${errorMessage(err)}`);