lark-remote 0.1.6 → 0.1.7

package/dist/router/utils.d.ts

@@ -12,6 +12,8 @@ export interface SessionDisplayUsage {
     cacheCreationTokens?: number;
 }
 export declare function activeRunUsage(activeRun: ActiveRunSnapshot | undefined): SessionDisplayUsage | undefined;
+/** Clamp `v` into [min, max]. */
+export declare function clampInt(v: number, min: number, max: number): number;
 /**
  * Format usage stats (context length, compact count, cache tokens) into a display string.
  * Each stat on its own line with blank lines between sections.

package/dist/router/utils.js

@@ -13,6 +13,10 @@ export function activeRunUsage(activeRun) {
     };
 }
 // --- Extracted helpers for refactoring ---
+/** Clamp `v` into [min, max]. */
+export function clampInt(v, min, max) {
+    return Math.min(Math.max(v, min), max);
+}
 /**
  * Format number to human-readable unit string.
  * - >= 1M: one decimal, M suffix (e.g., 1200000 → 1.2M, 25000000 → 25M)

package/dist/runner/agent-choices-common.d.ts

@@ -0,0 +1,16 @@
+import type { AgentKind } from './types.js';
+/** 一对需要同步的字段：agents.<agent> 上的配置键 ↔ agentChoices.<agent> 上的选择键。 */
+export interface ChoiceField {
+    configKey: string;
+    choicesKey: string;
+}
+/**
+ * 非 claude agent 的字段映射表。
+ *
+ * claude 的配置在顶层 `config.claude`，不走 agents/agentChoices，因此不在此表中。
+ * syncAgentChoices（保存配置时写入 agentChoices）与 resolveAgentChoices（启动时
+ * 恢复）共用这张表，新增字段只需改一处。
+ */
+export declare const AGENT_CHOICE_FIELDS: Record<Exclude<AgentKind, 'claude'>, readonly ChoiceField[]>;
+/** 返回指定 agent 的字段映射；claude 或未知 agent 返回 undefined。 */
+export declare function choiceFieldsFor(agent: string): readonly ChoiceField[] | undefined;

package/dist/runner/agent-choices-common.js

@@ -0,0 +1,31 @@
+/**
+ * 非 claude agent 的字段映射表。
+ *
+ * claude 的配置在顶层 `config.claude`，不走 agents/agentChoices，因此不在此表中。
+ * syncAgentChoices（保存配置时写入 agentChoices）与 resolveAgentChoices（启动时
+ * 恢复）共用这张表，新增字段只需改一处。
+ */
+export const AGENT_CHOICE_FIELDS = {
+    codex: [
+        { configKey: 'model', choicesKey: 'model' },
+        { configKey: 'modelProvider', choicesKey: 'modelProvider' },
+    ],
+    pi: [
+        { configKey: 'model', choicesKey: 'model' },
+        { configKey: 'provider', choicesKey: 'provider' },
+        { configKey: 'thinking', choicesKey: 'thinking' },
+    ],
+    opencode: [
+        { configKey: 'modelID', choicesKey: 'modelID' },
+        { configKey: 'providerID', choicesKey: 'providerID' },
+    ],
+    kimi: [
+        { configKey: 'model', choicesKey: 'model' },
+        { configKey: 'thinkingEffort', choicesKey: 'thinkingEffort' },
+    ],
+};
+/** 返回指定 agent 的字段映射；claude 或未知 agent 返回 undefined。 */
+export function choiceFieldsFor(agent) {
+    return AGENT_CHOICE_FIELDS[agent];
+}
+//# sourceMappingURL=agent-choices-common.js.map

package/dist/runner/claude/runner.d.ts

