lark-remote 0.1.12 → 0.2.0

package/dist/runner/common/acp/base-acp-runner.d.ts

@@ -0,0 +1,116 @@
+/**
+ * BaseAcpRunner: shared turn machinery for the kimi / opencode ACP runners.
+ *
+ * Both runners extend ConnectionBasedRunner and were structurally aligned
+ * (kimi's header even said so) — but session/resume→set_config→turn_started→
+ * prompt orchestration, compact orchestration, approval response dispatch,
+ * cancel/clear/release plumbing and the pendingApprovals registry were
+ * line-for-line duplicated with only constants/field names differing
+ * (2026-09 round-2 simplification). This base absorbs them; what stays in
+ * subclasses:
+ *   - applyTurnSettings: mode/model下发 semantics differ (kimi unconditional,
+ *     opencode conditional on cached values)
+ *   - onCompactPromptFired: kimi polls wire.jsonl compaction records (§5.2,
+ *     background compaction), opencode settles synchronously
+ *   - shouldDeferStop: kimi defers while prompt unsettled, opencode defers
+ *     until the prompt has been SENT (deliberately narrower window)
+ *   - handleNotification/handleServerRequest: kimi filters terminal-backed
+ *     Bash notifications and serves terminal/* reverse RPC; opencode is plain
+ *   - getStatusInfo / updateApprovalMode: agent-specific extras & mode vocab
+ */
+import type { AgentEvent, AgentKind, AgentSessionReader, SpawnOptions } from '../../types.js';
+import { ConnectionManager } from '../jsonrpc/connection-manager.js';
+import { JsonRpcClient } from '../jsonrpc/client.js';
+import { type SessionNewResult, type SessionResumeResult, type SessionPromptResult, type RequestPermissionParams } from './protocol-types.js';
+import { type AcpPendingApproval } from './protocol-helpers.js';
+import { ConnectionBasedRunner } from '../connection-based-runner.js';
+import { BaseAcpTranslator, type AcpTranslatorEvent } from './base-translator.js';
+export type { AcpTranslatorEvent } from './base-translator.js';
+export declare abstract class BaseAcpRunner<TTranslator extends BaseAcpTranslator> extends ConnectionBasedRunner<JsonRpcClient, AcpTranslatorEvent> {
+    protected readonly connectionManager: ConnectionManager;
+    protected currentTranslator: TTranslator | null;
+    protected activeSessionId: string | null;
+    protected model?: string;
+    /** Pending approval requests: requestId → kind + view + options. */
+    protected pendingApprovals: Map<string | number, AcpPendingApproval>;
+    /** Tracker for the in-flight prompt request — needed for cancellation. */
+    protected promptSettled: boolean;
+    /** Whether the prompt request has been fired (opencode defer-stop window). */
+    protected promptSent: boolean;
+    protected constructor(opts: {
+        kind: AgentKind;
+        sessionReader: AgentSessionReader;
+        turnIdleTimeoutMs?: number;
+    }, connectionManager: ConnectionManager);
+    /** failTurn message when the ACP connection drops mid-turn. */
+    protected abstract get connectionClosedMessage(): string;
+    /** Create the per-turn translator instance. */
+    protected abstract createTranslator(): TTranslator;
+    /**
+     * Apply turn-scoped settings on a fresh session: configured model and
+     * permission/mode. kimi sends both unconditionally (fresh ACP sessions
+     * always start in 'default'), opencode skips when the cached value already
+     * matches. Failures are non-fatal (warn only).
+     */
+    protected abstract applyTurnSettings(client: JsonRpcClient, sessionId: string): Promise<void>;
+    /**
+     * Dispatch the compact prompt result once fired. kimi: background
+     * compaction — poll wire.jsonl for a NEW terminal record before translating
+     * (§5.2). opencode: synchronous — standard prompt-settle translation.
+     */
+    protected abstract onCompactPromptFired(promptPromise: Promise<SessionPromptResult>, translator: TTranslator, sessionId: string, opts: SpawnOptions, baselineTotalCount: number): void;
+    protected currentSessionId(): string | null;
+    protected cancelCurrentTurn(): Promise<void>;
+    protected clearTurnState(): void;
+    protected releaseConnection(cwd: string): Promise<void>;
+    protected notifyIdle(cwd: string): void;
+    protected disposeConnections(): Promise<void>;
+    /**
+     * Respond to an approval server request. `response` is the bridge
+     * ApprovalAction (`{ action: 'accept' | 'decline' | 'cancel' }`).
+     */
+    respondApproval(requestId: number | string, response: unknown): Promise<void>;
+    /** Agent-specific outcome encoding (kimi: question bridge; opencode: permission). */
+    protected abstract buildApprovalOutcome(action: string, pending: AcpPendingApproval, response: unknown): unknown;
+    /** Shared tail of updateApprovalMode: re-send session/set_mode to the live session. */
+    protected sendApprovalModeUpdate(modeId: string): Promise<void>;
+    /**
+     * Register approval_requested events yielded by the translator into the
+     * pendingApprovals map (shared tail of handleServerRequest).
+     */
+    protected registerApprovalEvents(events: AcpTranslatorEvent[], options: RequestPermissionParams['options'], proto?: AcpPendingApproval['proto']): void;
+    /**
+     * Standard prompt-settle translation: on resolve → result event (unless
+     * stopRequested); on reject → error result (or warn when already stopped).
+     * `context` only decorates the stopRequested warn line.
+     */
+    protected handlePromptRejected(err: unknown, translator: TTranslator, sessionId: string, context: string): void;
+    protected handlePromptResolved(result: SessionPromptResult, translator: TTranslator, sessionId: string): void;
+    /**
+     * Acquire the connection and set up the turn: session/new (new session) or
+     * session/resume (existing sessionId) → applyTurnSettings → session/prompt.
+     */
+    protected setupTurn(message: string, opts: SpawnOptions): Promise<void>;
+    /**
+     * Run a compact operation on the current session: resume → '/compact'
+     * prompt text (both servers intercept it) → agent-specific result dispatch.
+     */
+    runCompact(_message: string, opts: SpawnOptions): AsyncGenerator<AgentEvent>;
+    /** After the connection is acquired per turn (kimi: record active cwd). */
+    protected onConnectionAcquired(_opts: SpawnOptions): void;
+    /** When the ACP connection drops (kimi: kill live terminals). */
+    protected onConnectionClosed(): void;
+    /** After the turn's session id is known (opencode: start log error monitor). */
+    protected onTurnSessionReady(_sessionId: string, _opts: SpawnOptions): void;
+    /** After session/new|resume resolves (opencode: track configOptions). */
+    protected onSessionEstablished(_result: SessionResumeResult | SessionNewResult): void;
+    /** Compaction baseline record count, captured before the compact prompt (kimi). */
+    protected compactBaseline(_sessionId: string, _opts: SpawnOptions): number;
+    /** Wire the active client's JSON-RPC hooks into the subclass dispatcher. */
+    protected abstract handleNotification(method: string, params: unknown): void;
+    protected abstract handleServerRequest(id: number | string, method: string, params: unknown): void;
+    /** Extra per-turn state cleanup (kimi: active cwd; opencode: error monitor). */
+    protected onClearTurnState(): void;
+    /** Extra dispose-time cleanup before connections are disposed (kimi: terminals). */
+    protected beforeDisposeConnections(): Promise<void>;
+}

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

