lark-remote 0.1.5 → 0.1.6

package/dist/runner/codex/app-server/transport.d.ts

@@ -0,0 +1,49 @@
+/**
+ * JSONL-RPC transport for the Codex app-server protocol.
+ *
+ * Wraps a child process (spawned from `codex app-server`) with
+ * JSON-line-based bidirectional communication: each line on stdout is a JSON
+ * message from the server; each `write()` sends a JSON line to stdin.
+ */
+export interface TransportEvents {
+    onMessage(msg: unknown): void;
+    onClose(reason: string): void;
+}
+export declare class JsonlRpcTransport {
+    private proc;
+    private _closed;
+    private events;
+    private stopper;
+    private readonly binary;
+    private readonly args;
+    private readonly cwd;
+    private readonly env;
+    /** JSON lines buffered while stdin is under backpressure (bounded by callers). */
+    private writeQueue;
+    private flushing;
+    constructor(opts: {
+        binary: string;
+        args: string[];
+        cwd: string;
+        env?: Record<string, string | undefined>;
+    });
+    get closed(): boolean;
+    /**
+     * Spawn the child process and start reading its stdout.
+     * Returns when the process closes (or immediately if spawn fails).
+     */
+    start(events: TransportEvents): Promise<void>;
+    /**
+     * Write a JSON message as a single line to the process's stdin.
+     * On EPIPE, triggers onClose('epipe') without throwing.
+     */
+    write(msg: object): void;
+    /** Send queued lines to stdin, pausing on backpressure until drain. */
+    private flush;
+    /**
+     * Gracefully stop the child process: SIGTERM → grace → SIGKILL.
+     * Idempotent — safe to call multiple times.
+     */
+    close(): Promise<void>;
+    private handleClose;
+}

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

