lark-remote 0.1.5 → 0.1.7

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

@@ -0,0 +1,429 @@
+/**
+ * OpencodeAcpRunner: workspace-lifetime runner using opencode's ACP mode
+ * (`opencode acp`, JSON-RPC over stdio). Registered as the opencode agent's
+ * runner.
+ *
+ * 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 KimiAcpRunner via the shared ConnectionBasedRunner
+ * base (same notification queue + waitResolve pattern, same forceFinish/
+ * stopRequested semantics, same turn idle timeout, same ConnectionLostError
+ * retry). Differences from kimi:
+ * - session/set_mode applies the configured mode (build/plan; default 'build'
+ *   keeps manual approvals flowing); opencode sends no set_mode notification,
+ *   so the client refreshes the local mode view itself
+ * - no wire.jsonl compaction polling (opencode /compact is synchronous:
+ *   service.ts:555-571 summarize completes before the prompt response)
+ * - text/thinking go to the assistant incremental channel (opencode wire
+ *   deltas), not turn_diff snapshots
+ */
+import { ConnectionManager, } from '../../common/jsonrpc/connection-manager.js';
+import { OpencodeAcpTranslator } from './translator.js';
+import { RpcErrorCode, } 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';
+/**
+ * Build the ACP protocol response for a permission approval decision.
+ *
+ * accept            → {outcome:{outcome:'selected', optionId:<allow_once kind>}}
+ * accept_for_session → {outcome:{outcome:'selected', optionId:<allow_always kind>}}
+ * decline           → {outcome:{outcome:'selected', optionId:<reject kind>}}
+ * cancel            → {outcome:{outcome:'cancelled'}}
+ *
+ * optionId is opaque and echoed back as-is (opencode permission.ts:20-24
+ * offers once/always/reject with kinds allow_once/allow_always/reject_once;
+ * the server maps optionId 'once'/'always' → approve, anything else →
+ * reject — permission.ts:219-223). If no matching option is found, fall
+ * back to cancelled (safe universal default).
+ */
+function buildApprovalResponse(action, pending) {
+    if (action === 'cancel') {
+        return { outcome: { outcome: 'cancelled' } };
+    }
+    if (action === 'accept') {
+        const optionId = findOptionIdByKind(pending.options, ['allow_once', 'allow_always']);
+        if (optionId) {
+            return { outcome: { outcome: 'selected', optionId } };
+        }
+        return { outcome: { outcome: 'cancelled' } };
+    }
+    if (action === 'accept_for_session') {
+        // §P4: 卡片「允许本次会话」→ always 类 optionId（opencode 'always'）
+        const optionId = findOptionIdByKind(pending.options, ['allow_always', 'approve_always']);
+        if (optionId) {
+            return { outcome: { outcome: 'selected', optionId } };
+        }
+        return { outcome: { outcome: 'cancelled' } };
+    }
+    // decline
+    const optionId = findOptionIdByKind(pending.options, ['reject_once', 'reject']);
+    if (optionId) {
+        return { outcome: { outcome: 'selected', optionId } };
+    }
+    return { outcome: { outcome: 'cancelled' } };
+}
+// =============================================================================
+// Runner
+// =============================================================================
+export class OpencodeAcpRunner extends ConnectionBasedRunner {
+    connectionManager;
+    currentTranslator = null;
+    activeSessionId = null;
+    model;
+    /** Configured session mode applied via session/set_mode (§P5). */
+    configuredMode;
+    /** Current session mode id, parsed from session/new|resume configOptions. */
+    currentModeId;
+    /** Current model value (`provider/model`), parsed from configOptions. */
+    currentModelValue;
+    /** Pending approval requests: requestId → kind + view + options. */
+    pendingApprovals = new Map();
+    /** Tracker for the in-flight prompt request — needed for cancellation. */
+    promptSettled = false;
+    /** Whether the prompt request has been fired (distinguishes "stop before
+     *  prompt sent" from "stop while prompt in-flight" — the latter sends
+     *  session/cancel immediately). */
+    promptSent = false;
+    constructor(opts) {
+        super({ kind: opts.kind, sessionReader: opts.sessionReader }, opts.turnIdleTimeoutMs);
+        this.model = opts.model;
+        this.configuredMode = opts.mode ?? 'build';
+        const managerOpts = {
+            binary: opts.binary ?? 'opencode',
+            args: opts.acpArgs ?? ['acp'],
+            env: opts.env,
+            requestTimeoutMs: opts.requestTimeoutMs,
+            idleTtlMs: opts.idleTtlMs,
+            // ACP handshake: declare no fs/terminal capabilities — opencode only
+            // reads _meta['terminal-auth'] (service.ts:102) and gates edit-apply on
+            // the client's fs capability (permission.ts:99-115), which we refuse.
+            initializeParams: {
+                protocolVersion: 1,
+                clientCapabilities: {
+                    fs: { readTextFile: false, writeTextFile: false },
+                    terminal: false,
+                },
+            },
+        };
+        this.connectionManager = new ConnectionManager(managerOpts);
+    }
+    get logTag() {
+        return 'opencode-acp-runner';
+    }
+    get turnTimeoutErrorMessage() {
+        return 'opencode ACP turn timed out';
+    }
+    get turnInterruptedErrorMessage() {
+        return 'opencode ACP turn interrupted';
+    }
+    currentSessionId() {
+        return this.activeSessionId;
+    }
+    shouldDeferStop() {
+        return !this.promptSent;
+    }
+    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.promptSent = 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.
+     *
+     * opencode special-cases the `/compact` text prompt server-side
+     * (service.ts:555-571): it runs session.summarize synchronously and the
+     * prompt response settles only after compaction completes — no background
+     * record polling needed (unlike kimi).
+     */
+    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('opencode 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.
+            const resumeParams = { sessionId, cwd: opts.cwd };
+            const resumeResult = await client.request('session/resume', resumeParams);
+            this.trackConfigOptions(resumeResult);
+            const translator = new OpencodeAcpTranslator();
+            translator.setOperationKind('compact');
+            this.currentTranslator = translator;
+            // Emit turn_started with operationKind='compaction' before the prompt.
+            const turnId = `compact-${Date.now()}`;
+            const turnStarted = translator.produceTurnStarted(sessionId, turnId);
+            this.currentTurnId = turnId;
+            this.pushEvents([turnStarted]);
+            // Send /compact as prompt text (opencode intercepts it server-side).
+            const promptParams = {
+                sessionId,
+                prompt: [{ type: 'text', text: '/compact' }],
+            };
+            this.promptSettled = false;
+            // ACP holds the session/prompt response for the ENTIRE turn, so the
+            // RPC-level timeout must not apply — turn liveness is guarded by the
+            // rolling idle watchdog instead.
+            const promptPromise = client.request('session/prompt', promptParams, Number.POSITIVE_INFINITY);
+            this.promptSent = true;
+            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}] 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 ?? '(opencode-acp)',
+            extras: {
+                mode: 'acp',
+                ...(this.currentModeId ? { sessionMode: this.currentModeId } : {}),
+            },
+        };
+    }
+    /**
+     * Hot-apply a mode change to the live ACP session (§P5).
+     *
+     * opencode's session/set_mode sends no notification — the client refreshes
+     * the local mode view itself. The local mode is always updated so
+     * `getStatusInfo()` (and therefore `/s`) reflects the new value
+     * immediately; when a session is connected, also 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 when it differs from the session's current
+     * mode.
+     */
+    async updateApprovalMode(settings) {
+        if (settings.mode !== undefined) {
+            this.configuredMode = settings.mode;
+            this.currentModeId = settings.mode;
+        }
+        if (!this.currentClient || !this.activeSessionId)
+            return;
+        const modeParams = {
+            sessionId: this.activeSessionId,
+            modeId: this.configuredMode,
+        };
+        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)
+     * → 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('opencode ACP connection closed');
+            },
+        });
+        let sessionId;
+        if (opts.sessionId) {
+            const resumeParams = {
+                sessionId: opts.sessionId,
+                cwd: opts.cwd,
+            };
+            const resumeResult = await client.request('session/resume', resumeParams);
+            this.trackConfigOptions(resumeResult);
+            sessionId = opts.sessionId;
+        }
+        else {
+            const newParams = { cwd: opts.cwd, mcpServers: [] };
+            const newResult = await client.request('session/new', newParams);
+            this.trackConfigOptions(newResult);
+            sessionId = newResult.sessionId;
+        }
+        this.activeSessionId = sessionId;
+        // §P5: apply the configured mode (build/plan). If the session already
+        // runs it (from session/new|resume configOptions), skip the wire call;
+        // otherwise send session/set_mode and refresh the local view (opencode
+        // sends no notification for set_mode).
+        if (this.currentModeId !== this.configuredMode) {
+            const modeParams = {
+                sessionId,
+                modeId: this.configuredMode,
+            };
+            try {
+                await client.request('session/set_mode', modeParams);
+                this.currentModeId = this.configuredMode;
+            }
+            catch (err) {
+                getLogger().warn(`[${this.logTag}] session/set_mode failed (non-fatal): ${err.message}`);
+            }
+        }
+        // Apply the configured model (`provider/model`) via set_config_option.
+        // Without this the session runs opencode's own default model (e.g.
+        // opencode/big-pickle), which may be unusable — 2026-08-17 live smoke:
+        // default zen model left session/prompt hanging with no response.
+        // Non-fatal on failure (unknown model → server InvalidModelError).
+        if (this.model && this.currentModelValue !== this.model) {
+            try {
+                await client.request('session/set_config_option', {
+                    sessionId,
+                    configId: 'model',
+                    value: this.model,
+                });
+                this.currentModelValue = this.model;
+            }
+            catch (err) {
+                getLogger().warn(`[${this.logTag}] set_config_option model failed (non-fatal): ${err.message}`);
+            }
+        }
+        const translator = new OpencodeAcpTranslator();
+        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. The prompt request races with notifications (the
+        // server streams session/update before the prompt response); the
+        // response settles the turn and is translated into the result event.
+        const promptParams = {
+            sessionId,
+            prompt: [{ type: 'text', text: message }],
+        };
+        this.promptSettled = false;
+        const promptPromise = client.request('session/prompt', promptParams, Number.POSITIVE_INFINITY);
+        this.promptSent = true;
+        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]);
+        });
+    }
+    /**
+     * Track the current session mode and model from a session/new|resume
+     * result's configOptions (opencode buildModeSelectOption/buildModelSelectOption:
+     * {id, category, currentValue}).
+     */
+    trackConfigOptions(result) {
+        const options = result.configOptions;
+        if (!Array.isArray(options))
+            return;
+        const mode = options.find((opt) => opt?.category === 'mode' || opt?.id === 'mode');
+        if (typeof mode?.currentValue === 'string') {
+            this.currentModeId = mode.currentValue;
+        }
+        const model = options.find((opt) => opt?.category === 'model' || opt?.id === 'model');
+        if (typeof model?.currentValue === 'string') {
+            this.currentModelValue = model.currentValue;
+        }
+    }
+    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 requests must be explicitly responded
+            // to (error = "rejected"), otherwise the server hangs waiting.
+            // This includes fs/write_text_file: we do NOT declare the fs
+            // capability, and if opencode still calls it (edit approved →
+            // writeProposedEdit), we refuse with method-not-found — the server
+            // side tolerates the error (permission.ts writeProposedEdit catches).
+            this.currentClient?.respondError(id, RpcErrorCode.METHOD_NOT_FOUND, `Unsupported server request: ${method}`);
+            getLogger().info(`[${this.logTag}] rejected unsupported server request method=${method} id=${id}`);
+            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/opencode/acp/translator.d.ts