@@ -0,0 +1,248 @@
+import { respondAcpApproval, sendAcpSetMode } from './protocol-helpers.js';
+import { getLogger } from '../../../logger/index.js';
+import { ConnectionBasedRunner } from '../connection-based-runner.js';
+export class BaseAcpRunner extends ConnectionBasedRunner {
+    connectionManager;
+    currentTranslator = null;
+    activeSessionId = null;
+    model;
+    /** 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 (opencode defer-stop window). */
+    promptSent = false;
+    constructor(opts, connectionManager) {
+        super(opts);
+        this.connectionManager = connectionManager;
+    }
+    // =========================================================================
+    // Shared plumbing
+    // =========================================================================
+    currentSessionId() {
+        return this.activeSessionId;
+    }
+    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.onClearTurnState();
+        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.beforeDisposeConnections();
+        await this.connectionManager.disposeAll();
+    }
+    /**
+     * Respond to an approval server request. `response` is the bridge
+     * ApprovalAction (`{ action: 'accept' | 'decline' | 'cancel' }`).
+     */
+    async respondApproval(requestId, response) {
+        respondAcpApproval({
+            client: this.currentClient,
+            pendingApprovals: this.pendingApprovals,
+            requestId,
+            response,
+            logTag: this.logTag,
+            buildOutcome: (action, pending, resp) => this.buildApprovalOutcome(action, pending, resp),
+        });
+    }
+    /** Shared tail of updateApprovalMode: re-send session/set_mode to the live session. */
+    async sendApprovalModeUpdate(modeId) {
+        await sendAcpSetMode({
+            client: this.currentClient,
+            activeSessionId: this.activeSessionId,
+            modeId,
+            logTag: this.logTag,
+        });
+    }
+    /**
+     * Register approval_requested events yielded by the translator into the
+     * pendingApprovals map (shared tail of handleServerRequest).
+     */
+    registerApprovalEvents(events, options, proto) {
+        for (const ev of events) {
+            if (ev.type === 'approval_requested') {
+                this.pendingApprovals.set(ev.requestId, {
+                    kind: ev.kind,
+                    view: ev.view,
+                    options,
+                    ...(proto ? { proto } : {}),
+                });
+                getLogger().info(`[${this.logTag}] approval requested requestId=${ev.requestId} kind=${ev.kind}`);
+            }
+        }
+    }
+    /**
+     * Standard prompt-settle translation: on resolve → result event (unless
+     * stopRequested); on reject → error result (or warn when already stopped).
+     * `context` only decorates the stopRequested warn line.
+     */
+    handlePromptRejected(err, translator, sessionId, context) {
+        this.promptSettled = true;
+        if (this.stopRequested) {
+            getLogger().warn(`[${this.logTag}] ${context} prompt rejected after stopRequested: ${err.message}`);
+            return;
+        }
+        const resultEvent = translator.produceErrorResult(sessionId, err.message);
+        this.pushEvents([resultEvent]);
+    }
+    handlePromptResolved(result, translator, sessionId) {
+        this.promptSettled = true;
+        if (this.stopRequested)
+            return; // already cancelled
+        const resultEvent = translator.handlePromptResponse(sessionId, result);
+        this.pushEvents([resultEvent]);
+    }
+    // =========================================================================
+    // Turn orchestration
+    // =========================================================================
+    /**
+     * Acquire the connection and set up the turn: session/new (new session) or
+     * session/resume (existing sessionId) → applyTurnSettings → session/prompt.
+     */
+    async setupTurn(message, opts) {
+        const client = await this.connectionManager.acquire(opts.cwd);
+        this.connectionManager.notifyActivity(opts.cwd);
+        this.currentClient = client;
+        this.onConnectionAcquired(opts);
+        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.onConnectionClosed();
+                this.failTurn(this.connectionClosedMessage);
+            },
+        });
+        let sessionId;
+        if (opts.sessionId) {
+            const resumeParams = {
+                sessionId: opts.sessionId,
+                cwd: opts.cwd,
+            };
+            const resumeResult = await client.request('session/resume', resumeParams);
+            this.onSessionEstablished(resumeResult);
+            sessionId = opts.sessionId;
+        }
+        else {
+            const newParams = { cwd: opts.cwd, mcpServers: [] };
+            const newResult = await client.request('session/new', newParams);
+            this.onSessionEstablished(newResult);
+            sessionId = newResult.sessionId;
+        }
+        this.activeSessionId = sessionId;
+        this.onTurnSessionReady(sessionId, opts);
+        await this.applyTurnSettings(client, sessionId);
+        const translator = this.createTranslator();
+        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.handlePromptResolved(result, translator, sessionId), (err) => this.handlePromptRejected(err, translator, sessionId, ''));
+    }
+    /**
+     * Run a compact operation on the current session: resume → '/compact'
+     * prompt text (both servers intercept it) → agent-specific result dispatch.
+     */
+    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;
+            this.onConnectionAcquired(opts);
+            client.setHooks({
+                onNotification: (method, params) => this.handleNotification(method, params),
+                onServerRequest: (id, method, params) => this.handleServerRequest(id, method, params),
+                onClose: () => {
+                    this.onConnectionClosed();
+                    this.failTurn(this.connectionClosedMessage);
+                },
+            });
+            const sessionId = opts.sessionId;
+            if (!sessionId) {
+                throw new Error('compact requires a sessionId');
+            }
+            this.activeSessionId = sessionId;
+            this.onTurnSessionReady(sessionId, opts);
+            // 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.onSessionEstablished(resumeResult);
+            const translator = this.createTranslator();
+            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]);
+            const promptParams = {
+                sessionId,
+                prompt: [{ type: 'text', text: '/compact' }],
+            };
+            // Baseline is captured BEFORE the prompt fires (kimi §5.2: a begin
+            // record landing after the fire must count as "new activity").
+            const baselineTotalCount = this.compactBaseline(sessionId, opts);
+            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;
+            this.onCompactPromptFired(promptPromise, translator, sessionId, opts, baselineTotalCount);
+        });
+    }
+    // =========================================================================
+    // Optional hooks (defaults: no-op)
+    // =========================================================================
+    /** After the connection is acquired per turn (kimi: record active cwd). */
+    onConnectionAcquired(_opts) { }
+    /** When the ACP connection drops (kimi: kill live terminals). */
+    onConnectionClosed() { }
+    /** After the turn's session id is known (opencode: start log error monitor). */
+    onTurnSessionReady(_sessionId, _opts) { }
+    /** After session/new|resume resolves (opencode: track configOptions). */
+    onSessionEstablished(_result) { }
+    /** Compaction baseline record count, captured before the compact prompt (kimi). */
+    compactBaseline(_sessionId, _opts) {
+        return 0;
+    }
+    /** Extra per-turn state cleanup (kimi: active cwd; opencode: error monitor). */
+    onClearTurnState() { }
+    /** Extra dispose-time cleanup before connections are disposed (kimi: terminals). */
+    async beforeDisposeConnections() { }
+}
+//# sourceMappingURL=base-acp-runner.js.map

