lark-remote 0.5.12 → 0.5.14

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

@@ -1,4 +1,4 @@
-import type { AgentKind } from '../runner/types.js';
+import type { AgentKind } from '../agent-kinds.js';
 /**
  * 入队时刻快照：当前 defaultAgent + 该 agent 的 sessionId（无 session 则 undefined）。
  * 唯一捕获点：排队消息在入队时刻把 agent+session 钉进 AgentBinding，随任务闭包带到执行时刻
@@ -221,8 +221,32 @@ export declare class QueueManager {
     /**
      * Enqueue a task into the workspace-level serial queue.
      * Each cwd has its own serial queue for parallel execution across workspaces.
+     *
+     * 三段各自的职责：`registerQueuedTask`（排队元数据 + 满队拒收）、
+     * `beginQueuedTask`（接跑时刻的撤销检查/替换闭包/占用登记）、本方法
+     * （promise 链拼接与 settle 记账）。红线：链的拼接必须同步完成，
+     * 中途不得 await（否则两条入队会乱序）。
      */
     enqueue(cwd: string, task: () => Promise<void>, opts?: EnqueueOptions): void;
+    /**
+     * 登记排队元数据（展示卡数据源 + 计数 + 排队卡）。
+     *
+     * @returns false = 队列已满被拒收（不入队、不占执行槽位），调用方必须
+     *   直接把任务链跳过。背压红线：满队时拒收而不是继续 append，否则 promise
+     *   链与闭包在消息洪峰下无界增长，还会多打一张排队卡。
+     */
+    private registerQueuedTask;
+    /** 满队拒收卡（best-effort 送达，失败只记日志：任务已经被拒，不能再吞一次反馈）。 */
+    private sendQueueFullRejection;
+    /**
+     * 轮到本任务执行：撤销检查 → 消费一次性替换闭包 → 排队卡转「执行中」→
+     * 重新武装计数与 lane 占用登记 → 跑任务闭包。
+     *
+     * @returns 任务闭包的 promise；被撤销时返回 undefined（本槽位什么都不跑）。
+     */
+    private beginQueuedTask;
+    /** 取走并清除该任务的一次性替换闭包（消费即销毁）。 */
+    private takeTaskReplacement;
     /**
      * Execute a task immediately without going through the queue.
      * Used for / commands that should respond immediately.

package/dist/bridge/queue-manager.js

@@ -144,6 +144,11 @@ export class QueueManager {
     /**
      * Enqueue a task into the workspace-level serial queue.
      * Each cwd has its own serial queue for parallel execution across workspaces.
+     *
+     * 三段各自的职责：`registerQueuedTask`（排队元数据 + 满队拒收）、
+     * `beginQueuedTask`（接跑时刻的撤销检查/替换闭包/占用登记）、本方法
+     * （promise 链拼接与 settle 记账）。红线：链的拼接必须同步完成，
+     * 中途不得 await（否则两条入队会乱序）。
      */
     enqueue(cwd, task, opts) {
         // Guard: reject non-function tasks that would poison the queue chain
@@ -156,77 +161,9 @@ export class QueueManager {
         // interrupt credit granted by `resetExecutingCount` can only be consumed
         // by the interrupted task's own settle.
         const slotId = ++this.slotCounter;
-        // Track this task in the queue for display card
         const taskMeta = opts?.taskMeta;
-        let messagePreview;
-        if (taskMeta) {
-            messagePreview = taskMeta.messagePreview;
-            const queuedTask = {
-                userId: taskMeta.userId,
-                chatId: taskMeta.chatId,
-                messageId: taskMeta.messageId,
-                feishuReplyTo: taskMeta.feishuReplyTo,
-                cwd,
-                timestamp: Date.now(),
-                messagePreview,
-                editable: taskMeta.editable,
-                binding: taskMeta.binding,
-            };
-            // Check if there are tasks waiting BEFORE adding this one
-            const currentExecutingCount = this.pendingOrExecutingCount.get(cwd) ?? 0;
-            const currentQueueLength = this.queuedTasks.get(cwd)?.length ?? 0;
-            const hasWaitingTasks = currentExecutingCount > 0 || currentQueueLength > 0;
-            // bound the waiting backlog. When the queue is full, reject the
-            // task with a visible card instead of appending it (which would grow
-            // the promise chain + closures unboundedly under a message flood and
-            // fire another queue card). Do NOT increment pendingOrExecutingCount —
-            // a rejected task never executes, so it must not occupy a slot.
-            if (currentQueueLength >= MAX_WAITING_QUEUE) {
-                getLogger().warn(`[queue-manager] queue full cwd=${cwd} depth=${currentQueueLength} rejecting task messageId=${taskMeta.messageId}`);
-                void this.sendCard(taskMeta.chatId, cardWithHeader({
-                    template: 'red',
-                    title: '🚫 队列已满',
-                    elements: [
-                        {
-                            tag: 'div',
-                            text: {
-                                tag: 'lark_md',
-                                content: `当前工作目录已有 ${MAX_WAITING_QUEUE} 条消息排队等待，为防止积压已拒收本条消息。请等待队列消化后重发，或用 \`/stop\` 清空当前任务。`,
-                            },
-                        },
-                    ],
-                }), { replyTo: taskMeta.feishuReplyTo ?? taskMeta.messageId }).catch((err) => {
-                    getLogger().error('[queue-manager] failed to send queue-full rejection card:', err);
-                });
-                return;
-            }
-            // Add to cwd queue list
-            let taskList = this.queuedTasks.get(cwd);
-            if (!taskList) {
-                taskList = [];
-                this.queuedTasks.set(cwd, taskList);
-            }
-            // 身份不变量 tripwire：同一 cwd 内 queue key 必须唯一（一次入队动作一个
-            // key，铸造点 router.mintQueueTaskKey）。撞 key 时数组（追加）与 taskIndex
-            // （覆盖）必然漂移，位置显示/撤销/立即执行/卡片更新会串到别的条目上——
-            // 2026-10-08 线上缺陷就是这么长出来的。这里不改行为，只留证据。
-            if (this.indexGet(cwd, queuedTask.messageId)) {
-                getLogger().warn(`[queue-manager] duplicate queue key cwd=${cwd} messageId=${queuedTask.messageId} — ` +
-                    'queue identity must be minted per enqueue action (see router.mintQueueTaskKey)');
-            }
-            taskList.push(queuedTask);
-            this.indexAdd(cwd, queuedTask);
-            // Increment executing count SYNCHRONOUSLY so subsequent enqueues see it
-            this.pendingOrExecutingCount.set(cwd, currentExecutingCount + 1);
-            // Only send the queue card if the task actually has to wait.
-            if (hasWaitingTasks) {
-                void this.sendQueueStatusCard(cwd, taskMeta.chatId, taskMeta.messageId, messagePreview, 
-                // Reply to the real Feishu message id when the queue key is an
-                // internal key (order.exec); otherwise messageId IS the Feishu id.
-                taskMeta.feishuReplyTo);
-            }
-            getLogger().debug(`[queue-manager] enqueue task queued cwd=${cwd} queueCard=${hasWaitingTasks} executing=${currentExecutingCount + 1} queueLen=${currentQueueLength + 1}`);
-        }
+        if (taskMeta && !this.registerQueuedTask(cwd, taskMeta))
+            return;
         // Get or create the queue for this cwd
         let queue = this.queues.get(cwd);
         if (!queue) {
@@ -236,97 +173,8 @@ export class QueueManager {
         getLogger().debug(`[queue-manager] enqueue cwd=${cwd}`);
         // Capture messageId for cancellation guard
         const messageId = taskMeta?.messageId;
-        // messagePreview already captured above (outside taskMeta block)
         const newQueue = queue
-            .then(() => {
-            getLogger().debug(`[queue-manager] task begin cwd=${cwd} messageId=${messageId}`);
-            // Live preview for the executing card: read from the QueuedTask at
-            // begin time, not the enqueue-closure `taskMeta` (which is frozen).
-            // `updateQueuedTaskMessage` (queue.edit/queue.input) mutates the live
-            // task, so a task edited while queued must show the edited content
-            // when it naturally starts.
-            let livePreview = taskMeta?.messagePreview ?? '';
-            // Check if this task was cancelled before executing
-            if (messageId) {
-                // O(1) index lookup replaces the old `find` + `findIndex`
-                // double O(N) scan. The ordered array still drives removal (splice
-                // preserves queue order for position display); the index stays in
-                // sync via indexRemove.
-                const task = this.indexGet(cwd, messageId);
-                if (!task) {
-                    getLogger().debug(`[queue-manager] task skipped (cancelled) cwd=${cwd} messageId=${messageId}`);
-                    return;
-                }
-                livePreview = task.messagePreview;
-                // Remove this task's metadata by messageId
-                const taskList = this.queuedTasks.get(cwd);
-                const idx = taskList?.findIndex((t) => t.messageId === messageId) ?? -1;
-                if (taskList && idx >= 0) {
-                    taskList.splice(idx, 1);
-                }
-                this.indexRemove(cwd, messageId);
-                // Cancellation check passed and the task has been removed: it is
-                // about to run, so record it as began for queue.immediate feedback.
-                // Bounded: ids are only consulted for the current immediate target,
-                // so pruning the oldest entries is safe.
-                if (this.beganMessageIds.size >= 10_000) {
-                    const oldest = this.beganMessageIds.values().next().value;
-                    if (oldest !== undefined)
-                        this.beganMessageIds.delete(oldest);
-                }
-                this.beganMessageIds.add(messageId);
-            }
-            // Consume any one-shot replacement closure registered by
-            // `setTaskReplacement` (queue.edit + queue.immediate). The replacement
-            // swaps in the edited content at this task's original queue slot, so
-            // tasks queued behind it still run after it. Deleted here (one-shot)
-            // so a stale closure can never run on a later task.
-            let replacement;
-            if (messageId) {
-                const workspaceReplacements = this.taskReplacements.get(cwd);
-                replacement = workspaceReplacements?.get(messageId);
-                if (replacement) {
-                    workspaceReplacements?.delete(messageId);
-                    if (workspaceReplacements && workspaceReplacements.size === 0) {
-                        this.taskReplacements.delete(cwd);
-                    }
-                }
-            }
-            // Update queue card to "executing" status BEFORE running the task.
-            // This must happen after the cancellation check: a skipped/cancelled
-            // task must keep its "❌ 已撤销" card, not be flipped to executing.
-            if (messageId) {
-                void this.updateQueueCardToExecuting(cwd, messageId, livePreview, true);
-            }
-            // Re-arm the pending/executing count for every task that is about to
-            // run. `resetExecutingCount` (external interrupt) zeroes the count,
-            // and the interrupted task's settle consumes the skip-credit — so a
-            // task enqueued BEFORE the interrupt can begin with count 0. Without
-            // this, a running task is invisible to later enqueues and they
-            // silently skip the "⏳ 消息排队中" card. This applies regardless of
-            // taskMeta: resetExecutingCount can clear the count for any cwd,
-            // and a task that resumes after an interrupt must re-arm even when it
-            // carries no metadata.
-            const currentCount = this.pendingOrExecutingCount.get(cwd) ?? 0;
-            if (currentCount < 1) {
-                this.pendingOrExecutingCount.set(cwd, 1);
-                getLogger().debug(`[queue-manager] re-armed pendingOrExecutingCount cwd=${cwd} (interrupt resume)`);
-            }
-            // Mark this task as the lane occupant for its whole execution period
-            // before running it. `resetExecutingCount` reads the slot id to grant
-            // the interrupt credit to exactly this task; the settle removes the
-            // record. `kind`/`label` let a later message's queue card name what it
-            // is waiting for instead of reporting "前面还有 0 条".
-            this.executingInfo.set(cwd, {
-                slotId,
-                messageId,
-                kind: taskMeta?.kind ?? 'message',
-                label: laneOccupantLabel(taskMeta?.kind ?? 'message', livePreview),
-                preview: livePreview,
-                startedAt: Date.now(),
-            });
-            return replacement ? replacement() : task();
-        })
+            .then(() => this.beginQueuedTask(cwd, slotId, messageId, task, taskMeta))
             .then(() => {
             getLogger().debug(`[queue-manager] task end cwd=${cwd}`);
             // beganMessageIds entry intentionally retained: sticky by design
@@ -343,6 +191,177 @@ export class QueueManager {
         });
         this.queues.set(cwd, newQueue);
     }
+    /**
+     * 登记排队元数据（展示卡数据源 + 计数 + 排队卡）。
+     *
+     * @returns false = 队列已满被拒收（不入队、不占执行槽位），调用方必须
+     *   直接把任务链跳过。背压红线：满队时拒收而不是继续 append，否则 promise
+     *   链与闭包在消息洪峰下无界增长，还会多打一张排队卡。
+     */
+    registerQueuedTask(cwd, taskMeta) {
+        // Check if there are tasks waiting BEFORE adding this one
+        const currentExecutingCount = this.pendingOrExecutingCount.get(cwd) ?? 0;
+        const currentQueueLength = this.queuedTasks.get(cwd)?.length ?? 0;
+        const hasWaitingTasks = currentExecutingCount > 0 || currentQueueLength > 0;
+        if (currentQueueLength >= MAX_WAITING_QUEUE) {
+            getLogger().warn(`[queue-manager] queue full cwd=${cwd} depth=${currentQueueLength} rejecting task messageId=${taskMeta.messageId}`);
+            void this.sendQueueFullRejection(taskMeta);
+            return false;
+        }
+        const queuedTask = {
+            userId: taskMeta.userId,
+            chatId: taskMeta.chatId,
+            messageId: taskMeta.messageId,
+            feishuReplyTo: taskMeta.feishuReplyTo,
+            cwd,
+            timestamp: Date.now(),
+            messagePreview: taskMeta.messagePreview,
+            editable: taskMeta.editable,
+            binding: taskMeta.binding,
+        };
+        // Add to cwd queue list
+        let taskList = this.queuedTasks.get(cwd);
+        if (!taskList) {
+            taskList = [];
+            this.queuedTasks.set(cwd, taskList);
+        }
+        // 身份不变量 tripwire：同一 cwd 内 queue key 必须唯一（一次入队动作一个
+        // key，铸造点 router.mintQueueTaskKey）。撞 key 时数组（追加）与 taskIndex
+        // （覆盖）必然漂移，位置显示/撤销/立即执行/卡片更新会串到别的条目上——
+        // 2026-10-08 线上缺陷就是这么长出来的。这里不改行为，只留证据。
+        if (this.indexGet(cwd, queuedTask.messageId)) {
+            getLogger().warn(`[queue-manager] duplicate queue key cwd=${cwd} messageId=${queuedTask.messageId} — ` +
+                'queue identity must be minted per enqueue action (see router.mintQueueTaskKey)');
+        }
+        taskList.push(queuedTask);
+        this.indexAdd(cwd, queuedTask);
+        // Increment executing count SYNCHRONOUSLY so subsequent enqueues see it
+        this.pendingOrExecutingCount.set(cwd, currentExecutingCount + 1);
+        // Only send the queue card if the task actually has to wait.
+        if (hasWaitingTasks) {
+            void this.sendQueueStatusCard(cwd, taskMeta.chatId, taskMeta.messageId, taskMeta.messagePreview, 
+            // Reply to the real Feishu message id when the queue key is an
+            // internal key (order.exec); otherwise messageId IS the Feishu id.
+            taskMeta.feishuReplyTo);
+        }
+        getLogger().debug(`[queue-manager] enqueue task queued cwd=${cwd} queueCard=${hasWaitingTasks} executing=${currentExecutingCount + 1} queueLen=${currentQueueLength + 1}`);
+        return true;
+    }
+    /** 满队拒收卡（best-effort 送达，失败只记日志：任务已经被拒，不能再吞一次反馈）。 */
+    async sendQueueFullRejection(taskMeta) {
+        await this.sendCard(taskMeta.chatId, cardWithHeader({
+            template: 'red',
+            title: '🚫 队列已满',
+            elements: [
+                {
+                    tag: 'div',
+                    text: {
+                        tag: 'lark_md',
+                        content: `当前工作目录已有 ${MAX_WAITING_QUEUE} 条消息排队等待，为防止积压已拒收本条消息。请等待队列消化后重发，或用 \`/stop\` 清空当前任务。`,
+                    },
+                },
+            ],
+        }), { replyTo: taskMeta.feishuReplyTo ?? taskMeta.messageId }).catch((err) => {
+            getLogger().error('[queue-manager] failed to send queue-full rejection card:', err);
+        });
+    }
+    /**
+     * 轮到本任务执行：撤销检查 → 消费一次性替换闭包 → 排队卡转「执行中」→
+     * 重新武装计数与 lane 占用登记 → 跑任务闭包。
+     *
+     * @returns 任务闭包的 promise；被撤销时返回 undefined（本槽位什么都不跑）。
+     */
+    beginQueuedTask(cwd, slotId, messageId, task, taskMeta) {
+        getLogger().debug(`[queue-manager] task begin cwd=${cwd} messageId=${messageId}`);
+        // Live preview for the executing card: read from the QueuedTask at
+        // begin time, not the enqueue-closure `taskMeta` (which is frozen).
+        // `updateQueuedTaskMessage` (queue.edit/queue.input) mutates the live
+        // task, so a task edited while queued must show the edited content
+        // when it naturally starts.
+        let livePreview = taskMeta?.messagePreview ?? '';
+        // Check if this task was cancelled before executing
+        if (messageId) {
+            // O(1) index lookup replaces the old `find` + `findIndex`
+            // double O(N) scan. The ordered array still drives removal (splice
+            // preserves queue order for position display); the index stays in
+            // sync via indexRemove.
+            const queued = this.indexGet(cwd, messageId);
+            if (!queued) {
+                getLogger().debug(`[queue-manager] task skipped (cancelled) cwd=${cwd} messageId=${messageId}`);
+                return undefined;
+            }
+            livePreview = queued.messagePreview;
+            // Remove this task's metadata by messageId
+            const taskList = this.queuedTasks.get(cwd);
+            const idx = taskList?.findIndex((t) => t.messageId === messageId) ?? -1;
+            if (taskList && idx >= 0) {
+                taskList.splice(idx, 1);
+            }
+            this.indexRemove(cwd, messageId);
+            // Cancellation check passed and the task has been removed: it is
+            // about to run, so record it as began for queue.immediate feedback.
+            // Bounded: ids are only consulted for the current immediate target,
+            // so pruning the oldest entries is safe.
+            if (this.beganMessageIds.size >= 10_000) {
+                const oldest = this.beganMessageIds.values().next().value;
+                if (oldest !== undefined)
+                    this.beganMessageIds.delete(oldest);
+            }
+            this.beganMessageIds.add(messageId);
+        }
+        // Consume any one-shot replacement closure registered by
+        // `setTaskReplacement` (queue.edit + queue.immediate). The replacement
+        // swaps in the edited content at this task's original queue slot, so
+        // tasks queued behind it still run after it. Deleted here (one-shot)
+        // so a stale closure can never run on a later task.
+        const replacement = messageId ? this.takeTaskReplacement(cwd, messageId) : undefined;
+        // Update queue card to "executing" status BEFORE running the task.
+        // This must happen after the cancellation check: a skipped/cancelled
+        // task must keep its "❌ 已撤销" card, not be flipped to executing.
+        if (messageId) {
+            void this.updateQueueCardToExecuting(cwd, messageId, livePreview, true);
+        }
+        // Re-arm the pending/executing count for every task that is about to
+        // run. `resetExecutingCount` (external interrupt) zeroes the count,
+        // and the interrupted task's settle consumes the skip-credit — so a
+        // task enqueued BEFORE the interrupt can begin with count 0. Without
+        // this, a running task is invisible to later enqueues and they
+        // silently skip the "⏳ 消息排队中" card. This applies regardless of
+        // taskMeta: resetExecutingCount can clear the count for any cwd,
+        // and a task that resumes after an interrupt must re-arm even when it
+        // carries no metadata.
+        const currentCount = this.pendingOrExecutingCount.get(cwd) ?? 0;
+        if (currentCount < 1) {
+            this.pendingOrExecutingCount.set(cwd, 1);
+            getLogger().debug(`[queue-manager] re-armed pendingOrExecutingCount cwd=${cwd} (interrupt resume)`);
+        }
+        // Mark this task as the lane occupant for its whole execution period
+        // before running it. `resetExecutingCount` reads the slot id to grant
+        // the interrupt credit to exactly this task; the settle removes the
+        // record. `kind`/`label` let a later message's queue card name what it
+        // is waiting for instead of reporting "前面还有 0 条".
+        this.executingInfo.set(cwd, {
+            slotId,
+            messageId,
+            kind: taskMeta?.kind ?? 'message',
+            label: laneOccupantLabel(taskMeta?.kind ?? 'message', livePreview),
+            preview: livePreview,
+            startedAt: Date.now(),
+        });
+        return replacement ? replacement() : task();
+    }
+    /** 取走并清除该任务的一次性替换闭包（消费即销毁）。 */
+    takeTaskReplacement(cwd, messageId) {
+        const workspaceReplacements = this.taskReplacements.get(cwd);
+        const replacement = workspaceReplacements?.get(messageId);
+        if (replacement) {
+            workspaceReplacements?.delete(messageId);
+            if (workspaceReplacements && workspaceReplacements.size === 0) {
+                this.taskReplacements.delete(cwd);
+            }
+        }
+        return replacement;
+    }
     /**
      * Execute a task immediately without going through the queue.
      * Used for / commands that should respond immediately.

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

@@ -0,0 +1,16 @@
+import { type AppConfig } from '../config/index.js';
+import type { AgentKind } from '../agent-kinds.js';
+import type { Runner } from '../runner/index.js';
+import type { RunCardSession } from '../card/run-card-session.js';
+import { ApprovalCoordinator } from './approval-coordinator.js';
+export declare function remindPendingApproval(connector: {
+    removeReactionByEmoji(messageId: string, emoji: string): Promise<void>;
+    addReaction(messageId: string, emoji: string): Promise<void>;
+}, messageId: string, runId: string): void;
+export declare function createRunApprovalCoordinator(opts: {
+    runner: Runner;
+    cardSession: RunCardSession;
+    config: AppConfig;
+    runId: string;
+    agentKind: AgentKind;
+}): ApprovalCoordinator;

package/dist/bridge/run-approval.js

@@ -0,0 +1,41 @@
+import { DEFAULT_APPROVAL_TIMEOUT_MS } from '../config/index.js';
+import { ApprovalCoordinator } from './approval-coordinator.js';
+import { getLogger } from '../logger/index.js';
+import { errorMessage } from './final-usage.js';
+export function remindPendingApproval(connector, messageId, runId) {
+    void (async () => {
+        try {
+            await connector.removeReactionByEmoji(messageId, 'Typing');
+        }
+        catch (err) {
+            getLogger().warn(`[lark-remote] remove Typing reaction failed runId=${runId}: ${errorMessage(err)}`);
+        }
+        try {
+            await connector.addReaction(messageId, 'Typing');
+        }
+        catch (err) {
+            getLogger().warn(`[lark-remote] re-add Typing reaction failed runId=${runId}: ${errorMessage(err)}`);
+        }
+    })();
+}
+export function createRunApprovalCoordinator(opts) {
+    return new ApprovalCoordinator({
+        approvalTimeoutMs: opts.agentKind === 'claude'
+            ? (opts.config.claude?.approvalTimeoutMs ?? DEFAULT_APPROVAL_TIMEOUT_MS)
+            : DEFAULT_APPROVAL_TIMEOUT_MS,
+        responder: async (requestId, response) => {
+            const runner = opts.runner;
+            if (typeof runner.respondApproval === 'function') {
+                await runner.respondApproval(requestId, response);
+            }
+        },
+        interruptTurn: async () => {
+            await opts.runner.stop();
+        },
+        pushToCard: async (events) => {
+            for (const event of events)
+                await opts.cardSession.push(event);
+        },
+    });
+}
+//# sourceMappingURL=run-approval.js.map

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

@@ -0,0 +1,32 @@
+import type { ResultEvent } from '../runner/types.js';
+import type { FinalUsageSnapshot } from './final-usage.js';
+import type { UsageSnapshot } from '../session-contract.js';
+export type UsageAuthority = 'live' | 'jsonl';
+/**
+ * 一张 run 的用量记账：live 侧（result 事件 / compact_boundary）先收着，
+ * run 结束时与 jsonl 快照按权威来源合成一份 `UsageSnapshot`。
+ *
+ * live 侧字段清单只有 `UsageSnapshot` 一份：此前这里是 19 个 `final*` 平铺
+ * 字段逐字段搬运，加一个 usage 字段要改三处（§9.21 的一致性靠人记）。
+ */
+export declare class RunUsageCollector {
+    /** live 侧观察值（jsonl 读不到时的兜底）。 */
+    private contextLength?;
+    private liveInput?;
+    private liveOutput?;
+    private liveContextLimit?;
+    private liveCacheRead?;
+    private liveCacheCreation?;
+    private liveTotal?;
+    private liveReasoningTokens?;
+    /** finalize() 之后的最终口径；meta() 的唯一数据源。 */
+    private resolved;
+    resultNotSuccess: boolean;
+    get liveInputTokens(): number | undefined;
+    get liveOutputTokens(): number | undefined;
+    observeCompaction(postTokens: number): void;
+    observeResult(event: ResultEvent): void;
+    finalize(finalUsage: FinalUsageSnapshot | undefined, authority: UsageAuthority | undefined): void;
+    meta(): UsageSnapshot;
+    logSummary(runId: string): string;
+}

package/dist/bridge/run-usage.js

@@ -0,0 +1,87 @@
+import { normalizeResultUsage } from '../runner/common/result-usage.js';
+/**
+ * 一张 run 的用量记账：live 侧（result 事件 / compact_boundary）先收着，
+ * run 结束时与 jsonl 快照按权威来源合成一份 `UsageSnapshot`。
+ *
+ * live 侧字段清单只有 `UsageSnapshot` 一份：此前这里是 19 个 `final*` 平铺
+ * 字段逐字段搬运，加一个 usage 字段要改三处（§9.21 的一致性靠人记）。
+ */
+export class RunUsageCollector {
+    /** live 侧观察值（jsonl 读不到时的兜底）。 */
+    contextLength;
+    liveInput;
+    liveOutput;
+    liveContextLimit;
+    liveCacheRead;
+    liveCacheCreation;
+    liveTotal;
+    liveReasoningTokens;
+    /** finalize() 之后的最终口径；meta() 的唯一数据源。 */
+    resolved = {};
+    resultNotSuccess = false;
+    get liveInputTokens() {
+        return this.liveInput;
+    }
+    get liveOutputTokens() {
+        return this.liveOutput;
+    }
+    observeCompaction(postTokens) {
+        this.contextLength = postTokens;
+    }
+    observeResult(event) {
+        this.resultNotSuccess = event.subtype !== 'success';
+        if (!event.usage)
+            return;
+        const usage = normalizeResultUsage(event.usage);
+        if (!this.contextLength)
+            this.contextLength = usage.contextLength;
+        this.liveInput = usage.inputTokens;
+        this.liveOutput = usage.outputTokens;
+        this.liveContextLimit = usage.contextLimit;
+        if (usage.cacheReadTokens !== undefined)
+            this.liveCacheRead = usage.cacheReadTokens;
+        if (usage.cacheCreationTokens !== undefined) {
+            this.liveCacheCreation = usage.cacheCreationTokens;
+        }
+        if (usage.totalTokens !== undefined)
+            this.liveTotal = usage.totalTokens;
+        if (usage.reasoningTokens !== undefined)
+            this.liveReasoningTokens = usage.reasoningTokens;
+    }
+    finalize(finalUsage, authority) {
+        const resolved = {
+            // 从 jsonl 快照整体展开，新增 UsageSnapshot 字段无需再改这里。
+            ...finalUsage,
+            contextLength: finalUsage?.contextLength ?? this.contextLength,
+            contextLimit: finalUsage?.contextLimit ?? this.liveContextLimit,
+            compactCount: finalUsage?.compactCount,
+            // result 事件里的 cache/total 两条路径都要带：jsonl 读得到时被覆盖，
+            // 读不到（或走 live flow scope）时它就是最终数字。
+            cacheReadTokens: this.liveCacheRead,
+            cacheCreationTokens: this.liveCacheCreation,
+            totalTokens: this.liveTotal,
+            reasoningTokens: this.liveReasoningTokens,
+        };
+        const useLiveFlowScope = authority !== 'jsonl' && this.liveInput !== undefined && this.liveOutput !== undefined;
+        if (useLiveFlowScope) {
+            resolved.inputTokens = this.liveInput;
+            resolved.outputTokens = this.liveOutput;
+            this.resolved = resolved;
+            return;
+        }
+        resolved.inputTokens = finalUsage?.inputTokens ?? this.liveInput;
+        resolved.outputTokens = finalUsage?.outputTokens ?? this.liveOutput;
+        resolved.cacheReadTokens = finalUsage?.cacheReadTokens ?? this.liveCacheRead;
+        resolved.cacheCreationTokens = finalUsage?.cacheCreationTokens ?? this.liveCacheCreation;
+        resolved.totalTokens = finalUsage?.totalTokens ?? this.liveTotal;
+        this.resolved = resolved;
+    }
+    meta() {
+        return this.resolved;
+    }
+    logSummary(runId) {
+        const meta = this.meta();
+        return `[lark-remote] final usage runId=${runId} contextLength=${meta.contextLength} contextLimit=${meta.contextLimit ?? 'undefined'} compactCount=${meta.compactCount ?? 'undefined'} cacheRead=${meta.cacheReadTokens ?? 'undefined'} cacheCreate=${meta.cacheCreationTokens ?? 'undefined'}`;
+    }
+}
+//# sourceMappingURL=run-usage.js.map

package/dist/bridge/session-writeback.d.ts

@@ -0,0 +1,19 @@
+import type { AgentKind } from '../agent-kinds.js';
+import type { TurnStartedEvent } from '../runner/index.js';
+import type { SessionStore } from '../session/index.js';
+interface InitEvent {
+    session_id: string;
+    cwd?: string;
+}
+export interface WritebackContext {
+    sessionStore: SessionStore;
+    userId: string;
+    agentKind: AgentKind;
+    cwd: string;
+    sessionEpochAtStart: number;
+    runId: string;
+}
+export declare function writeBackInitSession(ctx: WritebackContext, event: InitEvent): void;
+export declare function writeBackTurnStarted(ctx: WritebackContext, event: TurnStartedEvent): boolean;
+export declare function writeBackResultSession(ctx: WritebackContext, sessionId: string | undefined): void;
+export {};

package/dist/bridge/session-writeback.js

@@ -0,0 +1,36 @@
+import { getLogger } from '../logger/index.js';
+function pointerMoved(ctx) {
+    return ctx.sessionStore.getSessionEpoch(ctx.userId, ctx.agentKind) !== ctx.sessionEpochAtStart;
+}
+export function writeBackInitSession(ctx, event) {
+    if (pointerMoved(ctx)) {
+        getLogger().info(`[lark-remote] system.init write-back skipped: session pointer moved since run start runId=${ctx.runId} sessionId=${event.session_id}`);
+        return;
+    }
+    const eventCwd = typeof event.cwd === 'string' ? event.cwd : '';
+    const hasCwd = !!ctx.sessionStore.getCwd(ctx.userId);
+    const realCwd = eventCwd.length > 0 ? eventCwd : ctx.cwd;
+    if (hasCwd && eventCwd && eventCwd !== ctx.cwd) {
+        getLogger().info(`[lark-remote] system.init: cwd=${ctx.cwd}, session cwd=${eventCwd}`);
+        ctx.sessionStore.setSessionIdAndSessionCwd(ctx.userId, ctx.agentKind, event.session_id, realCwd);
+        return;
+    }
+    const bootstrapSessionCwd = !hasCwd && eventCwd.length > 0 ? eventCwd : undefined;
+    ctx.sessionStore.setSessionIdAndCwd(ctx.userId, ctx.agentKind, event.session_id, realCwd, bootstrapSessionCwd);
+}
+export function writeBackTurnStarted(ctx, event) {
+    if (pointerMoved(ctx)) {
+        getLogger().info(`[lark-remote] turn_started write-back skipped: session pointer moved since run start runId=${ctx.runId} sessionId=${event.threadId}`);
+        return false;
+    }
+    ctx.sessionStore.setSessionIdAndCwd(ctx.userId, ctx.agentKind, event.threadId, ctx.cwd);
+    getLogger().info(`[lark-remote] turn_started session write-back runId=${ctx.runId} sessionId=${event.threadId}`);
+    return true;
+}
+export function writeBackResultSession(ctx, sessionId) {
+    if (!sessionId || pointerMoved(ctx))
+        return;
+    ctx.sessionStore.setSessionIdAndCwd(ctx.userId, ctx.agentKind, sessionId, ctx.cwd);
+    getLogger().info(`[lark-remote] result session write-back runId=${ctx.runId} sessionId=${sessionId}`);
+}
+//# sourceMappingURL=session-writeback.js.map