lark-remote 0.5.12 → 0.5.14

package/dist/session/opencode/sessions.js

@@ -22,9 +22,9 @@ import os from 'node:os';
 import path from 'node:path';
 import { truncateUtf8, TOOL_RESULT_MAX_BYTES } from '../../common/truncate.js';
 import { isStale } from '../common/constants.js';
-import { samePath } from '../../platform/path.js';
+import { safeRealpath, samePath } from '../../platform/path.js';
 import { paginate, capEvents } from '../common/pagination.js';
-import { sortByRecencyDesc } from '../common/recency.js';
+import { newestOf, sortByRecencyDesc } from '../common/recency.js';
 import { TtlCache } from '../../common/ttl-cache.js';
 import { getLogger } from '../../logger/index.js';
 /** v2 CLI defaults `session list` to 100 entries; keep the reader's historical
@@ -81,6 +81,35 @@ function v2ToolOutput(state) {
         return state.result;
     return undefined;
 }
+/**
+ * 把会话级累计 token 落到 usage 上（v1 export 与 v2 export 两条读取路径共用）。
+ *
+ * 已有 usage 就地补累计字段；没有 usage 但累计非零（例如只有 cache 计数）时，
+ * 构造一条只带累计的，避免"会话有消耗却显示无 usage"。
+ */
+function withCumulativeUsage(usage, cum) {
+    if (usage) {
+        usage.cumulativeTotalTokens = cum.total;
+        usage.cumulativeInputTokens = cum.input;
+        usage.cumulativeOutputTokens = cum.output;
+        usage.cumulativeCacheReadTokens = cum.cacheRead;
+        usage.cumulativeCacheCreationTokens = cum.cacheWrite;
+        return usage;
+    }
+    if (!(cum.input || cum.output || cum.total || cum.cacheRead || cum.cacheWrite)) {
+        return undefined;
+    }
+    return {
+        inputTokens: 0,
+        outputTokens: 0,
+        contextLength: 0,
+        cumulativeTotalTokens: cum.total,
+        cumulativeInputTokens: cum.input,
+        cumulativeOutputTokens: cum.output,
+        cumulativeCacheReadTokens: cum.cacheRead,
+        cumulativeCacheCreationTokens: cum.cacheWrite,
+    };
+}
 export class OpencodeSessionReader {
     binary;
     cacheTtlMs;
@@ -124,7 +153,7 @@ export class OpencodeSessionReader {
      * Get the newest session in a given cwd.
      */
     getNewestSession(cwd) {
-        return this.listSessions(cwd, { limit: 1 }).sessions[0] ?? null;
+        return newestOf(this, cwd);
     }
     /**
      * Read session content: extract catch-up tail (last user message + everything after).
@@ -283,25 +312,13 @@ export class OpencodeSessionReader {
                     }
                 }
             }
-            if (usage) {
-                usage.cumulativeTotalTokens = cumTotal;
-                usage.cumulativeInputTokens = cumInput;
-                usage.cumulativeOutputTokens = cumOutput;
-                usage.cumulativeCacheReadTokens = cumCacheRead;
-                usage.cumulativeCacheCreationTokens = cumCacheWrite;
-            }
-            else if (cumInput || cumOutput || cumTotal || cumCacheRead || cumCacheWrite) {
-                usage = {
-                    inputTokens: 0,
-                    outputTokens: 0,
-                    contextLength: 0,
-                    cumulativeTotalTokens: cumTotal,
-                    cumulativeInputTokens: cumInput,
-                    cumulativeOutputTokens: cumOutput,
-                    cumulativeCacheReadTokens: cumCacheRead,
-                    cumulativeCacheCreationTokens: cumCacheWrite,
-                };
-            }
+            usage = withCumulativeUsage(usage, {
+                total: cumTotal,
+                input: cumInput,
+                output: cumOutput,
+                cacheRead: cumCacheRead,
+                cacheWrite: cumCacheWrite,
+            });
             // Use info.title as aiTitle
             if (data.info.title) {
                 aiTitle = data.info.title;
@@ -470,25 +487,13 @@ export class OpencodeSessionReader {
                 };
             }
         }
-        if (latest) {
-            latest.cumulativeTotalTokens = cumTotal;
-            latest.cumulativeInputTokens = cumInput;
-            latest.cumulativeOutputTokens = cumOutput;
-            latest.cumulativeCacheReadTokens = cumCacheRead;
-            latest.cumulativeCacheCreationTokens = cumCacheWrite;
-        }
-        else if (cumInput || cumOutput || cumTotal || cumCacheRead || cumCacheWrite) {
-            latest = {
-                inputTokens: 0,
-                outputTokens: 0,
-                contextLength: 0,
-                cumulativeTotalTokens: cumTotal,
-                cumulativeInputTokens: cumInput,
-                cumulativeOutputTokens: cumOutput,
-                cumulativeCacheReadTokens: cumCacheRead,
-                cumulativeCacheCreationTokens: cumCacheWrite,
-            };
-        }
+        latest = withCumulativeUsage(latest, {
+            total: cumTotal,
+            input: cumInput,
+            output: cumOutput,
+            cacheRead: cumCacheRead,
+            cacheWrite: cumCacheWrite,
+        });
         return {
             events: capEvents(events, opts?.maxEvents),
             usage: latest,
@@ -510,19 +515,19 @@ export class OpencodeSessionReader {
             // Check if updated within STALE_MS
             return !isStale(entry.updated);
         }
-        catch {
+        catch (err) {
+            getLogger().debug(`[opencode-session-reader] isSessionActive failed session=${sessionId}: ${err?.message ?? String(err)}`);
             return false;
         }
     }
     // --- Private helpers ---
     /** realpath 归一化（public：测试直接调用，替代 as unknown as）。 */
     realpath(cwd) {
-        try {
-            return fs.realpathSync(cwd);
-        }
-        catch {
-            return cwd;
-        }
+        return safeRealpath(cwd, (err) => {
+            if (err.code === 'ENOENT')
+                return;
+            getLogger().debug(`[opencode-session-reader] realpath ${cwd} failed, using the path as given: ${err?.message ?? String(err)}`);
+        });
     }
     fetchSessionList(cwd) {
         const realCwd = this.realpath(cwd);

package/dist/session/pi/sessions.d.ts

@@ -1,5 +1,5 @@
 import { type ContentBlockMapping } from '../common/content-blocks.js';
-import type { AgentSession, AgentSessionReader, SessionContent } from '../../runner/index.js';
+import type { AgentSession, AgentSessionReader, SessionContent } from '../../session-contract.js';
 /** Pi-specific field-name mapping for content block extraction. */
 export declare const PI_MAPPING: ContentBlockMapping;
 /**

package/dist/session/pi/sessions.js

@@ -8,8 +8,9 @@ import { UsageAccumulator, contextWindowOccupancy, cumulativeUsageFields, } from
 import { isStale } from '../common/constants.js';
 import { encodeProjectDirName, samePath } from '../../platform/path.js';
 import { paginate } from '../common/pagination.js';
-import { sortByRecencyDesc } from '../common/recency.js';
+import { newestOf, sortByRecencyDesc } from '../common/recency.js';
 import { TtlCache } from '../../common/ttl-cache.js';
+import { getLogger } from '../../logger/index.js';
 function defaultPiDir() {
     return path.join(os.homedir(), '.pi', 'agent');
 }
@@ -134,8 +135,11 @@ function findSessionFile(sessionId, cwd, sessionsDir) {
             }
         }
     }
-    catch {
-        // dir doesn't exist
+    catch (err) {
+        // dir 不存在（陈旧 cwd / 该 cwd 从没有会话）是正常空态；其余留痕。
+        if (err.code !== 'ENOENT') {
+            getLogger().debug(`[pi-session-reader] cannot read ${dir}: ${err?.message ?? String(err)}`);
+        }
     }
     return null;
 }
@@ -281,7 +285,7 @@ export class PiSessionReader {
         };
     }
     getNewestSession(cwd) {
-        return this.listSessions(cwd, { limit: 1 }).sessions[0] ?? null;
+        return newestOf(this, cwd);
     }
     readSessionContent(sessionId, cwd, opts) {
         let filePath = null;
@@ -318,7 +322,10 @@ export class PiSessionReader {
             const st = fs.statSync(filePath);
             return !isStale(st.mtimeMs);
         }
-        catch {
+        catch (err) {
+            if (err.code !== 'ENOENT') {
+                getLogger().debug(`[pi-session-reader] stat ${filePath} failed: ${err?.message ?? String(err)}`);
+            }
             return false;
         }
     }
@@ -334,8 +341,15 @@ export class PiSessionReader {
         try {
             files = fs.readdirSync(dir).filter((f) => f.endsWith('.jsonl'));
         }
-        catch {
-            return [];
+        catch (err) {
+            // ENOENT：该 cwd 还没有会话目录（正常空态）。其余失败上抛，由 router
+            // 显示「列表失败」——静默 [] 与真空不可区分（与 opencode 同口径）。
+            if (err.code === 'ENOENT') {
+                return [];
+            }
+            getLogger().error(`[pi-session-reader] listSessions failed: ${err}`);
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`pi session list 读取失败: ${msg}`, { cause: err });
         }
         const sessions = [];
         for (const f of files) {
@@ -356,8 +370,8 @@ export class PiSessionReader {
                     mtime: st.mtimeMs,
                 });
             }
-            catch {
-                // skip
+            catch (err) {
+                getLogger().debug(`[pi-session-reader] skipped ${full}: ${err?.message ?? String(err)}`);
             }
         }
         // Same-mtime ties: secondary key keeps the full order deterministic.

package/dist/session/registry.d.ts

@@ -1,4 +1,5 @@
-import type { AgentKind, AgentSessionReader } from '../runner/index.js';
+import type { AgentKind } from '../agent-kinds.js';
+import type { AgentSessionReader } from '../session-contract.js';
 /**
  * Registry of `AgentSessionReader` instances, keyed by `AgentKind`. Mirrors
  * `AgentRegistry` but for session-history reads. `index.ts` registers one

package/dist/session/session-store.d.ts

@@ -1,4 +1,4 @@
-import type { AgentKind } from '../runner/index.js';
+import type { AgentKind } from '../agent-kinds.js';
 interface SessionEntry {
     /** Session IDs per agent kind (Map for in-memory, plain object for persistence). */
     sessions: Map<AgentKind, string>;
@@ -58,7 +58,6 @@ export declare class SessionStore {
      */
     private mutateEntry;
     get(userId: string): SessionEntry | undefined;
-    set(userId: string, entry: SessionEntry): void;
     delete(userId: string): void;
     /** Clear sessionId for a specific agent, keeping cwd and other agent sessions */
     clearSessionId(userId: string, agent?: AgentKind, opts?: {

package/dist/session/session-store.js

@@ -85,10 +85,6 @@ export class SessionStore {
     get(userId) {
         return this.sessions.get(userId);
     }
-    set(userId, entry) {
-        this.sessions.set(userId, entry);
-        this.autoPersist();
-    }
     delete(userId) {
         this.sessions.delete(userId);
         this.autoPersist();
@@ -170,7 +166,7 @@ export class SessionStore {
     /** Get sessionId for a specific agent, or undefined if no session or sessionId is empty */
     getSessionId(userId, agent = 'claude') {
         const entry = this.sessions.get(userId);
-        if (!entry || !entry.sessions)
+        if (!entry)
             return undefined;
         const sessionId = entry.sessions.get(agent);
         if (!sessionId)
@@ -284,8 +280,19 @@ export class SessionStore {
                 }
             }
         }
-        catch {
-            getLogger().warn('[session] persisted session store corrupted, ignoring');
+        catch (err) {
+            getLogger().warn(`[session] persisted session store corrupted (${this.persistPath ?? '(memory)'}), ignoring:`, err);
+            // 改名保留现场：原文件继续原地躺着会让下次启动重复告警，也丢掉排障证据。
+            if (this.persistPath) {
+                const brokenPath = `${this.persistPath}.corrupt-${Date.now()}`;
+                try {
+                    fs.renameSync(this.persistPath, brokenPath);
+                    getLogger().warn(`[session] moved corrupt store to ${brokenPath}`);
+                }
+                catch (renameErr) {
+                    getLogger().warn('[session] failed to preserve corrupt store:', renameErr);
+                }
+            }
         }
     }
     autoPersist() {

package/dist/session-contract.d.ts

@@ -0,0 +1,178 @@
+/**
+ * 会话读取契约：`AgentSessionReader` 与其数据类型。
+ *
+ * 中立模块——runner 与 session 两侧都只是它的实现方/消费方。此前住在
+ * `runner/types.ts` 里，于是 session/* 有十一处为了一个类型反向 import 上层
+ * runner（runner ↔ session 双向循环的一半）；挪到这里后两边同向依赖它。
+ */
+/** Unified session descriptor returned by every AgentSessionReader. */
+export interface AgentSession {
+    sessionId: string;
+    summary: string;
+    mtime: number;
+    /** DSH：session 创建时固定的 preset；其他 agent 无此概念（undefined）。 */
+    agentPreset?: string;
+    /**
+     * 服务端投影已有的会话标题（DSH `projections.values.title`）。
+     *
+     * 与 `summary` 的区别：`summary` 是「首条用户输入」的兜底口径（claude /
+     * codex / pi / kimi 无标题字段），`title` 是 agent 自己起的标题。列表卡
+     * 用它决定标签文案（标题 / 会话摘要），缺省时回退 `summary`。
+     */
+    title?: string;
+    /**
+     * 最后一轮用户输入（服务端投影，单行预览）。
+     *
+     * 只给「列表响应里已顺带返回」的 reader 用（DSH 的 `turnOutline` 末条），
+     * 目的是让列表卡不必为每行做一次全量内容读取。
+     */
+    lastUserMessage?: string;
+    /** 最后一轮助手输出（服务端投影已截断，单行预览）。 */
+    lastAssistantMessage?: string;
+}
+/** A single renderable event from session history. */
+export interface AgentSessionContentEvent {
+    type: string;
+    /** 正文（展开后的面板内容）。 */
+    content: string;
+    /**
+     * 面板标题（可选，覆盖 reader 的默认标签）。
+     *
+     * 折叠面板默认只显示标题：工具调用这种"标题即全部信息"的事件必须把
+     * `bash — npm test` 这类摘要放进标题，否则折叠态只剩 `🔧 工具调用`。
+     */
+    title?: string;
+    timestamp?: string;
+}
+export interface AgentSessionUsage {
+    inputTokens: number;
+    outputTokens: number;
+    contextLength: number;
+    /** Agent 上报的当前模型 context window 上限（codex token_count.info.model_context_window）。
+     *  仅 codex 提供；缺省时卡片只显示绝对量、不显示百分比。 */
+    contextLimit?: number;
+    /** Claude auto-compact 次数（数 compact_boundary 事件）；codex/opencode 无此概念，留 undefined。 */
+    compactCount?: number;
+    /** 压缩前上下文水位（codex compact 后从会话 jsonl 读取，仅会话以压缩收尾时有值）。 */
+    compactPreContextLength?: number;
+    /** 从缓存读取的 token 数（节省的费用）。 */
+    cacheReadTokens?: number;
+    /** 新建缓存的 token 数。 */
+    cacheCreationTokens?: number;
+    /** Agent 声明的总量；展示用 max(total, 分项和)。 */
+    totalTokens?: number;
+    /** 会话累计 total token（所有 run 之和，含本次）。用于 Run 卡片"累计"展示。 */
+    cumulativeTotalTokens?: number;
+    /** 会话累计 input token（所有 run 之和，含本次）。用于 Run 卡片"累计"展示。 */
+    cumulativeInputTokens?: number;
+    /** 会话累计 output token（所有 run 之和，含本次）。 */
+    cumulativeOutputTokens?: number;
+    /** 会话累计 cache read token（所有 run 之和）。用于 Run 卡片展示累计缓存命中。 */
+    cumulativeCacheReadTokens?: number;
+    /** 会话累计 cache creation token（所有 run 之和）。 */
+    cumulativeCacheCreationTokens?: number;
+}
+/**
+ * 一张 run 卡的用量快照：`AgentSessionUsage` 的可选形态 + 只有 live 侧有的
+ * 推理计数。桥侧记账、reducer 写入 RunState、渲染层格式化都吃这一份——
+ * 字段清单原先手抄在 6 个 interface 里（§9.21「五处一致」靠人记），
+ * 新增一个 usage 字段要同步改 6 处，漏一处就是卡片少一行。
+ *
+ * 中立层：card / bridge / runner / router 都引用它，谁也不向上依赖。
+ */
+export type UsageSnapshot = Partial<AgentSessionUsage> & {
+    /** 推理 token（pi usage.reasoning 累加）；reader 契约里没有，只有 live 事件带。 */
+    reasoningTokens?: number;
+};
+/** Unified session content payload returned by every AgentSessionReader. */
+export interface SessionContent {
+    events: AgentSessionContentEvent[];
+    usage?: AgentSessionUsage;
+    aiTitle?: string;
+    recap?: string;
+    displayTitle?: string;
+}
+/**
+ * Lightweight session summary used by `/resume` list prefetch.
+ *
+ * Carries only the display fields (title / recap / usage) — **no `events`
+ * array**. Readers that can extract these without constructing the full event
+ * list (e.g. codex, which would otherwise JSON.parse every response_item and
+ * build an `events[]` that the prefetch immediately discards) implement the
+ * optional `readSessionSummary` on `AgentSessionReader`.
+ */
+export interface SessionSummary {
+    aiTitle?: string;
+    recap?: string;
+    displayTitle?: string;
+    usage?: AgentSessionUsage;
+}
+/**
+ * 手动压缩的在途状态（由会话里的 begin/terminal 记录重建）。
+ * 只有把压缩写成 wire 状态机的 agent 能提供，见
+ * {@link AgentSessionReader.readCompactionState}。
+ */
+export interface CompactionState {
+    inFlight: boolean;
+    /** 在途 begin 的 time（epoch ms）。 */
+    inFlightSince?: number;
+}
+/**
+ * Reads an agent's session history. Each agent implements its own (Claude reads
+ * `~/.claude/projects/`, Codex calls `thread/list`, OpenCode calls `GET /session`).
+ *
+ * Q-C decision: `projectsDir` and other agent-specific path config live on the
+ * concrete reader's constructor, NOT on these method opts. The router/bridge
+ * depend only on this interface and never pass path config.
+ */
+export interface AgentSessionReader {
+    /**
+     * List sessions for a cwd, newest first by mtime.
+     *
+     * `sessions` is the page `[offset, offset+limit)` of the full set ordered
+     * by mtime desc, with same-mtime ties broken by a deterministic secondary
+     * key (sessionId/file path) so ordering is stable across calls. When
+     * `limit` is omitted, codex/pi/kimi return their default-sized page
+     * (default 20); claude/opencode return the full remaining set from
+     * `offset`. `total` is ALWAYS the size of the full cwd-matched set before
+     * pagination — never the truncated page length. A negative `offset` is
+     * clamped to 0 (first page).
+     */
+    listSessions(cwd: string, opts?: {
+        limit?: number;
+        offset?: number;
+    }): {
+        sessions: AgentSession[];
+        total: number;
+    };
+    getNewestSession(cwd: string): AgentSession | null;
+    readSessionContent(sessionId: string, cwd: string, opts?: {
+        maxEvents?: number;
+    }): SessionContent;
+    /**
+     * Optional lightweight summary for list-prefetch.
+     *
+     * Returns only the display fields (aiTitle/recap/displayTitle/usage) without
+     * constructing the full `events` array. When absent, callers fall back to
+     * `readSessionContent` and take the needed fields.
+     */
+    readSessionSummary?(sessionId: string, cwd: string): SessionSummary;
+    /**
+     * 这个会话此刻是否还在被使用。**证据强度按 reader 不同，调用方必须知道自己
+     * 问的是哪一个**：
+     *
+     * - DSH：服务端事实（session 有在跑的 turn）。启动自动恢复路径用它，
+     *   见 `src/index.ts` 的 `stillRunning` 分支。
+     * - claude/codex/opencode/pi/kimi：只有「最近一段时间有写入」这一层文件证据
+     *   （mtime + 末行终态标记），拿它当 turn 在跑会每次误报。
+     *
+     * 「agent 现在忙不忙」的运行时真相仍归 `bridge.isBusyFor(cwd)`（内存态，
+     * 见 cmdPs）；本方法是文件/服务端侧的补充探针，不是它的替代品。
+     */
+    isSessionActive(sessionId: string, cwd: string): boolean;
+    /**
+     * 手动压缩是否已在途（只有把压缩写成 wire 状态机的 agent 能提供，目前 kimi）。
+     * 未实现 = 该 agent 没有这个概念，调用方按「不在途」处理。
+     */
+    readCompactionState?(sessionId: string, cwd: string): CompactionState;
+}

package/dist/session-contract.js

@@ -0,0 +1,9 @@
+/**
+ * 会话读取契约：`AgentSessionReader` 与其数据类型。
+ *
+ * 中立模块——runner 与 session 两侧都只是它的实现方/消费方。此前住在
+ * `runner/types.ts` 里，于是 session/* 有十一处为了一个类型反向 import 上层
+ * runner（runner ↔ session 双向循环的一半）；挪到这里后两边同向依赖它。
+ */
+export {};
+//# sourceMappingURL=session-contract.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lark-remote",
-  "version": "0.5.12",
+  "version": "0.5.14",
   "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",

package/dist/router/usage-format.d.ts

@@ -1,60 +0,0 @@
-/**
- * Format session/run usage stats (context, compact count, tokens, cost) into
- * the display strings shown on cards. Pure — no Router state.
- */
-import type { ActiveRunSnapshot } from '../bridge/index.js';
-export interface SessionDisplayUsage {
-    contextLength?: number;
-    /** 当前模型 context window 上限（仅 codex 提供）；用于渲染 "Context - X (Y%)"。 */
-    contextLimit?: number;
-    compactCount?: number;
-    cacheReadTokens?: number;
-    cacheCreationTokens?: number;
-}
-export declare function activeRunUsage(activeRun: ActiveRunSnapshot | undefined): SessionDisplayUsage | undefined;
-/**
- * Format usage stats (context length, compact count, cache tokens) into a display string.
- * Each stat on its own line with blank lines between sections.
- * @param usage - Usage stats object
- * @param options - Optional display options (showResult adds result line)
- */
-export declare function formatUsageStats(usage?: {
-    contextLength?: number;
-    contextLimit?: number;
-    compactCount?: number;
-    /** 压缩前上下文水位；与 contextLength（压缩后）成对出现在 Compact 卡上。 */
-    compactPreContextLength?: number;
-    cacheReadTokens?: number;
-    cacheCreationTokens?: number;
-    /** Agent-declared total; when present the display uses max(total, sum of parts). */
-    totalTokens?: number;
-    /** Real input tokens from the agent's result event. When present, used
-     *  directly for the "Input token" line instead of contextLength+cache. */
-    inputTokens?: number;
-    /** Real output tokens from the agent's result event. When present, used
-     *  directly instead of the 10% estimate. */
-    outputTokens?: number;
-    /** Session-cumulative total/input/output (all runs), from session jsonl. When
-     *  present, appended as "· 累计 X" on the Total/Input/Output lines. */
-    cumulativeTotalTokens?: number;
-    cumulativeInputTokens?: number;
-    cumulativeOutputTokens?: number;
-    /** Session-cumulative cache read tokens (all runs). */
-    cumulativeCacheReadTokens?: number;
-    /** Session-cumulative cache creation tokens (all runs). */
-    cumulativeCacheCreationTokens?: number;
-    /** 实际生效模型（system.init 携带）。非空字符串才显示。 */
-    model?: string;
-    /** 本次 run 花费（USD）。存在才显示。 */
-    costUsd?: number;
-    /** 推理 token（pi 提供）。> 0 才显示。 */
-    reasoningTokens?: number;
-}, options?: {
-    showResult?: boolean;
-    result?: string;
-    /**
-     * 首行状态文案。默认 `✅ 已完成`；goal 仍 active 的收尾卡必须换掉它——
-     * 本轮 turn 结束不等于任务结束。
-     */
-    completedLabel?: string;
-}): string;