lark-remote 0.1.5 → 0.1.7

package/dist/runner/common/connection-based-runner.js

@@ -0,0 +1,261 @@
+import { ConnectionLostError } from './jsonrpc/client.js';
+import { getLogger } from '../../logger/index.js';
+import { syntheticInitEvent } from './runner-utils.js';
+/** How long to wait for turn output notifications before failing. */
+export const TURN_IDLE_TIMEOUT_MS = 10 * 60 * 1000;
+export class ConnectionBasedRunner {
+    kind;
+    sessionReader;
+    lifetime = 'workspace';
+    currentClient = null;
+    currentTurnId = null;
+    lastEventAt = 0;
+    _isRunning = false;
+    turnIdleTimeoutMs;
+    /** Notification queue consumed by the active run generator. */
+    notificationQueue = [];
+    waitResolve = null;
+    forceFinish = false;
+    /** stop() 在 turn/start 或 prompt 响应前到达时置位，完成后再补发 cancel/interrupt。 */
+    stopRequested = false;
+    constructor(opts, defaultTurnIdleTimeoutMs = TURN_IDLE_TIMEOUT_MS) {
+        this.kind = opts.kind;
+        this.sessionReader = opts.sessionReader;
+        this.turnIdleTimeoutMs = opts.turnIdleTimeoutMs ?? defaultTurnIdleTimeoutMs;
+    }
+    get isRunning() {
+        return this._isRunning;
+    }
+    /**
+     * Run a message. Delegates to executeTurn() with the standard setup.
+     */
+    async *run(message, opts) {
+        yield* this.executeTurn(opts, () => this.setupTurn(message, opts));
+    }
+    /**
+     * Shared turn lifecycle used by run() and runCompact(): isRunning guard →
+     * resetRunState → setupFn (with connection-lost respawn-and-retry-once) →
+     * deferred stop → synthetic init → consumeTurn; catch yields synthetic init
+     * + error result; finally resets flags + notifyIdle.
+     *
+     * `setupFn` performs the turn-specific setup (acquire, session new/resume,
+     * prompt, etc.) and may push events into the notification queue.
+     */
+    async *executeTurn(opts, setupFn) {
+        if (this._isRunning) {
+            throw new Error(`${this.constructor.name} is already running`);
+        }
+        this._isRunning = true;
+        this.resetRunState();
+        try {
+            try {
+                await setupFn();
+            }
+            catch (err) {
+                // 连接在 setup 期间丢失（进程被误杀/异常退出）：重拉进程并重试一次。
+                if (err instanceof ConnectionLostError && !this.stopRequested) {
+                    getLogger().warn(`[${this.logTag}] connection lost during turn setup (${err.message}), respawning and retrying once`);
+                    await this.respawnAfterConnectionLost(opts);
+                    await setupFn();
+                }
+                else {
+                    throw err;
+                }
+            }
+            if (this.stopRequested) {
+                // 启动期 /stop：turn/start 或 prompt 尚未完成，补发 cancel/interrupt，
+                // 避免 server 端 turn 无人接管继续执行。
+                getLogger().warn(`[${this.logTag}] stop requested before turn resolved`);
+                try {
+                    await this.cancelCurrentTurn();
+                }
+                catch (err) {
+                    getLogger().warn(`[${this.logTag}] deferred cancel failed: ${err.message}`);
+                }
+            }
+            // §9.22 守卫前提：桥的 pre-init result guard 和 run-state reducer 都以
+            // system.init 作为「本轮真实开始」的标记，而这些协议没有 init 事件。
+            // 缺了它，成功的 result 会被当作 pre-init 丢弃，卡片终态停在 running。
+            yield syntheticInitEvent(this.currentSessionId() ?? opts.sessionId ?? '');
+            yield* this.consumeTurn();
+        }
+        catch (err) {
+            getLogger().error(`[${this.logTag}] run error: ${err.message}`);
+            yield syntheticInitEvent(this.currentSessionId() ?? opts.sessionId ?? '');
+            yield {
+                type: 'result',
+                subtype: 'error',
+                // 优先上报本次 setup 创建/恢复的 session/thread id。
+                session_id: this.currentSessionId() ?? opts.sessionId ?? '',
+                errorMessage: err.message,
+            };
+        }
+        finally {
+            this._isRunning = false;
+            this.currentTurnId = null;
+            this.stopRequested = false;
+            this.clearTurnState();
+            this.notifyIdle(opts.cwd);
+        }
+    }
+    /**
+     * Stop the current turn by cancelling it. Shared skeleton: if the turn/start
+     * or prompt has not yet resolved (shouldDeferStop), mark stopRequested and
+     * unblock; otherwise cancel now via cancelCurrentTurn().
+     */
+    async stop(_opts) {
+        if (!this._isRunning || !this.currentClient || !this.currentSessionId())
+            return;
+        if (this.shouldDeferStop()) {
+            // turn/start 或 prompt 尚未响应：先标记，等 run() 完成后再补发 cancel。
+            this.stopRequested = true;
+            this.forceFinish = true;
+            this.wakeWaiters();
+            return;
+        }
+        // turn/start 或 prompt 已 resolved：立即 cancel；同时置 stopRequested 抑制
+        // 尚未结算的 prompt 结果翻译（opencode 语义），对已结算方无害。
+        this.stopRequested = true;
+        try {
+            await this.cancelCurrentTurn();
+        }
+        catch (err) {
+            getLogger().warn(`[${this.logTag}] stop error: ${err.message}`);
+        }
+        // Unblock the turn loop regardless of whether the server sends a
+        // completed notification afterwards.
+        this.forceFinish = true;
+        this.wakeWaiters();
+    }
+    /**
+     * Dispose the runner: release the connection.
+     */
+    async dispose() {
+        try {
+            await this.disposeConnections();
+        }
+        catch (err) {
+            getLogger().warn(`[${this.logTag}] dispose error: ${err.message}`);
+        }
+    }
+    getUsageAuthority() {
+        return 'live';
+    }
+    killOrphan() {
+        // No-op: the connection is managed by ConnectionManager.
+    }
+    registerExitHandlers() {
+        // No-op: connection manager handles cleanup on exit.
+    }
+    unregisterExitHandlers() {
+        // No-op.
+    }
+    // =========================================================================
+    // Shared turn machinery
+    // =========================================================================
+    /**
+     * Consume the notification queue until a result event arrives or the turn
+     * times out / is interrupted. forceFinish drains the queue first (the
+     * deferred cancel's own events may still be in it) before yielding the
+     * interrupted result.
+     */
+    async *consumeTurn() {
+        while (true) {
+            const timedOut = await this.waitForEvents(this.nextTurnIdleDeadline());
+            if (timedOut) {
+                await this.cancelCurrentTurn();
+                getLogger().warn(`[${this.logTag}] turn wait timed out`);
+                yield {
+                    type: 'result',
+                    subtype: 'error',
+                    session_id: this.currentSessionId() ?? '',
+                    errorMessage: this.turnTimeoutErrorMessage,
+                };
+                return;
+            }
+            if (this.forceFinish && this.notificationQueue.length === 0) {
+                yield {
+                    type: 'result',
+                    subtype: 'interrupted',
+                    session_id: this.currentSessionId() ?? '',
+                    errorMessage: this.turnInterruptedErrorMessage,
+                };
+                return;
+            }
+            while (this.notificationQueue.length > 0) {
+                const ev = this.notificationQueue.shift();
+                yield ev;
+                if (ev.type === 'result') {
+                    return;
+                }
+            }
+        }
+    }
+    /** Compute the current idle deadline. 0 disables; otherwise rolling on last event. */
+    nextTurnIdleDeadline() {
+        if (this.turnIdleTimeoutMs <= 0)
+            return Number.POSITIVE_INFINITY;
+        return this.lastEventAt + this.turnIdleTimeoutMs;
+    }
+    async waitForEvents(deadline) {
+        while (this.notificationQueue.length === 0 && !this.forceFinish) {
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                return true;
+            await new Promise((resolve) => {
+                this.waitResolve = resolve;
+                setTimeout(() => {
+                    if (this.waitResolve === resolve) {
+                        this.waitResolve = null;
+                        resolve();
+                    }
+                }, Math.min(remaining, 30_000));
+            });
+        }
+        return false;
+    }
+    pushEvents(events) {
+        if (events.length === 0)
+            return;
+        this.lastEventAt = Date.now();
+        this.notificationQueue.push(...events);
+        this.wakeWaiters();
+    }
+    wakeWaiters() {
+        if (this.waitResolve) {
+            const resolve = this.waitResolve;
+            this.waitResolve = null;
+            resolve();
+        }
+    }
+    failTurn(message) {
+        this.pushEvents([
+            {
+                type: 'result',
+                subtype: 'error',
+                session_id: this.currentSessionId() ?? '',
+                errorMessage: message,
+            },
+        ]);
+    }
+    resetRunState() {
+        this.notificationQueue = [];
+        this.waitResolve = null;
+        this.lastEventAt = Date.now();
+        this.forceFinish = false;
+    }
+    /** Release the connection + detach stale client hooks after a lost connection. */
+    async respawnAfterConnectionLost(opts) {
+        await this.releaseConnection(opts.cwd);
+        const staleClient = this.currentClient;
+        if (staleClient?.setHooks) {
+            staleClient.setHooks({
+                onNotification: () => { },
+                onServerRequest: () => { },
+                onClose: () => { },
+            });
+        }
+        this.resetRunState();
+    }
+}
+//# sourceMappingURL=connection-based-runner.js.map

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