package/dist/runner/common/acp/base-translator.d.ts

@@ -0,0 +1,141 @@
+/**
+ * BaseAcpTranslator: shared skeleton for the kimi / opencode ACP translators.
+ *
+ * Both agents' session/update notification envelopes, prompt-response
+ * stopReason mapping, tool_call/tool_call_update normalization, usage_update
+ * occupancy bookkeeping and self-produced turn_started events are
+ * line-for-line identical — extracted here in the 2026-09 round-2
+ * simplification. What genuinely diverges is the content channel:
+ * kimi accumulates wire deltas into turn_diff snapshots (snapshot semantics,
+ * see KimiAcpTranslator header), opencode forwards `assistant` deltas
+ * directly (delta semantics) — those chunk handlers stay abstract.
+ *
+ * Extension points (all no-op or passthrough by default):
+ *   handleAgentMessageChunk / handleAgentThoughtChunk — content channel (abstract)
+ *   handleRequestPermission                           — approval rendering (abstract)
+ *   handleOtherServerRequest                          — extra reverse RPC (kimi: elicitation)
+ *   extractToolResultContent                          — tool_result content (default: rawOutput)
+ *   onUsageSample                                     — extra usage bookkeeping (opencode: cost)
+ */
+import type { AgentEvent, ApprovalRequestedEvent, ResultEvent } from '../../types.js';
+import { type AgentMessageChunkEvent, type AgentThoughtChunkEvent, type ToolCallEvent, type ToolCallUpdateEvent, type UsageUpdateEvent, type RequestPermissionParams, type AcpPlanEvent } from './protocol-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 ACP wire carries context
+ * occupancy (`used`) and the model context window (`size`) — there is NO
+ * input/output token split. input_tokens/output_tokens stay undefined so the
+ * bridge falls back to per-agent transcript readback for cumulative stats.
+ */
+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 abstract class BaseAcpTranslator {
+    /** Logger tag, e.g. 'kimi-acp-translator'. */
+    protected abstract readonly logTag: string;
+    /** Current operation kind (turn vs compact). */
+    private operationKind;
+    /** Live usage snapshot from usage_update events (context occupancy only). */
+    protected liveUsage: AcpLiveUsage;
+    /** Whether any usage_update has been seen this turn (no update → no usage). */
+    protected hasLiveUsage: boolean;
+    /** Session cost from usage_update cost.amount (USD). Written by opencode only. */
+    protected liveCostUsd?: number;
+    /** Current turn id, set by produceTurnStarted. */
+    protected currentTurnId: string;
+    /**
+     * Handle a notification from the ACP server and return translated events.
+     * Wire envelope: {sessionId, update: {sessionUpdate: '<kind>', ...}} — the
+     * discriminator is `update.sessionUpdate`.
+     */
+    handleNotification(method: string, params: unknown): AcpTranslatorEvent[];
+    /**
+     * Handle a server request (reverse RPC from the ACP server). Subclasses
+     * hook additional methods via handleOtherServerRequest.
+     */
+    handleServerRequest(id: number | string, method: string, params: unknown): AcpTranslatorEvent[];
+    /** Hook for server requests other than session/request_permission. */
+    protected handleOtherServerRequest(_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.
+     * stopReason: end_turn → success; cancelled → interrupted (independent
+     * terminal state, must NOT merge into error); 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;
+    /**
+     * plan update → PlanEvent（信息保真 C3.2：不再显式丢弃）。
+     * ACP PlanEntry: { content, priority, status }（status: pending/in_progress/
+     * completed）。基类具体方法：kimi/opencode wire 结构相同，直接复用。
+     */
+    protected handlePlan(event: AcpPlanEvent): AcpTranslatorEvent[];
+    /**
+     * 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 字段
+     * （渲染层做面板副标题）。
+     */
+    protected handleToolCall(event: ToolCallEvent, _sessionId: string): AcpTranslatorEvent[];
+    /**
+     * tool_call_update → user/tool_result. status:'failed' → is_error:true.
+     */
+    protected handleToolCallUpdate(event: ToolCallUpdateEvent, _sessionId: string): AcpTranslatorEvent[];
+    /**
+     * tool_result content extraction. Default: rawOutput passthrough (kimi
+     * semantics). opencode overrides — its rawOutput is an OBJECT
+     * ({output} / {error}).
+     */
+    protected extractToolResultContent(event: ToolCallUpdateEvent): unknown;
+    /**
+     * usage_update → context occupancy bookkeeping. The wire shape is
+     * {used, size} (+ opencode: cost:{amount}) — context occupancy, not
+     * cumulative tokens.
+     */
+    protected handleUsageUpdate(event: UsageUpdateEvent): AcpTranslatorEvent[];
+    /** Extra per-sample usage bookkeeping (opencode: session cost amount). */
+    protected onUsageSample(_event: UsageUpdateEvent): void;
+    /**
+     * 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.
+     */
+    protected liveUsageSnapshot(): ResultEvent['usage'];
+    protected abstract handleAgentMessageChunk(event: AgentMessageChunkEvent, sessionId: string): AcpTranslatorEvent[];
+    protected abstract handleAgentThoughtChunk(event: AgentThoughtChunkEvent, sessionId: string): AcpTranslatorEvent[];
+    protected abstract handleRequestPermission(requestId: number | string, params: RequestPermissionParams): AcpTranslatorEvent[];
+}