lark-remote 0.1.11 → 0.1.13

package/CHANGELOG.md

@@ -5,6 +5,29 @@ 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.1.13] - 2026-09-04
+
+### 修复
+
+- kimi ACP Compact 等待机制重构：等待协议终态（complete / cancel / unknown）再收尾，移除「30s 超时即视为成功」的假完成路径——Compact 实际失败或被取消时如实反馈
+
+### 变更
+
+- 代码与测试清理：死导出/死字段清理、bridge usage 统计收敛、router 样板收敛、session 公共件下沉（`ttl-cache` / `recency`）、ACP 共享层下沉
+- 测试治理：超大测试文件按主题拆分、agent choices 测试表驱动化、弱断言收敛、移除无效测试
+- 移除未使用的 `@types/form-data` 依赖
+
+## [0.1.12] - 2026-08-29
+
+### 修复
+
+- opencode ACP stream error 实时上报：tail opencode 日志即时捕获错误行，配额类错误秒级报错，不再挂起卡片等待超时
+
+### 变更
+
+- codex 会话历史读取轻量化：长会话生成轻量摘要，模型目录异步加载，减少启动阻塞
+- CI 覆盖率门禁纳入 `src/index.ts`，覆盖率统计更完整
+
 ## [0.1.11] - 2026-08-24
 
 ### 新增

package/dist/bridge/inbound-media.d.ts

@@ -23,9 +23,6 @@ export declare function sanitizeFileName(name: string): string;
  * 两者都无法识别时返回 undefined（调用方省略扩展名，避免错误标注格式）。
  */
 export declare function imageExtension(mimeType: string | undefined, head: Buffer): string | undefined;
-/** 按 UTF-8 字节数截断字符串（避免截在多字节字符中间）。 */
-import { truncateUtf8 } from '../common/truncate.js';
-export { truncateUtf8 };
 /**
  * 文件名长度限制（字节级，保留扩展名），避免 ENAMETOOLONG 整文件失败。
  * 极罕见情况（扩展名本身超限）直接截断全名。

package/dist/bridge/inbound-media.js

@@ -99,7 +99,6 @@ export function imageExtension(mimeType, head) {
 }
 /** 按 UTF-8 字节数截断字符串（避免截在多字节字符中间）。 */
 import { truncateUtf8 } from '../common/truncate.js';
