lark-remote 0.5.2 → 0.5.4

package/CHANGELOG.md

@@ -5,6 +5,26 @@ 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.4] - 2026-10-12
+
+### 修复
+
+- **codex「本 run」token 少算（多步运行只统计了最后一步）**：codex 每发起一次模型调用就记一条 token 用量，一个回合里有几趟工具往返就有几条，而运行结束卡片与 `/resume` 末尾统计此前只取最后一条。于是一个跑了 7 趟工具往返的回合，实际输出 3,648 个 token 只显示 679、未命中缓存的输入 3,022 只显示 212。现在按回合汇总该回合内所有调用的用量，与 codex 自己按回合统计的结果逐字段一致；「Context」仍显示最后一次调用的上下文窗口占用，累计用量与 `Total` 的取法不变。恢复会话时服务端可能重放上回合的用量，已按回合标识丢弃。更早的、不带回合标识的记录保持原读法
+
+### 变更
+
+- **测试注释与用例类型对齐**：一处用例注释改为不点名具体消息；两处 app-server 用例的类型写法与协议定义对齐（这些文件不在既有类型检查覆盖范围内，改动不影响运行时行为）。无行为变化
+
+## [0.5.3] - 2026-10-12
+
+### 修复
+
+- **中断后紧接着发下一条消息，不再报 `thread already has an active writer`**：点停止打断正在运行的 codex 时，中断流程会把复用的运行实例从缓存摘掉并立即销毁连接，而队列链在这一步的等待窗口里就把下一条消息发了出去、并已取到同一个实例——那条运行的长驻连接于是挂在无人托管的实例上，`codex app-server` 进程要等空闲超时（默认 30 分钟）才回收，期间一直持有该会话的写锁，同一会话的下一次恢复因此被拒。现在中断只把实例标为「待替换」，统一由下一次运行收尾时回收，标过的实例不再返回缓存；被摘掉的实例也会在运行结束时主动关闭连接，不再挂 30 分钟的超时。逐条消息新建实例的 agent 不受影响，行为照旧
+
+### 变更
+
+- **注释里的运维现场数据与仓库外引用清理**：一处测试注释记录的崩溃进程号、实例名与精确到秒的重启时间改为占位描述；若干注释不再指向仓库之外的维护规范文件名。无行为变化
+
 ## [0.5.2] - 2026-10-11
 
 ### 修复

package/dist/bridge/index.js

