lark-remote 0.1.6 → 0.1.7

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

@@ -2,6 +2,7 @@ import { spawn, execFileSync } from 'node:child_process';
 import path from 'node:path';
 import os from 'node:os';
 import fs from 'node:fs';
+import { silentlyUnlink } from '../../common/fs.js';
 import { getLogger } from '../../logger/index.js';
 import { ProcessStopper } from './process-stopper.js';
 import { SpawnHeartbeat } from './spawn-heartbeat.js';
@@ -17,6 +18,9 @@ import { DEFAULT_STOP_GRACE_MS } from '../../config/index.js';
 const STDERR_TAIL_BYTES = 4000;
 /** Max bytes of stderr surfaced in the non-zero-exit log line. */
 const STDERR_LOG_TAIL = 500;
+/** Error thrown by `spawnChild` when the child process fails to spawn. */
+class SpawnChildError extends Error {
+}
 /**
  * Timeout (ms) for awaiting the spawn 'error' event when proc.pid === undefined
  * (review P2-11). Node guarantees 'error' for ENOENT/EACCES, but some binaries
@@ -58,26 +62,21 @@ export function unregisterExitCleanup(handler) {
  * 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:
+ * Claude/Pi runners. Subclasses override:
  *   - buildArgv(opts)              → agent-specific CLI flags (required)
- *   - createTranslator(opts)       → stateful translator (codex/opencode/pi/kimi)
+ *   - createTranslator(opts)       → stateful translator (pi)
  *     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)
+ *   - 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 codex/opencode/pi/kimi subclass anchors and the
- * bridge's `runAgentStreamToEnd` error handling (which accepts both thrown
- * errors and yielded error-result events).
+ * 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).
  */
 export class SpawningRunner {
     currentProcess = null;
@@ -86,6 +85,8 @@ export class SpawningRunner {
     spawnHeartbeat;
     binary;
     stopGraceMs;
+    /** Accumulated stderr tail for the current run (filled by spawnChild). */
+    spawnStderr = '';
     /**
      * Log prefix used in all operational log lines emitted by this runner
      * (spawn, pid file, non-zero exit, stderr, killOrphan, stop cleanup) and
@@ -130,72 +131,31 @@ export class SpawningRunner {
     // --- Hooks (subclasses override as needed) ---
     /**
      * 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`.
+     * prompt via argv).
      */
     getStdio() {
         return ['ignore', 'pipe', 'pipe'];
     }
-    /**
-     * Env vars for spawn. Default: process.env. opencode overrides to sync
-     * PWD=opts.cwd (opencode's directory detection reads PWD, not cwd).
-     */
-    getSpawnEnv(_opts) {
-        return process.env;
-    }
-    /**
-     * Write the prompt to the child's stdin (called after spawn succeeds).
-     * Default: no-op. codex/opencode override to `proc.stdin.end(message)`.
-     */
-    setupStdin(_proc, _message) {
-        // no-op by default
-    }
     /**
      * 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.
      */
     createStreamReader(stdout) {
         return createJSONLStream(stdout, {
-            onParseError: (line) => this.handleBadStreamLine(line),
+            onParseError: (line) => {
+                getLogger().warn(`[jsonl-stream] failed to parse JSONL: ${line.slice(0, 100)}`);
+            },
             pauseThreshold: 100,
             resumeThreshold: 50,
         });
     }
-    /**
-     * 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).
-     */
-    handleBadStreamLine(line) {
-        getLogger().warn(`[jsonl-stream] failed to parse JSONL: ${line.slice(0, 100)}`);
-    }
     /**
      * 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.
+     * stateless passthrough). pi overrides to return its translator instance.
      */
     createTranslator(_opts) {
         return 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).
-     */
-    validateBeforeRun(_opts) {
-        return 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).
-     */
-    awaitCompletion(_proc, completion) {
-        return completion;
-    }
     /**
      * Await the spawn 'error' event when proc.pid === undefined. Races a
      * finite timeout (review P2-11) against the 'error' event: Node guarantees
@@ -214,60 +174,24 @@ export class SpawningRunner {
         ]);
     }
     /**
-     * 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).
+     * Spawn the agent binary with the subclass's argv and run the shared spawn
+     * lead-in: pid-undefined check, pid-file write, heartbeat start, and stderr
+     * accumulation (tail-capped).
      *
-     * Subclasses can override for custom precedence but the default matches
-     * the contract pinned by codex/opencode subclass anchors.
-     */
-    resolveTranslatorError(translator, ctx) {
-        if (!translator)
-            return undefined;
-        const agentError = translator.hasAgentTerminalError();
-        const hasExternalCause = this.stoppedByUser || ctx.signal !== null || (ctx.code !== null && ctx.code !== 0);
-        return agentError || !hasExternalCause ? translator.getTerminalError() : 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).
+     * 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.
      *
-     * Spawn failures (binary missing, pid undefined) yield an `authErrorEvent`
-     * instead of throwing, so the user sees a friendly error card.
+     * 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.
      */
-    async *run(message, opts) {
-        if (this.isRunning) {
-            getLogger().warn(`[${this.logTag}] run() called while already running, refusing`);
-            throw new Error(`${this.binary} process already running`);
-        }
-        this.stoppedByUser = false;
-        this.currentMessage = message;
-        // 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;
-        }
-        const args = this.buildArgv(opts);
-        const proc = spawn(this.binary, args, {
+    async spawnChild(opts) {
+        const proc = spawn(this.binary, this.buildArgv(opts), {
             cwd: opts.cwd,
             stdio: this.getStdio(),
-            env: this.getSpawnEnv(opts),
+            env: process.env,
             // Spawn in a new process group so we can kill the entire group
             // when stopping. This ensures child processes (shell wrappers,
             // sub-processes) are also terminated.
@@ -292,10 +216,56 @@ 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;
+            throw new SpawnChildError(msg);
+        }
+        const pidDir = path.dirname(this.pidFilePath);
+        fs.mkdirSync(pidDir, { recursive: true });
+        fs.writeFileSync(this.pidFilePath, String(proc.pid), 'utf-8');
+        getLogger().info(`[${this.logTag}] wrote pid file ${this.pidFilePath}=${proc.pid}`);
+        this.spawnHeartbeat.start({ pid: proc.pid, binary: this.binary, cwd: opts.cwd });
+        proc.stdout?.once('data', () => {
+            this.spawnHeartbeat.notifyStdout();
+        });
+        this.spawnStderr = '';
+        proc.stderr?.on('data', (chunk) => {
+            const text = chunk.toString('utf-8').trim();
+            if (text) {
+                this.spawnStderr = (this.spawnStderr + '\n' + text).trim().slice(-STDERR_TAIL_BYTES);
+                // P2-16: most agent CLIs emit progress/warnings/deprecation notices on
+                // stderr, not real errors. Logging each chunk at error level drowns out
+                // genuine errors. Downgrade to warn — the accumulated stderr is already
+                // surfaced at error level in the non-zero-exit result path.
+                getLogger().warn(`[${this.logTag} stderr] ${text}`);
+            }
+        });
+        return proc;
+    }
+    /**
+     * 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.
+     */
+    async *run(message, opts) {
+        if (this.isRunning) {
+            getLogger().warn(`[${this.logTag}] run() called while already running, refusing`);
+            throw new Error(`${this.binary} process already running`);
+        }
+        this.stoppedByUser = false;
+        this.currentMessage = message;
+        let proc;
+        try {
+            proc = await this.spawnChild(opts);
+        }
+        catch (err) {
             // §9.22: yield synthetic init before the error result so bridge/run-state
-            // guards don't silently drop it (same rationale as validateBeforeRun).
+            // guards don't silently drop it.
             yield syntheticInitEvent(opts.sessionId);
-            yield authErrorEvent(msg);
+            yield authErrorEvent(err.message);
             return;
         }
         const completion = new Promise((resolve) => {
@@ -317,29 +287,7 @@ export class SpawningRunner {
                 resolve({ code, signal });
             });
         });
-        const pidDir = path.dirname(this.pidFilePath);
-        fs.mkdirSync(pidDir, { recursive: true });
-        fs.writeFileSync(this.pidFilePath, String(proc.pid), 'utf-8');
-        getLogger().info(`[${this.logTag}] wrote pid file ${this.pidFilePath}=${proc.pid}`);
-        this.spawnHeartbeat.start({ pid: proc.pid, binary: this.binary, cwd: opts.cwd });
-        proc.stdout?.once('data', () => {
-            this.spawnHeartbeat.notifyStdout();
-        });
-        let stderr = '';
-        proc.stderr?.on('data', (chunk) => {
-            const text = chunk.toString('utf-8').trim();
-            if (text) {
-                stderr = (stderr + '\n' + text).trim().slice(-STDERR_TAIL_BYTES);
-                // P2-16: most agent CLIs emit progress/warnings/deprecation notices on
-                // stderr, not real errors. Logging each chunk at error level drowns out
-                // genuine errors. Downgrade to warn — the accumulated stderr is already
-                // surfaced at error level in the non-zero-exit result path.
-                getLogger().warn(`[${this.logTag} stderr] ${text}`);
-            }
-        });
-        // Hook: write prompt to stdin (codex/opencode)
-        this.setupStdin(proc, message);
-        // Create translator (per-run state) — null for stateless passthrough (claude)
+        // Create translator (per-run state) — null for stateless passthrough
         const translator = this.createTranslator(opts);
         // Create stream reader (jsonl or readline)
         const stream = this.createStreamReader(proc.stdout);
@@ -380,7 +328,7 @@ export class SpawningRunner {
             catch (error) {
                 getLogger().error(`[${this.logTag}] stream error: ${error}`);
             }
-            const { code, signal } = await this.awaitCompletion(proc, completion);
+            const { code, signal } = await completion;
             // If the stream ended before a terminal event, let the translator
             // record its terminal state (e.g. codex `finish('failed')` stashes
             // "stream ended before a terminal event"). The runner folds this
@@ -389,18 +337,27 @@ export class SpawningRunner {
                 const reason = this.stoppedByUser ? 'interrupted' : 'failed';
                 translator.finish(reason);
             }
-            const translatorError = this.resolveTranslatorError(translator, { code, signal });
+            // Resolve translatorError precedence (most-specific first):
+            //   - agent-reported terminal error always wins
+            //   - stream-ended-early symptom only surfaces with no external cause
+            let translatorError;
+            if (translator) {
+                const agentError = translator.hasAgentTerminalError();
+                const hasExternalCause = this.stoppedByUser || signal !== null || (code !== null && code !== 0);
+                translatorError =
+                    agentError || !hasExternalCause ? translator.getTerminalError() : undefined;
+            }
             const nonUserError = !this.stoppedByUser && ((code !== null && code !== 0) || signal !== null);
             yield this.buildResultEvent({
                 code,
                 signal,
-                stderr,
+                stderr: this.spawnStderr,
                 sessionId: translator?.getSessionId?.() ?? '',
                 usage: translator?.getLastUsage?.(),
                 translatorError,
             });
             if (nonUserError) {
-                getLogger().error(`[${this.logTag}] non-zero exit code=${code} signal=${signal} stderr=${stderr.slice(-STDERR_LOG_TAIL)}`);
+                getLogger().error(`[${this.logTag}] non-zero exit code=${code} signal=${signal} stderr=${this.spawnStderr.slice(-STDERR_LOG_TAIL)}`);
             }
         }
         finally {
@@ -420,12 +377,7 @@ export class SpawningRunner {
                 }
             }
             this.currentProcess = null;
-            try {
-                fs.unlinkSync(this.pidFilePath);
-            }
-            catch {
-                /* ignore — file may not exist if spawn failed before write */
-            }
+            silentlyUnlink(this.pidFilePath);
         }
     }
     /**
@@ -444,10 +396,7 @@ export class SpawningRunner {
         this.stoppedByUser = true;
         await this.stopper.stop(proc, { immediate: opts?.immediate });
         this.currentProcess = null;
-        try {
-            fs.unlinkSync(this.pidFilePath);
-        }
-        catch { }
+        silentlyUnlink(this.pidFilePath);
         getLogger().debug(`[${this.logTag}] cleaned pid file ${this.pidFilePath}`);
     }
     killOrphan() {
@@ -457,7 +406,7 @@ export class SpawningRunner {
             const pidStr = fs.readFileSync(this.pidFilePath, 'utf-8').trim();
             const pid = Number(pidStr);
             if (isNaN(pid) || pid <= 0) {
-                fs.unlinkSync(this.pidFilePath);
+                silentlyUnlink(this.pidFilePath);
                 return;
             }
             // P1-10: pid 复用防护。pid 文件里的 pid 可能是 bridge 崩溃后系统回收复用
@@ -470,7 +419,7 @@ export class SpawningRunner {
                 // 统一原则：只有身份匹配才杀；验证失败一律不杀。
                 getLogger().warn(`[${this.logTag}] killOrphan: pid ${pid} not confirmed as ${this.binary} ` +
                     `(${match}), skipping kill`);
-                fs.unlinkSync(this.pidFilePath);
+                silentlyUnlink(this.pidFilePath);
                 return;
             }
             // 身份匹配：杀整个进程组（detached:true 下 agent 是组长），与
@@ -482,7 +431,7 @@ export class SpawningRunner {
             catch {
                 // process may have exited
             }
-            fs.unlinkSync(this.pidFilePath);
+            silentlyUnlink(this.pidFilePath);
         }
         catch {
             // ignore
@@ -561,10 +510,7 @@ export class SpawningRunner {
             }
             catch { }
         }
-        try {
-            fs.unlinkSync(this.pidFilePath);
-        }
-        catch { }
+        silentlyUnlink(this.pidFilePath);
     }
     /**
      * Build a unified result event from process exit state. Centralizes the

package/dist/runner/index.d.ts

@@ -8,10 +8,10 @@
  * （共享工具由消费方直接 import `common/*` 具体模块，不走 barrel）
  */
 export { ClaudeRunner } from './claude/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 { CodexAppServerRunner } from './codex/index.js';
+export { OpencodeAcpRunner } from './opencode/index.js';
+export { PiRpcRunner } from './pi/index.js';
+export { KimiAcpRunner } from './kimi/index.js';
 export { BashProcessRunner, type BashRunner } from './bash/index.js';
 export { AgentRegistry } from './registry.js';
 export type { ResultEvent, PlanEvent, FileChangeEvent, AgentEvent, Runner, RunnerLifetime, AgentKind, AgentSession, AgentSessionContentEvent, AgentSessionUsage, SessionContent, AgentSessionReader, AgentRunner, TurnStartedEvent, TurnDiffEvent, ApprovalView, ApprovalRequestedEvent, ApprovalResolvedEvent, } from './types.js';

package/dist/runner/index.js

@@ -9,10 +9,10 @@
  */
 // Re-export AgentRunner 实现（从各 agent 目录）
 export { ClaudeRunner } from './claude/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 { CodexAppServerRunner } from './codex/index.js';
+export { OpencodeAcpRunner } from './opencode/index.js';
+export { PiRpcRunner } from './pi/index.js';
+export { KimiAcpRunner } from './kimi/index.js';
 export { BashProcessRunner } from './bash/index.js';
 // Re-export registry
 export { AgentRegistry } from './registry.js';

package/dist/runner/kimi/acp/runner.d.ts

@@ -0,0 +1,106 @@
+/**
+ * KimiAcpRunner: workspace-lifetime runner using the Kimi ACP protocol
+ * (`kimi acp`, JSON-RPC over stdio).
+ *
+ * Flow per run: acquire persistent connection → session/new or session/resume
+ * → synthetic init → session/prompt → consume session/update notifications
+ * until prompt settles → result event.
+ *
+ * Structurally aligned with codex AppServerRunner (design doc §3.1) via the
+ * shared ConnectionBasedRunner base: same notification queue + waitResolve
+ * pattern, same forceFinish/stopRequested semantics, same turn idle timeout,
+ * same ConnectionLostError retry.
+ */
+import type { AgentKind, AgentSessionReader, AgentEvent, AgentStatusInfo, SpawnOptions } from '../../types.js';
+import { JsonRpcClient as KimiAcpClient } from '../../common/jsonrpc/client.js';
+import { type AcpTranslatorEvent } from './translator.js';
+import { ConnectionBasedRunner } from '../../common/connection-based-runner.js';
+export interface KimiAcpRunnerOptions {
+    kind: AgentKind;
+    sessionReader: AgentSessionReader;
+    /** Path to the kimi binary. Defaults to `kimi`. */
+    binary?: string;
+    /** Environment variables. */
+    env?: Record<string, string | undefined>;
+    /** Args to spawn the ACP server with. Defaults to `['acp']`. */
+    acpArgs?: string[];
+    /** Request timeout in milliseconds. */
+    requestTimeoutMs?: number;
+    /** Idle TTL for connection manager. */
+    idleTtlMs?: number;
+    /** How long to wait for turn output before failing. Defaults to 10 min. */
+    turnIdleTimeoutMs?: number;
+    /** R2: how long to poll wire.jsonl for the compaction record after the
+     *  /compact prompt settles. Defaults to 30s; WARN (not fail) on timeout. */
+    compactPollTimeoutMs?: number;
+    model?: string;
+    /** Kimi permission mode (user-facing: manual/auto/yolo). */
+    permissionMode?: 'manual' | 'auto' | 'yolo';
+}
+export declare class KimiAcpRunner extends ConnectionBasedRunner<KimiAcpClient, AcpTranslatorEvent> {
+    private connectionManager;
+    private currentTranslator;
+    private activeSessionId;
+    private model?;
+    private permissionMode;
+    private readonly compactPollTimeoutMs;
+    /** Pending approval requests: requestId → kind + view + options. */
+    private pendingApprovals;
+    /** Tracker for the in-flight prompt request — needed for cancellation. */
+    private promptSettled;
+    constructor(opts: KimiAcpRunnerOptions);
+    protected get logTag(): string;
+    protected get turnTimeoutErrorMessage(): string;
+    protected get turnInterruptedErrorMessage(): string;
+    protected currentSessionId(): string | null;
+    protected shouldDeferStop(): boolean;
+    protected cancelCurrentTurn(): Promise<void>;
+    protected clearTurnState(): void;
+    protected releaseConnection(cwd: string): Promise<void>;
+    protected notifyIdle(cwd: string): void;
+    protected disposeConnections(): Promise<void>;
+    /**
+     * Run a compact operation on the current session.
+     *
+     * Design doc §6.1: acquire → session/resume → session/prompt with "/compact"
+     * text (builtin slash command, host intercepts) → consume notifications until
+     * prompt settles.
+     */
+    runCompact(_message: string, opts: SpawnOptions): AsyncGenerator<AgentEvent>;
+    /**
+     * Respond to an approval server request. `response` is the bridge
+     * ApprovalAction (`{ action: 'accept' | 'decline' | 'cancel' }`).
+     */
+    respondApproval(requestId: number | string, response: unknown): Promise<void>;
+    getStatusInfo(): AgentStatusInfo;
+    /**
+     * Hot-apply a permission-mode change to the live ACP session (§P5).
+     *
+     * The local cache is always updated so `getStatusInfo()` (and therefore
+     * `/s`) reflects the new mode immediately. When a session is connected,
+     * re-sends `session/set_mode` so the running session picks up the new mode
+     * without waiting for the runner to be evicted/recreated. Failure is
+     * non-fatal: the next setupTurn re-applies the cached mode unconditionally.
+     */
+    updateApprovalMode(settings: {
+        permissionMode?: 'manual' | 'auto' | 'yolo';
+    }): Promise<void>;
+    /**
+     * Acquire the connection and set up the turn:
+     * session/new (new session) or session/resume (existing sessionId)
+     * → set permission mode if needed → session/prompt.
+     */
+    protected setupTurn(message: string, opts: SpawnOptions): Promise<void>;
+    /**
+     * R2: poll wire.jsonl until a NEW compaction record
+     * (context.apply_compaction / full_compaction.complete) appears.
+     *
+     * The /compact prompt settles before the background compaction lands its
+     * record; returning early would let the caller dispose the connection and
+     * kill the background job. Timeout is WARN-only (the compact may have been
+     * a no-op) — never fails the turn. Aborts early on stop/forceFinish.
+     */
+    private waitForCompactionRecord;
+    private handleNotification;
+    private handleServerRequest;
+}