@@ -0,0 +1,231 @@
+/**
+ * JSONL-RPC transport for the Codex app-server protocol.
+ *
+ * Wraps a child process (spawned from `codex app-server`) with
+ * JSON-line-based bidirectional communication: each line on stdout is a JSON
+ * message from the server; each `write()` sends a JSON line to stdin.
+ */
+import { spawn } from 'node:child_process';
+import { ProcessStopper } from '../../common/process-stopper.js';
+import { getLogger } from '../../../logger/index.js';
+/** Max bytes for a single line before we disconnect (10MB). */
+const MAX_LINE_BYTES = 10 * 1024 * 1024;
+/** Max bytes retained from stderr for diagnostics (64KB). */
+const MAX_STDERR_BYTES = 64 * 1024;
+export class JsonlRpcTransport {
+    proc = null;
+    _closed = false;
+    events = null;
+    stopper;
+    binary;
+    args;
+    cwd;
+    env;
+    /** JSON lines buffered while stdin is under backpressure (bounded by callers). */
+    writeQueue = [];
+    flushing = false;
+    constructor(opts) {
+        this.binary = opts.binary;
+        this.args = opts.args;
+        this.cwd = opts.cwd;
+        this.env = opts.env ?? {};
+        this.stopper = new ProcessStopper({ graceMs: 5000 });
+    }
+    get closed() {
+        return this._closed;
+    }
+    /**
+     * Spawn the child process and start reading its stdout.
+     * Returns when the process closes (or immediately if spawn fails).
+     */
+    async start(events) {
+        this.events = events;
+        // 与 exec 模式对齐（SpawningRunner.getSpawnEnv 全量透传 process.env）：
+        // codex 是用户自己的可信二进制，provider 认证依赖 OPENAI_API_KEY /
+        // ANTHROPIC_API_KEY / 自定义 provider 的 env_key（codex-config.ts
+        // providerEnvKeys），代理环境依赖 HTTP(S)_PROXY、TMPDIR 等；任何白名单
+        // 收窄都会打断认证或网络。调用方 this.env 覆盖 process.env 同名键。
+        const childEnv = { ...process.env, ...this.env };
+        const proc = spawn(this.binary, this.args, {
+            cwd: this.cwd,
+            stdio: ['pipe', 'pipe', 'pipe'],
+            detached: true,
+            env: childEnv,
+        });
+        this.proc = proc;
+        if (proc.pid === undefined) {
+            // ENOENT early check
+            const err = await new Promise((resolve) => {
+                proc.once('error', (e) => resolve(e));
+                setTimeout(() => resolve(undefined), 5000);
+            });
+            this._closed = true;
+            const reason = err ? `ENOENT: ${this.binary} not found` : `spawn failed: ${this.binary}`;
+            events.onClose(reason);
+            return;
+        }
+        getLogger().info(`[codex-transport] spawned pid=${proc.pid} binary=${this.binary}`);
+        proc.stdin?.on('error', (err) => {
+            getLogger().warn(`[codex-transport] stdin error: ${err.message}`);
+            this.handleClose('epipe');
+        });
+        // Stderr: rolling buffer, last 64KB retained, only log
+        let stderrBuf = '';
+        proc.stderr?.on('data', (chunk) => {
+            const text = chunk.toString('utf-8');
+            stderrBuf = (stderrBuf + text).slice(-MAX_STDERR_BYTES);
+            getLogger().debug(`[codex-transport] stderr: ${text.trimEnd()}`);
+        });
+        // Stdout: line-split with 10MB line limit
+        let remainder = '';
+        proc.stdout?.on('data', (chunk) => {
+            remainder += chunk.toString('utf-8');
+            const lines = remainder.split('\n');
+            // Lines except the last (incomplete) one
+            remainder = lines.pop() ?? '';
+            for (const line of lines) {
+                if (line.length === 0)
+                    continue;
+                if (line.length > MAX_LINE_BYTES) {
+                    getLogger().error(`[codex-transport] line exceeds ${MAX_LINE_BYTES} bytes, disconnecting`);
+                    this.handleClose('parse_error');
+                    return;
+                }
+                try {
+                    const msg = JSON.parse(line);
+                    events.onMessage(msg);
+                }
+                catch (err) {
+                    getLogger().warn(`[codex-transport] failed to parse JSON: ${err.message} line=${line.slice(0, 200)}`);
+                }
+            }
+        });
+        // Handle process exit
+        const onExit = (code, signal) => {
+            this._closed = true;
+            this.proc = null;
+            // Flush remaining buffer
+            if (remainder.length > 0) {
+                try {
+                    const msg = JSON.parse(remainder);
+                    events.onMessage(msg);
+                }
+                catch {
+                    // ignore trailing incomplete line
+                }
+            }
+            const reason = signal ? `signal:${signal}` : `exit:${code}`;
+            events.onClose(reason);
+            getLogger().info(`[codex-transport] process exited pid=${proc.pid} code=${code} signal=${signal}`);
+        };
+        proc.once('exit', onExit);
+        proc.once('error', (err) => {
+            getLogger().error(`[codex-transport] process error: ${err.message}`);
+            this.handleClose(`error:${err.message}`);
+        });
+    }
+    /**
+     * Write a JSON message as a single line to the process's stdin.
+     * On EPIPE, triggers onClose('epipe') without throwing.
+     */
+    write(msg) {
+        if (this._closed || !this.proc?.stdin) {
+            return;
+        }
+        try {
+            // 入队后顺序 flush；write() 返回 false（高水位）时暂停直到 drain，
+            // 避免大消息/突发消息在 Node 内部无限缓冲（review P3-8）。
+            this.writeQueue.push(Buffer.from(JSON.stringify(msg) + '\n', 'utf8'));
+            this.flush();
+        }
+        catch {
+            this.handleClose('epipe');
+        }
+    }
+    /** Send queued lines to stdin, pausing on backpressure until drain. */
+    flush() {
+        const stdin = this.proc?.stdin;
+        if (this._closed || !stdin || this.flushing)
+            return;
+        this.flushing = true;
+        const next = () => {
+            if (this._closed) {
+                this.writeQueue = [];
+                this.flushing = false;
+                return;
+            }
+            const chunk = this.writeQueue.shift();
+            if (!chunk) {
+                this.flushing = false;
+                return;
+            }
+            try {
+                const ok = stdin.write(chunk, (err) => {
+                    if (err) {
+                        this.handleClose('epipe');
+                    }
+                });
+                if (!ok) {
+                    // 流满：等待 drain 再发下一条，队列有界（调用方同步节奏）。
+                    stdin.once('drain', next);
+                }
+                else {
+                    next();
+                }
+            }
+            catch {
+                this.handleClose('epipe');
+            }
+        };
+        next();
+    }
+    /**
+     * Gracefully stop the child process: SIGTERM → grace → SIGKILL.
+     * Idempotent — safe to call multiple times.
+     */
+    async close() {
+        if (this._closed)
+            return;
+        this._closed = true;
+        const proc = this.proc;
+        if (proc) {
+            try {
+                await this.stopper.stop(proc);
+            }
+            catch {
+                // Ignore stop errors — process may already be dead
+            }
+            if (proc.stdin && !proc.stdin.destroyed) {
+                proc.stdin.end();
+            }
+        }
+    }
+    handleClose(reason) {
+        if (this._closed)
+            return;
+        this._closed = true;
+        this.writeQueue = [];
+        // Remove the exit listener to avoid double-firing
+        if (this.proc) {
+            this.proc.removeAllListeners('exit');
+            this.proc.removeAllListeners('error');
+        }
+        const proc = this.proc;
+        this.proc = null;
+        if (proc) {
+            if (proc.stdin && !proc.stdin.destroyed) {
+                proc.stdin.end();
+            }
+            // 异常路径（EPIPE/超长行/进程 error）也要收掉子进程，避免孤儿进程
+            // 继续运行（如超长行场景子进程还在往 stdout 灌数据）。
+            void this.stopper.stop(proc).catch((err) => {
+                getLogger().warn(`[codex-transport] failed to stop process during close: ${err instanceof Error ? err.message : String(err)}`);
+            });
+        }
+        // 统一关闭出口：EPIPE/超长行/进程 error 都必须通知上层（connection-manager
+        // 靠 onClose 删除 slot、client 靠它 failPending），否则 slot 悬挂死连接。
+        this.events?.onClose(reason);
+        getLogger().info(`[codex-transport] closed: ${reason}`);
+    }
+}
+//# sourceMappingURL=transport.js.map

