lark-remote 0.1.13 → 0.2.0

package/dist/runner/common/acp/base-translator.js

@@ -0,0 +1,271 @@
+import { NotificationMethod, ServerRequestMethod, SessionEventType, } from './protocol-types.js';
+/**
+ * ACP tool kind → 常用工具名映射（信息保真 C3.1，数据驱动无 agent 分支）。
+ * kind 命中映射时用映射名渲染结构化面板；否则回落 title（维持现状）。
+ */
+const KIND_TO_TOOL = {
+    execute: 'Bash',
+    read: 'Read',
+    edit: 'Edit',
+    write: 'Write',
+    search: 'Grep',
+    fetch: 'WebFetch',
+};
+// =============================================================================
+// Translator base class
+// =============================================================================
+export class BaseAcpTranslator {
+    /** Current operation kind (turn vs compact). */
+    operationKind = 'turn';
+    /** Live usage snapshot from usage_update events (context occupancy only). */
+    liveUsage = {};
+    /** Whether any usage_update has been seen this turn (no update → no usage). */
+    hasLiveUsage = false;
+    /** Session cost from usage_update cost.amount (USD). Written by opencode only. */
+    liveCostUsd;
+    /** Current turn id, set by produceTurnStarted. */
+    currentTurnId = '';
+    /**
+     * Handle a notification from the ACP server and return translated events.
+     * Wire envelope: {sessionId, update: {sessionUpdate: '<kind>', ...}} — the
+     * discriminator is `update.sessionUpdate`.
+     */
+    handleNotification(method, params) {
+        if (method !== NotificationMethod.SESSION_UPDATE) {
+            return [];
+        }
+        const notif = params;
+        const update = notif.update;
+        switch (update.sessionUpdate) {
+            case SessionEventType.AGENT_MESSAGE_CHUNK:
+                return this.handleAgentMessageChunk(update, notif.sessionId);
+            case SessionEventType.AGENT_THOUGHT_CHUNK:
+                return this.handleAgentThoughtChunk(update, notif.sessionId);
+            case SessionEventType.TOOL_CALL:
+                return this.handleToolCall(update, notif.sessionId);
+            case SessionEventType.TOOL_CALL_UPDATE:
+                return this.handleToolCallUpdate(update, notif.sessionId);
+            case SessionEventType.USAGE_UPDATE:
+                return this.handleUsageUpdate(update);
+            case SessionEventType.PLAN:
+                return this.handlePlan(update);
+            case SessionEventType.SESSION_INFO_UPDATE: {
+                // 会话标题更新 → session_info 事件（title 缺省时不发，避免空事件噪声）。
+                const info = update;
+                if (!info.title)
+                    return [];
+                const event = {
+                    type: 'session_info',
+                    title: info.title,
+                    timestamp: new Date().toISOString(),
+                };
+                return [event];
+            }
+            case SessionEventType.CURRENT_MODE_UPDATE: {
+                // 模式切换 → session_info 事件（mode 字段）。
+                const mode = update;
+                const event = {
+                    type: 'session_info',
+                    mode: mode.currentModeId,
+                    timestamp: new Date().toISOString(),
+                };
+                return [event];
+            }
+            default:
+                // Control-plane noise (config echoes, user replay) — not content.
+                // available_commands_update / config_option_update 维持丢弃：
+                // 控制面回显，无用户价值。
+                return [];
+        }
+    }
+    /**
+     * Handle a server request (reverse RPC from the ACP server). Subclasses
+     * hook additional methods via handleOtherServerRequest.
+     */
+    handleServerRequest(id, method, params) {
+        if (method === ServerRequestMethod.REQUEST_PERMISSION) {
+            return this.handleRequestPermission(id, params);
+        }
+        return this.handleOtherServerRequest(id, method, params);
+    }
+    /** Hook for server requests other than session/request_permission. */
+    handleOtherServerRequest(_id, _method, _params) {
+        return [];
+    }
+    /**
+     * Produce a turn_started event. Called by the runner when session/prompt
+     * is sent (no wire notification for this — self-produced).
+     */
+    produceTurnStarted(sessionId, turnId) {
+        this.currentTurnId = turnId;
+        return {
+            type: 'turn_started',
+            threadId: sessionId,
+            turnId,
+            operationKind: this.operationKind === 'compact' ? 'compaction' : 'turn',
+            timestamp: new Date().toISOString(),
+        };
+    }
+    /**
+     * Translate a prompt response into a result event.
+     * stopReason: end_turn → success; cancelled → interrupted (independent
+     * terminal state, must NOT merge into error); anything else
+     * (max_tokens / refusal / …) → error.
+     */
+    handlePromptResponse(sessionId, result) {
+        const subtype = result.stopReason === 'end_turn'
+            ? 'success'
+            : result.stopReason === 'cancelled'
+                ? 'interrupted'
+                : 'error';
+        return {
+            type: 'result',
+            subtype,
+            session_id: sessionId,
+            ...(this.hasLiveUsage ? { usage: this.liveUsageSnapshot() } : {}),
+            ...(this.liveCostUsd !== undefined ? { total_cost_usd: this.liveCostUsd } : {}),
+            ...(subtype === 'error'
+                ? { errorMessage: `Prompt ended with stopReason: ${result.stopReason}` }
+                : {}),
+        };
+    }
+    /**
+     * Produce an error result event (for JSON-RPC errors during prompt).
+     */
+    produceErrorResult(sessionId, errorMessage) {
+        return {
+            type: 'result',
+            subtype: 'error',
+            session_id: sessionId,
+            errorMessage,
+            ...(this.hasLiveUsage ? { usage: this.liveUsageSnapshot() } : {}),
+            ...(this.liveCostUsd !== undefined ? { total_cost_usd: this.liveCostUsd } : {}),
+        };
+    }
+    /**
+     * Set the operation kind (turn vs compact).
+     */
+    setOperationKind(kind) {
+        this.operationKind = kind;
+    }
+    // =========================================================================
+    // Shared notification handlers
+    // =========================================================================
+    /**
+     * plan update → PlanEvent（信息保真 C3.2：不再显式丢弃）。
+     * ACP PlanEntry: { content, priority, status }（status: pending/in_progress/
+     * completed）。基类具体方法：kimi/opencode wire 结构相同，直接复用。
+     */
+    handlePlan(event) {
+        const ICON = { completed: '✅', in_progress: '🔄', pending: '⬜', error: '❌' };
+        const entries = Array.isArray(event.entries) ? event.entries : [];
+        const markdown = entries
+            .map((e) => {
+            const entry = e;
+            const status = entry.status && entry.status in ICON ? entry.status : 'pending';
+            return `${ICON[status]} ${entry.content ?? ''}`;
+        })
+            .join('\n')
+            .trim();
+        if (!markdown)
+            return [];
+        return [{ type: 'plan', plan: markdown, timestamp: new Date().toISOString() }];
+    }
+    /**
+     * tool_call → assistant/tool_use. rawInput normalization is contractual:
+     * missing → {} (lazy-create tool_call carries no rawInput field), string →
+     * JSON.parse (older agents send JSON strings) — keeps the card from
+     * crashing on undefined input.
+     *
+     * 信息保真 C3.1：kind 命中 KIND_TO_TOOL 时用映射名渲染结构化面板；
+     * title 与 name 不同时把 title 存到 content block 的 summary 字段
+     * （渲染层做面板副标题）。
+     */
+    handleToolCall(event, _sessionId) {
+        let input = event.rawInput ?? {};
+        if (typeof event.rawInput === 'string') {
+            try {
+                input = JSON.parse(event.rawInput);
+            }
+            catch {
+                // Keep raw string as-is
+            }
+        }
+        const mapped = event.kind ? KIND_TO_TOOL[event.kind] : undefined;
+        const name = mapped ?? event.title;
+        const summary = mapped && event.title && event.title !== name ? event.title : undefined;
+        return [
+            {
+                type: 'assistant',
+                message: {
+                    content: [
+                        {
+                            type: 'tool_use',
+                            id: event.toolCallId,
+                            name,
+                            input,
+                            ...(summary !== undefined ? { summary } : {}),
+                        },
+                    ],
+                },
+                timestamp: new Date().toISOString(),
+            },
+        ];
+    }
+    /**
+     * tool_call_update → user/tool_result. status:'failed' → is_error:true.
+     */
+    handleToolCallUpdate(event, _sessionId) {
+        const isError = event.status === 'failed';
+        const content = this.extractToolResultContent(event);
+        return [
+            {
+                type: 'user',
+                message: {
+                    content: [
+                        {
+                            type: 'tool_result',
+                            tool_use_id: event.toolCallId,
+                            content,
+                            is_error: isError,
+                        },
+                    ],
+                },
+                timestamp: new Date().toISOString(),
+            },
+        ];
+    }
+    /**
+     * tool_result content extraction. Default: rawOutput passthrough (kimi
+     * semantics). opencode overrides — its rawOutput is an OBJECT
+     * ({output} / {error}).
+     */
+    extractToolResultContent(event) {
+        return event.rawOutput ?? '';
+    }
+    /**
+     * usage_update → context occupancy bookkeeping. The wire shape is
+     * {used, size} (+ opencode: cost:{amount}) — context occupancy, not
+     * cumulative tokens.
+     */
+    handleUsageUpdate(event) {
+        this.liveUsage = {
+            total_tokens: event.used,
+            context_limit: event.size,
+        };
+        this.hasLiveUsage = true;
+        this.onUsageSample(event);
+        return [];
+    }
+    /** Extra per-sample usage bookkeeping (opencode: session cost amount). */
+    onUsageSample(_event) { }
+    /**
+     * ResultEvent.usage requires input_tokens/output_tokens: number, but the
+     * ACP wire has no such split — the live snapshot is context occupancy only.
+     * Cast is deliberate: consumers must tolerate undefined input/output.
+     */
+    liveUsageSnapshot() {
+        return { ...this.liveUsage };
+    }
+}
+//# sourceMappingURL=base-translator.js.map

