lark-remote 0.5.13 → 0.5.15

package/dist/runner/kimi/acp/runner.js

@@ -582,11 +582,55 @@ export class KimiAcpRunner extends BaseAcpRunner {
             : undefined;
         const cwd = params.cwd ?? this.activeCwd ?? undefined;
         const outputLimit = params.outputByteLimit ?? TERMINAL_DEFAULT_OUTPUT_LIMIT;
-        // 走 shell seam：argv 逐 token 保留，只把「可执行文件在哪」
-        // 收口——win32 上 Git Bash 缺失时在这里抛 ShellUnavailableError，由
-        // handleTerminalRequest 转成明确的 Terminal request failed 回执，而不是一个
-        // 语焉不详的 spawn ENOENT。
-        const proc = this.shell.spawnArgv(params.command, params.args ?? [], {
+        const proc = this.spawnTerminalProcess(params, cwd, env);
+        // spawn 失败（如 ENOENT）只发 'error' 不发 'exit'——一并 resolve，防止
+        // wait_for_exit 永久挂起（runner 层 ENOENT 兜底红线）。
+        // 用 resolveExit 承接，避免回调在 handle 初始化前引用它（TDZ）。
+        let resolveExit;
+        const exitPromise = new Promise((resolve) => {
+            resolveExit = resolve;
+        });
+        // 与 resolveExit 同款 TDZ 规避：tool_result 发射闭包在 terminalId 初始化
+        // 后赋值，exit/error 回调执行时经 emitResult 间接调用。
+        let emitTerminalResult = undefined;
+        const emitResult = () => {
+            emitTerminalResult?.();
+        };
+        const handle = {
+            proc,
+            output: '',
+            outputBytes: 0,
+            outputLimit,
+            truncated: false,
+            exitCode: null,
+            signal: null,
+            exitPromise,
+        };
+        this.attachTerminalOutputBuffer(proc, handle);
+        this.wireTerminalExit(proc, handle, emitResult, () => resolveExit?.());
+        const terminalId = `term-${++this.terminalSeq}`;
+        this.terminals.set(terminalId, handle);
+        // Bash 工具事件由本 runner 自产（kimi 通知已过滤）：create 即推 tool_use
+        // 带真实命令，让 run 卡立刻出现可识别的 Bash 面板。
+        const script = Array.isArray(params.args) && params.args.length > 1 ? params.args[1] : params.command;
+        let resultEmitted = false;
+        emitTerminalResult = () => {
+            if (resultEmitted)
+                return;
+            resultEmitted = true;
+            this.pushTerminalToolResult(terminalId, handle.output, handle.exitCode);
+        };
+        this.pushTerminalToolUse(terminalId, script, cwd);
+        getLogger().info(`[${this.logTag}] terminal created id=${terminalId} command=${params.command} args=${JSON.stringify(params.args ?? [])}`);
+        this.currentClient?.respond(id, { terminalId });
+    }
+    /**
+     * 走 shell seam：argv 逐 token 保留，只把「可执行文件在哪」收口——win32 上
+     * Git Bash 缺失时在这里抛 ShellUnavailableError，由 handleTerminalRequest 转成
+     * 明确的 Terminal request failed 回执，而不是一个语焉不详的 spawn ENOENT。
+     */
+    spawnTerminalProcess(params, cwd, env) {
+        return this.shell.spawnArgv(params.command, params.args ?? [], {
             cwd,
             options: {
                 // env 覆盖大小写不敏感合并（win32 PATH/Path 双键防护）
@@ -600,8 +644,12 @@ export class KimiAcpRunner extends BaseAcpRunner {
                 windowsHide: true,
             },
         });
-        // 每个流独立 decoder：多字节字符跨 chunk 拆分时由 decoder 保留不完整
-        // 序列，避免按 chunk 单独 toString 产生 U+FFFD 替换符。
+    }
+    /**
+     * 有界输出缓冲：每个流独立 decoder（多字节字符跨 chunk 拆分时由 decoder 保留
+     * 不完整序列，避免按 chunk 单独 toString 产生 U+FFFD 替换符）。
+     */
+    attachTerminalOutputBuffer(proc, handle) {
         const stdoutDecoder = new StringDecoder('utf8');
         const stderrDecoder = new StringDecoder('utf8');
         const append = (chunk, decoder) => {
@@ -624,29 +672,11 @@ export class KimiAcpRunner extends BaseAcpRunner {
         };
         proc.stdout?.on('data', (chunk) => append(chunk, stdoutDecoder));
         proc.stderr?.on('data', (chunk) => append(chunk, stderrDecoder));
-        // spawn 失败（如 ENOENT）只发 'error' 不发 'exit'——一并 resolve，防止
-        // wait_for_exit 永久挂起（runner 层 ENOENT 兜底红线）。
-        // 用 resolveExit 承接，避免回调在 handle 初始化前引用它（TDZ）。
-        let resolveExit;
-        const exitPromise = new Promise((resolve) => {
-            resolveExit = resolve;
-        });
-        // 与 resolveExit 同款 TDZ 规避：tool_result 发射闭包在 terminalId 初始化
-        // 后赋值，exit/error 回调执行时经 emitResult 间接调用。
-        let emitTerminalResult = undefined;
-        const emitResult = () => {
-            emitTerminalResult?.();
-        };
-        const handle = {
-            proc,
-            output: '',
-            outputBytes: 0,
-            outputLimit,
-            truncated: false,
-            exitCode: null,
-            signal: null,
-            exitPromise,
-        };
+    }
+    /**
+     * 退出/错误收尾管线：tool_result 必须先入队，再放行 `wait_for_exit`。
+     */
+    wireTerminalExit(proc, handle, emitResult, resolveExit) {
         proc.once('exit', (code, signal) => {
             handle.exitCode = code;
             handle.signal = signal;
@@ -661,7 +691,7 @@ export class KimiAcpRunner extends BaseAcpRunner {
             const flushThenEmit = () => {
                 clearTimeout(emitTimer);
                 emitResult();
-                resolveExit?.();
+                resolveExit();
             };
             const emitTimer = setTimeout(flushThenEmit, 200);
             emitTimer.unref?.();
@@ -680,35 +710,30 @@ export class KimiAcpRunner extends BaseAcpRunner {
             }
             // 同 exit：tool_result 先入队，再放行 wait_for_exit。
             emitResult();
-            resolveExit?.();
+            resolveExit();
         });
-        const terminalId = `term-${++this.terminalSeq}`;
-        this.terminals.set(terminalId, handle);
-        // Bash 工具事件由本 runner 自产（kimi 通知已过滤）：create 即推 tool_use
-        // 带真实命令，让 run 卡立刻出现可识别的 Bash 面板。
-        const script = Array.isArray(params.args) && params.args.length > 1 ? params.args[1] : params.command;
-        let resultEmitted = false;
-        emitTerminalResult = () => {
-            if (resultEmitted)
-                return;
-            resultEmitted = true;
-            this.pushEvents([
-                {
-                    type: 'user',
-                    message: {
-                        content: [
-                            {
-                                type: 'tool_result',
-                                tool_use_id: terminalId,
-                                content: handle.output,
-                                is_error: handle.exitCode !== 0,
-                            },
-                        ],
-                    },
-                    timestamp: new Date().toISOString(),
+    }
+    /** Bash 面板的 tool_result 帧（输出全量 + 是否失败）。 */
+    pushTerminalToolResult(terminalId, output, exitCode) {
+        this.pushEvents([
+            {
+                type: 'user',
+                message: {
+                    content: [
+                        {
+                            type: 'tool_result',
+                            tool_use_id: terminalId,
+                            content: output,
+                            is_error: exitCode !== 0,
+                        },
+                    ],
                 },
-            ]);
-        };
+                timestamp: new Date().toISOString(),
+            },
+        ]);
+    }
+    /** Bash 面板的 tool_use 帧（真实命令 + cwd，create 时立刻可见）。 */
+    pushTerminalToolUse(terminalId, script, cwd) {
         this.pushEvents([
             {
                 type: 'assistant',
@@ -725,8 +750,6 @@ export class KimiAcpRunner extends BaseAcpRunner {
                 timestamp: new Date().toISOString(),
             },
         ]);
-        getLogger().info(`[${this.logTag}] terminal created id=${terminalId} command=${params.command} args=${JSON.stringify(params.args ?? [])}`);
-        this.currentClient?.respond(id, { terminalId });
     }
     /** terminal/output: 回累计全量输出 + truncated + 当前退出状态（可未退出）。 */
     handleTerminalOutput(id, params) {

package/dist/runner/opencode/acp/error-monitor.d.ts

@@ -45,6 +45,12 @@ export declare class OpencodeLogErrorMonitor {
     private timer;
     private sessionId;
     private onError;
+    /**
+     * IO 故障留痕的节流状态：poll 每 2s 一次，同一条 EACCES 不得刷满日志，
+     * 但也不能像以前那样完全静默（监视器自己坏了没人知道）。
+     */
+    private lastIoError;
+    private lastIoErrorAt;
     constructor(opts: OpencodeLogErrorMonitorOptions);
     /**
      * Start monitoring the given session. Replaces any previous monitor state;
@@ -54,6 +60,11 @@ export declare class OpencodeLogErrorMonitor {
     /** Stop monitoring and clear all state. Safe to call multiple times. */
     stop(): void;
     private currentSize;
+    /**
+     * 监视器自身读不到日志时留痕（同一条最多每分钟一次）。ENOENT 通常是日志
+     * 还没生成，属正常空态，不记。
+     */
+    private noteIoError;
     private poll;
     /** Match a main-turn stream error line for the monitored session with a
      *  limit/quota reason; returns the extracted error text or null. */

package/dist/runner/opencode/acp/error-monitor.js

@@ -27,9 +27,12 @@
 import { closeSync, openSync, readSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import { join } from 'node:path';
+import { getLogger } from '../../../logger/index.js';
 /** Error text we fail fast on: quota/limit conditions opencode backs off on. */
 const LIMIT_ERROR_RE = /usage limit|quota|rate limit|rate_limit|too many requests|insufficient balance|free usage/i;
 const STREAM_ERROR_RE = /message="stream error"/;
+/** 同一条 IO 故障的日志节流窗口。 */
+const IO_ERROR_LOG_INTERVAL_MS = 60_000;
 const MAIN_TURN_RE = /small=false/;
 const ERROR_MESSAGE_RE = /error\.error="((?:[^"\\]|\\.)*)"/;
 /**
@@ -50,6 +53,12 @@ export class OpencodeLogErrorMonitor {
     timer = null;
     sessionId = null;
     onError = null;
+    /**
+     * IO 故障留痕的节流状态：poll 每 2s 一次，同一条 EACCES 不得刷满日志，
+     * 但也不能像以前那样完全静默（监视器自己坏了没人知道）。
+     */
+    lastIoError = '';
+    lastIoErrorAt = 0;
     constructor(opts) {
         this.logPath = opts.logPath;
         this.pollIntervalMs = opts.pollIntervalMs ?? 2000;
@@ -81,10 +90,28 @@ export class OpencodeLogErrorMonitor {
         try {
             return statSync(this.logPath).size;
         }
-        catch {
+        catch (err) {
+            this.noteIoError(err);
             return 0;
         }
     }
+    /**
+     * 监视器自身读不到日志时留痕（同一条最多每分钟一次）。ENOENT 通常是日志
+     * 还没生成，属正常空态，不记。
+     */
+    noteIoError(err) {
+        if (err.code === 'ENOENT')
+            return;
+        const message = err?.message ?? String(err);
+        const now = Date.now();
+        if (message === this.lastIoError && now - this.lastIoErrorAt < IO_ERROR_LOG_INTERVAL_MS) {
+            return;
+        }
+        this.lastIoError = message;
+        this.lastIoErrorAt = now;
+        getLogger().warn(`[opencode-error-monitor] cannot read ${this.logPath}: ${message}; ` +
+            'limit errors will fall back to the idle watchdog');
+    }
     poll() {
         if (this.sessionId === null || this.onError === null)
             return;
@@ -107,9 +134,11 @@ export class OpencodeLogErrorMonitor {
                     closeSync(fd);
                 }
             }
-            catch {
+            catch (err) {
+                this.noteIoError(err);
                 return;
             }
+            this.lastIoError = '';
             this.offset = size;
             this.pendingTail += chunk;
         }

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

@@ -19,7 +19,9 @@
  * - OpencodeLogErrorMonitor tails opencode's own log for LLM stream errors
  *   the ACP protocol never forwards
  */
-import type { AgentKind, AgentSessionReader, AgentStatusInfo } from '../../types.js';
+import type { AgentKind } from '../../../agent-kinds.js';
+import type { AgentSessionReader } from '../../../session-contract.js';
+import type { AgentStatusInfo } from '../../types.js';
 import { JsonRpcClient } from '../../common/jsonrpc/client.js';
 import { OpencodeAcpTranslator } from './translator.js';
 import { type SessionNewResult, type SessionResumeResult, type SessionPromptResult } from '../../common/acp/protocol-types.js';
@@ -89,9 +91,20 @@ export declare class OpencodeAcpRunner extends BaseAcpRunner<OpencodeAcpTranslat
      * starting or still activating location plugins when the first session is
      * created; both surface as a JSON-RPC internal error. Retry a few times
      * before failing the turn.
+     *
+     * 单次 attempt 自身还要等 opencode 侧超时（~10s），所以真实窗口 ≈ Σdelay +
+     * 每次的等待。2026-10-30 现场：daemon 刚重启，`/api/model` 因模型目录拉取
+     * 超时连续 503 约 7 分钟，旧退避 0.5/1.5/3s（合计 ~45s）全落在这段里，4 次
+     * 重试无一成功。现在铺到 ~75s + 每次超时 ≈ 2 分钟，覆盖一次冷启动窗口，
+     * 又不至于让真故障的用户干等太久。
      */
     protected sessionSetupRetryDelaysMs(): number[];
     protected isRetryableSessionSetupError(err: unknown): boolean;
+    /**
+     * 用户可见文案。这里刻意**不**建议 `opencode service restart`：卡住的是
+     * opencode 的模型目录/位置服务冷启动，重启只会清掉刚热好的状态、重新回到
+     * 同一个窗口（2026-10-30 现场：照提示重启两次仍然失败，等几分钟自己好了）。
+     */
     protected enrichSessionSetupError(err: unknown): Error;
     getStatusInfo(): AgentStatusInfo;
     /**

package/dist/runner/opencode/acp/runner.js

@@ -173,20 +173,31 @@ export class OpencodeAcpRunner extends BaseAcpRunner {
      * starting or still activating location plugins when the first session is
      * created; both surface as a JSON-RPC internal error. Retry a few times
      * before failing the turn.
+     *
+     * 单次 attempt 自身还要等 opencode 侧超时（~10s），所以真实窗口 ≈ Σdelay +
+     * 每次的等待。2026-10-30 现场：daemon 刚重启，`/api/model` 因模型目录拉取
+     * 超时连续 503 约 7 分钟，旧退避 0.5/1.5/3s（合计 ~45s）全落在这段里，4 次
+     * 重试无一成功。现在铺到 ~75s + 每次超时 ≈ 2 分钟，覆盖一次冷启动窗口，
+     * 又不至于让真故障的用户干等太久。
      */
     sessionSetupRetryDelaysMs() {
-        return [500, 1500, 3000];
+        return [500, 2000, 8000, 20000, 45000];
     }
     isRetryableSessionSetupError(err) {
         const message = err instanceof Error ? err.message : String(err);
         return /ServiceUnavailableError|Location plugins did not finish activating|Internal service failure|ECONNREFUSED|fetch failed/i.test(message);
     }
+    /**
+     * 用户可见文案。这里刻意**不**建议 `opencode service restart`：卡住的是
+     * opencode 的模型目录/位置服务冷启动，重启只会清掉刚热好的状态、重新回到
+     * 同一个窗口（2026-10-30 现场：照提示重启两次仍然失败，等几分钟自己好了）。
+     */
     enrichSessionSetupError(err) {
         if (!this.isRetryableSessionSetupError(err)) {
             return super.enrichSessionSetupError(err);
         }
         const message = err instanceof Error ? err.message : String(err);
-        return new Error(`opencode 2.0 后台服务不可用（${message}）。请在终端执行 \`opencode service restart\` 后重试。`, { cause: err });
+        return new Error(`opencode 后台服务尚未就绪（${message}）。这是 opencode 冷启动 / 模型目录加载期间的临时状态：等 1–2 分钟重发即可，重启服务只会重新进入同一窗口。`, { cause: err });
     }
     getStatusInfo() {
         return {

package/dist/runner/pi/rpc/runner.d.ts

@@ -17,7 +17,8 @@
  *   - pi，极简风格，没有 Ask User question。
  *   - `prompt` ack ≠ turn completion; the turn ends on `agent_settled`.
  */
-import type { AgentSessionReader, AgentEvent, AgentStatusInfo, SpawnOptions } from '../../types.js';
+import type { AgentSessionReader } from '../../../session-contract.js';
+import type { AgentEvent, AgentStatusInfo, SpawnOptions } from '../../types.js';
 import { ConnectionBasedRunner } from '../../common/connection-based-runner.js';
 import { PiRpcClient } from './client.js';
 import { type PiRpcTranslatorEvent } from './translator.js';

package/dist/runner/probe.d.ts

@@ -17,7 +17,7 @@
  *   does PATH + X_OK on posix (same semantics) and PATH × PATHEXT on win32,
  *   with no child process at all.
  */
-import type { AgentKind } from './types.js';
+import type { AgentKind } from '../agent-kinds.js';
 /**
  * Probe a single agent, using cache when fresh.
  * Updates cache on completion.

package/dist/runner/probe.js

@@ -18,6 +18,7 @@
  *   with no child process at all.
  */
 import { resolveExecutable } from '../platform/command.js';
+import { TtlCache } from '../common/ttl-cache.js';
 /** Map from AgentKind to its CLI binary name. */
 const BINARY_MAP = {
     claude: 'claude',
@@ -30,8 +31,11 @@ const BINARY_MAP = {
     dsh: '',
 };
 const CACHE_TTL_MS = 5 * 60_000;
-/** Module-level cache, survives across calls within the process. */
-const cache = new Map();
+/**
+ * Module-level cache, survives across calls within the process. 键集就是
+ * AgentKind（有界），因此不设条目上限；共享 `TtlCache` 与 session readers 同语义。
+ */
+const cache = new TtlCache(CACHE_TTL_MS);
 /**
  * Probe a single agent's availability (pure PATH lookup; dsh has no CLI
  * binary and is always unavailable here).
@@ -49,10 +53,10 @@ async function probeOne(kind) {
  */
 export async function probeAgentAvailability(kind) {
     const cached = cache.get(kind);
-    if (cached && Date.now() - cached.ts < CACHE_TTL_MS)
-        return cached.ok;
+    if (cached !== undefined)
+        return cached;
     const ok = await probeOne(kind);
-    cache.set(kind, { ts: Date.now(), ok });
+    cache.set(kind, ok);
     return ok;
 }
 /**
@@ -76,10 +80,7 @@ export async function probeAllAgents() {
  * Used by synchronous code paths (e.g. buildConfigCard) that cannot await.
  */
 export function getCachedAvailability(kind) {
-    const cached = cache.get(kind);
-    if (!cached || Date.now() - cached.ts >= CACHE_TTL_MS)
-        return undefined;
-    return cached.ok;
+    return cache.get(kind);
 }
 /** Clear all cache entries. Exported for test use only (cache auto-expires via TTL). */
 export function _clearCacheForTest() {

package/dist/runner/registry.d.ts

@@ -1,4 +1,5 @@
-import type { AgentKind, Runner } from './index.js';
+import type { AgentKind } from '../agent-kinds.js';
+import type { Runner } from './index.js';
 /**
  * Registry of agent factories, keyed by `AgentKind`. `index.ts` registers one
  * factory per available agent at startup; `Bridge.getRunner(cwd)` looks

package/dist/runner/types.d.ts

@@ -3,7 +3,10 @@
  *
  * 本文件包含所有 Agent 相关的类型定义，从 runner/index.ts 提取。
  * 所有下游模块应从本文件 import 类型，而非直接依赖实现。
+ * （例外：`AgentKind` 住在 `src/agent-kinds.ts`，见文件底部说明。）
  */
+import type { AgentKind } from '../agent-kinds.js';
+import type { AgentSessionReader } from '../session-contract.js';
 export interface SystemInitEvent {
     type: 'system';
     subtype: 'init';
@@ -552,18 +555,7 @@ export interface Runner {
      */
     unregisterExitHandlers?(): void;
 }
-/**
- * Agent 名单单源（运行时数组 + 类型同源，二者不可能漂移）。
- *
- * 历史上这份名单被手抄成多份（router 的 VALID_AGENTS、bridge 的 resume.compact
- * 校验、各 agent 的 config builder…），漂移过：dsh 加入后 bridge 的
- * resume.compact 仍只有 5 个，带 dsh 的 resume 卡片会静默退回 defaultAgent。
- * 新增 agent 只改这里。
- */
-export declare const AGENT_KINDS: readonly ["claude", "codex", "opencode", "pi", "kimi", "dsh"];
-export type AgentKind = (typeof AGENT_KINDS)[number];
-/** 用户可见 agent 显示名单源：启动注册与无 registry 的回退路径共用。 */
-export declare const AGENT_DISPLAY_NAMES: Record<AgentKind, string>;
+export { AGENT_DISPLAY_NAMES } from '../agent-kinds.js';
 /**
  * Compact 能力声明（运行时门控的能力清单，编译期强制完整）。
  *
@@ -579,147 +571,6 @@ export declare const AGENT_DISPLAY_NAMES: Record<AgentKind, string>;
 export declare const COMPACT_CAPABILITY: Readonly<Record<AgentKind, boolean>>;
 /** 该 agent 是否声明支持 compact（渲染门控与执行门控共用的唯一判据）。 */
 export declare function supportsCompact(kind: AgentKind): boolean;
-/** Unified session descriptor returned by every AgentSessionReader. */
-export interface AgentSession {
-    sessionId: string;
-    summary: string;
-    mtime: number;
-    /** DSH：session 创建时固定的 preset；其他 agent 无此概念（undefined）。 */
-    agentPreset?: string;
-    /**
-     * 服务端投影已有的会话标题（DSH `projections.values.title`）。
-     *
-     * 与 `summary` 的区别：`summary` 是「首条用户输入」的兜底口径（claude /
-     * codex / pi / kimi 无标题字段），`title` 是 agent 自己起的标题。列表卡
-     * 用它决定标签文案（标题 / 会话摘要），缺省时回退 `summary`。
-     */
-    title?: string;
-    /**
-     * 最后一轮用户输入（服务端投影，单行预览）。
-     *
-     * 只给「列表响应里已顺带返回」的 reader 用（DSH 的 `turnOutline` 末条），
-     * 目的是让列表卡不必为每行做一次全量内容读取。
-     */
-    lastUserMessage?: string;
-    /** 最后一轮助手输出（服务端投影已截断，单行预览）。 */
-    lastAssistantMessage?: string;
-}
-/** A single renderable event from session history. */
-export interface AgentSessionContentEvent {
-    type: string;
-    /** 正文（展开后的面板内容）。 */
-    content: string;
-    /**
-     * 面板标题（可选，覆盖 reader 的默认标签）。
-     *
-     * 折叠面板默认只显示标题：工具调用这种"标题即全部信息"的事件必须把
-     * `bash — npm test` 这类摘要放进标题，否则折叠态只剩 `🔧 工具调用`。
-     */
-    title?: string;
-    timestamp?: string;
-}
-export interface AgentSessionUsage {
-    inputTokens: number;
-    outputTokens: number;
-    contextLength: number;
-    /** Agent 上报的当前模型 context window 上限（codex token_count.info.model_context_window）。
-     *  仅 codex 提供；缺省时卡片只显示绝对量、不显示百分比。 */
-    contextLimit?: number;
-    /** Claude auto-compact 次数（数 compact_boundary 事件）；codex/opencode 无此概念，留 undefined。 */
-    compactCount?: number;
-    /** 压缩前上下文水位（codex compact 后从会话 jsonl 读取，仅会话以压缩收尾时有值）。 */
-    compactPreContextLength?: number;
-    /** 从缓存读取的 token 数（节省的费用）。 */
-    cacheReadTokens?: number;
-    /** 新建缓存的 token 数。 */
-    cacheCreationTokens?: number;
-    /** Agent 声明的总量；展示用 max(total, 分项和)。 */
-    totalTokens?: number;
-    /** 会话累计 total token（所有 run 之和，含本次）。用于 Run 卡片"累计"展示。 */
-    cumulativeTotalTokens?: number;
-    /** 会话累计 input token（所有 run 之和，含本次）。用于 Run 卡片"累计"展示。 */
-    cumulativeInputTokens?: number;
-    /** 会话累计 output token（所有 run 之和，含本次）。 */
-    cumulativeOutputTokens?: number;
-    /** 会话累计 cache read token（所有 run 之和）。用于 Run 卡片展示累计缓存命中。 */
-    cumulativeCacheReadTokens?: number;
-    /** 会话累计 cache creation token（所有 run 之和）。 */
-    cumulativeCacheCreationTokens?: number;
-}
-/** Unified session content payload returned by every AgentSessionReader. */
-export interface SessionContent {
-    events: AgentSessionContentEvent[];
-    usage?: AgentSessionUsage;
-    aiTitle?: string;
-    recap?: string;
-    displayTitle?: string;
-}
-/**
- * Lightweight session summary used by `/resume` list prefetch.
- *
- * Carries only the display fields (title / recap / usage) — **no `events`
- * array**. Readers that can extract these without constructing the full event
- * list (e.g. codex, which would otherwise JSON.parse every response_item and
- * build an `events[]` that the prefetch immediately discards) implement the
- * optional `readSessionSummary` on `AgentSessionReader`.
- */
-export interface SessionSummary {
-    aiTitle?: string;
-    recap?: string;
-    displayTitle?: string;
-    usage?: AgentSessionUsage;
-}
-/**
- * Reads an agent's session history. Each agent implements its own (Claude reads
- * `~/.claude/projects/`, Codex calls `thread/list`, OpenCode calls `GET /session`).
- *
- * Q-C decision: `projectsDir` and other agent-specific path config live on the
- * concrete reader's constructor, NOT on these method opts. The router/bridge
- * depend only on this interface and never pass path config.
- */
-export interface AgentSessionReader {
-    /**
-     * List sessions for a cwd, newest first by mtime.
-     *
-     * `sessions` is the page `[offset, offset+limit)` of the full set ordered
-     * by mtime desc, with same-mtime ties broken by a deterministic secondary
-     * key (sessionId/file path) so ordering is stable across calls. When
-     * `limit` is omitted, codex/pi/kimi return their default-sized page
-     * (default 20); claude/opencode return the full remaining set from
-     * `offset`. `total` is ALWAYS the size of the full cwd-matched set before
-     * pagination — never the truncated page length. A negative `offset` is
-     * clamped to 0 (first page).
-     */
-    listSessions(cwd: string, opts?: {
-        limit?: number;
-        offset?: number;
-    }): {
-        sessions: AgentSession[];
-        total: number;
-    };
-    getNewestSession(cwd: string): AgentSession | null;
-    readSessionContent(sessionId: string, cwd: string, opts?: {
-        maxEvents?: number;
-    }): SessionContent;
-    /**
-     * Optional lightweight summary for list-prefetch.
-     *
-     * Returns only the display fields (aiTitle/recap/displayTitle/usage) without
-     * constructing the full `events` array. When absent, callers fall back to
-     * `readSessionContent` and take the needed fields.
-     */
-    readSessionSummary?(sessionId: string, cwd: string): SessionSummary;
-    /**
-     * Whether a session is still active (process may still be running).
-     *
-     * Dormant API: no production caller reads this today — the router decides
-     * "is an agent running" via the in-memory `bridge.isBusyFor(cwd)` (see
-     * `cmdPs`), not by probing session files. Retained on the reader contract
-     * because all 5 readers implement it and it is the natural hook if a
-     * file-based liveness check is ever needed; not wired into the bridge.
-     */
-    isSessionActive(sessionId: string, cwd: string): boolean;
-}
 /**
  * AgentRunner extends Runner with agent identity and a session reader.
  * Bridge/Router depend on this interface so adding a new agent is
@@ -732,6 +583,22 @@ export interface AgentRunner extends Runner {
     getStatusInfo(): AgentStatusInfo;
     /** Whether this runner provides live usage data (vs. file-based). */
     getUsageAuthority?(): 'live' | 'jsonl';
+    /**
+     * 回传审批决策（codex thread/permissions、ACP elicitation、DSH approval
+     * resolve）。未实现的 agent 由协调器按「无人应答」超时收尾。
+     */
+    respondApproval?(requestId: number | string, response: unknown): Promise<void>;
+    /**
+     * 停止 agent 侧的一个后台任务（DSH 的 background job）。只有支持后台任务的
+     * agent 实现；调用方按能力存在与否门控。
+     */
+    killJob?(sessionId: string, jobId: string): Promise<boolean>;
+    /**
+     * 热更审批模式/权限预设（config.save 后推给在跑的 runner，不必重启会话）。
+     * 各家 settings 词表不同（codex: approvalPolicy/sandbox；kimi: permissionMode；
+     * opencode: mode；dsh: permissionPreset），故为开放载荷。
+     */
+    updateApprovalMode?(settings: Record<string, unknown>): Promise<void>;
 }
 /** Agent self-describing status info for /status display. */
 export interface AgentStatusInfo {
@@ -746,4 +613,3 @@ export interface AgentStatusInfo {
     /** Agent-specific extra fields (e.g. codex.sandbox). */
     extras?: Record<string, string>;
 }
-export {};

package/dist/runner/types.js

@@ -1,30 +1,10 @@
-/**
- * Runner 模块类型定义
- *
- * 本文件包含所有 Agent 相关的类型定义，从 runner/index.ts 提取。
- * 所有下游模块应从本文件 import 类型，而非直接依赖实现。
- */
 // =============================================================================
 // Multi-Agent Adapter Types
 // =============================================================================
-/**
- * Agent 名单单源（运行时数组 + 类型同源，二者不可能漂移）。
- *
- * 历史上这份名单被手抄成多份（router 的 VALID_AGENTS、bridge 的 resume.compact
- * 校验、各 agent 的 config builder…），漂移过：dsh 加入后 bridge 的
- * resume.compact 仍只有 5 个，带 dsh 的 resume 卡片会静默退回 defaultAgent。
- * 新增 agent 只改这里。
- */
-export const AGENT_KINDS = ['claude', 'codex', 'opencode', 'pi', 'kimi', 'dsh'];
-/** 用户可见 agent 显示名单源：启动注册与无 registry 的回退路径共用。 */
-export const AGENT_DISPLAY_NAMES = {
-    claude: 'Claude',
-    codex: 'Codex',
-    opencode: 'Opencode',
-    pi: 'Pi',
-    kimi: 'Kimi',
-    dsh: 'DSH',
-};
+// Agent 名单与显示名住在 `src/agent-kinds.ts`（中立层，config/session/card 都
+// 要用）；本模块只 import `AgentKind` 类型来签名 runner 契约。保留旧路径的
+// re-export 兼容调用方，但值仍只由 agent-kinds.ts 定义。
+export { AGENT_DISPLAY_NAMES } from '../agent-kinds.js';
 /**
  * Compact 能力声明（运行时门控的能力清单，编译期强制完整）。
  *