package/dist/runner/codex/factory.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Codex runner factory: selects the concrete runner based on `serviceMode`.
+ *
+ * `exec` (default) → CodexExecRunner (spawn-per-message `codex exec`).
+ * `app-server` → CodexAppServerRunner (persistent `codex app-server` JSON-RPC
+ * connection with approval support and sandbox enforcement).
+ */
+import type { AgentSessionReader } from '../types.js';
+import { CodexExecRunner } from './runner.js';
+import { CodexAppServerRunner } from './app-server/runner.js';
+import type { AskForApproval, SandboxMode } from './app-server/protocol-types.js';
+export interface CreateCodexRunnerOptions {
+    model?: string;
+    modelProvider?: string;
+    reasoningEffort?: string;
+    stopGraceMs?: number;
+    pidDir: string;
+    workspace: string;
+    sessionReader: AgentSessionReader;
+    serviceMode?: 'exec' | 'app-server';
+    sandbox?: SandboxMode;
+    approvalPolicy?: AskForApproval;
+    appServerBinary?: string;
+    appServerArgs?: string[];
+    appServerRequestTimeoutMs?: number;
+    appServerIdleTtlMs?: number;
+    appServerTurnIdleTimeoutMinutes?: number;
+}
+export declare function createCodexRunner(opts: CreateCodexRunnerOptions): CodexExecRunner | CodexAppServerRunner;

package/dist/runner/codex/factory.js

