lark-remote 0.1.6 → 0.1.7

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

@@ -0,0 +1,448 @@
+/**
+ * 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 { ConnectionManager as KimiAcpConnectionManager, } from '../../common/jsonrpc/connection-manager.js';
+import { KimiAcpTranslator } from './translator.js';
+import { RpcErrorCode, ServerRequestMethod, } from '../../common/acp/protocol-types.js';
+import { findOptionIdByKind } from '../../common/acp/protocol-helpers.js';
+import { getLogger } from '../../../logger/index.js';
+import { ConnectionBasedRunner } from '../../common/connection-based-runner.js';
+/** R2: how long to wait for the background compaction record after the
+ *  /compact prompt settles (design doc §6.1). Real kimi 0.36.0 lands
+ *  context.apply_compaction ~8s after end_turn. */
+const COMPACT_POLL_TIMEOUT_MS = 30_000;
+/** Poll interval for the wire.jsonl compaction record. */
+const COMPACT_POLL_INTERVAL_MS = 1_000;
+/**
+ * Map user-facing permission mode to ACP mode id.
+ *
+ * ACP layer mode ids (acp-server/src/modes.ts:49):
+ *   default → permission manual
+ *   auto    → permission auto
+ *   yolo    → permission yolo
+ *   plan    → not exposed in v1
+ *
+ * This is not self-invented naming — both are official enums at their
+ * respective layers. The mapping happens only at the ACP boundary.
+ */
+function toAcpMode(mode) {
+    switch (mode) {
+        case 'manual':
+            return 'default';
+        case 'auto':
+            return 'auto';
+        case 'yolo':
+            return 'yolo';
+    }
+}
+/**
+ * Build the ACP protocol response for a permission approval decision.
+ *
+ * accept            → {outcome:{outcome:'selected', optionId:<approve_once kind>}}
+ * accept_for_session → {outcome:{outcome:'selected', optionId:<approve_always kind>}}
+ * decline           → {outcome:{outcome:'selected', optionId:<reject kind>}}
+ * cancel            → {outcome:{outcome:'cancelled'}}
+ *
+ * optionId is looked up from the request's options[] by kind (approval.ts:28-29):
+ * approve_once / approve_always / allow_once for accept;
+ * approve_always / allow_always for accept_for_session;
+ * reject / reject_once for decline. If not found, fall back to cancelled
+ * (safe universal default — the server treats it as "user declined").
+ *
+ * 2026-08-15 live test: approve_once + approve_always + reject observed.
+ */
+function buildApprovalResponse(action, pending) {
+    if (action === 'cancel') {
+        return { outcome: { outcome: 'cancelled' } };
+    }
+    if (action === 'accept') {
+        const optionId = findOptionIdByKind(pending.options, [
+            'approve_once',
+            'approve_always',
+            'allow_once',
+        ]);
+        if (optionId) {
+            return { outcome: { outcome: 'selected', optionId } };
+        }
+        // Fallback: can't find allow option → cancel is safe
+        return { outcome: { outcome: 'cancelled' } };
+    }
+    if (action === 'accept_for_session') {
+        // §P4: 卡片「允许本次会话」→ always 类 optionId（kimi approve_always）
+        const optionId = findOptionIdByKind(pending.options, ['approve_always', 'allow_always']);
+        if (optionId) {
+            return { outcome: { outcome: 'selected', optionId } };
+        }
+        return { outcome: { outcome: 'cancelled' } };
+    }
+    // decline
+    const optionId = findOptionIdByKind(pending.options, ['reject', 'reject_once']);
+    if (optionId) {
+        return { outcome: { outcome: 'selected', optionId } };
+    }
+    return { outcome: { outcome: 'cancelled' } };
+}
+// =============================================================================
+// Runner
+// =============================================================================
+export class KimiAcpRunner extends ConnectionBasedRunner {
+    connectionManager;
+    currentTranslator = null;
+    activeSessionId = null;
+    model;
+    permissionMode;
+    compactPollTimeoutMs;
+    /** Pending approval requests: requestId → kind + view + options. */
+    pendingApprovals = new Map();
+    /** Tracker for the in-flight prompt request — needed for cancellation. */
+    promptSettled = false;
+    constructor(opts) {
+        super({ kind: opts.kind, sessionReader: opts.sessionReader }, opts.turnIdleTimeoutMs);
+        this.model = opts.model;
+        this.permissionMode = opts.permissionMode ?? 'manual';
+        this.compactPollTimeoutMs = opts.compactPollTimeoutMs ?? COMPACT_POLL_TIMEOUT_MS;
+        const managerOpts = {
+            binary: opts.binary ?? 'kimi',
+            args: opts.acpArgs ?? ['acp'],
+            env: opts.env,
+            requestTimeoutMs: opts.requestTimeoutMs,
+            idleTtlMs: opts.idleTtlMs,
+            initializeParams: {
+                protocolVersion: 1,
+                clientCapabilities: {
+                    fs: { readTextFile: false, writeTextFile: false },
+                    terminal: false,
+                },
+            },
+        };
+        this.connectionManager = new KimiAcpConnectionManager(managerOpts);
+    }
+    get logTag() {
+        return 'kimi-acp-runner';
+    }
+    get turnTimeoutErrorMessage() {
+        return 'Kimi ACP turn timed out';
+    }
+    get turnInterruptedErrorMessage() {
+        return 'Kimi ACP turn interrupted';
+    }
+    currentSessionId() {
+        return this.activeSessionId;
+    }
+    shouldDeferStop() {
+        return !this.promptSettled;
+    }
+    async cancelCurrentTurn() {
+        if (!this.currentClient || !this.activeSessionId)
+            return;
+        try {
+            // session/cancel is a NOTIFICATION (no id, no response) per ACP spec.
+            const cancelParams = { sessionId: this.activeSessionId };
+            this.currentClient.notify('session/cancel', cancelParams);
+        }
+        catch (err) {
+            getLogger().warn(`[${this.logTag}] session/cancel failed: ${err.message}`);
+        }
+    }
+    clearTurnState() {
+        this.currentTranslator = null;
+        this.promptSettled = false;
+        this.activeSessionId = null;
+    }
+    async releaseConnection(cwd) {
+        await this.connectionManager.release(cwd);
+    }
+    notifyIdle(cwd) {
+        this.connectionManager.notifyIdle(cwd);
+    }
+    async disposeConnections() {
+        await this.connectionManager.disposeAll();
+    }
+    /**
+     * 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.
+     */
+    async *runCompact(_message, opts) {
+        yield* this.executeTurn(opts, async () => {
+            const client = await this.connectionManager.acquire(opts.cwd);
+            this.connectionManager.notifyActivity(opts.cwd);
+            this.currentClient = client;
+            client.setHooks({
+                onNotification: (method, params) => this.handleNotification(method, params),
+                onServerRequest: (id, method, params) => this.handleServerRequest(id, method, params),
+                onClose: () => this.failTurn('Kimi ACP connection closed'),
+            });
+            const sessionId = opts.sessionId;
+            if (!sessionId) {
+                throw new Error('compact requires a sessionId');
+            }
+            this.activeSessionId = sessionId;
+            // Cold-connection fallback: session/resume loads the session into memory.
+            // On a reused connection the session is already loaded — resume is
+            // idempotent and harmless; after connection rebuild it's required.
+            const resumeParams = {
+                sessionId,
+                cwd: opts.cwd,
+            };
+            await client.request('session/resume', resumeParams);
+            const translator = new KimiAcpTranslator();
+            translator.setOperationKind('compact');
+            this.currentTranslator = translator;
+            // Emit turn_started with operationKind='compaction' before the prompt
+            // (consumeTurn yields it while the background compaction runs).
+            const turnId = `compact-${Date.now()}`;
+            const turnStarted = translator.produceTurnStarted(sessionId, turnId);
+            this.currentTurnId = turnId;
+            this.pushEvents([turnStarted]);
+            // Send /compact as prompt text
+            const promptParams = {
+                sessionId,
+                prompt: [{ type: 'text', text: '/compact' }],
+            };
+            // R2: compaction is a BACKGROUND task — the prompt settles before the
+            // wire.jsonl compaction record lands (real kimi: ~8s). Baseline the
+            // record count, fire the prompt without awaiting (notifications flow
+            // through consumeTurn), then poll for a NEW record before producing
+            // the result. This keeps the connection alive while the background
+            // compaction finishes — otherwise dispose/exit kills it and the record
+            // never lands (S5/S6 打回复现).
+            const compactionReader = this.sessionReader.readCompactionRecords;
+            const baselineCount = compactionReader
+                ? compactionReader.call(this.sessionReader, sessionId, opts.cwd).length
+                : 0;
+            this.promptSettled = false;
+            // ACP holds the session/prompt response for the ENTIRE turn (unlike
+            // codex turn/start), so the RPC-level timeout must not apply here —
+            // turn liveness is guarded by the rolling idle watchdog instead.
+            const promptPromise = client.request('session/prompt', promptParams, Number.POSITIVE_INFINITY);
+            promptPromise.then(async (result) => {
+                this.promptSettled = true;
+                if (this.stopRequested)
+                    return; // already cancelled
+                if (compactionReader) {
+                    await this.waitForCompactionRecord(compactionReader, opts, baselineCount);
+                }
+                if (this.forceFinish)
+                    return; // stopped while polling
+                // Translate prompt result into a result event
+                const resultEvent = translator.handlePromptResponse(sessionId, result);
+                this.pushEvents([resultEvent]);
+            }, (err) => {
+                this.promptSettled = true;
+                if (this.stopRequested) {
+                    getLogger().warn(`[${this.logTag}] compact prompt rejected after stopRequested: ${err.message}`);
+                    return;
+                }
+                const resultEvent = translator.produceErrorResult(sessionId, err.message);
+                this.pushEvents([resultEvent]);
+            });
+        });
+    }
+    /**
+     * Respond to an approval server request. `response` is the bridge
+     * ApprovalAction (`{ action: 'accept' | 'decline' | 'cancel' }`).
+     */
+    async respondApproval(requestId, response) {
+        const client = this.currentClient;
+        const pending = this.pendingApprovals.get(requestId);
+        if (!client || !pending)
+            return;
+        const action = response?.action ?? 'decline';
+        const acpResponse = buildApprovalResponse(action, pending);
+        client.respond(requestId, acpResponse);
+        this.pendingApprovals.delete(requestId);
+        getLogger().info(`[${this.logTag}] approval responded requestId=${requestId} action=${action}`);
+    }
+    getStatusInfo() {
+        return {
+            kind: this.kind,
+            model: this.model ?? '(kimi-acp)',
+            extras: {
+                mode: 'acp',
+                permissionMode: this.permissionMode,
+            },
+        };
+    }
+    /**
+     * 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.
+     */
+    async updateApprovalMode(settings) {
+        if (settings.permissionMode !== undefined) {
+            this.permissionMode = settings.permissionMode;
+        }
+        if (!this.currentClient || !this.activeSessionId)
+            return;
+        const modeParams = {
+            sessionId: this.activeSessionId,
+            modeId: toAcpMode(this.permissionMode),
+        };
+        try {
+            await this.currentClient.request('session/set_mode', modeParams);
+            getLogger().info(`[${this.logTag}] session/set_mode hot-applied session=${this.activeSessionId} modeId=${modeParams.modeId}`);
+        }
+        catch (err) {
+            getLogger().warn(`[${this.logTag}] session/set_mode failed (non-fatal): ${err.message}`);
+        }
+    }
+    // =========================================================================
+    // Internal
+    // =========================================================================
+    /**
+     * Acquire the connection and set up the turn:
+     * session/new (new session) or session/resume (existing sessionId)
+     * → set permission mode if needed → session/prompt.
+     */
+    async setupTurn(message, opts) {
+        const client = await this.connectionManager.acquire(opts.cwd);
+        this.connectionManager.notifyActivity(opts.cwd);
+        this.currentClient = client;
+        client.setHooks({
+            onNotification: (method, params) => this.handleNotification(method, params),
+            onServerRequest: (id, method, params) => this.handleServerRequest(id, method, params),
+            onClose: () => {
+                getLogger().warn(`[${this.logTag}] client connection closed`);
+                this.failTurn('Kimi ACP connection closed');
+            },
+        });
+        let sessionId;
+        if (opts.sessionId) {
+            const resumeParams = {
+                sessionId: opts.sessionId,
+                cwd: opts.cwd,
+            };
+            await client.request('session/resume', resumeParams);
+            sessionId = opts.sessionId;
+        }
+        else {
+            const newParams = { cwd: opts.cwd, mcpServers: [] };
+            const newResult = await client.request('session/new', newParams);
+            sessionId = newResult.sessionId;
+        }
+        this.activeSessionId = sessionId;
+        // Set permission mode (§5.1): EVERY fresh ACP session starts in
+        // 'default' (= manual approvals, acp-server modes.ts DEFAULT_MODE_ID),
+        // so the mode must be sent unconditionally — skipping yolo leaves the
+        // session in manual and tool calls stall on unanswered approvals
+        // (live dark-test repro: approval_requested → idle timeout).
+        const modeParams = {
+            sessionId,
+            modeId: toAcpMode(this.permissionMode),
+        };
+        try {
+            await client.request('session/set_mode', modeParams);
+        }
+        catch (err) {
+            getLogger().warn(`[${this.logTag}] session/set_mode failed (non-fatal): ${err.message}`);
+        }
+        const translator = new KimiAcpTranslator();
+        this.currentTranslator = translator;
+        // Emit turn_started before prompt
+        const turnId = `turn-${Date.now()}`;
+        const turnStarted = translator.produceTurnStarted(sessionId, turnId);
+        this.currentTurnId = turnId;
+        this.pushEvents([turnStarted]);
+        // Send the prompt
+        const promptParams = {
+            sessionId,
+            prompt: [{ type: 'text', text: message }],
+        };
+        // Fire the prompt request; notifications will be buffered in the queue.
+        // We process them concurrently.
+        this.promptSettled = false;
+        const promptPromise = client.request('session/prompt', promptParams, Number.POSITIVE_INFINITY);
+        // Wait for prompt to settle, then push the result event.
+        // Notifications are pushed concurrently by the hook handlers.
+        promptPromise.then((result) => {
+            this.promptSettled = true;
+            if (this.stopRequested)
+                return; // already cancelled
+            const resultEvent = translator.handlePromptResponse(sessionId, result);
+            this.pushEvents([resultEvent]);
+        }, (err) => {
+            this.promptSettled = true;
+            if (this.stopRequested) {
+                getLogger().warn(`[${this.logTag}] prompt rejected after stopRequested: ${err.message}`);
+                return;
+            }
+            const resultEvent = translator.produceErrorResult(sessionId, err.message);
+            this.pushEvents([resultEvent]);
+        });
+    }
+    /**
+     * 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.
+     */
+    async waitForCompactionRecord(reader, opts, baselineCount) {
+        const sessionId = this.activeSessionId ?? opts.sessionId ?? '';
+        const deadline = Date.now() + this.compactPollTimeoutMs;
+        while (Date.now() < deadline) {
+            if (this.forceFinish || this.stopRequested)
+                return;
+            const records = reader.call(this.sessionReader, sessionId, opts.cwd);
+            if (records.length > baselineCount) {
+                getLogger().info(`[${this.logTag}] compaction record observed (${records.length} > baseline ${baselineCount})`);
+                return;
+            }
+            await new Promise((resolve) => setTimeout(resolve, COMPACT_POLL_INTERVAL_MS));
+        }
+        getLogger().warn(`[${this.logTag}] compaction record not observed within ${this.compactPollTimeoutMs}ms (baseline=${baselineCount}); proceeding without confirmation`);
+    }
+    handleNotification(method, params) {
+        const events = this.currentTranslator?.handleNotification(method, params) ?? [];
+        this.pushEvents(events);
+    }
+    handleServerRequest(id, method, params) {
+        const events = this.currentTranslator?.handleServerRequest(id, method, params) ?? [];
+        if (events.length === 0) {
+            // Unhandled/unsupported server request must be explicitly responded to
+            // (error = "rejected"), otherwise the server hangs waiting for a
+            // response. For question elicitation (§5.4), auto-respond cancelled.
+            const rpParams = params;
+            if (method === ServerRequestMethod.REQUEST_PERMISSION &&
+                (rpParams.isQuestion || !rpParams.toolCall)) {
+                this.currentClient?.respond(id, { outcome: { outcome: 'cancelled' } });
+                getLogger().info(`[${this.logTag}] auto-responded cancelled to question elicitation requestId=${id}`);
+            }
+            else {
+                this.currentClient?.respondError(id, RpcErrorCode.METHOD_NOT_FOUND, `Unsupported server request: ${method}`);
+            }
+            return;
+        }
+        for (const ev of events) {
+            if (ev.type === 'approval_requested') {
+                this.pendingApprovals.set(ev.requestId, {
+                    kind: ev.kind,
+                    view: ev.view,
+                    options: params.options,
+                });
+                getLogger().info(`[${this.logTag}] approval requested requestId=${ev.requestId} kind=${ev.kind}`);
+            }
+        }
+        this.pushEvents(events);
+    }
+}
+//# sourceMappingURL=runner.js.map

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

