lark-remote 0.1.6 → 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/{codex/app-server → common/jsonrpc}/client.d.ts

@@ -1,11 +1,13 @@
 /**
- * JSON-RPC client for the Codex App Server protocol.
+ * 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.
+ * 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';
-import { type InitializeResult } from './protocol-types.js';
 export declare class RpcError extends Error {
     readonly code: number;
     readonly data?: unknown;
@@ -22,7 +24,7 @@ export interface ClientHooks {
     onServerRequest(id: number | string, method: string, params: unknown): void;
     onClose(): void;
 }
-export declare class CodexAppServerClient {
+export declare class JsonRpcClient<InitializeResult = unknown> {
     private transport;
     /**
      * Lifecycle hooks owned by the connection layer (ConnectionManager): slot
@@ -32,17 +34,18 @@ export declare class CodexAppServerClient {
     /** 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);
+    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 app-server process was killed.
+     * leaving dead slots behind after the server process was killed.
      */
     setHooks(hooks: ClientHooks): void;
     get ready(): boolean;
@@ -59,8 +62,12 @@ export declare class CodexAppServerClient {
     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): Promise<R>;
+    request<P, R>(method: string, params?: P, timeoutMs?: number): Promise<R>;
     /**
      * Send a JSON-RPC notification (no response expected).
      */

package/dist/runner/{codex/app-server → common/jsonrpc}/client.js

