lark-remote 0.1.4 → 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/argv.d.ts

@@ -5,7 +5,7 @@
  * - `approval_policy="never"` eliminates the approval handshake (root cause ①).
  * - Prompt goes via stdin (`-` flag) to avoid argv escaping issues.
  * - `--skip-git-repo-check`: lark-remote's cwd may not be a git repo.
- * - User's `~/.codex/config.toml` and AGENTS.md/CLAUDE.md rules are preserved
+ * - User's `~/.codex/config.toml` and project rules are preserved
  *   (no `--ignore-user-config` / `--ignore-rules`).
  */
 interface BuildCodexExecArgsInput {

package/dist/runner/codex/argv.js

@@ -5,7 +5,7 @@
  * - `approval_policy="never"` eliminates the approval handshake (root cause ①).
  * - Prompt goes via stdin (`-` flag) to avoid argv escaping issues.
  * - `--skip-git-repo-check`: lark-remote's cwd may not be a git repo.
- * - User's `~/.codex/config.toml` and AGENTS.md/CLAUDE.md rules are preserved
+ * - User's `~/.codex/config.toml` and project rules are preserved
  *   (no `--ignore-user-config` / `--ignore-rules`).
  */
 /**

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/runner-utils.d.ts

@@ -11,6 +11,18 @@ export declare function pipeAllStdio(): ('ignore' | 'pipe')[];
  * rather than argv.
  */
 export declare function endStdinWithPrompt(proc: ChildProcess, message: string): void;
+/**
+ * Build a synthetic system.init event for pre-spawn failure paths.
+ *
+ * When the runner exits before spawning a process (validateBeforeRun failure,
+ * ENOENT spawn failure), no real system.init arrives from stdout. Without a
+ * synthetic init, the bridge's pre-init result guard (§9.22) and the run-state
+ * reducer's sessionId check would silently drop the error result, leaving the
+ * card showing "输出流已结束，但未收到 result 事件" instead of the actual
+ * error message. The synthetic init satisfies both guards so the real error
+ * result is processed normally.
+ */
+export declare function syntheticInitEvent(sessionId?: string): AgentEvent;
 /**
  * Build a standardized auth/error result event for yield.
  *

package/dist/runner/common/runner-utils.js

@@ -46,6 +46,27 @@ export function endStdinWithPrompt(proc, message) {
         }
     }
 }
+/**
+ * Build a synthetic system.init event for pre-spawn failure paths.
+ *
+ * When the runner exits before spawning a process (validateBeforeRun failure,
+ * ENOENT spawn failure), no real system.init arrives from stdout. Without a
+ * synthetic init, the bridge's pre-init result guard (§9.22) and the run-state
+ * reducer's sessionId check would silently drop the error result, leaving the
+ * card showing "输出流已结束，但未收到 result 事件" instead of the actual
+ * error message. The synthetic init satisfies both guards so the real error
+ * result is processed normally.
+ */
+export function syntheticInitEvent(sessionId = '') {
+    return {
+        type: 'system',
+        subtype: 'init',
+        session_id: sessionId,
+        cwd: '',
+        model: '',
+        timestamp: new Date().toISOString(),
+    };
+}
 /**
  * Build a standardized auth/error result event for yield.
  *

package/dist/runner/common/spawning-runner.js

@@ -6,7 +6,7 @@ import { getLogger } from '../../logger/index.js';
 import { ProcessStopper } from './process-stopper.js';
 import { SpawnHeartbeat } from './spawn-heartbeat.js';
 import { createJSONLStream } from './jsonl-stream.js';
-import { authErrorEvent } from './runner-utils.js';
+import { authErrorEvent, syntheticInitEvent } from './runner-utils.js';
 import { DEFAULT_STOP_GRACE_MS } from '../../config/index.js';
 /**
  * Magic-number constants (Clean Code P3-1, G25 Replace Magic Numbers with
@@ -255,6 +255,11 @@ export class SpawningRunner {
         // Pre-spawn validation hook (e.g. codex API key check)
         const validationError = this.validateBeforeRun(opts);
         if (validationError) {
+            // §9.22: yield synthetic init so the bridge's pre-init result guard and
+            // the run-state reducer's sessionId check don't silently drop the error
+            // result. Without init, the card would show a generic "输出流已结束"
+            // instead of the specific validation error message.
+            yield syntheticInitEvent(opts.sessionId);
             yield validationError;
             return;
         }
@@ -287,6 +292,9 @@ export class SpawningRunner {
             // so the user is not misdiagnosed into reinstalling the binary.
             const baseMsg = `${this.binary} 命令不可用（未找到或不可执行），请检查是否已安装或在 PATH 中`;
             const msg = spawnErr ? `${baseMsg}：${spawnErr.message}` : baseMsg;
+            // §9.22: yield synthetic init before the error result so bridge/run-state
+            // guards don't silently drop it (same rationale as validateBeforeRun).
+            yield syntheticInitEvent(opts.sessionId);
             yield authErrorEvent(msg);
             return;
         }

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';