@@ -1,16 +1,21 @@
-import { type AgentEvent, type SpawnOptions, type AgentSessionReader, type AgentRunner as IAgentRunner, type AgentStatusInfo } from '../types.js';
-import { SpawningRunner } from '../common/spawning-runner.js';
+import { type AgentEvent, type SpawnOptions, type AgentSessionReader, type AgentRunner, type AgentStatusInfo } from '../types.js';
 /**
- * Claude Agent Runner
+ * Claude Agent Runner（长驻交互模式）。
  *
- * 使用 Claude Code CLI (claude) 作为后端 AI 代理
+ * 权限模式（permissionMode）在 spawn 时经 --permission-mode 生效：
+ * - 默认 bypassPermissions：claude 内部自动放行，无 control_request → 行为与
+ *   旧版完全一致（无审批卡）；
+ * - 配置为 default/acceptEdits/manual/plan 等：工具调用经 control_request
+ *   上抛 → bridge ApprovalCoordinator → run 卡审批区。
  */
-export declare class ClaudeRunner extends SpawningRunner implements IAgentRunner {
+export declare class ClaudeRunner implements AgentRunner {
     readonly kind: "claude";
+    readonly lifetime: "workspace";
     readonly sessionReader: AgentSessionReader;
-    private defaultModel;
-    private defaultEffort;
-    private defaultSettings?;
+    private readonly session;
+    private readonly defaultModel;
+    private readonly defaultEffort;
+    private readonly permissionMode;
     constructor(opts: {
         model?: string;
         effort?: string;
@@ -20,9 +25,41 @@ export declare class ClaudeRunner extends SpawningRunner implements IAgentRunner
         workspace: string;
         spawnHeartbeatMs?: number;
         sessionReader?: AgentSessionReader;
+        /** Claude 权限模式（官方 --permission-mode 枚举；'default'=省略参数）。 */
+        permissionMode?: string;
+        /** 会话级空闲回收 TTL（ms）；0=禁用。 */
+        idleTtlMs?: number;
     });
+    get isRunning(): boolean;
     get pid(): number | undefined;
     getStatusInfo(): AgentStatusInfo;
-    protected buildArgv(opts: SpawnOptions): string[];
-    protected translate(rawEvent: unknown, _ctx: unknown): AgentEvent | AgentEvent[] | null;
+    /**
+     * 每 turn 入口：委托 ClaudeSession（确保进程 → 写消息 → 消费到 result）。
+     */
+    run(message: string, opts: SpawnOptions): AsyncGenerator<AgentEvent>;
+    /**
+     * 压缩当前会话：把 CLI 内建 `/compact` 命令作为一条 user 消息写入
+     * stream-json 通道，复用 run() 的进程回收/长驻逻辑消费到 turn 终态。
+     * bridge 通过鸭子类型（`'runCompact' in runner`）探测该能力，与 codex
+     * app-server / kimi ACP 的 runCompact 契约一致。
+     */
+    runCompact(_message: string, opts: SpawnOptions): AsyncGenerator<AgentEvent>;
+    /**
+     * 审批响应（bridge ApprovalCoordinator → runner）：映射 ApprovalAction 到
+     * Claude 控制协议的 allow/deny（accept_all = allow + 本会话自动放行）。
+     */
+    respondApproval(requestId: number | string, response: unknown): Promise<void>;
+    stop(opts?: {
+        immediate?: boolean;
+    }): Promise<void>;
+    killOrphan(): void;
+    registerExitHandlers(): void;
+    unregisterExitHandlers(): void;
+    /**
+     * 进程级退出清理（SIGINT/SIGTERM/exit 分发器最终调 session.cleanupOnExit）。
+     * 暴露为委托 seam 供测试直接触发；生产路径由注册到分发器的 session 触发。
+     */
+    cleanupOnExit(): void;
+    /** 释放会话（bridge 淘汰槽位时调用，进程组终止）。 */
+    dispose(): Promise<void>;
 }

package/dist/runner/claude/runner.js

@@ -1,39 +1,64 @@
 /**
  * Claude Runner 实现
  *
- * 从 runner/index.ts 提取的 ClaudeRunner 类
+ * ClaudeRunner 从「一次一跑」（claude -p <msg> --permission-mode
+ * bypassPermissions）升级为长驻交互会话（--input-format stream-json 双向
+ * 通道），同时复用本项目已有的 ApprovalCoordinator + run 卡审批区。
+ *
+ * 架构：ClaudeRunner 是 workspace-lifetime 的薄包装，进程与协议细节在
+ * ClaudeSession（src/runner/claude/session.ts，extends SpawningRunner 复用
+ * pid 文件/killOrphan/ProcessStopper/心跳/退出分发器机制）。每次 run() 委托
+ * session：确保进程（可 --resume）→ 写 user 消息 → 消费事件直到本 turn result。
  */
 import { ClaudeSessionReader } from '../../session/claude/index.js';
-import { SpawningRunner } from '../common/spawning-runner.js';
+import { ClaudeSession } from './session.js';
 import { MODEL_ID_TO_ALIAS } from '../../config/index.js';
 /**
- * Claude Agent Runner
+ * Claude 内建压缩命令。stream-json 输入模式下该文本会被 CLI 本地拦截为
+ * slash 命令（不会作为模型提示词转发），压缩 turn 以普通 result 收尾
+ * （真实 claude 2.1.233 实测：小会话返回 "Not enough messages to compact."，
+ * 有内容则返回摘要文本 + result success）。
+ */
+const COMPACT_COMMAND = '/compact';
+/**
+ * Claude Agent Runner（长驻交互模式）。
  *
- * 使用 Claude Code CLI (claude) 作为后端 AI 代理
+ * 权限模式（permissionMode）在 spawn 时经 --permission-mode 生效：
+ * - 默认 bypassPermissions：claude 内部自动放行，无 control_request → 行为与
+ *   旧版完全一致（无审批卡）；
+ * - 配置为 default/acceptEdits/manual/plan 等：工具调用经 control_request
+ *   上抛 → bridge ApprovalCoordinator → run 卡审批区。
  */
-export class ClaudeRunner extends SpawningRunner {
+export class ClaudeRunner {
     kind = 'claude';
+    lifetime = 'workspace';
     sessionReader;
+    session;
     defaultModel;
     defaultEffort;
-    defaultSettings;
+    permissionMode;
     constructor(opts) {
-        super({
+        this.defaultModel = opts.model ?? 'claude-opus-4-8';
+        this.defaultEffort = opts.effort ?? 'medium';
+        this.permissionMode = opts.permissionMode ?? 'bypassPermissions';
+        this.sessionReader = opts.sessionReader ?? new ClaudeSessionReader();
+        this.session = new ClaudeSession({
             pidDir: opts.pidDir,
             workspace: opts.workspace,
             stopGraceMs: opts.stopGraceMs,
             spawnHeartbeatMs: opts.spawnHeartbeatMs,
-            pidFilePrefix: 'claude',
-            logTag: 'claude-runner',
+            permissionMode: this.permissionMode,
+            settings: opts.settings,
+            model: this.defaultModel,
+            effort: this.defaultEffort,
+            idleTtlMs: opts.idleTtlMs,
         });
-        this.binary = 'claude';
-        this.defaultModel = opts.model ?? 'claude-opus-4-8';
-        this.defaultEffort = opts.effort ?? 'medium';
-        this.defaultSettings = opts.settings;
-        this.sessionReader = opts.sessionReader ?? new ClaudeSessionReader();
+    }
+    get isRunning() {
+        return this.session.isRunning;
     }
     get pid() {
-        return this.currentProcess?.pid;
+        return this.session.pid;
     }
     getStatusInfo() {
         const alias = MODEL_ID_TO_ALIAS[this.defaultModel] ?? this.defaultModel;
@@ -42,42 +67,88 @@ export class ClaudeRunner extends SpawningRunner {
             kind: 'claude',
             model: alias,
             reasoning: isHaiku ? 'off' : this.defaultEffort,
+            extras: { permissionMode: this.permissionMode },
         };
     }
-    buildArgv(opts) {
-        const args = [
-            '-p',
-            this.currentMessage,
-            '--output-format',
-            'stream-json',
-            '--verbose',
-            // Hardcoded: Feishu chat doesn't support interactive approval.
-            '--permission-mode',
-            'bypassPermissions',
-        ];
-        if (opts.sessionId) {
-            args.push('--resume', opts.sessionId);
-        }
-        if (opts.model) {
-            args.push('--model', opts.model);
-        }
-        const effort = opts.effort ?? this.defaultEffort;
-        if (effort) {
-            args.push('--effort', effort);
-        }
-        const settings = opts.settings ?? this.defaultSettings;
-        if (settings) {
-            args.push('--settings', settings);
+    /**
+     * 每 turn 入口：委托 ClaudeSession（确保进程 → 写消息 → 消费到 result）。
+     */
+    async *run(message, opts) {
+        yield* this.session.run(message, opts);
+    }
+    /**
+     * 压缩当前会话：把 CLI 内建 `/compact` 命令作为一条 user 消息写入
+     * stream-json 通道，复用 run() 的进程回收/长驻逻辑消费到 turn 终态。
+     * bridge 通过鸭子类型（`'runCompact' in runner`）探测该能力，与 codex
+     * app-server / kimi ACP 的 runCompact 契约一致。
+     */
+    async *runCompact(_message, opts) {
+        if (!opts.sessionId) {
+            throw new Error('compact requires a sessionId');
         }
-        return args;
+        yield* this.session.run(COMPACT_COMMAND, opts);
     }
-    translate(rawEvent, _ctx) {
-        const event = rawEvent;
-        // 统一方案：所有 runner 自己生成 timestamp
-        if (!event.timestamp) {
-            event.timestamp = new Date().toISOString();
+    /**
+     * 审批响应（bridge ApprovalCoordinator → runner）：映射 ApprovalAction 到
+     * Claude 控制协议的 allow/deny（accept_all = allow + 本会话自动放行）。
+     */
+    async respondApproval(requestId, response) {
+        const action = response?.action ?? 'decline';
+        switch (action) {
+            case 'accept':
+                await this.session.respondPermission(requestId, { behavior: 'allow' });
+                return;
+            case 'accept_all':
+                this.session.setAutoApprove(true);
+                await this.session.respondPermission(requestId, { behavior: 'allow' });
+                return;
+            case 'decline':
+                await this.session.respondPermission(requestId, { behavior: 'deny' });
+                return;
+            case 'cancel': {
+                // 审批超时/取消：deny 送达后中断 turn（对齐方案验收「审批超时未响应，
+                // 已自动取消」终态；仅 deny 会让 claude 继续回合导致卡片 done）。
+                await this.session.respondPermission(requestId, {
+                    behavior: 'deny',
+                    message: '审批超时未响应，已自动取消。',
+                });
+                await this.session.stop({ immediate: true });
+                return;
+            }
+            case 'answer': {
+                const answers = response.answers;
+                if (!answers) {
+                    throw new Error('approval answer missing answers payload');
+                }
+                await this.session.respondAskUserQuestion(requestId, answers);
+                return;
+            }
+            default:
+                await this.session.respondPermission(requestId, { behavior: 'deny' });
         }
-        return event;
+    }
+    async stop(opts) {
+        await this.session.stop(opts);
+    }
+    killOrphan() {
+        this.session.killOrphan();
+    }
+    registerExitHandlers() {
+        this.session.registerExitHandlers();
+    }
+    unregisterExitHandlers() {
+        this.session.unregisterExitHandlers();
+    }
+    /**
+     * 进程级退出清理（SIGINT/SIGTERM/exit 分发器最终调 session.cleanupOnExit）。
+     * 暴露为委托 seam 供测试直接触发；生产路径由注册到分发器的 session 触发。
+     */
+    cleanupOnExit() {
+        this.session.cleanupOnExit();
+    }
+    /** 释放会话（bridge 淘汰槽位时调用，进程组终止）。 */
+    async dispose() {
+        await this.session.dispose();
     }
 }
 //# sourceMappingURL=runner.js.map

package/dist/runner/claude/session.d.ts

@@ -0,0 +1,166 @@
+/**
+ * ClaudeSession: 长驻交互式 Claude Code 会话（stream-json 双向通道）。
+ *
+ * 协议（本机 claude 2.1.233 真实 spike 验证）：
+ * - spawn 参数：
+ *     --output-format stream-json --input-format stream-json
+ *     --permission-prompt-tool stdio --replay-user-messages [--verbose]
+ *     [--permission-mode <mode>] [--resume <sessionId>]
+ * - 用户消息（stdin）：
+ *     {"type":"user","message":{"role":"user","content":"..."}}
+ * - 压缩（stdin）：content 为 "/compact" 时 CLI 本地拦截为 slash 命令（不会
+ *   作为模型提示词），压缩 turn 以普通 result 收尾（真实 claude 2.1.233 实测）。
+ * - 权限请求（stdout）：
+ *     {"type":"control_request","request_id":"...","request":{
+ *       "subtype":"can_use_tool","tool_name":"Bash","input":{...}}}
+ * - 审批响应（stdin）：
+ *     {"type":"control_response","response":{"subtype":"success",
+ *       "request_id":"...","response":{"behavior":"allow","updatedInput":{...}}}}
+ *   deny 时 response={"behavior":"deny","message":"..."}
+ * - AskUserQuestion 走同一通道（tool_name="AskUserQuestion"），选项在
+ *   input.questions[]；答案回填 input.answers 后 allow。
+ * - result 事件 subtype 为 compact/compaction 是 turn 中途压缩，不是 turn 结束；
+ *   其余 subtype（success/error/...）才是 turn 终态。
+ *
+ * 生命周期：一个 workspace 一个长驻进程（lifetime='workspace'）。每次
+ * run(message) = 写一条 user 消息 + 消费 stdout 事件直到本 turn 的 result；
+ * 进程在 turn 之间保持存活（stdin 不关闭），/stop / /new / /cd / 看门狗超时
+ * 时经 ProcessStopper 组杀，下条消息按 SessionStore 的 sessionId --resume。
+ */
+import { SpawningRunner } from '../common/spawning-runner.js';
+import type { AgentEvent, SpawnOptions } from '../types.js';
+export interface ClaudeSessionOptions {
+    pidDir?: string;
+    workspace: string;
+    stopGraceMs?: number;
+    spawnHeartbeatMs?: number;
+    /** Claude 权限模式（官方 --permission-mode 枚举；'default' 省略该参数）。 */
+    permissionMode?: string;
+    settings?: string;
+    model?: string;
+    effort?: string;
+    /** 会话级空闲回收 TTL（ms）：turn 之间无活动超过该窗口则停止进程。0=禁用。 */
+    idleTtlMs?: number;
+}
+/** 审批响应结果（behavior allow/deny）。 */
+export interface PermissionResult {
+    behavior: 'allow' | 'deny';
+    message?: string;
+}
+/**
+ * ClaudeSession extends SpawningRunner 复用其 spawn/pid 文件/killOrphan/
+ * ProcessStopper/SpawnHeartbeat/退出分发器机制（P1-1/P1-10/P1-11 契约保持），
+ * 但 run() 覆盖为「长驻 + 按 turn 消费」：进程跨 turn 存活，turn 结束以
+ * stream-json result 事件（非 compact）为界，而不是进程退出。
+ */
+export declare class ClaudeSession extends SpawningRunner {
+    private readonly permissionMode;
+    private readonly settings?;
+    private readonly defaultModel?;
+    private readonly defaultEffort?;
+    private readonly idleTtlMs;
+    /** 当前 turn 是否在途（防止并发 run 写乱 stdin）。 */
+    private turnActive;
+    /** 本进程是否已收到 system/init（--resume 会先重放上一轮旧 result）。 */
+    private sawInit;
+    /** stdout 流是否已结束（进程退出/崩溃）。 */
+    private streamEnded;
+    /** 最近一次 spawn 的工作目录（control_request 视图用）。 */
+    private cwd;
+    /** 最近一次 init 报告的 session_id（错误结果与视图摘要用）。 */
+    private sessionId;
+    /** 已翻译事件队列（turn 消费循环读取；turn 之间清空）。 */
+    private eventQueue;
+    private waitResolve;
+    /** 待审批的 control_request 原始 input（回写 updatedInput 需要）。 */
+    private pendingToolInputs;
+    /** 允许所有：后续 control_request 自动 allow（本会话进程生命周期内有效）。 */
+    private autoApprove;
+    /** 串行化 stdin 写入（用户消息与审批响应交错到达）。 */
+    private stdinQueue;
+    private startPromise;
+    /**
+     * 进程代际 token：stop()/dispose() 会先把 currentProcess 置 null，流 reader
+     * 的 finally 不能再用 `currentProcess === proc` 判断归属（会漏掉 streamEnded
+     * 唤醒，turn 循环永久挂起）。每次 spawn 递增，旧代际 reader 的残留事件与
+     * 收尾一律跳过。
+     */
+    private processGeneration;
+    private idleTimer;
+    /** 进程退出登记（'close' 事件后 exitCode 才可靠；流结束错误路径 await 它）。 */
+    private processExitPromise;
+    constructor(opts: ClaudeSessionOptions);
+    get pid(): number | undefined;
+    /**
+     * 每 turn 入口：确保进程已 spawn（可带 --resume）→ 写用户消息 → 消费事件
+     * 直到本 turn 的 result。进程在 turn 结束后保持存活，供下一条消息复用。
+     */
+    run(message: string, opts: SpawnOptions): AsyncGenerator<AgentEvent>;
+    /**
+     * 写一条用户消息到 stdin（--input-format stream-json 的 user 事件）。
+     */
+    sendUserMessage(message: string): Promise<void>;
+    /**
+     * 回写审批响应（允许/拒绝）。
+     */
+    respondPermission(requestId: number | string, result: PermissionResult): Promise<void>;
+    /**
+     * 回写 AskUserQuestion 答案：updatedInput = 原 input + answers。
+     */
+    respondAskUserQuestion(requestId: number | string, answers: Record<string, string | string[]>): Promise<void>;
+    /** 允许所有：后续 control_request 自动 allow（本会话进程生命周期内有效）。 */
+    setAutoApprove(value: boolean): void;
+    /** 释放会话：停止进程（优雅 SIGTERM→SIGKILL）。 */
+    dispose(): Promise<void>;
+    /**
+     * 停止会话（覆盖基类以先清空闲回收 timer）。
+     */
+    stop(opts?: {
+        immediate?: boolean;
+    }): Promise<void>;
+    protected getStdio(): ('ignore' | 'pipe')[];
+    protected buildArgv(opts: SpawnOptions): string[];
+    /**
+     * 确保长驻进程已 spawn（首次或上次被停止后）。串行化并发调用。
+     * 返回 null = 成功；返回 string = spawn 失败的错误消息（调用方 yield）。
+     */
+    private startProcess;
+    private doStartProcess;
+    /**
+     * 后台消费 stdout JSONL → 翻译 → 入队。进程退出时清理 pid 文件并标记
+     * streamEnded 唤醒等待中的 turn 循环。
+     */
+    private startStreamReader;
+    /** 最近一次进程退出的 code/signal（流结束错误结果构造用）。 */
+    private exitCode;
+    private exitSignal;
+    /**
+     * 消费事件队列直到本 turn 的 result 事件（非 compact/compaction）。
+     * 消费者提前关闭生成器（bridge 循环体抛错）→ 杀进程防孤儿（P1-11 语义）。
+     *
+     * result = turn 终态（2026-08-16 真实 claude 实测：长驻模式下 result 之后
+     * 不再有 stdout 事件，后台任务完成是静默的；旧 -p 流程「等进程退出再收尾」
+     * 的 post-result drain 在长驻模式下无对应物）。
+     */
+    private consumeTurn;
+    /** 构造进程退出且无终态 result 时的统一错误结果（对齐 SpawningRunner 语义）。 */
+    private buildStreamEndedError;
+    private wakeWaiters;
+    /**
+     * 会话级空闲回收：turn 结束后 idleTtlMs 无新消息则停止进程（对齐 codex
+     * ConnectionManager 的 idle TTL；/cd 遗留的旧 cwd runner 靠它回收）。
+     * turn 在途时永不触发；0 表示禁用。
+     */
+    private armIdleTimer;
+    private clearIdleTimer;
+    private writeUserMessage;
+    private writeControlResponse;
+    /**
+     * 串行化 stdin 写入（互斥）。进程未运行/管道已毁 → 抛错（调用方按需忽略）。
+     */
+    private writeStdin;
+    private translateEvent;
+    private translateControlRequest;
+    /** 统一方案：所有 runner 自己生成 timestamp（缺失时补）。 */
+    private withTimestamp;
+}