@@ -1,8 +1,11 @@
 /**
- * JSON-RPC client for the Codex App Server protocol.
+ * 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.
+ * 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';
 // =============================================================================
@@ -33,7 +36,7 @@ export class ConnectionLostError extends Error {
 // =============================================================================
 // Client
 // =============================================================================
-export class CodexAppServerClient {
+export class JsonRpcClient {
     transport;
     /**
      * Lifecycle hooks owned by the connection layer (ConnectionManager): slot
@@ -43,21 +46,23 @@ export class CodexAppServerClient {
     /** 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) {
+    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 app-server process was killed.
+     * leaving dead slots behind after the server process was killed.
      */
     setHooks(hooks) {
         this.runHooks = hooks;
@@ -92,26 +97,27 @@ export class CodexAppServerClient {
         // ENOENT/启动失败时 transport 已在 start() 内触发 onClose 并置 closed；
         // 直接 fail-fast，避免 initialize 请求挂满 requestTimeoutMs 才报错。
         if (this.transport.closed) {
-            throw new ConnectionLostError('codex app-server failed to start (binary missing or crashed)');
+            throw new ConnectionLostError('JSON-RPC server failed to start (binary missing or crashed)');
         }
-        // Send initialize request
-        const initParams = {
-            clientInfo: {
-                name: 'lark-remote',
-                version: '1.0.0',
-            },
-        };
-        const result = await this.request('initialize', initParams);
+        // 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) {
+    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',
@@ -120,10 +126,13 @@ export class CodexAppServerClient {
             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}`));
-            }, this.requestTimeoutMs);
+            }, effectiveTimeout);
             this.pendingRequests.set(id, {
                 resolve: resolve,
                 reject,
@@ -214,14 +223,14 @@ export class CodexAppServerClient {
             return;
         }
         if ('method' in message && 'id' in message) {
-            // Server request (incoming request from server)
+            // 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(`[codex-client] unknown message type: ${JSON.stringify(message).slice(0, 200)}`);
+        getLogger().warn(`[jsonrpc-client] unknown message type: ${JSON.stringify(message).slice(0, 200)}`);
     }
     failPending(err) {
         for (const [_id, pending] of this.pendingRequests) {

package/dist/runner/common/jsonrpc/connection-manager.d.ts

@@ -0,0 +1,125 @@
+/**
+ * ConnectionManager: manages agent-server connections per workspace, shared by
+ * all workspace-lifetime JSON-line runners (codex app-server, kimi acp,
+ * opencode acp, and pi rpc).
+ *
+ * Each workspace gets its own connection (transport + client). Connections are
+ * created on demand via `acquire()`, cached for reuse, and released after an
+ * idle timeout (30 minutes default).
+ *
+ * The manager is protocol-agnostic over the concrete client. The default
+ * `clientFactory` builds a JsonRpcClient with the `initialize` handshake (the
+ * ACP-style reference protocol); protocols that are NOT JSON-RPC (pi's
+ * `--mode rpc`, which has no handshake and binds the session at spawn) inject
+ * their own `clientFactory` + `buildArgs` + `shouldReuse` + `bindSession`.
+ */
+import { JsonlRpcTransport } from './transport.js';
+import { JsonRpcClient } from './client.js';
+/** Minimal client surface the manager needs from any protocol client. */
+export interface ConnectionClient {
+    ready: boolean;
+    healthy: boolean;
+    connect(): Promise<unknown>;
+    dispose(): Promise<void>;
+}
+/** Request context for acquire() — currently only an optional session id. */
+export interface AcquireRequest {
+    sessionId?: string;
+}
+/** Context passed to clientFactory to build + wire a concrete client. */
+export interface ClientFactoryContext {
+    transport: JsonlRpcTransport;
+    requestTimeoutMs: number;
+    /** Wire into the client's close callback so slot cleanup + onConnectionLost fire. */
+    baseOnClose: () => void;
+}
+export interface ConnectionManagerOptions<TClient extends ConnectionClient = JsonRpcClient> {
+    /** Path to the server binary. */
+    binary: string;
+    /**
+     * Args to spawn the server with. Defaults to `[]` — each protocol's runner
+     * injects its own default (e.g. codex `['app-server', '--stdio']`, kimi
+     * `['acp']`).
+     */
+    args?: string[];
+    /**
+     * Optional arg builder over the acquire request — used by protocols that bind
+     * a session at spawn (pi: `--session-id`). Defaults to `() => this.args`.
+     */
+    buildArgs?: (req: AcquireRequest) => string[];
+    /** Environment variables to pass to the binary. */
+    env?: Record<string, string | undefined>;
+    /** Request timeout in milliseconds. */
+    requestTimeoutMs?: number;
+    /** Idle TTL in milliseconds. */
+    idleTtlMs?: number;
+    /**
+     * Initialize handshake params for the default JsonRpcClient path. Ignored
+     * when `clientFactory` is provided.
+     */
+    initializeParams?: object;
+    /**
+     * Build + wire a concrete protocol client. Defaults to a JsonRpcClient with
+     * the initialize handshake. Non-JSON-RPC protocols inject their own client.
+     */
+    clientFactory?: (ctx: ClientFactoryContext) => TClient;
+    /**
+     * Whether an existing (cached) connection can be reused for a request.
+     * Defaults to `client.ready && client.healthy`. Session-bound protocols (pi)
+     * additionally require the requested session id to match the bound one.
+     */
+    shouldReuse?: (ctx: {
+        client: TClient;
+        req: AcquireRequest;
+        boundSessionId: string | undefined;
+    }) => boolean;
+    /** Log tag prefix for operational log lines. */
+    logTag?: string;
+}
+export declare class ConnectionManager<TClient extends ConnectionClient = JsonRpcClient> {
+    private slots;
+    private readonly binary;
+    private readonly buildArgs;
+    private readonly env;
+    private readonly requestTimeoutMs;
+    private readonly idleTtlMs;
+    private readonly initializeParams;
+    private readonly clientFactory;
+    private readonly shouldReuse;
+    private readonly logTag;
+    /** Callback when a connection is lost — cleared from slot map. */
+    onConnectionLost?: (workspace: string) => void;
+    constructor(opts: ConnectionManagerOptions<TClient>);
+    /**
+     * Acquire a connection for the given workspace.
+     * Creates a new connection if one does not exist or the previous one was lost
+     * (or, for session-bound protocols, bound to a different session).
+     * Serializes creation so concurrent calls share the same connection.
+     */
+    acquire(workspace: string, req?: AcquireRequest): Promise<TClient>;
+    /**
+     * Record the session id a fresh connection actually bound to (e.g. discovered
+     * via a protocol `get_state` after a fresh spawn). This lets a subsequent run
+     * resume the SAME session on the live connection instead of respawning it.
+     */
+    bindSession(workspace: string, sessionId: string): void;
+    /**
+     * Release (dispose) a connection for the given workspace.
+     */
+    release(workspace: string): Promise<void>;
+    /**
+     * Dispose all connections.
+     */
+    disposeAll(): Promise<void>;
+    /**
+     * Notify that the workspace is active — disarm the idle timer.
+     */
+    notifyActivity(workspace: string): void;
+    /**
+     * Notify that the workspace is idle — arm the idle timer.
+     */
+    notifyIdle(workspace: string): void;
+    private createClient;
+    private clearIdleTimer;
+    private disposeSlot;
+}