lark-remote 0.1.6 → 0.1.7

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

@@ -0,0 +1,345 @@
+/**
+ * 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 { NotificationMethod, ServerRequestMethod, SessionEventType, } from '../../common/acp/protocol-types.js';
+import { getLogger } from '../../../logger/index.js';
+// =============================================================================
+// Translator
+// =============================================================================
+export class OpencodeAcpTranslator {
+    /** Pending tool calls keyed by toolCallId (for matching tool_call_update). */
+    pendingToolCalls = new Map();
+    /** Current operation kind (turn vs compact). */
+    operationKind = 'turn';
+    /** Live usage snapshot from usage_update events (context occupancy only). */
+    liveUsage = {};
+    /** Session cost from usage_update cost.amount (USD). */
+    liveCostUsd;
+    /** Whether any usage_update has been seen this turn (no update → no usage). */
+    hasLiveUsage = false;
+    /** Current turn id, set by produceTurnStarted. */
+    currentTurnId = '';
+    /**
+     * Handle a notification from the ACP server and return translated events.
+     */
+    handleNotification(method, params) {
+        if (method !== NotificationMethod.SESSION_UPDATE) {
+            return [];
+        }
+        // Envelope: {sessionId, update: {sessionUpdate: ...}} (same as kimi).
+        const notif = params;
+        const update = notif.update;
+        switch (update.sessionUpdate) {
+            case SessionEventType.AGENT_MESSAGE_CHUNK:
+                return this.handleAgentMessageChunk(update);
+            case SessionEventType.AGENT_THOUGHT_CHUNK:
+                return this.handleAgentThoughtChunk(update);
+            case SessionEventType.TOOL_CALL:
+                return this.handleToolCall(update);
+            case SessionEventType.TOOL_CALL_UPDATE:
+                return this.handleToolCallUpdate(update);
+            case SessionEventType.USAGE_UPDATE:
+                return this.handleUsageUpdate(update);
+            case SessionEventType.PLAN:
+                getLogger().debug(`[opencode-acp-translator] discarding plan event`);
+                return [];
+            default:
+                // Control-plane noise (command list, mode/config echoes, user replay)
+                // — not content.
+                return [];
+        }
+    }
+    /**
+     * Handle a server request (reverse RPC from the ACP server).
+     */
+    handleServerRequest(id, method, params) {
+        if (method === ServerRequestMethod.REQUEST_PERMISSION) {
+            return this.handleRequestPermission(id, 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; 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;
+    }
+    // =========================================================================
+    // Private notification handlers
+    // =========================================================================
+    handleAgentMessageChunk(event) {
+        // opencode wire delta → assistant incremental channel directly
+        // (event.ts handlePartDelta: content.text = props.delta). The reducer
+        // appends assistant text — no accumulation here, no turn_diff.
+        return [
+            {
+                type: 'assistant',
+                message: {
+                    content: [{ type: 'text', text: event.content.text }],
+                },
+                timestamp: new Date().toISOString(),
+            },
+        ];
+    }
+    handleAgentThoughtChunk(event) {
+        return [
+            {
+                type: 'assistant',
+                message: {
+                    content: [{ type: 'thinking', thinking: event.content.text }],
+                },
+                timestamp: new Date().toISOString(),
+            },
+        ];
+    }
+    handleToolCall(event) {
+        // opencode pendingToolCall always carries rawInput as an object
+        // (tool.ts:124-138), but the event contract requires defensive
+        // normalization: missing → {} (lazy-create), string → JSON.parse.
+        let input = event.rawInput ?? {};
+        if (typeof event.rawInput === 'string') {
+            try {
+                input = JSON.parse(event.rawInput);
+            }
+            catch {
+                // Keep raw string as-is
+            }
+        }
+        this.pendingToolCalls.set(event.toolCallId, {
+            id: event.toolCallId,
+            name: event.title,
+            input,
+        });
+        return [
+            {
+                type: 'assistant',
+                message: {
+                    content: [
+                        {
+                            type: 'tool_use',
+                            id: event.toolCallId,
+                            name: event.title,
+                            input,
+                        },
+                    ],
+                },
+                timestamp: new Date().toISOString(),
+            },
+        ];
+    }
+    handleToolCallUpdate(event) {
+        const isError = event.status === 'failed';
+        const content = extractToolResultContent(event);
+        return [
+            {
+                type: 'user',
+                message: {
+                    content: [
+                        {
+                            type: 'tool_result',
+                            tool_use_id: event.toolCallId,
+                            content,
+                            is_error: isError,
+                        },
+                    ],
+                },
+                timestamp: new Date().toISOString(),
+            },
+        ];
+    }
+    handleUsageUpdate(event) {
+        // opencode usage_update: {used, size, cost:{amount, currency:'USD'}}
+        // (service.ts:653-663) — context occupancy + session cost, no
+        // input/output split.
+        this.liveUsage = {
+            total_tokens: event.used,
+            context_limit: event.size,
+        };
+        const cost = event.cost;
+        if (typeof cost?.amount === 'number') {
+            this.liveCostUsd = cost.amount;
+        }
+        this.hasLiveUsage = true;
+        return [];
+    }
+    // =========================================================================
+    // Private approval handlers
+    // =========================================================================
+    handleRequestPermission(requestId, params) {
+        // opencode always sends a toolCall (permission.ts:62-70 — built via
+        // permissionToolCall) and has no question elicitation; absent toolCall
+        // is treated as unsupported and left to the runner's reject fallback.
+        if (!params.toolCall) {
+            getLogger().info(`[opencode-acp-translator] permission request without toolCall, leaving to runner fallback (requestId=${requestId})`);
+            return [];
+        }
+        const rawInput = params.toolCall.rawInput;
+        const view = {
+            requestId,
+            kind: 'command',
+            command: params.toolCall.title ?? undefined,
+            reason: rawInput ? truncate(stringify(rawInput), 200) : undefined,
+            // §P4: 从服务端 options kind 派生——带 allow_always（或 approve_always）
+            // 才提供「本会话总是允许」（acceptForSession）。
+            availableDecisions: this.deriveAvailableDecisions(params),
+        };
+        return [
+            {
+                type: 'approval_requested',
+                requestId,
+                kind: 'command',
+                threadId: params.sessionId,
+                turnId: '',
+                itemId: '',
+                view,
+                timestamp: new Date().toISOString(),
+            },
+        ];
+    }
+    /**
+     * 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`).
+     */
+    deriveAvailableDecisions(params) {
+        const decisions = ['accept', 'decline', 'cancel'];
+        const hasAlwaysOption = (params.options ?? []).some((opt) => opt.kind === 'allow_always' || opt.kind === 'approve_always');
+        if (hasAlwaysOption) {
+            decisions.push('acceptForSession');
+        }
+        return decisions;
+    }
+    // =========================================================================
+    // Private helpers
+    // =========================================================================
+    /**
+     * 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.
+     */
+    liveUsageSnapshot() {
+        return { ...this.liveUsage };
+    }
+}
+// =============================================================================
+// Helpers
+// =============================================================================
+/**
+ * Extract a display string from a tool_call_update. opencode shapes
+ * (tool.ts): completed → rawOutput {output, metadata?}; failed → rawOutput
+ * {error, metadata}; in_progress → content[] with shell output snapshot.
+ */
+function extractToolResultContent(event) {
+    const rawOutput = event.rawOutput;
+    if (rawOutput && typeof rawOutput === 'object') {
+        const rec = rawOutput;
+        if (typeof rec.output === 'string')
+            return rec.output;
+        if (typeof rec.error === 'string')
+            return rec.error;
+    }
+    if (typeof rawOutput === 'string')
+        return rawOutput;
+    const content = event.content;
+    if (Array.isArray(content)) {
+        const texts = content
+            .map((item) => {
+            const c = item?.content;
+            return c?.type === 'text' && typeof c.text === 'string' ? c.text : '';
+        })
+            .filter((t) => t.length > 0);
+        if (texts.length > 0)
+            return texts.join('\n');
+    }
+    return '';
+}
+function truncate(text, maxLen) {
+    return text.length <= maxLen ? text : text.slice(0, maxLen) + '…';
+}
+function stringify(value) {
+    if (typeof value === 'string')
+        return value;
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        return String(value);
+    }
+}
+//# sourceMappingURL=translator.js.map