@@ -0,0 +1,39 @@
+/**
+ * Codex runner factory: selects the concrete runner based on `serviceMode`.
+ *
+ * `exec` (default) → CodexExecRunner (spawn-per-message `codex exec`).
+ * `app-server` → CodexAppServerRunner (persistent `codex app-server` JSON-RPC
+ * connection with approval support and sandbox enforcement).
+ */
+import { CodexExecRunner } from './runner.js';
+import { CodexAppServerRunner } from './app-server/runner.js';
+export function createCodexRunner(opts) {
+    if (opts.serviceMode === 'app-server') {
+        return new CodexAppServerRunner({
+            kind: 'codex',
+            sessionReader: opts.sessionReader,
+            binary: opts.appServerBinary ?? 'codex',
+            appServerArgs: opts.appServerArgs,
+            requestTimeoutMs: opts.appServerRequestTimeoutMs,
+            idleTtlMs: opts.appServerIdleTtlMs,
+            turnTimeoutMs: opts.appServerTurnIdleTimeoutMinutes != null
+                ? opts.appServerTurnIdleTimeoutMinutes * 60_000
+                : undefined,
+            model: opts.model,
+            modelProvider: opts.modelProvider,
+            reasoningEffort: opts.reasoningEffort,
+            sandbox: opts.sandbox,
+            approvalPolicy: opts.approvalPolicy,
+        });
+    }
+    return new CodexExecRunner({
+        model: opts.model,
+        modelProvider: opts.modelProvider,
+        reasoningEffort: opts.reasoningEffort,
+        stopGraceMs: opts.stopGraceMs,
+        pidDir: opts.pidDir,
+        workspace: opts.workspace,
+        sessionReader: opts.sessionReader,
+    });
+}
+//# sourceMappingURL=factory.js.map

package/dist/runner/codex/index.d.ts

@@ -1 +1,3 @@
 export { CodexExecRunner } from './runner.js';
+export { CodexAppServerRunner } from './app-server/runner.js';
+export { createCodexRunner } from './factory.js';

package/dist/runner/codex/index.js

@@ -1,2 +1,4 @@
 export { CodexExecRunner } from './runner.js';
+export { CodexAppServerRunner } from './app-server/runner.js';
+export { createCodexRunner } from './factory.js';
 //# sourceMappingURL=index.js.map

package/dist/runner/codex/runner.d.ts

@@ -52,6 +52,9 @@ export declare class CodexExecRunner extends SpawningRunner implements AgentRunn
     private readonly reasoningEffort?;
     constructor(opts: CodexExecRunnerOptions);
     getStatusInfo(): AgentStatusInfo;
+    /** exec 模式的 turn.completed.usage 是会话累计值，flow 字段必须 jsonl 优先
+     *  （review P3-7：桥侧统一走本接口，替代 agentKind 硬编码）。 */
+    getUsageAuthority(): 'jsonl';
     protected buildArgv(opts: SpawnOptions): string[];
     protected getStdio(): ('ignore' | 'pipe')[];
     protected setupStdin(proc: ChildProcess, message: string): void;

package/dist/runner/codex/runner.js

@@ -72,6 +72,11 @@ export class CodexExecRunner extends SpawningRunner {
             extras: { sandbox: 'danger-full-access' },
         };
     }