-export { truncateUtf8 };
 /**
  * 文件名长度限制（字节级，保留扩展名），避免 ENAMETOOLONG 整文件失败。
  * 极罕见情况（扩展名本身超限）直接截断全名。

package/dist/bridge/index.d.ts

@@ -463,6 +463,13 @@ export declare class Bridge {
     handleCodexCompact(value: {
         runId?: string;
     }, ctx: BridgeContext): Promise<void>;
+    /**
+     * §5.3: kimi 压缩在途检测——reader 鸭子实现 `readCompactionState` 时，若
+     * wire 状态机判定当前有未终结的压缩（最后一次 begin 无 terminal 记录），
+     * 直接回文本「已有一次 Compact 正在进行」并返回 true（调用方不开卡、不发
+     * session/prompt）。codex/claude 等 reader 无此方法 → 返回 false，行为不变。
+     */
+    private rejectIfCompactionInFlight;
     /**
      * Stream a compaction to a card: start a RunCardSession with
      * operationKind='compaction' (no recursive Compact button), consume

package/dist/bridge/index.js

@@ -834,6 +834,26 @@ export class Bridge {
         let finalCumulativeOutputTokens;
         let finalCumulativeCacheReadTokens;
         let finalCumulativeCacheCreationTokens;
+        // 统一的 usage meta 构造（finalize 各分支共享，本方法内原先 5 处手写 11-15
+        // 字段对象；第 6 处 streamCodexCompact 形状不同未收敛）。
+        // catch 路径需覆盖 flow 字段时在展开后覆写即可。catch error 路径亦复用此
+        // 闭包，相比旧手写对象补齐了累计 cache 字段（cumulativeCacheReadTokens/
+        // cumulativeCacheCreationTokens），属有意的口径对齐（向 done 路径看齐）。
+        const usageMeta = () => ({
+            contextLength: finalContextLength,
+            contextLimit: finalContextLimit,
+            compactCount: finalCompactCount,
+            cacheReadTokens: finalCacheReadTokens,
+            cacheCreationTokens: finalCacheCreationTokens,
+            totalTokens: finalTotalTokens,
+            inputTokens: finalInputTokens,
+            outputTokens: finalOutputTokens,
+            cumulativeTotalTokens: finalCumulativeTotalTokens,
+            cumulativeInputTokens: finalCumulativeInputTokens,
+            cumulativeOutputTokens: finalCumulativeOutputTokens,
+            cumulativeCacheReadTokens: finalCumulativeCacheReadTokens,
+            cumulativeCacheCreationTokens: finalCumulativeCacheCreationTokens,
+        });
         try {
             try {
                 getLogger().debug(`[bridge] cardSession.start() begin runId=${runId}`);
@@ -1156,57 +1176,19 @@ export class Bridge {
                 await cardSession.finish(terminal, {
                     resultSubtype: subtype,
                     errorMsg: finalState.errorMsg,
-                    contextLength: finalContextLength,
-                    contextLimit: finalContextLimit,
-                    compactCount: finalCompactCount,
-                    cacheReadTokens: finalCacheReadTokens,
-                    cacheCreationTokens: finalCacheCreationTokens,
-                    totalTokens: finalTotalTokens,
-                    inputTokens: finalInputTokens,
-                    outputTokens: finalOutputTokens,
-                    cumulativeTotalTokens: finalCumulativeTotalTokens,
-                    cumulativeInputTokens: finalCumulativeInputTokens,
-                    cumulativeOutputTokens: finalCumulativeOutputTokens,
-                    cumulativeCacheReadTokens: finalCumulativeCacheReadTokens,
-                    cumulativeCacheCreationTokens: finalCumulativeCacheCreationTokens,
+                    ...usageMeta(),
                 });
             }
             else if (finalState.terminal === 'running') {
                 await cardSession.finish('error', {
-                    contextLength: finalContextLength,
-                    contextLimit: finalContextLimit,
-                    compactCount: finalCompactCount,
-                    cacheReadTokens: finalCacheReadTokens,
-                    cacheCreationTokens: finalCacheCreationTokens,
-                    totalTokens: finalTotalTokens,
-                    inputTokens: finalInputTokens,
-                    outputTokens: finalOutputTokens,
-                    cumulativeTotalTokens: finalCumulativeTotalTokens,
-                    cumulativeInputTokens: finalCumulativeInputTokens,
-                    cumulativeOutputTokens: finalCumulativeOutputTokens,
-                    cumulativeCacheReadTokens: finalCumulativeCacheReadTokens,
-                    cumulativeCacheCreationTokens: finalCumulativeCacheCreationTokens,
+                    ...usageMeta(),
                     errorMsg: agentDisplayName(agentKind) + ' 输出流已结束，但未收到 result 事件',
                 });
             }
             else if (sawResult) {
                 // 已终态（interrupted/idle_timeout）+ result 已收到：首终态优先，
                 // 仅补充 usage meta（finalizing 期间被 /stop 或 idle 超时也展示 token 统计）
-                await cardSession.finish(finalState.terminal, {
-                    contextLength: finalContextLength,
-                    contextLimit: finalContextLimit,
-                    compactCount: finalCompactCount,
-                    cacheReadTokens: finalCacheReadTokens,
-                    cacheCreationTokens: finalCacheCreationTokens,
-                    totalTokens: finalTotalTokens,
-                    inputTokens: finalInputTokens,
-                    outputTokens: finalOutputTokens,
-                    cumulativeTotalTokens: finalCumulativeTotalTokens,
-                    cumulativeInputTokens: finalCumulativeInputTokens,
-                    cumulativeOutputTokens: finalCumulativeOutputTokens,
-                    cumulativeCacheReadTokens: finalCumulativeCacheReadTokens,
-                    cumulativeCacheCreationTokens: finalCumulativeCacheCreationTokens,
-                });
+                await cardSession.finish(finalState.terminal, usageMeta());
             }
             // else: 已终态且未收到 result（如 spawn 失败后 interrupted）-> 无 usage 可补，跳过
         }
@@ -1225,38 +1207,16 @@ export class Bridge {
             const catchTerminal = cardSession.currentState.terminal;
             if (catchTerminal === 'running' || catchTerminal === 'finalizing') {
                 await cardSession.finish('error', {
-                    contextLength: finalContextLength,
-                    contextLimit: finalContextLimit,
-                    compactCount: finalCompactCount,
-                    cacheReadTokens: finalCacheReadTokens,
-                    cacheCreationTokens: finalCacheCreationTokens,
-                    totalTokens: finalTotalTokens,
+                    ...usageMeta(),
                     inputTokens: liveInputTokens,
                     outputTokens: liveOutputTokens,
-                    cumulativeTotalTokens: finalCumulativeTotalTokens,
-                    cumulativeInputTokens: finalCumulativeInputTokens,
-                    cumulativeOutputTokens: finalCumulativeOutputTokens,
                     errorMsg: errorMessage(err),
                 });
             }
             else {
                 getLogger().info(`[bridge] skip error finish: state already terminal (${catchTerminal}) runId=${runId}`);
                 if (sawResult) {
-                    await cardSession.finish(catchTerminal, {
-                        contextLength: finalContextLength,
-                        contextLimit: finalContextLimit,
-                        compactCount: finalCompactCount,
-                        cacheReadTokens: finalCacheReadTokens,
-                        cacheCreationTokens: finalCacheCreationTokens,
-                        totalTokens: finalTotalTokens,
-                        inputTokens: finalInputTokens,
-                        outputTokens: finalOutputTokens,
-                        cumulativeTotalTokens: finalCumulativeTotalTokens,
-                        cumulativeInputTokens: finalCumulativeInputTokens,
-                        cumulativeOutputTokens: finalCumulativeOutputTokens,
-                        cumulativeCacheReadTokens: finalCumulativeCacheReadTokens,
-                        cumulativeCacheCreationTokens: finalCumulativeCacheCreationTokens,
-                    });
+                    await cardSession.finish(catchTerminal, usageMeta());
                 }
             }
         }
@@ -1562,6 +1522,10 @@ export class Bridge {
             await this.sendResult({ text: '⚠️ 未找到可压缩的会话' }, ctx);
             return;
         }
+        // §5.3: kimi 压缩在途检测（wire 状态机）。第二次点击在本地毫秒级如实回答，
+        // 不开卡、不发 session/prompt——否则 kimi 服务端拒绝并产生「秒回」假完成。
+        if (await this.rejectIfCompactionInFlight(last.sessionId, cwd, last.agentKind, ctx))
+            return;
         // Check that the runner has runCompact method
         const runner = this.getRunner(cwd, last.agentKind);
         if (!('runCompact' in runner) ||
@@ -1578,6 +1542,36 @@ export class Bridge {
             ctx,
         });
     }
+    /**
+     * §5.3: kimi 压缩在途检测——reader 鸭子实现 `readCompactionState` 时，若
+     * wire 状态机判定当前有未终结的压缩（最后一次 begin 无 terminal 记录），
+     * 直接回文本「已有一次 Compact 正在进行」并返回 true（调用方不开卡、不发
+     * session/prompt）。codex/claude 等 reader 无此方法 → 返回 false，行为不变。
+     */
+    async rejectIfCompactionInFlight(sessionId, cwd, agentKind, ctx) {
+        const reader = this.sessionReaderRegistry.get(agentKind);
+        if (!reader || !('readCompactionState' in reader))
+            return false;
+        try {
+            const state = reader.readCompactionState(sessionId, cwd);
+            if (state?.inFlight) {
+                const since = state.inFlightSince;
+                let timeLabel = '未知时刻';
+                if (since !== undefined) {
+                    const d = new Date(since);
+                    const hh = String(d.getHours()).padStart(2, '0');
+                    const mm = String(d.getMinutes()).padStart(2, '0');
+                    timeLabel = `${hh}:${mm}`;
+                }
+                await this.sendResult({ text: `⚠️ 已有一次 Compact 正在进行（开始于 ${timeLabel}），请等待完成` }, ctx);
+                return true;
+            }
+        }
+        catch (err) {
+            getLogger().warn(`[bridge] readCompactionState failed sessionId=${sessionId}: ${errorMessage(err)}`);
+        }
+        return false;
+    }
     /**
      * Stream a compaction to a card: start a RunCardSession with
      * operationKind='compaction' (no recursive Compact button), consume
@@ -1623,11 +1617,23 @@ export class Bridge {
                 operationKind: 'compaction',
             });
             let sawResult = false;
+            let resultSubtype;
+            let resultError;
             for await (const event of runner.runCompact('', { cwd, sessionId })) {
-                if (event.type === 'result')
+                if (event.type === 'result') {
                     sawResult = true;
+                    resultSubtype = event.subtype;
+                    resultError = event.errorMessage;
+                }
                 await cardSession.push(event);
             }
+            // §5.3: 卡片终态必须等于引擎真实终态。旧实现只看 sawResult 布尔——error
+            // subtype 的 result 也被 finish 'done'（放大器 bug，2026-08-31 事故）。
+            const terminal = resultSubtype === 'success'
+                ? 'done'
+                : resultSubtype === 'interrupted'
+                    ? 'interrupted'
+                    : 'error';
             // 压缩结束后从会话 jsonl 读权威统计（压缩后上下文、压缩次数、本次压缩
             // token 消耗与会话累计）。thread/compacted 通知与 jsonl 落盘几乎同时
             // （实测差 ~9ms），compactCount 未读到则短重试，仍失败优雅降级（无统计）。
@@ -1636,9 +1642,9 @@ export class Bridge {
                 await sleep(150);
                 finalUsage = this.resolveFinalUsage(sessionId, cwd, agentKind);
             }
-            await cardSession.finish(sawResult ? 'done' : 'error', {
-                resultSubtype: sawResult ? 'success' : 'error',
-                errorMsg: sawResult ? undefined : '未收到压缩结果',
+            await cardSession.finish(terminal, {
+                resultSubtype: resultSubtype ?? 'error',
+                errorMsg: terminal === 'error' ? (resultError ?? '未收到压缩结果') : undefined,
                 contextLength: finalUsage?.contextLength,
                 contextLimit: finalUsage?.contextLimit,
                 compactPreContextLength: finalUsage?.compactPreContextLength,
@@ -1654,7 +1660,7 @@ export class Bridge {
                 cumulativeCacheReadTokens: finalUsage?.cumulativeCacheReadTokens,
                 cumulativeCacheCreationTokens: finalUsage?.cumulativeCacheCreationTokens,
             });
-            log.info(`[bridge] streamCodexCompact finished sessionId=${sessionId} sawResult=${sawResult}`);
+            log.info(`[bridge] streamCodexCompact finished sessionId=${sessionId} sawResult=${sawResult} subtype=${resultSubtype ?? 'none'}`);
         }
         catch (err) {
             log.error(`[bridge] streamCodexCompact failed: ${errorMessage(err)}`);
@@ -1709,6 +1715,9 @@ export class Bridge {
             await this.sendResult({ text: `⚠️ 未找到 session ${sessionId}（当前目录: ${cwd}）` }, ctx);
             return;
         }
+        // §5.3: kimi 压缩在途检测（与 handleCodexCompact 同一入口）。
+        if (await this.rejectIfCompactionInFlight(sessionId, cwd, agentKind, ctx))
+            return;
         // Check that the runner has runCompact（codex/kimi/opencode/pi/claude 鸭子探测）。
         const runner = this.getRunner(cwd, agentKind);
         if (!('runCompact' in runner) ||

package/dist/card/card-shared.d.ts

@@ -8,10 +8,7 @@ import { type AgentKind } from '../runner/index.js';
  */
 export declare function agentDisplayName(kind: string): string;
 export { truncate } from '../common/truncate.js';
