@bastani/atomic 0.9.9 → 0.9.10-alpha.1

package/dist/modes/rpc/rpc-client.js

@@ -1,25 +1,75 @@
+import { BoundedWriter } from "./bounded-writer.js";
+import { attachJsonlLineReader, serializeJsonLine } from "./jsonl.js";
+import { InteractiveEngineMonitor } from "../interactive-engine/engine-monitor.js";
+import { INTERACTIVE_ENGINE_MAX_FRAME_BYTES, serializeInteractiveEngineFrame } from "../interactive-engine/protocol.js";
+import { sleep } from "../../utils/sleep.js";
+import { createInteractiveJsonlOptions, spawnRpcClientProcess, terminateRpcClientProcess } from "./rpc-client-process.js";
+import { RpcClientApi } from "./rpc-client-api.js";
+import { RpcEventBuffer } from "./rpc-event-buffer.js";
+import { collectRpcEvents, waitForRpcIdle } from "./rpc-client-waits.js";
+function restartArgs(args, sessionFile) {
+    const result = [];
+    for (let index = 0; index < (args?.length ?? 0); index += 1) {
+        const value = args[index];
+        if (value === "--no-session")
+            continue;
+        if (value === "--session") {
+            index += 1;
+            continue;
+        }
+        result.push(value);
+    }
+    result.push(sessionFile ? "--session" : "--no-session");
+    if (sessionFile)
+        result.push(sessionFile);
+    return result;
+}
 /**
- * RPC Client for programmatic access to the coding agent.
+ * Commands whose response is legitimately gated on human/agent interaction or a
+ * turn boundary and therefore must not be subject to the generic request
+ * timeout: interactive prompts and custom-UI pickers (routed through `prompt`),
+ * queued turn-boundary sends (`steer`/`follow_up`), long-running shell and
+ * compaction work, and session-tree navigation/mutation that can open pickers.
  *
- * Spawns the agent in RPC mode and provides a typed API for all operations.
+ * Failure detection is unaffected: engine exit, transport violations, aborts,
+ * generation replacement, and explicit stop all reject pending requests via
+ * rejectPendingRequests/failTransport independently of any timer.
  */