package/dist/runner/common/acp/protocol-helpers.d.ts

@@ -4,6 +4,7 @@
  * Extracted from runner.ts and translator.ts to avoid duplication (G5).
  * Shape source: approval.ts:28-29 — optionId is opaque, echo back as-is.
  */
+import type { ApprovalView } from '../../types.js';
 import type { PermissionOption } from './protocol-types.js';
 /**
  * Find an option by matching its `kind` against a list of candidate values,
@@ -43,3 +44,41 @@ export declare function buildAcpPermissionOutcome(action: string, options: Permi
 export declare function deriveAcpAvailableDecisions(options: PermissionOption[]): string[];
 /** 截断长文本并追加省略号（translator 审批 reason 用，原先两份相同拷贝）。 */
 export declare function truncateWithEllipsis(text: string, maxLen: number): string;
+/**
+ * 待审批请求登记（requestId → 登记，runner 持 Map）。
+ * kimi 的提问分叉额外带 proto 来源标记。
+ */
+export interface AcpPendingApproval {
+    kind: 'command' | 'file' | 'permissions' | 'question' | 'tool';
+    view: ApprovalView;
+    options: PermissionOption[];
+    /** 提问来源（kimi elicitation）：elicitation form / request_permission 兜底桥。 */
+    proto?: 'elicitation' | 'permission';
+}
+/**
+ * respondApproval 共用骨架：取 pending → 构建 ACP 响应 → respond + 清除 + 日志。
+ * buildOutcome 由调用方注入（kimi question 走 elicitation 回编，其余走
+ * buildAcpPermissionOutcome）。client 缺失或 requestId 未知时静默丢弃。
+ */
+export declare function respondAcpApproval(opts: {
+    client: {
+        respond(requestId: number | string, response: unknown): void;
+    } | null | undefined;
+    pendingApprovals: Map<number | string, AcpPendingApproval>;
+    requestId: number | string;
+    response: unknown;
+    logTag: string;
+    buildOutcome: (action: string, pending: AcpPendingApproval, response: unknown) => unknown;
+}): void;
+/**
+ * updateApprovalMode 共用尾段：本地缓存已由调用方按各自语义更新，会话在连时
+ * 重发 session/set_mode。失败非致命（下一次 setupTurn 会重新套用缓存模式）。
+ */
+export declare function sendAcpSetMode(opts: {
+    client: {
+        request(method: string, params: unknown): Promise<unknown>;
+    } | null | undefined;
+    activeSessionId: string | null | undefined;
+    modeId: string;
+    logTag: string;
+}): Promise<void>;