-interface TerminalLabelOptions {
-    prefix?: string;
-}
-export declare function terminalToLabel(terminal: string, options?: TerminalLabelOptions): string;
+export declare function terminalToLabel(terminal: string): string;
 export declare function terminalToColor(terminal: string): string;
 /**
  * Create a CardKit 2.0 stop button with behaviors callback.

package/dist/card/card-shared.js

@@ -34,10 +34,8 @@ const TERMINAL_LABELS = {
     running: '运行中',
     finalizing: '完成中',
 };
-export function terminalToLabel(terminal, options) {
-    const label = TERMINAL_LABELS[terminal] ?? '运行中';
-    const prefix = options?.prefix ?? '';
-    return prefix + label;
+export function terminalToLabel(terminal) {
+    return TERMINAL_LABELS[terminal] ?? '运行中';
 }
 export function terminalToColor(terminal) {
     if (terminal === 'done')

package/dist/common/truncate.d.ts

@@ -16,12 +16,6 @@ export declare const DEFAULT_TRUNCATE_SUFFIX = "\u2026\uFF08\u5DF2\u622A\u65AD\u
  * pathological tool_result never inflates the replay payload to megabytes.
  */
 export declare const TOOL_RESULT_MAX_BYTES = 4000;
-/**
- * Fit a UTF-8 string into `maxBytes` by iterating Unicode codepoints, never
- * splitting a multi-byte sequence. When `fromEnd` is true, keeps the TAIL
- * (useful for logs/tails); otherwise keeps the HEAD.
- */
-export declare function fitUtf8(value: string, maxBytes: number, fromEnd?: boolean): string;
 /**
  * Truncate a UTF-8 string to fit within `maxBytes`, appending `suffix`
  * (default `…（已截断）`) when truncation occurs. When `fromEnd` is true, keeps

package/dist/common/truncate.js

@@ -21,7 +21,7 @@ export const TOOL_RESULT_MAX_BYTES = 4000;
  * splitting a multi-byte sequence. When `fromEnd` is true, keeps the TAIL
  * (useful for logs/tails); otherwise keeps the HEAD.
  */