-import { spawn } from "node:child_process";
-import { attachJsonlLineReader, serializeJsonLine } from "./jsonl.js";
-// ============================================================================
-// RPC Client
-// ============================================================================
-export class RpcClient {
+const LONG_LIVED_COMMANDS = new Set([
+    "prompt",
+    "steer",
+    "follow_up",
+    "bash",
+    "user_bash",
+    "compact",
+    "fork",
+    "clone",
+    "switch_session",
+    "new_session",
+    "import_session",
+    "navigate_tree",
+    "invoke_shortcut",
+]);
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+export class RpcClient extends RpcClientApi {
     constructor(options = {}) {
+        super();
         this.process = null;
         this.stopReadingStdout = null;
         this.eventListeners = [];
+        this.extensionUIListeners = [];
+        this.pendingExtensionUIRequests = [];
+        this.engineMessageListeners = [];
+        this.pendingEngineMessages = [];
+        this.pendingEngineMessageBytes = 0;
         this.pendingRequests = new Map();
         this.requestId = 0;
         this.stderr = "";
         this.exitError = null;
+        this.generation = 0;
+        this.activeActivityIds = new Set();
         this.options = options;
     }
-    /** Start the RPC agent process. */
     async start() {
         if (this.process) {
             throw new Error("Client already started");
@@ -38,61 +88,105 @@ export class RpcClient {
         if (this.options.args) {
             args.push(...this.options.args);
         }
+        const generation = ++this.generation;
         this.exitError = null;
-        const childProcess = spawn("node", [cliPath, ...args], {
+        this.stderr = "";
+        this.activeActivityIds.clear();
+        this.enginePid = undefined;
+        this.engineMonitor = this.options.interactiveEngine
+            ? new InteractiveEngineMonitor(this.options.interactiveEngine.onDiagnostic, (message) => this.observeInteractiveEngineMessage(message))
+            : undefined;
+        this.eventBuffer = this.engineMonitor ? new RpcEventBuffer((event) => this.emitEvent(event)) : undefined;
+        const childProcess = spawnRpcClientProcess({
+            cliPath,
+            cliArgs: args,
             cwd: this.options.cwd,
-            env: { ...process.env, ...this.options.env },
-            stdio: ["pipe", "pipe", "pipe"],
+            env: this.options.env,
+            runtimeExecutable: this.options.runtimeExecutable,
+            runtimeArgs: this.options.runtimeArgs,
+            interactiveEngine: this.engineMonitor !== undefined,
         });
         this.process = childProcess;
+        this.stdinWriter = new BoundedWriter(childProcess.stdin, {
+            maxFrameBytes: INTERACTIVE_ENGINE_MAX_FRAME_BYTES,
+            maxQueuedBytes: 2 * INTERACTIVE_ENGINE_MAX_FRAME_BYTES,
+        });
         childProcess.once("exit", (code, signal) => {
+            if (generation !== this.generation)
+                return;
             const error = this.createProcessExitError(code, signal);
             this.exitError = error;
+            this.stdinWriter?.close(error);
+            this.engineMonitor?.fail(error);
+            this.activeActivityIds.clear();
+            this.options.interactiveEngine?.onActivityChange?.(false);
             this.rejectPendingRequests(error);
         });
         childProcess.once("error", (error) => {
+            if (generation !== this.generation)
+                return;
             this.exitError = error;
+            this.stdinWriter?.close(error);
+            this.engineMonitor?.fail(error);
             this.rejectPendingRequests(error);
         });
         childProcess.stdin?.on("error", (error) => {
+            if (generation !== this.generation)
+                return;
             this.exitError = error;
+            this.stdinWriter?.close(error);
+            this.engineMonitor?.fail(error);
             this.rejectPendingRequests(error);
         });
-        // Collect stderr for debugging
         childProcess.stderr?.on("data", (data) => {
-            this.stderr += data.toString();
+            if (generation !== this.generation)
+                return;
+            const next = this.stderr + data.toString();
+            this.stderr = Buffer.byteLength(next, "utf8") <= 256 * 1024
+                ? next
+                : `${Buffer.from(next).subarray(-256 * 1024).toString("utf8")}\n[stderr truncated]`;
             process.stderr.write(data);
         });
-        // Set up strict JSONL reader for stdout.
+        const readerOptions = createInteractiveJsonlOptions(this.engineMonitor !== undefined, this.options.interactiveEngine?.onDiagnostic);
         this.stopReadingStdout = attachJsonlLineReader(childProcess.stdout, (line) => {
-            this.handleLine(line);
+            if (generation === this.generation)
+                this.handleLine(line);
+        }, {
+            ...readerOptions,
+            onOversizedLine: () => {
+                readerOptions.onOversizedLine?.();
+                if (generation === this.generation)
+                    this.failTransport(new Error("Interactive engine emitted an oversized RPC frame"));
+            },
         });
-        // Wait a moment for process to initialize
-        await new Promise((resolve) => setTimeout(resolve, 100));
-        if (this.process.exitCode !== null) {
-            throw new Error(`Agent process exited immediately with code ${this.process.exitCode}. Stderr: ${this.stderr}`);
+        if (this.engineMonitor)
+            await this.engineMonitor.waitUntilReady();
+        else
+            await sleep(100);
+        if (generation !== this.generation || this.process?.exitCode !== null) {
+            throw new Error(`Agent process exited immediately. Stderr: ${this.stderr}`);
         }
     }
-    /** Stop the RPC agent process. */
     async stop() {
-        if (!this.process)
+        const child = this.process;
+        if (!child)
             return;
+        this.invalidateEngineShortcuts();
+        const terminateTree = this.engineMonitor !== undefined;
         this.stopReadingStdout?.();
+        this.engineMonitor?.stop();
+        this.stdinWriter?.close(new Error("Agent process stopped"));
+        this.engineMonitor = undefined;
         this.stopReadingStdout = null;
-        this.process.kill("SIGTERM");
-        // Wait for process to exit
-        await new Promise((resolve) => {
-            const timeout = setTimeout(() => {
-                this.process?.kill("SIGKILL");
-                resolve();
-            }, 1000);
-            this.process?.on("exit", () => {
-                clearTimeout(timeout);
-                resolve();
-            });
-        });
+        this.stdinWriter = undefined;
         this.process = null;
-        this.pendingRequests.clear();
+        this.generation += 1;
+        await terminateRpcClientProcess(child, terminateTree);
+        this.rejectPendingRequests(new Error("Agent process stopped"));
+        this.eventBuffer?.dispose();
+        this.eventBuffer = undefined;
+        this.activeActivityIds.clear();
+        this.options.interactiveEngine?.onActivityChange?.(false);
     }
     /** Subscribe to agent events. */
     onEvent(listener) {
@@ -104,193 +198,75 @@ export class RpcClient {
             }
         };
     }
-    /** Get collected stderr output (useful for debugging). */
-    getStderr() {
-        return this.stderr;
-    }
-    // =========================================================================
-    // Command Methods
-    // =========================================================================
-    /**
-     * Send a prompt to the agent.
-     * Returns immediately after sending; use onEvent() to receive streaming events.
-     * Use waitForIdle() to wait for completion.
-     */
-    async prompt(message, images) {
-        await this.send({ type: "prompt", message, images });
-    }
-    /** Queue a steering message to interrupt the agent mid-run. */
-    async steer(message, images) {
-        await this.send({ type: "steer", message, images });
-    }
-    /** Queue a follow-up message to be processed after the agent finishes. */
-    async followUp(message, images) {
-        await this.send({ type: "follow_up", message, images });
-    }
-    /** Abort current operation. */
-    async abort() {
-        await this.send({ type: "abort" });
-    }
-    /**
-     * Start a new session, optionally with parent tracking.
-     * @param parentSession - Optional parent session path for lineage tracking
-     * @returns Object with `cancelled: true` if an extension cancelled the new session
-     */
-    async newSession(parentSession) {
-        const response = await this.send({ type: "new_session", parentSession });
-        return this.getData(response);
-    }
-    /** Get current session state. */
-    async getState() {
-        const response = await this.send({ type: "get_state" });
-        return this.getData(response);
-    }
-    /** Set model by provider and ID. */
-    async setModel(provider, modelId) {
-        const response = await this.send({ type: "set_model", provider, modelId });
-        return this.getData(response);
-    }
-    /** Cycle to next model. */
-    async cycleModel() {
-        const response = await this.send({ type: "cycle_model" });
-        return this.getData(response);
-    }
-    /** Get list of available models. */
-    async getAvailableModels() {
-        const response = await this.send({ type: "get_available_models" });
-        return this.getData(response).models;
-    }
-    /** Set thinking level. */
-    async setThinkingLevel(level) {
-        await this.send({ type: "set_thinking_level", level });
-    }
-    /** Cycle thinking level. */
-    async cycleThinkingLevel() {
-        const response = await this.send({ type: "cycle_thinking_level" });
-        return this.getData(response);
-    }
-    /**
-     * Set the active context-window token budget for the current model.
-     * This is a runtime selection and does not persist context-window defaults.
-     */
-    async setContextWindow(contextWindow) {
-        const response = await this.send({ type: "set_context_window", contextWindow });
-        this.assertSuccess(response);
-    }
-    /** Get selectable context-window token budgets for the current model. */
-    async getAvailableContextWindows() {
-        const response = await this.send({ type: "get_available_context_windows" });
-        return this.getData(response);
-    }
-    /** Set steering mode. */
-    async setSteeringMode(mode) {
-        await this.send({ type: "set_steering_mode", mode });
-    }
-    /** Set follow-up mode. */
-    async setFollowUpMode(mode) {
-        await this.send({ type: "set_follow_up_mode", mode });
-    }
-    /** Compact session context with verbatim line-range compaction. */
-    async compact() {
-        const response = await this.send({ type: "compact" });
-        return this.getData(response);
-    }
-    async setAutoCompaction(enabled) {
-        await this.send({ type: "set_auto_compaction", enabled });
-    }
-    async setAutoRetry(enabled) {
-        await this.send({ type: "set_auto_retry", enabled });
-    }
-    async abortRetry() {
-        await this.send({ type: "abort_retry" });
-    }
-    async bash(command) {
-        const response = await this.send({ type: "bash", command });
-        return this.getData(response);
-    }
-    async abortBash() {
-        await this.send({ type: "abort_bash" });
-    }
-    async getSessionStats() {
-        const response = await this.send({ type: "get_session_stats" });
-        return this.getData(response);
-    }
-    async exportHtml(outputPath) {
-        const response = await this.send({ type: "export_html", outputPath });
-        return this.getData(response);
-    }
-    async switchSession(sessionPath) {
-        const response = await this.send({ type: "switch_session", sessionPath });
-        return this.getData(response);
-    }
-    async fork(entryId) {
-        const response = await this.send({ type: "fork", entryId });
-        return this.getData(response);
-    }
-    async clone() {
-        const response = await this.send({ type: "clone" });
-        return this.getData(response);
+    onExtensionUIRequest(listener) {
+        this.extensionUIListeners.push(listener);
+        for (const request of this.pendingExtensionUIRequests.splice(0))
+            listener(request);
+        return () => {
+            const index = this.extensionUIListeners.indexOf(listener);
+            if (index !== -1)
+                this.extensionUIListeners.splice(index, 1);
+        };
     }
-    async getForkMessages() {
-        const response = await this.send({ type: "get_fork_messages" });
-        return this.getData(response).messages;
+    async respondExtensionUI(response) {
+        await this.requireWriter().write(serializeJsonLine(response));
     }
-    /** Session entries in append order, optionally only those after the `since` entry id. */
-    async getEntries(since) {
-        const response = await this.send({ type: "get_entries", since });
-        return this.getData(response);
+    onInteractiveEngineMessage(listener) {
+        this.engineMessageListeners.push(listener);
+        for (const message of this.pendingEngineMessages.splice(0))
+            listener(message);
+        this.pendingEngineMessageBytes = 0;
+        return () => {
+            const index = this.engineMessageListeners.indexOf(listener);
+            if (index !== -1)
+                this.engineMessageListeners.splice(index, 1);
+        };
     }
-    /** The session entry tree. */
-    async getTree() {
-        const response = await this.send({ type: "get_tree" });
-        return this.getData(response);
+    onInteractiveEngineKeybindingState(listener) {
+        const messageListener = (message) => {
+            if (message.type === "engine_keybindings_reloaded")
+                listener(message.state);
+        };
+        this.engineMessageListeners.push(messageListener);
+        if (this.latestEngineKeybindingState)
+            listener(this.latestEngineKeybindingState);
+        return () => {
+            const index = this.engineMessageListeners.indexOf(messageListener);
+            if (index !== -1)
+                this.engineMessageListeners.splice(index, 1);
+        };
     }
-    async getLastAssistantText() {
-        const response = await this.send({ type: "get_last_assistant_text" });
-        return this.getData(response).text;
+    sendInteractiveEngineCommand(command) {
+        const writer = this.stdinWriter;
+        if (!writer)
+            return;
+        const frame = serializeInteractiveEngineFrame(command);
+        if (command.type === "engine_custom_render" || command.type === "engine_tool_render" || command.type === "engine_message_render") {
+            writer.offerLatest(`render:${command.componentId}`, frame);
+            return;
+        }
+        this.bestEffort(writer.write(frame), `engine command ${command.type}`);
     }
-    async setSessionName(name) {
-        await this.send({ type: "set_session_name", name });
+    waitForInteractiveEngineBound() { return this.engineMonitor?.waitUntilBound() ?? Promise.resolve(); }
+    getEnginePid() { return this.enginePid; }
+    getGeneration() { return this.generation; }
+    async restart(sessionFile) {
+        await this.stop();
+        this.options = { ...this.options, args: restartArgs(this.options.args, sessionFile) };
+        await this.start();
+        await this.waitForInteractiveEngineBound();
     }
-    async getMessages() {
-        const response = await this.send({ type: "get_messages" });
-        return this.getData(response).messages;
+    async requestInternal(command) {
+        return this.data(await this.request(command));
     }
-    async getCommands() {
-        const response = await this.send({ type: "get_commands" });
-        return this.getData(response).commands;
+    getStderr() {
+        return this.stderr;
     }
     waitForIdle(timeout = 60000) {
-        return new Promise((resolve, reject) => {
-            const timer = setTimeout(() => {
-                unsubscribe();
-                reject(new Error(`Timeout waiting for agent to become idle. Stderr: ${this.stderr}`));
-            }, timeout);
-            const unsubscribe = this.onEvent((event) => {
-                if (event.type === "agent_end") {
-                    clearTimeout(timer);
-                    unsubscribe();
-                    resolve();
-                }
-            });
-        });
+        return waitForRpcIdle(this, timeout);
     }
     collectEvents(timeout = 60000) {
-        return new Promise((resolve, reject) => {
-            const events = [];
-            const timer = setTimeout(() => {
-                unsubscribe();
-                reject(new Error(`Timeout collecting events. Stderr: ${this.stderr}`));
-            }, timeout);
-            const unsubscribe = this.onEvent((event) => {
-                events.push(event);
-                if (event.type === "agent_end") {
-                    clearTimeout(timer);
-                    unsubscribe();
-                    resolve(events);
-                }
-            });
-        });
+        return collectRpcEvents(this, timeout);
     }
     async promptAndWait(message, images, timeout = 60000) {
         const eventsPromise = this.collectEvents(timeout);
@@ -298,80 +274,150 @@ export class RpcClient {
         return eventsPromise;
     }
     handleLine(line) {
+        if (this.engineMonitor?.handleLine(line))
+            return;
         try {
             const data = JSON.parse(line);
+            if (data.type === "extension_ui_request") {
+                const request = data;
+                if (this.extensionUIListeners.length === 0)
+                    this.pendingExtensionUIRequests.push(request);
+                for (const listener of this.extensionUIListeners)
+                    listener(request);
+                return;
+            }
             if (data.type === "response" && data.id && this.pendingRequests.has(data.id)) {
                 const pending = this.pendingRequests.get(data.id);
                 this.pendingRequests.delete(data.id);
                 pending.resolve(data);
                 return;
             }
-            for (const listener of this.eventListeners) {
-                listener(data);
-            }
+            const event = data;
+            if (this.eventBuffer)
+                this.eventBuffer.enqueue(event);
+            else
+                this.emitEvent(event);
         }
         catch {
+            if (this.engineMonitor)
+                this.failTransport(new Error("Interactive engine emitted malformed JSONL"));
         }
     }
+    emitEvent(event) {
+        for (const listener of this.eventListeners)
+            listener(event);
+    }
+    emitInteractiveEngineMessage(message) {
+        if (this.engineMessageListeners.length === 0 && message.type.startsWith("engine_custom_")) {
+            const bytes = Buffer.byteLength(JSON.stringify(message), "utf8");
+            while (this.pendingEngineMessages.length > 0 && this.pendingEngineMessageBytes + bytes > INTERACTIVE_ENGINE_MAX_FRAME_BYTES) {
+                const removed = this.pendingEngineMessages.shift();
+                this.pendingEngineMessageBytes -= Buffer.byteLength(JSON.stringify(removed), "utf8");
+            }
+            if (bytes <= INTERACTIVE_ENGINE_MAX_FRAME_BYTES) {
+                this.pendingEngineMessages.push(message);
+                this.pendingEngineMessageBytes += bytes;
+            }
+        }
+        for (const listener of this.engineMessageListeners)
+            listener(message);
+    }
     createProcessExitError(code, signal) {
         return new Error(`Agent process exited (code=${code} signal=${signal}). Stderr: ${this.stderr}`);
     }
+    invalidateEngineShortcuts() {
+        if (!this.latestEngineKeybindingState || this.latestEngineKeybindingState.shortcuts.length === 0)
+            return;
+        const state = { ...this.latestEngineKeybindingState, shortcuts: [] };
+        this.latestEngineKeybindingState = state;
+        this.emitInteractiveEngineMessage({ type: "engine_keybindings_reloaded", state });
+    }
+    observeInteractiveEngineMessage(message) {
+        if (message.type === "engine_ready")
+            this.enginePid = message.pid;
+        if (message.type === "engine_keybindings_reloaded")
+            this.latestEngineKeybindingState = message.state;
+        if (message.type === "engine_activity_started")
+            this.activeActivityIds.add(message.activity.id);
+        else if (message.type === "engine_activity_finished")
+            this.activeActivityIds.delete(message.activityId);
+        this.options.interactiveEngine?.onActivityChange?.(this.activeActivityIds.size > 0);
+        this.emitInteractiveEngineMessage(message);
+    }
     rejectPendingRequests(error) {
-        for (const { reject } of this.pendingRequests.values()) {
+        for (const { reject } of this.pendingRequests.values())
             reject(error);
-        }
         this.pendingRequests.clear();
     }
-    async send(command) {
+    failTransport(error) {
+        this.exitError = error;
+        this.stdinWriter?.close(error);
+        this.engineMonitor?.fail(error);
+        this.rejectPendingRequests(error);
+        this.options.interactiveEngine?.onDiagnostic({
+            activity: undefined, elapsedMs: 0, level: "unresponsive", message: error.message,
+        });
+    }
+    requireWriter() {
+        if (!this.stdinWriter)
+            throw new Error("Agent process stdin is not writable");
+        return this.stdinWriter;
+    }
+    bestEffort(operation, label) {
+        void operation.catch((error) => {
+            if (!this.process || this.exitError)
+                return;
+            this.options.interactiveEngine?.onDiagnostic({
+                activity: undefined, elapsedMs: 0, level: "unresponsive",
+                message: `Interactive engine ${label} failed: ${error.message}`,
+            });
+        });
+    }
+    async request(command) {
         const childProcess = this.process;
-        const stdin = childProcess?.stdin;
-        if (!childProcess || !stdin) {
+        if (!childProcess)
             throw new Error("Client not started");
-        }
-        if (this.exitError) {
+        if (this.exitError)
             throw this.exitError;
-        }
         if (childProcess.exitCode !== null) {
             const error = this.createProcessExitError(childProcess.exitCode, childProcess.signalCode);
             this.exitError = error;
             throw error;
         }
-        if (stdin.destroyed || !stdin.writable) {
-            throw new Error("Agent process stdin is not writable");
-        }
         const id = `req_${++this.requestId}`;
         const fullCommand = { ...command, id };
-        return new Promise((resolve, reject) => {
-            const timeout = setTimeout(() => {
-                this.pendingRequests.delete(id);
-                reject(new Error(`Timeout waiting for response to ${command.type}. Stderr: ${this.stderr}`));
-            }, 30000);
+        let timeout;
+        let rejectResponse;
+        const response = new Promise((resolve, reject) => {
+            rejectResponse = reject;
             this.pendingRequests.set(id, {
-                resolve: (response) => {
-                    clearTimeout(timeout);
-                    resolve(response);
-                },
-                reject: (error) => {
-                    clearTimeout(timeout);
-                    reject(error);
-                },
+                resolve: (value) => { if (timeout)
+                    clearTimeout(timeout); resolve(value); },
+                reject: (error) => { if (timeout)
+                    clearTimeout(timeout); reject(error); },
             });
-            try {
-                stdin.write(serializeJsonLine(fullCommand));
-            }
-            catch (error) {
-                this.pendingRequests.delete(id);
-                clearTimeout(timeout);
-                reject(error instanceof Error ? error : new Error(String(error)));
-            }
         });
+        try {
+            await this.requireWriter().write(serializeJsonLine(fullCommand));
+        }
+        catch (error) {
+            this.pendingRequests.delete(id);
+            rejectResponse(error instanceof Error ? error : new Error(String(error)));
+            return response;
+        }
+        if (this.pendingRequests.has(id) && !LONG_LIVED_COMMANDS.has(command.type)) {
+            timeout = setTimeout(() => {
+                this.pendingRequests.delete(id);
+                rejectResponse(new Error(`Timeout waiting for response to ${command.type}. Stderr: ${this.stderr}`));
+            }, this.options.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS);
+        }
+        return response;
     }
     assertSuccess(response) {
-        if (!response.success) {
+        if (!response.success)
             throw new Error(response.error);
-        }
     }
-    getData(response) {
+    data(response) {
         this.assertSuccess(response);
         const successResponse = response;
         return successResponse.data;