@@ -0,0 +1,89 @@
+/**
+ * Generic JSON-RPC client for JSON-line-RPC agent servers
+ * (codex app-server, kimi acp, and future ACP-style integrations).
+ *
+ * Manages the handshake, request/response matching, notification dispatch,
+ * and timeout handling over a JsonlRpcTransport. The `initialize` params
+ * shape is protocol-specific and injected by the caller (constructor arg);
+ * the default is the ACP handshake shape (ACP is the reference protocol).
+ */
+import type { JsonlRpcTransport } from './transport.js';
+export declare class RpcError extends Error {
+    readonly code: number;
+    readonly data?: unknown;
+    constructor(code: number, message: string, data?: unknown);
+}
+export declare class RpcTimeoutError extends Error {
+    constructor(message: string);
+}
+export declare class ConnectionLostError extends Error {
+    constructor(message?: string);
+}
+export interface ClientHooks {
+    onNotification(method: string, params: unknown): void;
+    onServerRequest(id: number | string, method: string, params: unknown): void;
+    onClose(): void;
+}
+export declare class JsonRpcClient<InitializeResult = unknown> {
+    private transport;
+    /**
+     * Lifecycle hooks owned by the connection layer (ConnectionManager): slot
+     * cleanup + onConnectionLost. These must survive runner's setHooks().
+     */
+    private baseHooks;
+    /** Per-run hooks from the runner, layered over baseHooks via setHooks(). */
+    private runHooks;
+    private requestTimeoutMs;
+    private initializeParams;
+    private pendingRequests;
+    private nextId;
+    private _ready;
+    private _disposed;
+    constructor(transport: JsonlRpcTransport, hooks: ClientHooks, requestTimeoutMs: number | undefined, initializeParams: object);
+    /**
+     * Replace the per-run hooks (used by the runner to bridge
+     * notifications/server requests into the active turn's translator).
+     * Connection-layer hooks (slot cleanup / onConnectionLost) are preserved:
+     * review P2-1 — an overwrite here previously silenced onClose slot cleanup,
+     * leaving dead slots behind after the server process was killed.
+     */
+    setHooks(hooks: ClientHooks): void;
+    get ready(): boolean;
+    /**
+     * Whether the underlying transport is still alive (not disposed and not
+     * closed). Used by the connection manager to avoid handing out a cached
+     * client whose child process was killed externally.
+     */
+    get healthy(): boolean;
+    /**
+     * Connect and perform the initialize handshake.
+     * Returns the InitializeResult on success.
+     */
+    connect(): Promise<InitializeResult>;
+    /**
+     * Send a JSON-RPC request and wait for the response.
+     * `timeoutMs` overrides the default request timeout — turn-scoped requests
+     * (e.g. session/prompt) hold their response open for the whole turn, so
+     * callers pass the turn idle timeout (bounded by the runner's turn idle
+     * watchdog, not the control-plane request timeout).
+     */
+    request<P, R>(method: string, params?: P, timeoutMs?: number): Promise<R>;
+    /**
+     * Send a JSON-RPC notification (no response expected).
+     */
+    notify(method: string, params?: unknown): void;
+    /**
+     * Respond to a server request (success).
+     */
+    respond(id: number | string, result: unknown): void;
+    /**
+     * Respond to a server request (error).
+     */
+    respondError(id: number | string, code: number, message: string): void;
+    /**
+     * Dispose the client: cancel pending requests and close transport.
+     */
+    dispose(): Promise<void>;
+    private handleMessage;
+    private failPending;
+}

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

