lark-remote 0.1.4 → 0.1.6

package/dist/runner/codex/app-server/client.d.ts

@@ -0,0 +1,82 @@
+/**
+ * JSON-RPC client for the Codex App Server protocol.
+ *
+ * Manages the handshake, request/response matching, notification dispatch,
+ * and timeout handling over a JsonlRpcTransport.
+ */
+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;
+    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 CodexAppServerClient {
+    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 pendingRequests;
+    private nextId;
+    private _ready;
+    private _disposed;
+    constructor(transport: JsonlRpcTransport, hooks: ClientHooks, requestTimeoutMs?: number);
+    /**
+     * 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.
+     */
+    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.
+     */
+    request<P, R>(method: string, params?: P): 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/codex/app-server/client.js

@@ -0,0 +1,234 @@
+/**
+ * JSON-RPC client for the Codex App Server protocol.
+ *
+ * Manages the handshake, request/response matching, notification dispatch,
+ * and timeout handling over a JsonlRpcTransport.
+ */
+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 CodexAppServerClient {
+    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;
+    pendingRequests = new Map();
+    nextId = 1;
+    _ready = false;
+    _disposed = false;
+    constructor(transport, hooks, requestTimeoutMs = 60_000) {
+        this.transport = transport;
+        this.baseHooks = hooks;
+        this.requestTimeoutMs = requestTimeoutMs;
+    }
+    /**
+     * 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.
+     */
+    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('codex app-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);
+        this._ready = true;
+        return result;
+    }
+    /**
+     * Send a JSON-RPC request and wait for the response.
+     */
+    async request(method, params) {
+        if (this._disposed) {
+            throw new ConnectionLostError('client is disposed');
+        }
+        const id = this.nextId++;
+        const request = {
+            jsonrpc: '2.0',
+            id,
+            method,
+            params,
+        };
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pendingRequests.delete(id);
+                reject(new RpcTimeoutError(`request timed out: ${method}`));
+            }, this.requestTimeoutMs);
+            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)
+            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)}`);
+    }
+    failPending(err) {
+        for (const [_id, pending] of this.pendingRequests) {
+            clearTimeout(pending.timer);
+            pending.reject(err);
+        }
+        this.pendingRequests.clear();
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/runner/codex/app-server/connection-manager.d.ts

@@ -0,0 +1,56 @@
+/**
+ * ConnectionManager: manages Codex App Server connections per workspace.
+ *
+ * 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).
+ */
+import { CodexAppServerClient } from './client.js';
+export interface ConnectionManagerOptions {
+    /** Path to the codex binary. */
+    binary: string;
+    /** Args to spawn the app server with. Defaults to `['app-server', '--stdio']`. */
+    args?: 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;
+}
+export declare class ConnectionManager {
+    private slots;
+    private readonly binary;
+    private readonly args;
+    private readonly env;
+    private readonly requestTimeoutMs;
+    private readonly idleTtlMs;
+    /** Callback when a connection is lost — cleared from slot map. */
+    onConnectionLost?: (workspace: string) => void;
+    constructor(opts: ConnectionManagerOptions);
+    /**
+     * Acquire a connection for the given workspace.
+     * Creates a new connection if one does not exist or the previous one was lost.
+     * Serializes creation so concurrent calls share the same connection.
+     */
+    acquire(workspace: string): Promise<CodexAppServerClient>;
+    /**
+     * 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;
+}

package/dist/runner/codex/app-server/connection-manager.js

@@ -0,0 +1,170 @@
+/**
+ * ConnectionManager: manages Codex App Server connections per workspace.
+ *
+ * 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).
+ */
+import { JsonlRpcTransport } from './transport.js';
+import { CodexAppServerClient } from './client.js';
+import { getLogger } from '../../../logger/index.js';
+const DEFAULT_IDLE_TTL_MS = 30 * 60 * 1000; // 30 minutes
+const DEFAULT_REQUEST_TIMEOUT_MS = 60_000; // 60 seconds
+export class ConnectionManager {
+    slots = new Map();
+    binary;
+    args;
+    env;
+    requestTimeoutMs;
+    idleTtlMs;
+    /** Callback when a connection is lost — cleared from slot map. */
+    onConnectionLost;
+    constructor(opts) {
+        this.binary = opts.binary;
+        this.args = opts.args ?? ['app-server', '--stdio'];
+        this.env = opts.env ?? {};
+        this.requestTimeoutMs = opts.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS;
+        this.idleTtlMs = opts.idleTtlMs ?? DEFAULT_IDLE_TTL_MS;
+    }
+    /**
+     * Acquire a connection for the given workspace.
+     * Creates a new connection if one does not exist or the previous one was lost.
+     * Serializes creation so concurrent calls share the same connection.
+     */
+    async acquire(workspace) {
+        const existing = this.slots.get(workspace);
+        if (existing) {
+            // If a create is in flight, wait for it
+            if (existing.createPromise) {
+                return existing.createPromise;
+            }
+            // If the client is ready and its transport is alive, return it
+            if (existing.client.ready && existing.client.healthy) {
+                return existing.client;
+            }
+            // Client is disposed, dead (e.g. app-server process killed externally),
+            // or not ready — replace it so the next run respawns the process.
+            this.disposeSlot(workspace);
+        }
+        const createPromise = this.createClient(workspace);
+        this.slots.set(workspace, {
+            client: null, // placeholder
+            idleTimer: null,
+            createPromise: createPromise,
+        });
+        try {
+            const client = await createPromise;
+            // P2-2 竞态：创建期间 release()/disposeAll() 已把 slot 删掉（并可能已
+            // dispose 连接）。此时不能再把新连接塞回 slot——否则会复活一个无人管理、
+            // 无 idle timer 的连接泄漏。归还给调用者继续使用，但不再缓存。
+            const slotAfterCreate = this.slots.get(workspace);
+            if (!slotAfterCreate || slotAfterCreate.createPromise !== createPromise) {
+                return client;
+            }
+            this.slots.set(workspace, {
+                client,
+                idleTimer: null,
+                createPromise: null,
+            });
+            return client;
+        }
+        catch (err) {
+            // 只删除自己的槽位：并发 release + 重新 acquire 后 slot 可能已被新的
+            // createPromise 占据，误删会破坏新连接。
+            const current = this.slots.get(workspace);
+            if (current && current.createPromise === createPromise) {
+                this.slots.delete(workspace);
+            }
+            throw err;
+        }
+    }
+    /**
+     * Release (dispose) a connection for the given workspace.
+     */
+    async release(workspace) {
+        this.disposeSlot(workspace);
+    }
+    /**
+     * Dispose all connections.
+     */
+    async disposeAll() {
+        const workspaces = [...this.slots.keys()];
+        await Promise.all(workspaces.map((w) => this.disposeSlot(w)));
+    }
+    /**
+     * Notify that the workspace is active — disarm the idle timer.
+     */
+    notifyActivity(workspace) {
+        const slot = this.slots.get(workspace);
+        if (slot) {
+            this.clearIdleTimer(slot);
+        }
+    }
+    /**
+     * Notify that the workspace is idle — arm the idle timer.
+     */
+    notifyIdle(workspace) {
+        const slot = this.slots.get(workspace);
+        if (slot) {
+            this.clearIdleTimer(slot);
+            slot.idleTimer = setTimeout(() => {
+                getLogger().info(`[codex-connection-manager] idle timeout for workspace=${workspace}, releasing connection`);
+                this.disposeSlot(workspace);
+            }, this.idleTtlMs);
+        }
+    }
+    // =========================================================================
+    // Internal
+    // =========================================================================
+    async createClient(workspace) {
+        const transport = new JsonlRpcTransport({
+            binary: this.binary,
+            args: this.args,
+            cwd: workspace,
+            env: this.env,
+        });
+        let client = null;
+        const hooks = {
+            onNotification: (_method, _params) => {
+                // Notifications are handled by the runner via translator
+            },
+            onServerRequest: (_id, _method, _params) => {
+                // Server requests are handled by the runner via translator
+            },
+            onClose: () => {
+                getLogger().info(`[codex-connection-manager] connection closed workspace=${workspace}`);
+                // 只清理自己创建的 slot：并发 release + 重新 acquire 后 slot 可能已被
+                // 新连接占据，误删会破坏新连接。
+                if (this.slots.get(workspace)?.client === client) {
+                    this.slots.delete(workspace);
+                    this.onConnectionLost?.(workspace);
+                }
+            },
+        };
+        client = new CodexAppServerClient(transport, hooks, this.requestTimeoutMs);
+        await client.connect();
+        return client;
+    }
+    clearIdleTimer(slot) {
+        if (slot.idleTimer !== null) {
+            clearTimeout(slot.idleTimer);
+            slot.idleTimer = null;
+        }
+    }
+    async disposeSlot(workspace) {
+        const slot = this.slots.get(workspace);
+        if (!slot)
+            return;
+        this.slots.delete(workspace);
+        this.clearIdleTimer(slot);
+        if (slot.client) {
+            try {
+                await slot.client.dispose();
+            }
+            catch (err) {
+                getLogger().warn(`[codex-connection-manager] dispose error workspace=${workspace}: ${err}`);
+            }
+        }
+    }
+}
+//# sourceMappingURL=connection-manager.js.map