lark-remote 0.1.13 → 0.2.1

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

@@ -2,20 +2,20 @@ 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';
+import type { 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 刷屏，历史实例被闭包永久持有，内存无界增长。
+ * 背景：各 agent runner 的 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。
+ * 现在：进程级监听只注册一次，内部 Set 管理注册实例；registerExitHandlers()
+ * 只把实例加入集合（幂等），桥接层在淘汰槽位时调 unregisterExitHandlers()
+ * 移除实例，让 runner 可被 GC。SIGINT/SIGTERM 语义保持原样：cleanup 全部
+ * 已注册实例后 exit 130/143。
  */
 /**
  * Exit-cleanup contract: anything that spawns a child process group and wants
@@ -30,47 +30,22 @@ 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.
+ * Abstract base class encapsulating the spawn lifecycle shared by agent
+ * runners: spawn lead-in (pid-undefined check, pid file write, heartbeat,
+ * stderr tail accumulation), user-initiated stop, orphan kill with pid
+ * identity verification, and process-exit cleanup registration.
  *
- * `translate()` returns `AgentEvent | AgentEvent[] | null` (single event,
- * multiple events, or filtered-out). `isTerminal()` / `finish()` / `getTerminalError()`
- * / `hasAgentTerminalError()` are folded into the unified result event at the
- * end of `run()`.
+ * The sole production subclass is ClaudeSession (src/runner/claude/session.ts),
+ * a long-lived interactive session that overrides `run()` with its own
+ * per-turn consumption loop and reads `spawnStderr` / `stoppedByUser` /
+ * `commandNotFoundSeen` to build its terminal result events.
  *
- * `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/Pi runners. Subclasses override:
- *   - buildArgv(opts)              → agent-specific CLI flags (required)
- *   - createTranslator(opts)       → stateful translator (pi)
- *     OR translate(raw, ctx)       → stateless passthrough (claude)
+ * Subclasses override:
+ *   - buildArgv(opts) → agent-specific CLI flags (required)
  *
  * Optional hooks (with sensible defaults):
- *   - getStdio()                   → stdio config (default ['ignore','pipe','pipe'])
- *   - createStreamReader(stdout)   → JSONL or readline parser (default createJSONLStream)
- *   - awaitSpawnError(proc)        → wait for spawn error (default once('error'))
- *
- * 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 the agent subclass anchors and the bridge's
- * `runAgentStreamToEnd` error handling (which accepts both thrown errors and
- * yielded error-result events).
+ *   - getStdio()                 → stdio config (default ['ignore','pipe','pipe'])
+ *   - createStreamReader(stdout) → JSONL or readline parser (default createJSONLStream)
  */
 export declare abstract class SpawningRunner {
     protected currentProcess: ChildProcess | null;
@@ -85,26 +60,23 @@ export declare abstract class SpawningRunner {
      * 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.
+     * 'claude-runner') so operators can grep agent-specific logs.
      */
     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.
+     * subclasses reset it at the start of a turn and read it when building
+     * the terminal result event (interrupted vs error precedence).
      */
     protected stoppedByUser: boolean;
+    /**
+     * §4.4 win32 command-not-found 嗅探嫌疑标记：stderr 命中特征行时置位，
+     * 但**不**立即杀进程——agent 正常输出可能引用该错误文本（调试 Windows
+     * 报错场景），见行即杀会误杀 run。定性走双条件：子类收尾时「标记在 +
+     * 非零退出」才判 command-not-found；真挂起由既有 grace/超时兜底。
+     */
+    protected commandNotFoundSeen: boolean;
     constructor(opts: {
         pidDir?: string;
         workspace: string;
@@ -127,28 +99,23 @@ export declare abstract class SpawningRunner {
     });
     get isRunning(): boolean;
     /**
-     * stdio config for spawn. Default: stdin ignored (claude/kimi/pi pass the
-     * prompt via argv).
+     * stdio config for spawn. Default: stdin ignored (agents pass the prompt
+     * via argv).
      */
     protected getStdio(): ('ignore' | 'pipe')[];
     /**
      * Create an async iterator over the child's stdout. Default: createJSONLStream
-     * (claude/kimi/pi) with P1-4 backpressure enabled (pauseThreshold=100).
+     * with P1-4 backpressure enabled (pauseThreshold=100).
      */
     protected createStreamReader(stdout: Readable): AsyncGenerator<unknown>;
-    /**
-     * Create a stateful translator for this run. Default: null (uses the
-     * stateless passthrough). pi overrides to return its translator instance.
-     */
-    protected createTranslator(_opts: SpawnOptions): RunnerTranslator | 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.
+     * emitting it. Without the race, the spawn lead-in 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>;
     /**
@@ -158,30 +125,14 @@ export declare abstract class SpawningRunner {
      *
      * Throws a `SpawnChildError` (carrying the user-facing spawn failure
      * message) when the process fails to spawn (binary missing / pid undefined).
-     * On success returns the spawned child plus the accumulated stderr tail.
-     *
-     * Shared by the base `run()` (yields an authErrorEvent on failure) and
-     * ClaudeSession's `doStartProcess` (returns the error message), which would
-     * otherwise duplicate ~60 lines of spawn lead-in with two copies of the
-     * STDERR_TAIL_BYTES cap.
+     * On success returns the spawned child.
      */
     protected spawnChild(opts: SpawnOptions): Promise<ChildProcess>;
-    /**
-     * 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.
+     * flag verbatim so all subclasses inherit identical stop semantics.
      */
     stop(opts?: {
         immediate?: boolean;
@@ -224,51 +175,10 @@ export declare abstract class SpawningRunner {
     /**
      * 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
+     * registered runner; previously duplicated verbatim in the 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 {};