package/dist/runner/common/acp/protocol-helpers.js

@@ -4,6 +4,7 @@
  * Extracted from runner.ts and translator.ts to avoid duplication (G5).
  * Shape source: approval.ts:28-29 — optionId is opaque, echo back as-is.
  */
+import { getLogger } from '../../../logger/index.js';
 /**
  * Find an option by matching its `kind` against a list of candidate values,
  * and return the `optionId` to echo back in the approval response.
@@ -66,4 +67,37 @@ export function deriveAcpAvailableDecisions(options) {
 export function truncateWithEllipsis(text, maxLen) {
     return text.length <= maxLen ? text : text.slice(0, maxLen) + '…';
 }
+/**
+ * respondApproval 共用骨架：取 pending → 构建 ACP 响应 → respond + 清除 + 日志。
+ * buildOutcome 由调用方注入（kimi question 走 elicitation 回编，其余走
+ * buildAcpPermissionOutcome）。client 缺失或 requestId 未知时静默丢弃。
+ */
+export function respondAcpApproval(opts) {
+    const pending = opts.pendingApprovals.get(opts.requestId);
+    if (!opts.client || !pending)
+        return;
+    const action = opts.response?.action ?? 'decline';
+    const acpResponse = opts.buildOutcome(action, pending, opts.response);
+    opts.client.respond(opts.requestId, acpResponse);
+    opts.pendingApprovals.delete(opts.requestId);
+    getLogger().info(`[${opts.logTag}] approval responded requestId=${opts.requestId} action=${action}`);
+}
+/**
+ * updateApprovalMode 共用尾段：本地缓存已由调用方按各自语义更新，会话在连时
+ * 重发 session/set_mode。失败非致命（下一次 setupTurn 会重新套用缓存模式）。
+ */
+export async function sendAcpSetMode(opts) {
+    if (!opts.client || !opts.activeSessionId)
+        return;
+    try {
+        await opts.client.request('session/set_mode', {
+            sessionId: opts.activeSessionId,
+            modeId: opts.modeId,
+        });
+        getLogger().info(`[${opts.logTag}] session/set_mode hot-applied session=${opts.activeSessionId} modeId=${opts.modeId}`);
+    }
+    catch (err) {
+        getLogger().warn(`[${opts.logTag}] session/set_mode failed (non-fatal): ${err.message}`);
+    }
+}
 //# sourceMappingURL=protocol-helpers.js.map