package/dist/runner/opencode/index.d.ts

@@ -1 +1 @@
-export { OpencodeExecRunner } from './runner.js';
+export { OpencodeAcpRunner } from './acp/index.js';

package/dist/runner/opencode/index.js

@@ -1,2 +1,2 @@
-export { OpencodeExecRunner } from './runner.js';
+export { OpencodeAcpRunner } from './acp/index.js';
 //# sourceMappingURL=index.js.map

package/dist/runner/pi/index.d.ts

@@ -1 +1 @@
-export { PiRunner } from './runner.js';
+export { PiRpcRunner } from './rpc/index.js';

package/dist/runner/pi/index.js

@@ -1,2 +1,2 @@
-export { PiRunner } from './runner.js';
+export { PiRpcRunner } from './rpc/index.js';
 //# sourceMappingURL=index.js.map

package/dist/runner/pi/rpc/client.d.ts

@@ -0,0 +1,52 @@
+/**
+ * PiRpcClient: JSON-lines client for pi's `--mode rpc` protocol.
+ *
+ * Reuses the shared JsonlRpcTransport (spawn + line read/write + graceful
+ * close) but speaks pi's own framing — commands `{type,id,...}` on stdin,
+ * responses `{id,type:"response",command,success,...}` and bare events on
+ * stdout — rather than JSON-RPC. There is no initialize handshake: the server
+ * starts streaming events immediately after spawn.
+ *
+ * Response correlation is by command id; every non-response line is forwarded
+ * as an event to the active hooks (the runner's translator).
+ */
+import type { JsonlRpcTransport } from '../../common/jsonrpc/transport.js';
+import type { PiRpcCommand, PiRpcEvent, PiRpcResponse } from './protocol-types.js';
+/** Per-run hooks set by the runner. Accepts a superset so the base class's
+ *  respawnAfterConnectionLost({onNotification,onServerRequest,onClose})
+ *  detach call stays type-compatible. */
+export interface PiRpcClientHooks {
+    onEvent?(evt: PiRpcEvent): void;
+    onClose?(): void;
+    onNotification?(): void;
+    onServerRequest?(): void;
+}
+export declare class PiRpcClient {
+    private transport;
+    private readonly requestTimeoutMs;
+    /** Connection-layer close hook (slot cleanup) — survives setHooks(). */
+    private readonly baseOnClose;
+    /** Per-run hooks from the runner. */
+    private runHooks;
+    private pending;
+    private nextId;
+    private _disposed;
+    private _ready;
+    constructor(transport: JsonlRpcTransport, baseOnClose: () => void, requestTimeoutMs?: number);
+    /** Replace the per-run hooks (runner wires its translator + failTurn here). */
+    setHooks(hooks: PiRpcClientHooks): void;
+    get ready(): boolean;
+    get healthy(): boolean;
+    /** Start the transport. Throws ConnectionLostError if spawn fails (ENOENT). */
+    connect(): Promise<void>;
+    /**
+     * Send a command and await its response (correlated by id).
+     * `timeoutMs` overrides the default (defaults to requestTimeoutMs).
+     */
+    request(command: PiRpcCommand, timeoutMs?: number): Promise<PiRpcResponse>;
+    /** Fire-and-forget command (no response awaited) — e.g. `abort`. */
+    notify(command: PiRpcCommand): void;
+    dispose(): Promise<void>;
+    private handleMessage;
+    private failPending;
+}