@@ -0,0 +1,243 @@
+/**
+ * Generic JSON-RPC client for JSON-line-RPC agent servers
+ * (codex app-server, kimi acp, and future ACP-style integrations).
+ *
+ * Manages the handshake, request/response matching, notification dispatch,
+ * and timeout handling over a JsonlRpcTransport. The `initialize` params
+ * shape is protocol-specific and injected by the caller (constructor arg);
+ * the default is the ACP handshake shape (ACP is the reference protocol).
+ */
+import { getLogger } from '../../../logger/index.js';
+// =============================================================================
+// Error Types
+// =============================================================================
+export class RpcError extends Error {
+    code;
+    data;
+    constructor(code, message, data) {
+        super(message);
+        this.name = 'RpcError';
+        this.code = code;
+        this.data = data;
+    }
+}
+export class RpcTimeoutError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RpcTimeoutError';
+    }
+}
+export class ConnectionLostError extends Error {
+    constructor(message = 'Connection lost') {
+        super(message);
+        this.name = 'ConnectionLostError';
+    }
+}
+// =============================================================================
+// Client
+// =============================================================================
+export class JsonRpcClient {
+    transport;
+    /**
+     * Lifecycle hooks owned by the connection layer (ConnectionManager): slot
+     * cleanup + onConnectionLost. These must survive runner's setHooks().
+     */
+    baseHooks;
+    /** Per-run hooks from the runner, layered over baseHooks via setHooks(). */
+    runHooks = null;
+    requestTimeoutMs;
+    initializeParams;
+    pendingRequests = new Map();
+    nextId = 1;
+    _ready = false;
+    _disposed = false;
+    constructor(transport, hooks, requestTimeoutMs = 60_000, initializeParams) {
+        this.transport = transport;
+        this.baseHooks = hooks;
+        this.requestTimeoutMs = requestTimeoutMs;
+        this.initializeParams = initializeParams;
+    }
+    /**
+     * Replace the per-run hooks (used by the runner to bridge
+     * notifications/server requests into the active turn's translator).
+     * Connection-layer hooks (slot cleanup / onConnectionLost) are preserved:
+     * review P2-1 — an overwrite here previously silenced onClose slot cleanup,
+     * leaving dead slots behind after the server process was killed.
+     */
+    setHooks(hooks) {
+        this.runHooks = hooks;
+    }
+    get ready() {
+        return this._ready;
+    }
+    /**
+     * Whether the underlying transport is still alive (not disposed and not
+     * closed). Used by the connection manager to avoid handing out a cached
+     * client whose child process was killed externally.
+     */
+    get healthy() {
+        return !this._disposed && !this.transport.closed;
+    }
+    /**
+     * Connect and perform the initialize handshake.
+     * Returns the InitializeResult on success.
+     */
+    async connect() {
+        const events = {
+            onMessage: (msg) => this.handleMessage(msg),
+            onClose: () => {
+                this.failPending(new ConnectionLostError('transport closed'));
+                // 先通知连接层（slot 清理 + onConnectionLost），再通知当前 run 层
+                // （failTurn 等）。两层互不覆盖。
+                this.baseHooks.onClose();
+                this.runHooks?.onClose();
+            },
+        };
+        await this.transport.start(events);
+        // ENOENT/启动失败时 transport 已在 start() 内触发 onClose 并置 closed；
+        // 直接 fail-fast，避免 initialize 请求挂满 requestTimeoutMs 才报错。
+        if (this.transport.closed) {
+            throw new ConnectionLostError('JSON-RPC server failed to start (binary missing or crashed)');
+        }
+        // Send initialize request (shape injected by the caller)
+        const result = await this.request('initialize', this.initializeParams);
+        this._ready = true;
+        return result;
+    }
+    /**
+     * Send a JSON-RPC request and wait for the response.
+     * `timeoutMs` overrides the default request timeout — turn-scoped requests
+     * (e.g. session/prompt) hold their response open for the whole turn, so
+     * callers pass the turn idle timeout (bounded by the runner's turn idle
+     * watchdog, not the control-plane request timeout).
+     */
+    async request(method, params, timeoutMs) {
+        if (this._disposed) {
+            throw new ConnectionLostError('client is disposed');
+        }
+        if (this.transport.closed) {
+            throw new ConnectionLostError('transport closed');
+        }
+        const id = this.nextId++;
+        const request = {
+            jsonrpc: '2.0',
+            id,
+            method,
+            params,
+        };
+        return new Promise((resolve, reject) => {
+            // Clamp to setTimeout's max: callers may pass Infinity for turn-scoped
+            // requests (session/prompt) — Infinity would fire immediately in Node.
+            const effectiveTimeout = Math.min(timeoutMs ?? this.requestTimeoutMs, 2_147_483_647);
+            const timer = setTimeout(() => {
+                this.pendingRequests.delete(id);
+                reject(new RpcTimeoutError(`request timed out: ${method}`));
+            }, effectiveTimeout);
+            this.pendingRequests.set(id, {
+                resolve: resolve,
+                reject,
+                timer,
+            });
+            this.transport.write(request);
+        });
+    }
+    /**
+     * Send a JSON-RPC notification (no response expected).
+     */
+    notify(method, params) {
+        if (this._disposed)
+            return;
+        const notification = {
+            jsonrpc: '2.0',
+            method,
+            params,
+        };
+        this.transport.write(notification);
+    }
+    /**
+     * Respond to a server request (success).
+     */
+    respond(id, result) {
+        const response = {
+            jsonrpc: '2.0',
+            id,
+            result,
+        };
+        this.transport.write(response);
+    }
+    /**
+     * Respond to a server request (error).
+     */
+    respondError(id, code, message) {
+        const response = {
+            jsonrpc: '2.0',
+            id,
+            error: { code, message },
+        };
+        this.transport.write(response);
+    }
+    /**
+     * Dispose the client: cancel pending requests and close transport.
+     */
+    async dispose() {
+        if (this._disposed)
+            return;
+        this._disposed = true;
+        this._ready = false;
+        this.failPending(new ConnectionLostError('client disposed'));
+        await this.transport.close();
+    }
+    // =========================================================================
+    // Internal
+    // =========================================================================
+    handleMessage(msg) {
+        const message = msg;
+        if ('id' in message && 'result' in message) {
+            // Success response
+            const id = message.id;
+            const pending = this.pendingRequests.get(id);
+            if (pending) {
+                clearTimeout(pending.timer);
+                this.pendingRequests.delete(id);
+                pending.resolve(message.result);
+            }
+            return;
+        }
+        if ('id' in message && 'error' in message) {
+            // Error response
+            const id = message.id;
+            const err = message.error;
+            const pending = this.pendingRequests.get(id);
+            if (pending) {
+                clearTimeout(pending.timer);
+                this.pendingRequests.delete(id);
+                pending.reject(new RpcError(err.code, err.message, err.data));
+            }
+            return;
+        }
+        if ('method' in message && !('id' in message)) {
+            // Notification
+            const method = message.method;
+            this.baseHooks.onNotification(method, message.params);
+            this.runHooks?.onNotification(method, message.params);
+            return;
+        }
+        if ('method' in message && 'id' in message) {
+            // Server request (incoming request from server — reverse RPC)
+            const id = message.id;
+            const method = message.method;
+            this.baseHooks.onServerRequest(id, method, message.params);
+            this.runHooks?.onServerRequest(id, method, message.params);
+            return;
+        }
+        getLogger().warn(`[jsonrpc-client] unknown message type: ${JSON.stringify(message).slice(0, 200)}`);
+    }
+    failPending(err) {
+        for (const [_id, pending] of this.pendingRequests) {
+            clearTimeout(pending.timer);
+            pending.reject(err);
+        }
+        this.pendingRequests.clear();
+    }
+}
+//# sourceMappingURL=client.js.map