package/dist/runner/common/jsonrpc/transport.d.ts

@@ -22,6 +22,8 @@ export declare class JsonlRpcTransport {
     /** JSON lines buffered while stdin is under backpressure (bounded by callers). */
     private writeQueue;
     private flushing;
+    /** §4.4 win32 嗅探嫌疑标记（双条件定性见下方 onExit）。 */
+    private commandNotFoundSeen;
     constructor(opts: {
         binary: string;
         args: string[];

package/dist/runner/common/jsonrpc/transport.js

@@ -6,7 +6,7 @@
  * each line on stdout is a JSON message from the server; each `write()`
  * sends a JSON line to stdin.
  */
-import { spawn } from 'node:child_process';
+import { spawnProcess, mergeProcessEnv, isWindowsCommandNotFoundLine, useDetachedProcessGroup, } from '../../../platform/spawn.js';
 import { ProcessStopper } from '../process-stopper.js';
 import { getLogger } from '../../../logger/index.js';
 /** Max bytes for a single line before we disconnect (10MB). */
@@ -25,6 +25,8 @@ export class JsonlRpcTransport {
     /** JSON lines buffered while stdin is under backpressure (bounded by callers). */
     writeQueue = [];
     flushing = false;
+    /** §4.4 win32 嗅探嫌疑标记（双条件定性见下方 onExit）。 */
+    commandNotFoundSeen = false;
     constructor(opts) {
         this.binary = opts.binary;
         this.args = opts.args;
@@ -41,14 +43,18 @@ export class JsonlRpcTransport {
      */
     async start(events) {
         this.events = events;
+        this.commandNotFoundSeen = false;
         // agent 是用户自己的可信二进制，provider 认证依赖 API key /
         // 自定义 provider 的 env_key，代理环境依赖 HTTP(S)_PROXY、TMPDIR 等；
         // 任何白名单收窄都会打断认证或网络。调用方 this.env 覆盖 process.env 同名键。
-        const childEnv = { ...process.env, ...this.env };
-        const proc = spawn(this.binary, this.args, {
+        // env 覆盖必须大小写不敏感合并（win32 PATH/Path 双键防护，v2 §8.3）
+        const childEnv = mergeProcessEnv(process.env, this.env);
+        const proc = spawnProcess(this.binary, this.args, {
             cwd: this.cwd,
             stdio: ['pipe', 'pipe', 'pipe'],
-            detached: true,
+            // posix 建新进程组（负 PID 组杀）；win32 不 detached（`.cmd` 垫片丢 stdio）
+            detached: useDetachedProcessGroup(),
+            windowsHide: true,
             env: childEnv,
         });
         this.proc = proc;
@@ -74,6 +80,14 @@ export class JsonlRpcTransport {
             const text = chunk.toString('utf-8');
             stderrBuf = (stderrBuf + text).slice(-MAX_STDERR_BYTES);
             getLogger().debug(`[jsonrpc-transport] stderr: ${text.trimEnd()}`);
+            // §4.4 win32 command-not-found 嗅探：命中只记嫌疑标记，不立即杀——
+            // agent 正常输出可能引用该错误文本（调试 Windows 报错场景），见行即杀
+            // 会误杀 run；定性由 onExit 的「标记 + 非零退出」双条件完成，真挂起由
+            // 上层超时兜底
+            if (isWindowsCommandNotFoundLine(text)) {
+                this.commandNotFoundSeen = true;
+                getLogger().error(`[jsonrpc-transport] command not found suspected (win32 shim): ${text.trimEnd()}`);
+            }
         });
         // Stdout: line-split with 10MB line limit
         let remainder = '';
@@ -113,7 +127,13 @@ export class JsonlRpcTransport {
                     // ignore trailing incomplete line
                 }
             }
-            const reason = signal ? `signal:${signal}` : `exit:${code}`;
+            // §4.4 双条件定性：嫌疑标记 + 非零正常退出 → command-not-found。
+            // reason 仅供日志/诊断，消费方不解析该字符串（baseOnClose 无参）。
+            let reason = signal ? `signal:${signal}` : `exit:${code}`;
+            if (this.commandNotFoundSeen && signal === null && code !== null && code !== 0) {
+                getLogger().error(`[jsonrpc-transport] command not found confirmed (win32 shim): exit=${code} stderr=${stderrBuf.slice(-512)}`);
+                reason = `command_not_found:${reason}`;
+            }
             events.onClose(reason);
             getLogger().info(`[jsonrpc-transport] process exited pid=${proc.pid} code=${code} signal=${signal}`);
         };

package/dist/runner/common/process-stopper.d.ts

@@ -1,29 +1,7 @@
-import type { ChildProcess } from 'node:child_process';
-interface ProcessStopperOptions {
-    graceMs: number;
-}
-interface StopOptions {
-    immediate?: boolean;
-}
 /**
- * Unified process stop logic: SIGTERM → grace period → SIGKILL.
+ * 已迁移到平台 seam：`src/platform/terminator-posix.ts`（design.md §3.2）。
  *
- * Extracts the common pattern shared by ClaudeRunner and BashProcessRunner
- * so both use identical stop semantics.
+ * 本文件只保留 re-export，使既有调用方（bash runner、jsonrpc transport 等）
+ * 与既有测试不受影响；M2 调用点迁移时逐个换成 `createTerminator()` 后删除。
  */
-export declare class ProcessStopper {
-    private graceMs;
-    constructor(opts: ProcessStopperOptions);
-    /**
-     * Stop a child process: SIGTERM → wait grace → SIGKILL.
-     *
-     * Uses negative PID to kill the entire process group, ensuring child
-     * processes (shell wrappers, sub-processes) are also terminated.
-     *
-     * Pass `immediate: true` to skip the grace window — SIGTERM and SIGKILL
-     * are sent back-to-back. Safe to call on an already-exited process.
-     */
-    /** proc 可为 null（调用方已清理 currentProcess）；nullish 直接返回。 */
-    stop(proc: ChildProcess | null, opts?: StopOptions): Promise<void>;
-}
-export {};
+export { ProcessStopper } from '../../platform/terminator-posix.js';

package/dist/runner/common/process-stopper.js

@@ -1,80 +1,8 @@
-import { getLogger } from '../../logger/index.js';
 /**
- * Unified process stop logic: SIGTERM → grace period → SIGKILL.
+ * 已迁移到平台 seam：`src/platform/terminator-posix.ts`（design.md §3.2）。
  *
- * Extracts the common pattern shared by ClaudeRunner and BashProcessRunner
- * so both use identical stop semantics.
+ * 本文件只保留 re-export，使既有调用方（bash runner、jsonrpc transport 等）
+ * 与既有测试不受影响；M2 调用点迁移时逐个换成 `createTerminator()` 后删除。
  */
-export class ProcessStopper {
-    graceMs;
-    constructor(opts) {
-        this.graceMs = opts.graceMs;
-    }
-    /**
-     * Stop a child process: SIGTERM → wait grace → SIGKILL.
-     *
-     * Uses negative PID to kill the entire process group, ensuring child
-     * processes (shell wrappers, sub-processes) are also terminated.
-     *
-     * Pass `immediate: true` to skip the grace window — SIGTERM and SIGKILL
-     * are sent back-to-back. Safe to call on an already-exited process.
-     */
-    /** proc 可为 null（调用方已清理 currentProcess）；nullish 直接返回。 */
-    async stop(proc, opts) {
-        if (!proc || proc.exitCode !== null || proc.signalCode !== null) {
-            return;
-        }
-        const pid = proc.pid;
-        if (pid === undefined) {
-            return;
-        }
-        // Use negative PID to kill the entire process group.
-        // This ensures child processes (shell wrappers, sub-processes) are also killed.
-        // If the process is not a group leader, kill(-pid) behaves same as kill(pid).
-        const pgid = -pid;
-        const immediate = opts?.immediate === true;
-        getLogger().debug(`[process-stopper] sending SIGTERM to pgid=${pgid} immediate=${immediate}`);
-        try {
-            process.kill(pgid, 'SIGTERM');
-        }
-        catch {
-            /* process may have exited */
-        }
-        if (immediate) {
-            // Don't wait — send SIGKILL back-to-back. Even if proc just exited
-            // from SIGTERM, kill(SIGKILL) on a dead pid throws ESRCH which we ignore.
-            try {
-                process.kill(pgid, 'SIGKILL');
-            }
-            catch { }
-        }
-        else {
-            // Wait for exit with grace period. Use `once` so repeated stop() calls
-            // don't accumulate listeners on the proc. P2-15: save the grace timer id
-            // and clear it once the race settles — otherwise the timer lingers after
-            // an early exit, keeping the event loop alive and accumulating across
-            // frequent stop() calls.
-            let graceTimer;
-            const exited = await Promise.race([
-                new Promise((resolve) => {
-                    if (proc.exitCode !== null || proc.signalCode !== null)
-                        return resolve(true);
-                    proc.once('exit', () => resolve(true));
-                }),
-                new Promise((resolve) => {
-                    graceTimer = setTimeout(() => resolve(false), this.graceMs);
-                }),
-            ]);
-            if (graceTimer)
-                clearTimeout(graceTimer);
-            if (!exited) {
-                getLogger().info(`[process-stopper] process group ${pgid} did not exit within grace period, sending SIGKILL`);
-                try {
-                    process.kill(pgid, 'SIGKILL');
-                }
-                catch { }
-            }
-        }
-    }
-}
+export { ProcessStopper } from '../../platform/terminator-posix.js';
 //# sourceMappingURL=process-stopper.js.map

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

@@ -1,9 +1,4 @@
 import type { AgentEvent } from '../types.js';
-/**
- * Return the stdio config ['pipe','pipe','pipe'] used by the runner that
- * writes the prompt to the child's stdin (claude).
- */
-export declare function pipeAllStdio(): ('ignore' | 'pipe')[];
 /**
  * Build a synthetic system.init event for pre-spawn failure paths.
  *

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

@@ -1,10 +1,3 @@
-/**
- * Return the stdio config ['pipe','pipe','pipe'] used by the runner that
- * writes the prompt to the child's stdin (claude).
- */
-export function pipeAllStdio() {
-    return ['pipe', 'pipe', 'pipe'];
-}
 /**
  * Build a synthetic system.init event for pre-spawn failure paths.
  *