lark-remote 0.1.0

package/dist/runner/common/spawning-runner.d.ts

@@ -0,0 +1,321 @@
+import { type ChildProcess } from 'node:child_process';
+import type { Readable } from 'node:stream';
+import { ProcessStopper } from './process-stopper.js';
+import { SpawnHeartbeat } from './spawn-heartbeat.js';
+import type { AgentEvent, SpawnOptions } from '../types.js';
+/**
+ * 进程级退出监听单例分发（P1-1 修复，2026-08-02）。
+ *
+ * 背景：5 个 runner（claude/codex/opencode/pi/kimi）的 registerExitHandlers 曾是
+ * 同构复制，每个实例 process.on('exit'|'SIGINT'|'SIGTERM') 注册 3 个永不移除的
+ * 闭包（捕获整个 runner 实例 + sessionReader + pidFilePath）。Bridge 每次 run
+ * 结束淘汰 (cwd, kind) 槽位、下次 run cache miss 新建实例再注册 → 约第 4 个 run
+ * 起 MaxListenersExceededWarning 刷屏，历史实例被闭包永久持有，内存无界增长。
+ *
+ * 现在：进程级监听只注册一次，内部 Set<SpawningRunner> 管理注册实例；
+ * registerExitHandlers() 只把实例加入集合（幂等），桥接层在淘汰槽位时调
+ * unregisterExitHandlers() 移除实例，让 runner 可被 GC。SIGINT/SIGTERM 语义
+ * 保持原样：cleanup 全部已注册实例后 exit 130/143。
+ */
+/**
+ * Exit-cleanup contract: anything that spawns a child process group and wants
+ * process-level cleanup (agent runners via SpawningRunner, and BashProcessRunner
+ * for `!` commands, P1-22) registers with the singleton dispatcher.
+ */
+interface ExitCleanupHandler {
+    cleanupOnExit(): void;
+}
+/** Register a process-exit cleanup handler (installs listeners at most once). */
+export declare function registerExitCleanup(handler: ExitCleanupHandler): void;
+/** Remove a handler so it can be GC'd (agent slots / finished bash runs). */
+export declare function unregisterExitCleanup(handler: ExitCleanupHandler): void;
+/**
+ * Stateful translator contract for runners that need per-run translation state
+ * (codex/opencode/pi/kimi). Subclasses return an instance from
+ * `createTranslator(opts)`; the base `run()` loop calls `translate(raw)` per
+ * event, then folds terminal state into `buildResultEvent(...)` at the end.
+ *
+ * `translate()` returns `AgentEvent | AgentEvent[] | null` (single event,
+ * multiple events, or filtered-out). `isTerminal()` / `finish()` / `getTerminalError()`
+ * / `hasAgentTerminalError()` are folded into the unified result event via
+ * `resolveTranslatorError()`.
+ *
+ * `getSessionId()` / `getLastUsage()` are optional because ClaudeRunner uses
+ * the stateless `translate()` hook (no translator object) and reads neither.
+ */
+export interface RunnerTranslator {
+    translate(raw: unknown): AgentEvent | AgentEvent[] | null;
+    isTerminal(): boolean;
+    finish(reason: 'failed' | 'interrupted' | 'timeout'): void;
+    getTerminalError(): string | undefined;
+    hasAgentTerminalError(): boolean;
+    getSessionId?(): string | undefined;
+    getLastUsage?(): Record<string, unknown> | undefined;
+}
+/**
+ * Abstract base class for runners that spawn a child process per turn.
+ *
+ * Encapsulates the spawn + completion + cleanup orchestration shared by
+ * Claude/Codex/OpenCode/Pi/Kimi runners. Subclasses override:
+ *   - buildArgv(opts)              → agent-specific CLI flags (required)
+ *   - createTranslator(opts)       → stateful translator (codex/opencode/pi/kimi)
+ *     OR translate(raw, ctx)       → stateless passthrough (claude)
+ *
+ * Optional hooks (with sensible defaults):
+ *   - getStdio()                   → stdio config (default ['ignore','pipe','pipe'])
+ *   - getSpawnEnv(opts)            → env vars (default process.env)
+ *   - setupStdin(proc, message)    → write prompt to stdin (default no-op)
+ *   - createStreamReader(stdout)   → JSONL or readline parser (default createJSONLStream)
+ *   - validateBeforeRun(opts)      → pre-spawn validation (default no-op)
+ *   - awaitCompletion(proc, p)     → wait for exit (default return p; kimi adds 5s race)
+ *   - awaitSpawnError(proc)        → wait for spawn error (default once('error'); kimi adds 5s race)
+ *   - resolveTranslatorError(t, c) → translatorError precedence (default honors agent errors)
+ *
+ * The base class always emits a unified result event at the end of `run()`
+ * via `buildResultEvent(...)` — never throws on non-zero exit. This matches
+ * the contract pinned by codex/opencode/pi/kimi subclass anchors and the
+ * bridge's `runAgentStreamToEnd` error handling (which accepts both thrown
+ * errors and yielded error-result events).
+ */
+export declare abstract class SpawningRunner {
+    protected currentProcess: ChildProcess | null;
+    protected readonly pidFilePath: string;
+    protected readonly stopper: ProcessStopper;
+    protected readonly spawnHeartbeat: SpawnHeartbeat;
+    protected binary: string;
+    protected stopGraceMs: number;
+    /**
+     * Log prefix used in all operational log lines emitted by this runner
+     * (spawn, pid file, non-zero exit, stderr, killOrphan, stop cleanup) and
+     * as the SpawnHeartbeat label. Subclasses pass their own tag (e.g.
+     * 'claude-runner') so operators can grep agent-specific logs; the default
+     * 'spawning-runner' keeps the base-class anchor tests' neutral identity.
+     */
+    protected readonly logTag: string;
+    /**
+     * The `message` argument from the most recent `run(message, opts)` call.
+     * Set in `run()` before `buildArgv(opts)` is invoked so subclasses can
+     * embed the message in their agent-specific argv (e.g. claude's `-p
+     * <message>`). This avoids changing the `buildArgv(opts)` signature,
+     * which would break existing anchor subclasses.
+     */
+    protected currentMessage: string;
+    /**
+     * Whether the current run was interrupted by user-initiated stop().
+     * Set to true by stop() when a running process is being terminated;
+     * reset to false at the top of run(). `resolveTranslatorError()` and
+     * `buildResultEvent()` read this to decide result event subtype
+     * (error vs success) and the error message precedence.
+     */
+    protected stoppedByUser: boolean;
+    constructor(opts: {
+        binary?: string;
+        pidDir?: string;
+        workspace: string;
+        stopGraceMs?: number;
+        spawnHeartbeatMs?: number;
+        /**
+         * Filename prefix for the pid file. Defaults to 'spawning'. Each
+         * subclass should pass its own prefix (e.g. 'claude', 'codex') so
+         * multiple runners sharing the same pidDir do not clobber each
+         * other's pid files.
+         */
+        pidFilePrefix?: string;
+        /**
+         * Log prefix for operational log lines and the SpawnHeartbeat label.
+         * Defaults to 'spawning-runner'. Subclasses pass their own tag (e.g.
+         * 'claude-runner') so operators can grep agent-specific logs and the
+         * spawn-stage-stalled WARN identifies the right agent.
+         */
+        logTag?: string;
+    });
+    get isRunning(): boolean;
+    /**
+     * stdio config for spawn. Default: stdin ignored (claude/kimi/pi pass the
+     * prompt via argv). codex/opencode override to ['pipe','pipe','pipe'] so
+     * they can write the prompt to stdin via `setupStdin`.
+     */
+    protected getStdio(): ('ignore' | 'pipe')[];
+    /**
+     * Env vars for spawn. Default: process.env. opencode overrides to sync
+     * PWD=opts.cwd (opencode's directory detection reads PWD, not cwd).
+     */
+    protected getSpawnEnv(_opts: SpawnOptions): NodeJS.ProcessEnv;
+    /**
+     * Write the prompt to the child's stdin (called after spawn succeeds).
+     * Default: no-op. codex/opencode override to `proc.stdin.end(message)`.
+     */
+    protected setupStdin(_proc: ChildProcess, _message: string): void;
+    /**
+     * Create an async iterator over the child's stdout. Default: createJSONLStream
+     * (claude/kimi/pi) with P1-4 backpressure enabled (pauseThreshold=100).
+     * Subclasses that need to silently skip non-JSON lines should override
+     * `handleBadStreamLine` instead of this method.
+     */
+    protected createStreamReader(stdout: Readable): AsyncGenerator<unknown>;
+    /**
+     * Hook called when createJSONLStream encounters a line that cannot be parsed
+     * as JSON. Default: log a warning via getLogger().warn (same format as
+     * jsonl-stream's built-in warning). Subclasses override to change behavior
+     * (e.g. codex/opencode silently skip by providing an empty override).
+     */
+    protected handleBadStreamLine(line: string): void;
+    /**
+     * Create a stateful translator for this run. Default: null (uses the
+     * stateless `translate(raw, ctx)` hook). codex/opencode/pi/kimi override to
+     * return their translator instance.
+     */
+    protected createTranslator(_opts: SpawnOptions): RunnerTranslator | null;
+    /**
+     * Pre-spawn validation. Return an AgentEvent to yield it and abort run()
+     * (e.g. codex's API key check yields an error result and returns).
+     * Default: null (no validation).
+     */
+    protected validateBeforeRun(_opts: SpawnOptions): AgentEvent | null;
+    /**
+     * Await process completion. Default: return the completion promise as-is.
+     * kimi overrides to add a 5s timeout race + SIGKILL fallback (kimi
+     * sometimes hangs after stdout closes).
+     */
+    protected awaitCompletion(_proc: ChildProcess, completion: Promise<{
+        code: number | null;
+        signal: NodeJS.Signals | null;
+    }>): Promise<{
+        code: number | null;
+        signal: NodeJS.Signals | null;
+    }>;
+    /**
+     * Await the spawn 'error' event when proc.pid === undefined. Races a
+     * finite timeout (review P2-11) against the 'error' event: Node guarantees
+     * 'error' for ENOENT/EACCES, but some binaries fail silently without ever
+     * emitting it (kimi's CLI is documented to do so). Without the race, run()
+     * hangs forever → the workspace serial queue never settles → permanent
+     * deadlock, and /stop can't recover (ProcessStopper returns early when
+     * pid === undefined). The timeout keeps the deadlock bounded.
+     */
+    protected awaitSpawnError(proc: ChildProcess): Promise<Error | undefined>;
+    /**
+     * Resolve the translatorError to pass to buildResultEvent. Default
+     * precedence (most-specific first):
+     *   - agent-reported terminal error (translator.hasAgentTerminalError()):
+     *     always wins — the agent error is the root cause, signal/code is a
+     *     consequence. E.g. codex `turn.failed` then non-zero exit.
+     *   - stream-ended-early symptom (translator.getTerminalError() set by
+     *     finish('failed')): ONLY surfaces when there is no external cause
+     *     (signal / non-zero code / user stop). The signal/code is the root
+     *     cause; the early stream-end is a symptom.
+     *   - otherwise: undefined (signal/code/stoppedByUser drives the message).
+     *
+     * Subclasses can override for custom precedence but the default matches
+     * the contract pinned by codex/opencode subclass anchors.
+     */
+    protected resolveTranslatorError(translator: RunnerTranslator | null, ctx: {
+        code: number | null;
+        signal: NodeJS.Signals | null;
+    }): string | undefined;
+    /**
+     * Spawn the agent binary with argv built by buildArgv(opts), iterate its
+     * stdout stream, and yield translated events. Always emits a unified
+     * result event at the end via `buildResultEvent(...)` — never throws on
+     * non-zero exit (the bridge accepts both thrown errors and yielded
+     * error-result events, and the latter carries richer diagnostic info).
+     *
+     * Spawn failures (binary missing, pid undefined) yield an `authErrorEvent`
+     * instead of throwing, so the user sees a friendly error card.
+     */
+    run(message: string, opts: SpawnOptions): AsyncGenerator<AgentEvent>;
+    /**
+     * Stop the current process if one is running. Delegates the actual
+     * SIGTERM → grace → SIGKILL sequence to `this.stopper.stop(proc, opts)`
+     * (see `src/runner/common/process-stopper.ts`), forwarding the `immediate`
+     * flag verbatim so all 5 subclasses inherit identical stop semantics.
+     */
+    stop(opts?: {
+        immediate?: boolean;
+    }): Promise<void>;
+    killOrphan(): void;
+    /**
+     * P1-10: verify the process behind a stale pid file is actually ours before
+     * sending any signal. `ps -o command=` (not `comm=`) is used because agent
+     * binaries may be bash-wrapped scripts whose comm is the interpreter name
+     * (`/bin/bash`); the full command line contains the binary path/basename.
+     *
+     * Returns:
+     *   'match'    — ps succeeded and the command line contains this.binary
+     *                (absolute path) or its basename (PATH lookup).
+     *   'mismatch' — ps succeeded but the command line is clearly a different
+     *                process (pid was recycled to an unrelated process).
+     *   'unknown'  — ps failed / process gone / output unreadable: cannot tell.
+     */
+    private matchPidToBinary;
+    /**
+     * Register this runner with the process-level exit dispatcher (singleton).
+     * Process listeners are installed at most once; subsequent calls only add
+     * the instance to the internal Set (idempotent — no listener accumulation).
+     * Bridge evicts the (cwd, kind) slot after each run; call
+     * `unregisterExitHandlers()` there so the instance can be GC'd.
+     */
+    registerExitHandlers(): void;
+    /**
+     * Remove this runner from the process-level exit dispatcher. Called when
+     * the bridge evicts the runner cache slot (finalizeRun / interruptCurrentRun
+     * / clearRunners) so the instance is no longer retained by the dispatcher.
+     */
+    unregisterExitHandlers(): void;
+    /**
+     * Current number of runners registered with the process-level exit
+     * dispatcher. Diagnostics / test-support introspection (P1-1 anchor asserts
+     * the count returns to baseline after bridge eviction).
+     */
+    static getRegisteredExitHandlerCount(): number;
+    /**
+     * Shared process-exit cleanup: SIGTERM the still-running child process and
+     * remove the pid file. Called by the singleton dispatcher for every
+     * registered runner; previously duplicated verbatim in all 5 runner
+     * subclasses.
+     */
+    cleanupOnExit(): void;
+    /**
+     * Build a unified result event from process exit state. Centralizes the
+     * result-event semantics specified in Candidate 2:
+     *   - stoppedByUser → error ("interrupted by user")
+     *   - translatorError set → error (translator-supplied message, e.g. codex
+     *     `turn.failed` or "stream ended before a terminal event")
+     *   - code !== 0 && code !== null → error (exit code + stderr tail)
+     *   - signal !== null → error (killed by signal)
+     *   - otherwise → success (with optional usage)
+     *
+     * Error message precedence (most-specific first):
+     *   - stoppedByUser:  "{binary} interrupted by user"
+     *   - translatorError: verbatim translator-supplied message
+     *   - signal:         "{binary} killed by signal {signal}{stderr tail}"
+     *   - non-zero code:  "{binary} exited code={code}{stderr tail}"
+     *
+     * @param opts.code            - Process exit code (null if killed by signal)
+     * @param opts.signal          - Process signal code (null if exited normally)
+     * @param opts.stderr          - Accumulated stderr (tail included in code/signal errors)
+     * @param opts.sessionId       - Session ID to include in the result event
+     * @param opts.usage           - Token usage to include on success
+     * @param opts.translatorError - Agent-specific terminal error message (e.g.
+     *                                codex turn.failed, or "stream ended early")
+     * @returns AgentEvent with type='result'
+     */
+    protected buildResultEvent(opts: {
+        code: number | null;
+        signal: NodeJS.Signals | null;
+        stderr?: string;
+        sessionId?: string;
+        usage?: Record<string, unknown>;
+        translatorError?: string;
+    }): AgentEvent;
+    protected abstract buildArgv(opts: SpawnOptions): string[];
+    /**
+     * Stateless passthrough translator hook. Used by ClaudeRunner
+     * which does not need per-run translation state. Subclasses that return
+     * a translator from `createTranslator(opts)` leave this as the default
+     * no-op — the base `run()` loop only calls `translate()` when
+     * `createTranslator()` returns null.
+     */
+    protected translate(_rawEvent: unknown, _ctx: unknown): AgentEvent | AgentEvent[] | null;
+}
+export {};