@@ -320,6 +320,17 @@ export class Bridge {
         if (evicted && typeof evicted.unregisterExitHandlers === 'function') {
             evicted.unregisterExitHandlers();
         }
+        // 2026-10-11：先标记 orphan 再 dispose。evict 与「run 刚拿走本实例」竞态时
+        // （queue 链在 interruptCurrentRun await 期间推进），dispose 只能关掉当时
+        // 已存在的连接，run 后续 acquire 的新连接会挂在无人托管的实例上——orphan
+        // 标记让 executeTurn 在 run 结束时主动 dispose 这批连接，而不是挂 idle
+        // timer 等待 30 分钟（期间持有 agent 侧会话写锁，codex 报
+        // "thread already has an active writer"）。鸭子探测与 dispose/unregister
+        // 一致：claude（stream-json，无长驻连接）无此方法，跳过。
+        if (evicted &&
+            typeof evicted.markOrphaned === 'function') {
+            evicted.markOrphaned();
+        }
         // 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') {
@@ -574,7 +585,22 @@ export class Bridge {
                 // (eviction must also unregister the runner from the exit dispatcher)
                 // evict by the run's captured agentKind, not the live
                 // defaultAgent (may have changed mid-run via /config).
-                this.evictRunnerSlot(cwd, active.agentKind);
+                //
+                // 2026-10-11：workspace-lifetime runner 不能在这里立即 evict+dispose。
+                // interruptCurrentRun 的 await 窗口内 queue 链会推进下一条消息，其
+                // getRunner 可能刚拿走本实例（缓存命中先于本行执行）——立即 evict 会
+                // 让那个 run 的长驻连接脱管：进程残留至 idle TTL 才回收，期间持有
+                // agent 侧会话写锁（codex "thread already has an active writer"，
+                // 线上实测）。改为标 stale，由 finalizeRun 在下一次 run 结束时统一
+                // evict+dispose；「stop 后下一 run 换新实例」的语义
+                // 保留（stale 命中即最后一轮复用）。run-per-message runner 无长驻
+                // 连接，保持立即 evict 不变。
+                if (active.runner.lifetime === 'workspace') {
+                    this.staleRunnerSlots.add(`${cwd}\u0000${active.agentKind}`);
+                }
+                else {
+                    this.evictRunnerSlot(cwd, active.agentKind);
+                }
                 // Reset queue executing count: the task was interrupted externally, so
                 // its promise-chain settle (.then/.catch) may lag behind the process
                 // kill. Without this reset, subsequent messages would incorrectly show

package/dist/cli.js

@@ -2,8 +2,8 @@
 /**
  * CLI 引导层（bootstrap）：在 import 应用模块图之前决定运行时（bun/node）并拉起它。
  *
- * **这是全仓唯一被认可的 spawn 收口例外**（即 AGENTS.md「子进程 spawn 只走
- * platform/spawn.ts」红线的显式豁免）。三个理由缺一不可：
+ * **这是全仓唯一被认可的 spawn 收口例外**（红线：子进程 spawn 只走
+ * platform/spawn.ts，此处显式豁免）。三个理由缺一不可：
  *   1. 时序：preflight（Node 版本守卫、-v/-h/--advanced-help）必须在 import 应用
  *      模块图之前跑完——dist/cli.js 刻意不使用 ES2020+ 语法以便在 node 12 上仍
  *      可被解析，而 dist/index.js 是 ES2022；先 import platform/spawn 就等于先把

package/dist/inbound/receipt.d.ts

@@ -6,7 +6,7 @@
  * 2. 拿不到的东西（不支持类型 / 超限 / 下载失败 / 媒体保存已关闭）：明确告知，
  *    而不是把占位符塞给 agent。
  *
- * 用户可见文案指代本程序时只能写 `lark-remote`（AGENTS.md 命名纪律）。
+ * 命名纪律：用户可见文案指代本程序时只能写 `lark-remote`。
  */
 import type { PlaceholderKind } from './placeholder.js';
 import type { RejectedItem } from './turn.js';

package/dist/inbound/receipt.js

@@ -6,7 +6,7 @@
  * 2. 拿不到的东西（不支持类型 / 超限 / 下载失败 / 媒体保存已关闭）：明确告知，
  *    而不是把占位符塞给 agent。
  *
- * 用户可见文案指代本程序时只能写 `lark-remote`（AGENTS.md 命名纪律）。
+ * 命名纪律：用户可见文案指代本程序时只能写 `lark-remote`。
  */
 import path from 'node:path';
 /** 单条回执最多列出的文件数；超出折叠为 "… 等 N 个文件"（沿用旧提示口径）。 */

package/dist/platform/terminator-posix.js

@@ -9,7 +9,7 @@ function defaultLog(level, message) {
     else
         logger.info(message);
 }
-/** 退出判定统一口径（CLAUDE.md 红线）：exitCode !== null || signalCode !== null。 */
+/** 退出判定统一口径（红线）：exitCode !== null || signalCode !== null。 */
 function isAlive(proc) {
     return proc.exitCode === null && proc.signalCode === null;
 }

package/dist/platform/terminator-win32.js

@@ -12,7 +12,7 @@
  */
 import { spawn as nodeSpawn } from 'node:child_process';
 import { agentStopperRegistry } from './agent-stopper.js';
-/** 退出判定统一口径（CLAUDE.md 红线）：exitCode !== null || signalCode !== null。 */
+/** 退出判定统一口径（红线）：exitCode !== null || signalCode !== null。 */
 function isAlive(proc) {
     return proc.exitCode === null && proc.signalCode === null;
 }

package/dist/runner/codex/app-server/translator.js

@@ -222,6 +222,11 @@ export class CodexAppServerTranslator {
         this.threadId = params.threadId;
         this.turnId = params.turn.id;
         this.turnStatus = params.turn.status ?? 'inProgress';
+        // 单 turn 用量从零开始累计：turn 内每次采样都会发一条
+        // `thread/tokenUsage/updated`，本 run 的用量是这些增量之和（不是最后一条）。
+        // resume 后服务端重放的上一 turn 用量若在此之后到达，由 handleTokenUsageUpdated
+        // 的 turnId 闸门挡掉。
+        this.usage = { inputTokens: 0, outputTokens: 0 };
         this.textByItem.clear();
         this.reasoningByItem.clear();
         this.toolOutputByItem.clear();
@@ -455,22 +460,31 @@ export class CodexAppServerTranslator {
         ];
     }
     handleTokenUsageUpdated(params) {
+        // 归属闸门：resume 之后服务端可能重放上一 turn 的 tokenUsage（turnId 不同），
+        // 计入会把上一 turn 的消耗算成本 run。本轮 turnId 由 turn/started 确立。
+        if (params.turnId && this.turnId && params.turnId !== this.turnId) {
+            return [];
+        }
         const last = params.tokenUsage.last;
         // 协议原生 inputTokens 含 cached（total = input + output），而 lark-remote 的
         // 卡片契约是 ccusage 口径「input_tokens 表示未命中缓存的输入」（design §9.21）。
         // 在入口归一，否则 done 卡 Input 会等于 Context、cache% 分母重复计数、
         // Total 被 max(total, input+output+cache) 抬高一倍（实测 364K → 727K）。
         // jsonl 链路有同一处减法（session/codex/rollout-reader.ts buildUsageFromScan）。
+        // 单 turn 口径：一个 turn 内每次采样各发一条通知（实测 7 次工具往返 = 7 条），
+        // 本 run 是这些增量之和——只取最后一条会把多步 run 低报（实测 3,648 output 显示成 679）。
         const cachedInputTokens = last.cachedInputTokens === undefined
             ? undefined
             : Math.min(last.cachedInputTokens, last.inputTokens);
-        this.usage = {
-            inputTokens: last.inputTokens - (cachedInputTokens ?? 0),
-            outputTokens: last.outputTokens,
-            cachedInputTokens,
-            totalTokens: last.totalTokens,
-            contextLimit: params.tokenUsage.modelContextWindow,
-        };
+        this.usage.inputTokens += last.inputTokens - (cachedInputTokens ?? 0);
+        this.usage.outputTokens += last.outputTokens;
+        if (cachedInputTokens !== undefined) {
+            this.usage.cachedInputTokens = (this.usage.cachedInputTokens ?? 0) + cachedInputTokens;
+        }
+        if (last.totalTokens !== undefined) {
+            this.usage.totalTokens = (this.usage.totalTokens ?? 0) + last.totalTokens;
+        }
+        this.usage.contextLimit = params.tokenUsage.modelContextWindow ?? this.usage.contextLimit;
         return [];
     }
     /**

package/dist/runner/common/connection-based-runner.d.ts

@@ -31,6 +31,10 @@ export declare abstract class ConnectionBasedRunner<TClient, TEvent = AgentEvent
     protected forceFinish: boolean;
     /** stop() 在 turn/start 或 prompt 响应前到达时置位，完成后再补发 cancel/interrupt。 */
     protected stopRequested: boolean;
+    /** 缓存层除名标记（evictRunnerSlot → markOrphaned）。置位后 run 结束时主动
+     *  dispose 全部连接而不是挂 idle timer：被除名实例上创建的连接无人托管，
+     *  不主动收会残留进程至 idle TTL（30 分钟），期间持有 agent 侧会话写锁。 */
+    private orphaned;
     protected constructor(opts: {
         kind: AgentKind;
         sessionReader: AgentSessionReader;
@@ -96,6 +100,16 @@ export declare abstract class ConnectionBasedRunner<TClient, TEvent = AgentEvent
      * Dispose the runner: release the connection.
      */
     dispose(): Promise<void>;
+    /**
+     * Mark this runner as evicted from the bridge's runner cache while a run may
+     * still be holding/creating connections on it (queue-advance race during
+     * interruptCurrentRun's await window, 2026-10-11). The active run's finally
+     * disposes connections eagerly instead of arming the idle TTL timer —
+     * otherwise the agent server process lingers for up to 30 minutes holding
+     * its session write lock (codex: "thread already has an active writer").
+     * One-way by design: an evicted instance never returns to the cache.
+     */
+    markOrphaned(): void;
     getUsageAuthority(): 'live';
     killOrphan(): void;
     registerExitHandlers(): void;

package/dist/runner/common/connection-based-runner.js

@@ -22,6 +22,10 @@ export class ConnectionBasedRunner {
     forceFinish = false;
     /** stop() 在 turn/start 或 prompt 响应前到达时置位，完成后再补发 cancel/interrupt。 */
     stopRequested = false;
+    /** 缓存层除名标记（evictRunnerSlot → markOrphaned）。置位后 run 结束时主动
+     *  dispose 全部连接而不是挂 idle timer：被除名实例上创建的连接无人托管，
+     *  不主动收会残留进程至 idle TTL（30 分钟），期间持有 agent 侧会话写锁。 */
+    orphaned = false;
     constructor(opts, defaultTurnIdleTimeoutMs = TURN_IDLE_TIMEOUT_MS) {
         this.kind = opts.kind;
         this.sessionReader = opts.sessionReader;
@@ -130,7 +134,19 @@ export class ConnectionBasedRunner {
             this.currentTurnId = null;
             this.stopRequested = false;
             this.clearTurnState();
-            this.notifyIdle(opts.cwd);
+            if (this.orphaned) {
+                // 已被缓存层除名（evictRunnerSlot → markOrphaned）：本次 run 创建的
+                // 连接挂在无人托管的实例上。主动收掉而不是挂 idle timer——否则 agent
+                // server 进程残留至 idle TTL，期间持有 agent 侧会话写锁（codex
+                // "thread already has an active writer"，2026-10-11 线上实测）。
+                // dispose() 内部自带 try/catch，这里 fire-and-forget 不阻塞事件流收尾。
+                void this.disposeConnections().catch((err) => {
+                    getLogger().warn(`[${this.logTag}] orphan dispose error: ${err.message}`);
+                });
+            }
+            else {
+                this.notifyIdle(opts.cwd);
+            }
         }
     }
     /**
@@ -178,6 +194,18 @@ export class ConnectionBasedRunner {
             getLogger().warn(`[${this.logTag}] dispose error: ${err.message}`);
         }
     }
+    /**
+     * Mark this runner as evicted from the bridge's runner cache while a run may
+     * still be holding/creating connections on it (queue-advance race during
+     * interruptCurrentRun's await window, 2026-10-11). The active run's finally
+     * disposes connections eagerly instead of arming the idle TTL timer —
+     * otherwise the agent server process lingers for up to 30 minutes holding
+     * its session write lock (codex: "thread already has an active writer").
+     * One-way by design: an evicted instance never returns to the cache.
+     */
+    markOrphaned() {
+        this.orphaned = true;
+    }
     getUsageAuthority() {
         return 'live';
     }

package/dist/session/codex/rollout-reader.js

@@ -42,6 +42,9 @@ function subtractRawUsage(a, b) {
         total_tokens: a.total_tokens - b.total_tokens,
     };
 }
+function emptyTurnUsage() {
+    return { input: 0, cached: 0, output: 0, total: 0 };
+}
 /**
  * `compacted` 事件自带的摘要调用 usage（`latest_token_usage_record.usage`）。
  * 用于把「压缩前窗口」与「摘要调用自身的消耗」区分开——两者都写在 compacted 前。
@@ -141,12 +144,19 @@ function scanCodexRollout(filePath, includeEvents) {
     // exactly the 0.153 compatibility incident shape.
     let userResponseItemCount = 0;
     // token_count tracking: codex emits cumulative `total_token_usage` and an
-    // incremental `last_token_usage`. We want the LAST turn's usage (matches
-    // pi/opencode /resume "last turn" display semantics). When
+    // incremental `last_token_usage` **per sampling call** — one turn with tool
+    // round-trips logs several `token_count` lines. We want the LAST turn's usage
+    // = the sum of that turn's samplings (matches pi/opencode /resume "last turn"
+    // display semantics). Turn boundaries come from `task_started`. When
     // last_token_usage is absent we derive it as total - previous_total.
     let lastRawUsage;
     /** 上一条被接受的 raw usage；compacted 分支回退一条时用（见下方注释）。 */
     let previousRawUsage;
+    /**
+     * 末个 turn 的累计用量；`null` = 文件里没有 `task_started`（旧数据），
+     * 此时 flow 字段退回「末条 token_count」语义（见 buildUsageFromScan）。
+     */
+    let turnUsage = null;
     // Context window limit from the same token_count event as lastRawUsage
     // (codex reports info.model_context_window per turn; absent on old data).
     let lastContextLimit;
@@ -194,6 +204,12 @@ function scanCodexRollout(filePath, includeEvents) {
                     }
                     lastUserMessageSource = human.source;
                 }
+                else if (payload.type === 'task_started') {
+                    // turn 边界：一个 turn 一条 task_started（与 task_complete 成对，
+                    // turn_id 见 session_meta 之后的 `turn_context`）。从这里开始重新
+                    // 累计本 turn 的用量。
+                    turnUsage = emptyTurnUsage();
+                }
                 else if (payload.type === 'token_count') {
                     const info = payload.info;
                     const last = info?.last_token_usage;
@@ -217,6 +233,13 @@ function scanCodexRollout(filePath, includeEvents) {
                         lastRawUsage = raw;
                         const ctxWindow = info?.model_context_window;
                         lastContextLimit = typeof ctxWindow === 'number' ? ctxWindow : undefined;
+                        if (turnUsage) {
+                            const cached = Math.min(raw.cached_input_tokens, raw.input_tokens);
+                            turnUsage.input += raw.input_tokens - cached;
+                            turnUsage.cached += cached;
+                            turnUsage.output += raw.output_tokens;
+                            turnUsage.total += raw.total_tokens;
+                        }
                     }
                     // 压缩后的水位：压缩收尾 token_count 全 0（raw 不满足上面 zero-filter），
                     // 但 total_tokens 表达真实窗口；之后若出现普通 turn（input>0），
@@ -288,6 +311,7 @@ function scanCodexRollout(filePath, includeEvents) {
         lastContextLimit,
         lastTotalUsage,
         previousTotals,
+        turnUsage,
         compactCount,
         compactPreContextLength,
         compactPostContextLength,
@@ -298,25 +322,38 @@ function scanCodexRollout(filePath, includeEvents) {
  * input = raw - cached (codex reports cached input separately), cache
  * creation is never reported by codex, reasoning is a subset of output
  * (display-only, never added to total).
+ *
+ * Flow fields (input/output/cache/total) are the **sum over the last turn's
+ * samplings** when the file marks turn boundaries (`task_started`) — one codex
+ * turn logs one `token_count` per sampling, so the last line alone understates
+ * a tool-looping run (measured: 212 / 679 displayed vs 3,022 / 3,648 consumed).
+ * Legacy files without `task_started` keep the last-`token_count` semantics.
  * contextLength = input_tokens (= (input_tokens-cached) + cached + 0),
  * i.e. input + cacheRead + cacheCreation — the unified context-window
  * occupancy contract across all five readers (excludes
  * output/reasoning).
  */
 function buildUsageFromScan(scan) {
-    const { lastRawUsage, lastContextLimit, lastTotalUsage, compactCount, compactPreContextLength, compactPostContextLength, } = scan;
+    const { lastRawUsage, lastContextLimit, lastTotalUsage, turnUsage, compactCount, compactPreContextLength, compactPostContextLength, } = scan;
     if (!lastRawUsage)
         return undefined;
     const r = lastRawUsage;
     const cached = Math.min(r.cached_input_tokens, r.input_tokens);
+    // 本 run = 末个 turn 全部采样之和；旧数据（无 task_started）退回末条。
+    const flow = turnUsage ?? {
+        input: r.input_tokens - cached,
+        cached,
+        output: r.output_tokens,
+        total: r.total_tokens,
+    };
     const usage = {
-        inputTokens: r.input_tokens - cached,
-        outputTokens: r.output_tokens,
+        inputTokens: flow.input,
+        outputTokens: flow.output,
         contextLength: r.input_tokens,
         contextLimit: lastContextLimit,
-        cacheReadTokens: cached,
+        cacheReadTokens: flow.cached,
         cacheCreationTokens: 0,
-        totalTokens: r.total_tokens,
+        totalTokens: flow.total,
     };
     // Cumulative from the final total_token_usage (non-cached input +
     // output), summed across all turns in the session.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lark-remote",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "Feishu (Lark) private-chat bridge to local coding agents — Claude Code / Codex / opencode / pi / kimi, with live-streaming CardKit 2.0 cards",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",