+    /** exec 模式的 turn.completed.usage 是会话累计值，flow 字段必须 jsonl 优先
+     *  （review P3-7：桥侧统一走本接口，替代 agentKind 硬编码）。 */
+    getUsageAuthority() {
+        return 'jsonl';
+    }
     buildArgv(opts) {
         return buildCodexExecArgs({
             cwd: opts.cwd,

package/dist/runner/common/usage.d.ts

@@ -23,6 +23,8 @@ interface NormalizedResultUsage {
     cacheReadTokens?: number;
     cacheCreationTokens?: number;
     totalTokens?: number;
+    /** Model context window limit (codex app-server `modelContextWindow` passthrough). */
+    contextLimit?: number;
     /** Reconstructed or agent-declared context length (see JSDoc above). */
     contextLength: number;
 }

package/dist/runner/common/usage.js

@@ -14,6 +14,7 @@ export function normalizeResultUsage(usage) {
     const cacheRead = usage.cache_read_tokens ?? usage.cache_read_input_tokens;
     const cacheCreation = usage.cache_creation_tokens ?? usage.cache_creation_input_tokens;
     const totalTokens = usage.total_tokens;
+    const contextLimit = usage.context_limit;
     // total_tokens (agent-declared total) takes priority; otherwise reconstruct
     // from the parts: input + cacheRead + cacheCreation + output.
     const contextLength = totalTokens ?? inputTokens + (cacheRead ?? 0) + (cacheCreation ?? 0) + outputTokens;
@@ -23,6 +24,7 @@ export function normalizeResultUsage(usage) {
         cacheReadTokens: cacheRead,
         cacheCreationTokens: cacheCreation,
         totalTokens,
+        contextLimit,
         contextLength,
     };
 }

package/dist/runner/index.d.ts

@@ -8,12 +8,12 @@
  * （共享工具由消费方直接 import `common/*` 具体模块，不走 barrel）
  */
 export { ClaudeRunner } from './claude/index.js';
-export { CodexExecRunner } from './codex/index.js';
+export { CodexExecRunner, CodexAppServerRunner, createCodexRunner } from './codex/index.js';
 export { OpencodeExecRunner } from './opencode/index.js';
 export { PiRunner } from './pi/index.js';
 export { KimiRunner } from './kimi/index.js';
 export { BashProcessRunner, type BashRunner } from './bash/index.js';
 export { AgentRegistry } from './registry.js';
-export type { ResultEvent, PlanEvent, FileChangeEvent, AgentEvent, Runner, AgentKind, AgentSession, AgentSessionContentEvent, AgentSessionUsage, SessionContent, AgentSessionReader, AgentRunner, } from './types.js';
+export type { ResultEvent, PlanEvent, FileChangeEvent, AgentEvent, Runner, RunnerLifetime, AgentKind, AgentSession, AgentSessionContentEvent, AgentSessionUsage, SessionContent, AgentSessionReader, AgentRunner, TurnStartedEvent, TurnDiffEvent, ApprovalView, ApprovalRequestedEvent, ApprovalResolvedEvent, } from './types.js';
 export { resolveAgentChoices } from './resolve-agent-choices.js';
 export { syncAgentChoices } from './sync-agent-choices.js';

package/dist/runner/index.js

@@ -9,7 +9,7 @@
  */
 // Re-export AgentRunner 实现（从各 agent 目录）
 export { ClaudeRunner } from './claude/index.js';
-export { CodexExecRunner } from './codex/index.js';
+export { CodexExecRunner, CodexAppServerRunner, createCodexRunner } from './codex/index.js';
 export { OpencodeExecRunner } from './opencode/index.js';
 export { PiRunner } from './pi/index.js';
 export { KimiRunner } from './kimi/index.js';

package/dist/runner/types.d.ts

@@ -21,6 +21,75 @@ interface SystemCompactEvent {
         preTokens: number;
     };
 }
+export interface ApprovalRequestedEvent {
+    type: 'approval_requested';
+    /** JSON-RPC id of the server request. Wire type is string | integer — keep raw. */
+    requestId: number | string;
+    kind: 'command' | 'file' | 'permissions';
+    threadId: string;
+    turnId: string;
+    itemId: string;
+    view: ApprovalView;
+    timestamp?: string;
+}
+export interface ApprovalResolvedEvent {
+    type: 'approval_resolved';
+    requestId: number | string;
+    outcome: 'resolved' | 'expired';
+    timestamp?: string;
+}
+/** Approval card content update (out-of-order item/started arrives late). */
+export interface ApprovalViewUpdatedEvent {
+    type: 'approval_view_updated';
+    requestId: number | string;
+    view: ApprovalView;
+    timestamp?: string;
+}
+/** Approval expired locally (bridge-side timeout) — card should show expired UI. */
+export interface ApprovalExpiredEvent {
+    type: 'approval_expired';
+    requestId: number | string;
+    timestamp?: string;
+}
+export interface ApprovalView {
+    requestId: number | string;
+    kind: 'command' | 'file' | 'permissions';
+    reason?: string;
+    threadShort: string;
+    turnShort: string;
+    workspace: string;
+    command?: string;
+    commandCwd?: string;
+    fileChanges?: Array<{
+        path: string;
+        kind: 'add' | 'update' | 'delete';
+        diff?: string;
+    }>;
+    network?: {
+        host: string;
+        protocol: string;
+    };
+    permissions?: {
+        networkEnabled?: boolean;
+        fileSystemRead?: string[];
+        fileSystemWrite?: string[];
+        items: Array<{
+            id: string;
+            label: string;
+            target: {
+                kind: 'network';
+            } | {
+                kind: 'fsRead' | 'fsWrite';
+                path: string;
+            };
+            selected: boolean;
+        }>;
+    };
+    availableDecisions: string[];
+    /** Raw payloads for structured decisions (e.g. acceptWithExecpolicyAmendment). */
+    decisionPayloads?: Record<string, unknown>;
+    pendingTotal: number;
+}
 interface ThinkingContent {
     type: 'thinking';
     thinking: string;
@@ -58,7 +127,7 @@ export interface UserEvent {
 }
 export interface ResultEvent {
     type: 'result';
-    subtype: 'success' | 'error';
+    subtype: 'success' | 'error' | 'interrupted';
     session_id: string;
     timestamp?: string;
     usage?: {
@@ -75,6 +144,9 @@ export interface ResultEvent {
         cache_creation_input_tokens?: number;
         /** Agent-declared total; when present the display uses max(total, sum of parts). */
         total_tokens?: number;
+        /** 当前模型 context window 上限（codex app-server tokenUsage.modelContextWindow
+         *  透传）。仅 app-server 提供；缺省时卡片只显示绝对量、不显示百分比。 */
+        context_limit?: number;
     };
     total_cost_usd?: number;
     errorMessage?: string;
@@ -99,7 +171,50 @@ export interface FileChangeEvent {
     operation: 'create' | 'edit' | 'delete' | 'read';
     timestamp?: string;
 }
-export type AgentEvent = SystemInitEvent | SystemCompactEvent | AssistantEvent | UserEvent | ResultEvent | PlanEvent | FileChangeEvent;
+export interface TurnStartedEvent {
+    type: 'turn_started';
+    threadId: string;
+    turnId: string;
+    operationKind: 'turn' | 'compaction';
+    timestamp?: string;
+}
+export interface TurnDiffEvent {
+    type: 'turn_diff';
+    /**
+     * Thread item id this snapshot belongs to (app-server item-scoped stream).
+     * Each content item (reasoning / agentMessage / commandExecution / plan /
+     * fileChange) is tracked independently, so interleaved items keep their
+     * real chronology and update their own block instead of a shared one.
+     */
+    itemId: string;
+    /** Full accumulated assistant text snapshot for this item (replaces previous). */
+    text?: string;
+    /** Full accumulated reasoning snapshot for this item (replaces previous). */
+    reasoning?: string;
+    /** Full accumulated tool output snapshot for this item (replaces previous). */
+    toolOutput?: string;
+    /** Full accumulated plan text snapshot for this item (replaces previous). */
+    plan?: string;
+    /** Current set of file changes for this item (replaces previous). */
+    fileChanges?: Array<{
+        path: string;
+        kind: 'add' | 'update' | 'delete';
+        diff?: string;
+    }>;
+    /**
+     * Authoritative completion snapshot (item/completed or turn/completed).
+     * The reducer finalizes the block in place: thinking/plan active=false,
+     * tool status ok, completedAt stamped. Never reorders blocks.
+     */
+    complete?: boolean;
+    /** Authoritative tool status at completion (commandExecution item). */
+    toolStatus?: 'ok' | 'error';
+    threadId: string;
+    turnId: string;
+    timestamp?: string;
+}
+export type RunnerLifetime = 'turn' | 'workspace';
+export type AgentEvent = SystemInitEvent | SystemCompactEvent | ApprovalRequestedEvent | ApprovalResolvedEvent | ApprovalViewUpdatedEvent | ApprovalExpiredEvent | AssistantEvent | UserEvent | ResultEvent | PlanEvent | FileChangeEvent | TurnStartedEvent | TurnDiffEvent;
 export interface SpawnOptions {
     cwd: string;
     sessionId?: string;
@@ -117,6 +232,8 @@ export interface SpawnOptions {
  */
 export interface Runner {
     readonly isRunning: boolean;
+    readonly lifetime?: RunnerLifetime;
+    dispose?(): Promise<void>;
     run(message: string, opts: SpawnOptions): AsyncGenerator<AgentEvent>;
     /**
      * Stop the running process. SIGTERM → grace → SIGKILL on the per-workspace
@@ -158,6 +275,8 @@ export interface AgentSessionUsage {
     contextLimit?: number;
     /** Claude auto-compact 次数（数 compact_boundary 事件）；codex/opencode 无此概念，留 undefined。 */
     compactCount?: number;
+    /** 压缩前上下文水位（codex compact 后从会话 jsonl 读取，仅会话以压缩收尾时有值）。 */
+    compactPreContextLength?: number;
     /** 从缓存读取的 token 数（节省的费用）。 */
     cacheReadTokens?: number;
     /** 新建缓存的 token 数。 */
@@ -236,6 +355,8 @@ export interface AgentRunner extends Runner {
     readonly sessionReader: AgentSessionReader;
     /** Return current status info for /status display. */
     getStatusInfo(): AgentStatusInfo;
+    /** Whether this runner provides live usage data (vs. file-based). */
+    getUsageAuthority?(): 'live' | 'jsonl';
 }
 /** Agent self-describing status info for /status display. */
 export interface AgentStatusInfo {

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

@@ -58,6 +58,18 @@ export function readCodexRollout(filePath) {
         // Run card's "累计" display. Codex emits this alongside last_token_usage.
         let lastTotalUsage;
         let previousTotals;
+        // Compaction 统计：codex 的 compact turn 在会话文件里写顶层 `compacted`
+        // 事件（含摘要），压缩前后的上下文水位由相邻 token_count 表达。压缩收尾的
+        // token_count 增量是 input/cached/output 全 0、只有 total_tokens 有值
+        // （窗口被摘要+replacement history 占据），现有 zero-filter 会跳过它，
+        // 因此这里必须单独捕获，不能复用 lastRawUsage。
+        // 单位口径（review P3-9）：前后两侧统一用 total_tokens —— 压缩前取最近一次
+        // 非零 token_count 的 total_tokens（input+output，即该 turn 在窗口内的全部
+        // token），压缩后取收尾事件的 total_tokens（压缩后窗口）。不得一边 input
+        // 一边 total，否则「压缩前 X → 压缩后 Y」两边单位不一致。
+        let compactCount = 0;
+        let compactPreContextLength;
+        let compactPostContextLength;
         for (const line of lines) {
             const trimmed = line.trim();
             if (!trimmed)
@@ -101,6 +113,27 @@ export function readCodexRollout(filePath) {
                             const ctxWindow = info?.model_context_window;
                             lastContextLimit = typeof ctxWindow === 'number' ? ctxWindow : undefined;
                         }
+                        // 压缩后的水位：压缩收尾 token_count 全 0（raw 不满足上面 zero-filter），
+                        // 但 total_tokens 表达真实窗口；之后若出现普通 turn（input>0），
+                        // 水位回归该 turn，post-compact 值失效。
+                        if (compactCount > 0 && raw) {
+                            if (raw.total_tokens &&
+                                !raw.input_tokens &&
+                                !raw.cached_input_tokens &&
+                                !raw.output_tokens) {
+                                compactPostContextLength = raw.total_tokens;
+                            }
+                            else if (raw.input_tokens > 0) {
+                                compactPostContextLength = undefined;
+                            }
+                        }
+                    }
+                }
+                else if (parsed.type === 'compacted') {
+                    // 顶层 compacted 事件：压缩次数 +1，压缩前水位取最近一次非零 token_count。
+                    compactCount++;
+                    if (lastRawUsage?.total_tokens !== undefined) {
+                        compactPreContextLength = lastRawUsage.total_tokens;
                     }
                 }
                 else if (parsed.type === 'response_item' && parsed.payload) {
@@ -170,6 +203,16 @@ export function readCodexRollout(filePath) {
                 usage.cumulativeCacheReadTokens = cumCached;
                 usage.cumulativeCacheCreationTokens = 0; // Codex 不报告 cache creation
             }
+            // 压缩统计：会话内出现过 compacted 事件就计数（供 /resume 与 Compact 卡
+            // 展示）；仅当会话以压缩收尾时（post-compact 水位存在），contextLength
+            // 覆盖为压缩后水位并暴露压缩前水位——后续还有普通 turn 时水位回归该 turn。
+            if (compactCount > 0) {
+                usage.compactCount = compactCount;
+                if (compactPostContextLength !== undefined) {
+                    usage.contextLength = compactPostContextLength;
+                    usage.compactPreContextLength = compactPreContextLength;
+                }
+            }
         }
         return {
             threadId: sessionId,