-export function fitUtf8(value, maxBytes, fromEnd = false) {
+function fitUtf8(value, maxBytes, fromEnd = false) {
     if (fromEnd) {
         const codepoints = Array.from(value);
         let bytes = 0;

package/dist/common/ttl-cache.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Generic TTL + bounded LRU cache.
+ *
+ * Consolidates the per-reader memory caches that previously hand-rolled the
+ * same "mtime/TTL + entry cap" Map pattern (kimi/pi/opencode session readers).
+ * Semantics follow the kimi implementation:
+ * - TTL is measured from the cache-write time (P1-17 defect 2), not key mtime.
+ *   Note: ttlMs = 0 effectively disables caching — `Date.now() - at >= 0` is
+ *   always true, so every entry expires immediately.
+ * - A hit refreshes recency (LRU); eviction removes the least recently
+ *   inserted/used entry past `maxEntries` (P1-17 defect 1: unbounded growth).
+ *   The old pi implementation did NOT re-insert on hit (FIFO eviction); the
+ *   eviction order for pi therefore changes from FIFO to LRU here.
+ */
+export declare class TtlCache<K, V> {
+    private readonly ttlMs;
+    private readonly maxEntries?;
+    private map;
+    constructor(ttlMs: number, maxEntries?: number | undefined);
+    /** Return the fresh value for `key` (refreshing LRU order), or undefined. */
+    get(key: K): V | undefined;
+    set(key: K, value: V): void;
+    clear(): void;
+}

package/dist/common/ttl-cache.js

@@ -0,0 +1,53 @@
+/**
+ * Generic TTL + bounded LRU cache.
+ *
+ * Consolidates the per-reader memory caches that previously hand-rolled the
+ * same "mtime/TTL + entry cap" Map pattern (kimi/pi/opencode session readers).
+ * Semantics follow the kimi implementation:
+ * - TTL is measured from the cache-write time (P1-17 defect 2), not key mtime.
+ *   Note: ttlMs = 0 effectively disables caching — `Date.now() - at >= 0` is
+ *   always true, so every entry expires immediately.
+ * - A hit refreshes recency (LRU); eviction removes the least recently
+ *   inserted/used entry past `maxEntries` (P1-17 defect 1: unbounded growth).
+ *   The old pi implementation did NOT re-insert on hit (FIFO eviction); the
+ *   eviction order for pi therefore changes from FIFO to LRU here.
+ */
+export class TtlCache {
+    ttlMs;
+    maxEntries;
+    map = new Map();
+    constructor(ttlMs, maxEntries) {
+        this.ttlMs = ttlMs;
+        this.maxEntries = maxEntries;
+    }
+    /** Return the fresh value for `key` (refreshing LRU order), or undefined. */
+    get(key) {
+        const entry = this.map.get(key);
+        if (!entry)
+            return undefined;
+        if (Date.now() - entry.at >= this.ttlMs) {
+            this.map.delete(key);
+            return undefined;
+        }
+        // LRU refresh: re-insert to move to the tail of iteration order.
+        this.map.delete(key);
+        this.map.set(key, entry);
+        return entry.value;
+    }
+    set(key, value) {
+        this.map.delete(key);
+        this.map.set(key, { at: Date.now(), value });
+        if (this.maxEntries !== undefined) {
+            while (this.map.size > this.maxEntries) {
+                const oldest = this.map.keys().next().value;
+                if (oldest === undefined)
+                    break;
+                this.map.delete(oldest);
+            }
+        }
+    }
+    clear() {
+        this.map.clear();
+    }
+}
+//# sourceMappingURL=ttl-cache.js.map

package/dist/config/codex-config.d.ts

@@ -75,14 +75,36 @@ export declare function parseCodexModelsOutput(stdout: string): BundledModelInfo
  * 缓存：键含 binary/home/mode/models.json mtime:size + config.toml mtime:size
  * （P3-4/P3-15/P3-5）；成功结果 TTL 1h，失败/空结果短 TTL 负缓存；stat 异常时
  * 指纹为空（P1-1/P3-10）。
+ *
+ * 同步路径（卡片构建用）：缓存命中直接返回；若有一个后台异步加载
+ * （`loadCodexCatalogModelsAsync` / 启动 warm）在途，则不阻塞事件循环、不重复
+ * spawn，直接返回 [] 走既有 fallback（FALLBACK_MODELS / currentModel）——该
+ * [] 状态与命令失败/超时的已有语义一致，由调用方既有 fallback 兜底。
  */
 export declare function getCodexCatalogModels(codexHome?: string): BundledModelInfo[];
+/**
+ * 异步加载模型目录（execFile，不阻塞事件循环），写入与同步路径共享的
+ * `catalogCache`。按缓存 key 复用 in-flight Promise：并发调用（多个 warm /
+ * 显式调用）只 spawn 一次 `codex debug models`。
+ *
+ * 与同步路径的职责划分：启动时用 `warmCodexCatalogCache` 后台预热，使首次打开
+ * Codex 配置卡（同步读）时缓存已温、无需 8s execFileSync 阻塞；若用户在 warm
+ * 完成前打开卡片，同步路径会检测到 in-flight 并直接返回 [] fallback。
+ */
+export declare function loadCodexCatalogModelsAsync(codexHome?: string): Promise<BundledModelInfo[]>;
+/**
+ * 启动/后台预热：fire-and-forget 调用异步加载，消除首次打开 Codex 配置卡时的
+ * 8s 同步阻塞。非致命——失败/未安装 codex 时静默落负缓存。
+ */
+export declare function warmCodexCatalogCache(codexHome?: string): void;
 /**
  * Test utility: clear the catalog cache. Tests that exercise the bundled
  * command path (`--bundled`) directly use `invalidateCodexBundledTestCache`
  * from `tests/lib/codex-bundled-test-helpers.ts`.
  */
 export declare function invalidateCodexBundledCache(): void;
+/** Test utility: clear in-flight async catalog loads (see async loader tests). */
+export declare function _clearCodexCatalogInFlightForTest(): void;
 /**
  * Get supported reasoning effort options for a model.
  * @param codexHome 可选 codex 配置目录覆盖（与 loadCodexConfig 的 codexHome 对齐，