@@ -0,0 +1,124 @@
+/**
+ * KimiAcpTranslator: translates ACP session/update notifications and
+ * session/request_permission server requests into AgentEvents.
+ *
+ * Per-turn stateful: accumulates text/thinking deltas, tracks tool calls,
+ * and produces turn_started events with operationKind.
+ *
+ * Wire envelope (R1, source: kimi-code packages/acp-server/src/events-map.ts,
+ * verified live 2026-08-15/16 against kimi 0.36.0):
+ *   session/update params = {sessionId, update: {sessionUpdate: '<kind>', ...}}
+ *   — the discriminator is `update.sessionUpdate`, NOT a nested `event.type`.
+ *
+ * Event mapping (design doc §4.2):
+ *   agent_message_chunk   → turn_diff text snapshot (content.text accumulation)
+ *   agent_thought_chunk   → turn_diff reasoning snapshot (content.text accumulation)
+ *   tool_call             → assistant/tool_use (rawInput object passthrough,
+ *                           string → JSON.parse fallback)
+ *   tool_call_update      → user/tool_result (status:'failed' → is_error:true)
+ *   plan / available_commands_update / session_info_update /
+ *   current_mode_update / config_option_update → discard
+ *   usage_update          → live context occupancy {used, size} →
+ *                           {total_tokens, context_limit}; NO input/output
+ *                           split exists on the wire — cumulative token stats
+ *                           fall back to wire.jsonl usage.record (dual path)
+ *   prompt stopReason:'end_turn'   → result success
+ *   prompt stopReason:'cancelled'  → result interrupted (独立终态)
+ *   prompt other stopReason/error  → result error
+ *   turn_started (self-produced)   → operationKind 'turn'/'compaction'
+ *   session/request_permission     → approval_requested
+ */
+import type { AgentEvent } from '../../types.js';
+import type { ApprovalRequestedEvent } from '../../types.js';
+/** Self-produced turn_started event (no wire equivalent — produced on prompt start). */
+export interface AcpTurnStartedEvent {
+    type: 'turn_started';
+    threadId: string;
+    turnId: string;
+    operationKind: 'turn' | 'compaction';
+    timestamp?: string;
+}
+/**
+ * Live usage snapshot from usage_update. The wire only carries context
+ * occupancy (`used`) and the model context window (`size`) — there is NO
+ * input/output token split (events-map.ts:505-516). input_tokens/output_tokens
+ * stay undefined so the bridge falls back to wire.jsonl usage.record for
+ * cumulative token stats (R1 dual path).
+ */
+export interface AcpLiveUsage {
+    total_tokens?: number;
+    context_limit?: number;
+    input_tokens?: number;
+    output_tokens?: number;
+}
+/** Usage update event for live token display. */
+export interface AcpUsageEvent {
+    type: 'usage';
+    usage: AcpLiveUsage;
+    timestamp?: string;
+}
+export type AcpTranslatorEvent = AgentEvent | AcpTurnStartedEvent | AcpUsageEvent | ApprovalRequestedEvent;
+export declare class KimiAcpTranslator {
+    /** Accumulated text per tool-call or message (keyed by a logical item id). */
+    private textByItem;
+    /** Accumulated thinking per item. */
+    private thinkingByItem;
+    /** Pending tool calls keyed by toolCallId (for matching tool_call_update). */
+    private pendingToolCalls;
+    /** Current operation kind (turn vs compact). */
+    private operationKind;
+    /** Live usage snapshot from usage_update events (context occupancy only). */
+    private liveUsage;
+    /** Whether any usage_update has been seen this turn (no update → no usage). */
+    private hasLiveUsage;
+    /** Current turn id, set by produceTurnStarted; carried on turn_diff events. */
+    private currentTurnId;
+    /**
+     * Handle a notification from the ACP server and return translated events.
+     */
+    handleNotification(method: string, params: unknown): AcpTranslatorEvent[];
+    /**
+     * Handle a server request (reverse RPC from the ACP server).
+     */
+    handleServerRequest(id: number | string, method: string, params: unknown): AcpTranslatorEvent[];
+    /**
+     * Produce a turn_started event. Called by the runner when session/prompt
+     * is sent (no wire notification for this — self-produced).
+     */
+    produceTurnStarted(sessionId: string, turnId: string): AcpTurnStartedEvent;
+    /**
+     * Translate a prompt response into a result event. Carries the live usage
+     * snapshot only when a usage_update was seen (otherwise undefined, so the
+     * bridge falls back to wire.jsonl usage.record readback).
+     */
+    handlePromptResponse(sessionId: string, result: {
+        stopReason: string;
+    }): AgentEvent;
+    /**
+     * Produce an error result event (for JSON-RPC errors during prompt).
+     */
+    produceErrorResult(sessionId: string, errorMessage: string): AgentEvent;
+    /**
+     * Set the operation kind (turn vs compact).
+     */
+    setOperationKind(kind: 'turn' | 'compact'): void;
+    private handleAgentMessageChunk;
+    private handleAgentThoughtChunk;
+    private handleToolCall;
+    private handleToolCallUpdate;
+    private handleUsageUpdate;
+    private handleRequestPermission;
+    /**
+     * Derive the approval decision list from the server's offered options.
+     * accept/decline/cancel are universal; acceptForSession requires an
+     * always-class option (kimi `approve_always`, opencode `allow_always`).
+     */
+    private deriveAvailableDecisions;
+    /**
+     * 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 (the
+     * bridge's kimi path already falls back to wire.jsonl readback).
+     */
+    private liveUsageSnapshot;
+}