package/dist/runner/pi/rpc/client.js

@@ -0,0 +1,114 @@
+/**
+ * PiRpcClient: JSON-lines client for pi's `--mode rpc` protocol.
+ *
+ * Reuses the shared JsonlRpcTransport (spawn + line read/write + graceful
+ * close) but speaks pi's own framing — commands `{type,id,...}` on stdin,
+ * responses `{id,type:"response",command,success,...}` and bare events on
+ * stdout — rather than JSON-RPC. There is no initialize handshake: the server
+ * starts streaming events immediately after spawn.
+ *
+ * Response correlation is by command id; every non-response line is forwarded
+ * as an event to the active hooks (the runner's translator).
+ */
+import { ConnectionLostError } from '../../common/jsonrpc/client.js';
+export class PiRpcClient {
+    transport;
+    requestTimeoutMs;
+    /** Connection-layer close hook (slot cleanup) — survives setHooks(). */
+    baseOnClose;
+    /** Per-run hooks from the runner. */
+    runHooks = null;
+    pending = new Map();
+    nextId = 1;
+    _disposed = false;
+    _ready = false;
+    constructor(transport, baseOnClose, requestTimeoutMs = 60_000) {
+        this.transport = transport;
+        this.baseOnClose = baseOnClose;
+        this.requestTimeoutMs = requestTimeoutMs;
+    }
+    /** Replace the per-run hooks (runner wires its translator + failTurn here). */
+    setHooks(hooks) {
+        this.runHooks = hooks;
+    }
+    get ready() {
+        return this._ready;
+    }
+    get healthy() {
+        return !this._disposed && !this.transport.closed;
+    }
+    /** Start the transport. Throws ConnectionLostError if spawn fails (ENOENT). */
+    async connect() {
+        const events = {
+            onMessage: (msg) => this.handleMessage(msg),
+            onClose: () => {
+                this.failPending(new ConnectionLostError('pi rpc transport closed'));
+                this.baseOnClose();
+                this.runHooks?.onClose?.();
+            },
+        };
+        await this.transport.start(events);
+        if (this.transport.closed) {
+            throw new ConnectionLostError('pi RPC server failed to start (binary missing or crashed)');
+        }
+        this._ready = true;
+    }
+    /**
+     * Send a command and await its response (correlated by id).
+     * `timeoutMs` overrides the default (defaults to requestTimeoutMs).
+     */
+    async request(command, timeoutMs) {
+        if (this._disposed || this.transport.closed) {
+            throw new ConnectionLostError('pi rpc client is disposed/closed');
+        }
+        const id = `req_${this.nextId++}`;
+        return new Promise((resolve, reject) => {
+            const effectiveTimeout = Math.min(timeoutMs ?? this.requestTimeoutMs, 2_147_483_647);
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new Error(`timeout waiting for pi rpc response: ${command.type}`));
+            }, effectiveTimeout);
+            this.pending.set(id, { resolve, reject, timer });
+            this.transport.write({ ...command, id });
+        });
+    }
+    /** Fire-and-forget command (no response awaited) — e.g. `abort`. */
+    notify(command) {
+        if (this._disposed || this.transport.closed)
+            return;
+        this.transport.write({ ...command, id: `req_${this.nextId++}` });
+    }
+    async dispose() {
+        if (this._disposed)
+            return;
+        this._disposed = true;
+        this._ready = false;
+        this.failPending(new ConnectionLostError('pi rpc client disposed'));
+        await this.transport.close();
+    }
+    // =========================================================================
+    // Internal
+    // =========================================================================
+    handleMessage(msg) {
+        const message = msg;
+        if (message.type === 'response' && message.id != null) {
+            const id = String(message.id);
+            const pending = this.pending.get(id);
+            if (pending) {
+                clearTimeout(pending.timer);
+                this.pending.delete(id);
+                pending.resolve(message);
+            }
+            return;
+        }
+        this.runHooks?.onEvent?.(message);
+    }
+    failPending(err) {
+        for (const [_id, pending] of this.pending) {
+            clearTimeout(pending.timer);
+            pending.reject(err);
+        }
+        this.pending.clear();
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/runner/pi/rpc/index.d.ts

@@ -0,0 +1,4 @@
+export { PiRpcRunner } from './runner.js';
+export type { PiRpcRunnerOptions } from './runner.js';
+export { PiRpcClient } from './client.js';
+export { PiRpcTranslator } from './translator.js';

package/dist/runner/pi/rpc/index.js

@@ -0,0 +1,4 @@
+export { PiRpcRunner } from './runner.js';
+export { PiRpcClient } from './client.js';
+export { PiRpcTranslator } from './translator.js';
+//# sourceMappingURL=index.js.map

package/dist/runner/pi/rpc/protocol-types.d.ts

@@ -0,0 +1,127 @@
+/**
+ * Pi RPC protocol types.
+ *
+ * pi's `--mode rpc` is a headless JSON-lines protocol over stdio (NOT JSON-RPC):
+ *   - client → stdin:  commands `{ type, id, ... }`
+ *   - server → stdout: responses `{ id, type:"response", command, success, data|error }`
+ *                     and events (session lifecycle / message / compaction) as bare
+ *                     JSON objects (no envelope).
+ *
+ * Turn semantics (verified live against pi 0.84.1, 2026-08-18):
+ *   - `prompt` returns an ack (`success:true`) immediately; the turn then streams
+ *     events and completes with an `agent_settled` event.
+ *   - `compact` runs synchronously and returns its response at completion; it also
+ *     streams `compaction_start` / `compaction_end` events.
+ *   - `abort` cancels the current operation.
+ *   - `get_state` returns the bound session id (`data.sessionId`) — pi binds the
+ *     session at spawn via `--session-id`, so this is how a new session's id is
+ *     discovered.
+ */
+export type PiRpcCommand = {
+    type: 'prompt';
+    message: string;
+    images?: unknown[];
+} | {
+    type: 'compact';
+    customInstructions?: string;
+} | {
+    type: 'abort';
+} | {
+    type: 'new_session';
+    parentSession?: string;
+} | {
+    type: 'get_state';
+};
+export interface PiRpcGetStateData {
+    model?: unknown;
+    sessionId: string;
+    sessionFile?: string;
+    isStreaming?: boolean;
+    isCompacting?: boolean;
+    [key: string]: unknown;
+}
+export interface PiRpcSuccessResponse {
+    id?: string | number;
+    type: 'response';
+    command: string;
+    success: true;
+    data?: unknown;
+}
+export interface PiRpcErrorResponse {
+    id?: string | number;
+    type: 'response';
+    command: string;
+    success: false;
+    error: string;
+}
+export type PiRpcResponse = PiRpcSuccessResponse | PiRpcErrorResponse;
+export interface PiRpcSessionEvent {
+    type: 'session';
+    id: string;
+    cwd: string;
+    model?: string;
+}
+export interface PiRpcAgentEvent {
+    type: 'agent_start' | 'agent_end' | 'agent_settled';
+}
+export interface PiRpcTurnEvent {
+    type: 'turn_start' | 'turn_end';
+    message?: {
+        usage?: PiRpcUsage;
+    };
+}
+export interface PiRpcMessageStartEvent {
+    type: 'message_start';
+    message: {
+        role: 'user' | 'assistant' | 'toolResult';
+        content?: unknown[];
+        usage?: PiRpcUsage;
+    };
+}
+export interface PiRpcMessageUpdateEvent {
+    type: 'message_update';
+    usage?: PiRpcUsage;
+    assistantMessageEvent: {
+        type: 'text_start' | 'text_delta' | 'text_end' | 'thinking_start' | 'thinking_delta' | 'thinking_end' | 'toolcall_start' | 'toolcall_delta' | 'toolcall_end';
+        contentIndex?: number;
+        delta?: string;
+        content?: string;
+        toolCall?: {
+            id: string;
+            name: string;
+            arguments: Record<string, unknown>;
+        };
+    };
+}
+export interface PiRpcMessageEndEvent {
+    type: 'message_end';
+    message: {
+        role: 'user' | 'assistant' | 'toolResult';
+        content?: unknown[];
+        usage?: PiRpcUsage;
+        toolCallId?: string;
+        toolName?: string;
+        isError?: boolean;
+        stopReason?: string;
+        errorMessage?: string;
+    };
+}
+export interface PiRpcCompactionEvent {
+    type: 'compaction_start' | 'compaction_end';
+    reason?: string;
+    aborted?: boolean;
+    willRetry?: boolean;
+    errorMessage?: string;
+}
+export interface PiRpcUsage {
+    input?: number;
+    output?: number;
+    cacheRead?: number;
+    cacheWrite?: number;
+    totalTokens?: number;
+    reasoning?: number;
+}
+/** Any event line emitted by the pi RPC server (excluding responses). */
+export type PiRpcEvent = PiRpcSessionEvent | PiRpcAgentEvent | PiRpcTurnEvent | PiRpcMessageStartEvent | PiRpcMessageUpdateEvent | PiRpcMessageEndEvent | PiRpcCompactionEvent | {
+    type: string;
+};