@@ -0,0 +1,119 @@
+/**
+ * OpencodeAcpTranslator: translates opencode ACP session/update notifications
+ * and session/request_permission server requests into AgentEvents.
+ *
+ * Channel choice (event contract in common/acp/protocol-types.ts header):
+ * opencode's wire `content.text` IS an incremental delta
+ * (opencode acp/event.ts:231-258 handlePartDelta sends `props.delta`
+ * verbatim), so text/thinking chunks go straight onto the `assistant`
+ * incremental channel — NO accumulation in the translator, NO turn_diff
+ * snapshot. (Contrast kimi: same field is also a delta but kimi's contract
+ * accumulates into turn_diff snapshots; both end with exactly one
+ * concatenation in run-state, enforced by each side's seam test.)
+ *
+ * Event mapping (source: opencode acp/service.ts + event.ts + tool.ts,
+ * dev@1c965451b5):
+ *   agent_message_chunk   → assistant/text delta (content.text passthrough)
+ *   agent_thought_chunk   → assistant/thinking delta (content.text passthrough)
+ *   tool_call             → assistant/tool_use (rawInput object passthrough;
+ *                           missing → {} per contract, string → JSON.parse)
+ *   tool_call_update      → user/tool_result (status:'failed' → is_error:true;
+ *                           rawOutput is an OBJECT: {output} / {error})
+ *   usage_update          → live context occupancy {used, size} + cost →
+ *                           {total_tokens, context_limit, total_cost_usd}
+ *   available_commands_update / plan / session_info_update /
+ *   current_mode_update / config_option_update / user_message_chunk → discard
+ *   prompt stopReason:'end_turn'   → result success
+ *   prompt stopReason:'cancelled'  → result interrupted (独立终态)
+ *   prompt other stopReason/error  → result error
+ *   session/request_permission     → approval_requested (optionId echo)
+ */
+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 OpencodeAcpTurnStartedEvent {
+    type: 'turn_started';
+    threadId: string;
+    turnId: string;
+    operationKind: 'turn' | 'compaction';
+    timestamp?: string;
+}
+/**
+ * Live usage snapshot from usage_update. The wire carries context occupancy
+ * (`used`), the model context window (`size`) and session cost
+ * (`cost.amount`) — there is NO input/output token split.
+ */
+export interface OpencodeAcpLiveUsage {
+    total_tokens?: number;
+    context_limit?: number;
+    input_tokens?: number;
+    output_tokens?: number;
+}
+/** Usage update event for live token display. */
+export interface OpencodeAcpUsageEvent {
+    type: 'usage';
+    usage: OpencodeAcpLiveUsage;
+    timestamp?: string;
+}
+export type OpencodeAcpTranslatorEvent = AgentEvent | OpencodeAcpTurnStartedEvent | OpencodeAcpUsageEvent | ApprovalRequestedEvent;
+export declare class OpencodeAcpTranslator {
+    /** 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;
+    /** Session cost from usage_update cost.amount (USD). */
+    private liveCostUsd?;
+    /** Whether any usage_update has been seen this turn (no update → no usage). */
+    private hasLiveUsage;
+    /** Current turn id, set by produceTurnStarted. */
+    private currentTurnId;
+    /**
+     * Handle a notification from the ACP server and return translated events.
+     */
+    handleNotification(method: string, params: unknown): OpencodeAcpTranslatorEvent[];
+    /**
+     * Handle a server request (reverse RPC from the ACP server).
+     */
+    handleServerRequest(id: number | string, method: string, params: unknown): OpencodeAcpTranslatorEvent[];
+    /**
+     * 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): OpencodeAcpTurnStartedEvent;
+    /**
+     * Translate a prompt response into a result event.
+     * stopReason: end_turn → success; cancelled → interrupted; anything else
+     * (max_tokens / refusal / …) → error.
+     */
+    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 (opencode `allow_always`, kimi `approve_always`).
+     */
+    private deriveAvailableDecisions;
+    /**
+     * ResultEvent.usage nominally requires input_tokens/output_tokens, but the
+     * ACP wire has no such split — the live snapshot is context occupancy only.
+     * Cast is deliberate: consumers must tolerate undefined input/output.
+     */
+    private liveUsageSnapshot;
+}