indusagi-coding-agent 0.1.59 → 0.1.60

package/dist/interfaces/service-api/rpc-client.js

@@ -1,1333 +0,0 @@
-/**
- * RPC CLIENT - TYPED INTERFACE FOR AGENT RPC PROTOCOL
- *
- * ============================================================================
- * OVERVIEW
- * ============================================================================
- *
- * This module provides a complete TypeScript/Node.js client for the coding
- * agent's RPC protocol. It:
- *
- * - Spawns the agent in RPC mode as a subprocess
- * - Handles JSON serialization/deserialization automatically
- * - Provides a fully-typed API matching rpc-types.ts
- * - Manages request/response correlation with unique IDs
- * - Supports event subscription for streaming responses
- * - Handles errors gracefully with type-safe responses
- *
- * ============================================================================
- * CLIENT LIFECYCLE
- * ============================================================================
- *
- * Creation:
- *   const client = new RpcClient({ cliPath: "dist/cli.js" });
- *
- * Startup:
- *   await client.start();
- *   // Spawns agent in RPC mode, waits for initialization
- *
- * Usage:
- *   const state = await client.getState();
- *   await client.prompt("Your prompt here");
- *   const events = await client.collectEvents();
- *
- * Shutdown:
- *   await client.stop();
- *   // Terminates agent process, cleans up resources
- *
- * ============================================================================
- * USAGE PATTERNS
- * ============================================================================
- *
- * PATTERN 1: Simple Command
- * ──────────────────────────────────────────────────────────────────────
- * // Execute a command and wait for response
- * const client = new RpcClient();
- * await client.start();
- * const state = await client.getState();
- * console.log(`Session ID: ${state.sessionId}`);
- * await client.stop();
- *
- * PATTERN 2: Prompt with Event Subscription
- * ──────────────────────────────────────────────────────────────────────
- * // Send prompt and listen for events
- * const client = new RpcClient();
- * await client.start();
- *
- * client.onEvent((event) => {
- *   if (event.type === "message" && event.role === "assistant") {
- *     console.log("Assistant:", event.content[0].text);
- *   }
- *   if (event.type === "tool_call") {
- *     console.log("Calling tool:", event.toolName);
- *   }
- * });
- *
- * await client.prompt("What files are in /tmp?");
- * await client.waitForIdle();
- * await client.stop();
- *
- * PATTERN 3: Prompt and Collect All Events
- * ──────────────────────────────────────────────────────────────────────
- * // Send prompt and get all events in one call
- * const client = new RpcClient();
- * await client.start();
- *
- * const events = await client.promptAndWait("Explain the code", undefined, 30000);
- * events.forEach((event) => {
- *   console.log(`Event: ${event.type}`);
- * });
- *
- * await client.stop();
- *
- * PATTERN 4: Model Switching
- * ──────────────────────────────────────────────────────────────────────
- * // Get available models and switch
- * const client = new RpcClient({ provider: "anthropic" });
- * await client.start();
- *
- * const models = await client.getAvailableModels();
- * console.log(`Available models: ${models.length}`);
- *
- * if (models.length > 0) {
- *   await client.setModel(models[0].provider, models[0].id);
- *   const state = await client.getState();
- *   console.log(`Switched to: ${state.model?.id}`);
- * }
- *
- * await client.stop();
- *
- * PATTERN 5: Sequential Prompts
- * ──────────────────────────────────────────────────────────────────────
- * // Send multiple prompts sequentially
- * const client = new RpcClient();
- * await client.start();
- *
- * const prompts = ["First question", "Follow-up", "Another question"];
- * for (const prompt of prompts) {
- *   const events = await client.promptAndWait(prompt);
- *   const lastMsg = events
- *     .filter(e => e.type === "message" && e.role === "assistant")
- *     .pop();
- *   console.log("Response:", lastMsg?.content[0]?.text);
- * }
- *
- * await client.stop();
- *
- * PATTERN 6: Error Handling
- * ──────────────────────────────────────────────────────────────────────
- * // Gracefully handle errors
- * const client = new RpcClient();
- * try {
- *   await client.start();
- *   await client.setModel("anthropic", "nonexistent-model");
- * } catch (error) {
- *   console.error(`Client error: ${error.message}`);
- *   // Error includes stderr output for debugging
- * } finally {
- *   await client.stop();
- * }
- *
- * PATTERN 7: Timeout Handling
- * ──────────────────────────────────────────────────────────────────────
- * // Prompt with custom timeout
- * const client = new RpcClient();
- * await client.start();
- * try {
- *   const events = await client.promptAndWait(
- *     "Long-running operation",
- *     undefined,
- *     120000  // 2 minute timeout
- *   );
- * } catch (error) {
- *   console.error("Timeout or error:", error.message);
- * }
- * await client.stop();
- *
- * PATTERN 8: Export and Save Session
- * ──────────────────────────────────────────────────────────────────────
- * // Export session to HTML
- * const client = new RpcClient();
- * await client.start();
- * await client.prompt("Test prompt");
- * await client.waitForIdle();
- * const result = await client.exportHtml("/tmp/session.html");
- * console.log(`Exported to: ${result.path}`);
- * await client.stop();
- *
- * ============================================================================
- * CONFIGURATION OPTIONS (RpcClientOptions)
- * ============================================================================
- *
- * interface RpcClientOptions {
- *   // Path to CLI entry point
- *   // Default: searches for "dist/cli.js"
- *   // Can be absolute or relative path
- *   cliPath?: string;
- *
- *   // Working directory for agent process
- *   // Default: current working directory
- *   // Used for relative path resolution in agent
- *   cwd?: string;
- *
- *   // Environment variables for agent process
- *   // Merged with process.env
- *   // Can override API keys, model settings, etc.
- *   env?: Record<string, string>;
- *
- *   // Provider to use
- *   // Options: "anthropic", "openai", "google", etc.
- *   // Passed to agent via CLI arguments
- *   provider?: string;
- *
- *   // Model ID to use initially
- *   // Provider-specific format
- *   // Passed to agent via CLI arguments
- *   model?: string;
- *
- *   // Additional CLI arguments
- *   // Passed to agent process as-is
- *   // Example: ["--session", "abc123"]
- *   args?: string[];
- * }
- *
- * Usage:
- *   const client = new RpcClient({
- *     cliPath: "/opt/agent/dist/cli.js",
- *     cwd: "/home/user/project",
- *     env: { ANTHROPIC_API_KEY: "sk-..." },
- *     provider: "anthropic",
- *     model: "claude-3-5-sonnet",
- *     args: ["--thinking", "max"]
- *   });
- *
- * ============================================================================
- * EVENT SUBSCRIPTION
- * ============================================================================
- *
- * Subscribe to all agent events:
- *   const unsubscribe = client.onEvent((event) => {
- *     console.log("Event:", event.type);
- *   });
- *   // Later, to unsubscribe:
- *   unsubscribe();
- *
- * Event Types:
- *   - agent_start: Agent began processing
- *   - message: User or assistant message
- *   - tool_call: Agent called a tool
- *   - tool_output: Tool returned output
- *   - tool_error: Tool failed
- *   - agent_end: Agent finished processing
- *   - compaction_start: Context compaction began
- *   - compaction_complete: Context compaction finished
- *   - extension_ui_request: Extension requesting user input
- *   - extension_error: Extension threw error
- *   - hook_error: Hook threw error
- *
- * Filtering Events:
- *   client.onEvent((event) => {
- *     if (event.type === "message" && event.role === "assistant") {
- *       // Handle assistant message
- *     }
- *     if (event.type === "tool_call") {
- *       // Handle tool execution
- *     }
- *   });
- *
- * ============================================================================
- * HELPER METHODS
- * ============================================================================
- *
- * waitForIdle(timeout?: number): Promise<void>
- *   Wait for agent to finish processing.
- *   Resolves when agent_end event received.
- *   Timeout default: 60 seconds
- *   Throws: Error if timeout exceeded
- *   Use Case: Waiting for prompt completion
- *
- * collectEvents(timeout?: number): Promise<AgentEvent[]>
- *   Collect all events until agent becomes idle.
- *   Returns: Array of events in order
- *   Timeout default: 60 seconds
- *   Throws: Error if timeout exceeded
- *   Use Case: Getting full event history of prompt
- *
- * promptAndWait(message, images?, timeout?): Promise<AgentEvent[]>
- *   Send prompt and wait for completion in one call.
- *   Returns: All events from that prompt
- *   Equivalent to:
- *     const eventsPromise = client.collectEvents(timeout);
- *     await client.prompt(message, images);
- *     return eventsPromise;
- *   Use Case: Simple prompt-response pattern
- *
- * getStderr(): string
- *   Get collected stderr output from agent process.
- *   Useful for debugging client startup failures.
- *   Example:
- *     try { await client.start(); }
- *     catch (e) { console.log(client.getStderr()); }
- *
- * ============================================================================
- * ERROR HANDLING
- * ============================================================================
- *
- * Command Errors:
- *   // RPC commands that fail throw with error.message
- *   try {
- *     await client.setModel("anthropic", "nonexistent");
- *   } catch (error) {
- *     console.error(error.message); // "Model not found: anthropic/nonexistent"
- *   }
- *
- * Startup Errors:
- *   // Process failures throw error with stderr
- *   try {
- *     await client.start();
- *   } catch (error) {
- *     console.error(error.message); // Includes stderr output
- *     console.error(client.getStderr()); // Additional debugging
- *   }
- *
- * Timeout Errors:
- *   // Operations that exceed timeout throw error
- *   try {
- *     await client.waitForIdle(5000);
- *   } catch (error) {
- *     console.error(error.message); // "Timeout waiting for agent to become idle"
- *   }
- *
- * Graceful Degradation:
- *   // Always try to stop client even if errors occur
- *   const client = new RpcClient();
- *   try {
- *     await client.start();
- *     // ... use client ...
- *   } finally {
- *     await client.stop(); // Safe even if not started
- *   }
- *
- * ============================================================================
- * INTERNAL IMPLEMENTATION DETAILS
- * ============================================================================
- *
- * Spawn Configuration:
- *   - Spawns "node" with CLI path and --mode rpc
- *   - stdio: ["pipe", "pipe", "pipe"] (captures all streams)
- *   - Inherits environment variables with custom merges
- *   - Works directory: configurable via options.cwd
- *
- * Communication Protocol:
- *   - Sends commands as JSON lines on stdin
- *   - Reads responses and events as JSON lines on stdout
- *   - Errors/diagnostics on stderr (collected)
- *   - readline interface handles line buffering
- *
- * Request Correlation:
- *   - Each command gets unique ID: "req_" + incrementing number
- *   - Responses matched to commands by ID
- *   - Pending requests stored in Map<id, {resolve, reject}>
- *   - 30-second timeout per command by default
- *
- * Event Routing:
- *   - Non-response messages routed to event listeners
- *   - Listeners called synchronously when event arrives
- *   - Multiple listeners supported
- *   - All events delivered even if listener throws
- *
- * Subprocess Cleanup:
- *   - Graceful: kill("SIGTERM") with 1-second wait
- *   - Force: kill("SIGKILL") if SIGTERM fails
- *   - Exit event waits for process cleanup
- *   - Pending requests rejected on force kill
- *
- * ============================================================================
- * BASED ON RPCLIENT IMPLEMENTATION
- * ============================================================================
- *
- * This client provides a complete, type-safe TypeScript interface to the
- * agent's RPC protocol. It handles all JSON marshaling, process management,
- * and error handling transparently.
- *
- * Use this in Node.js applications, tools, or servers that need programmatic
- * access to the agent's capabilities.
- */
-import { spawn } from "node:child_process";
-import * as readline from "node:readline";
-import { isRpcResponse } from "./rpc-types.js";
-// ============================================================================
-// RPC Client
-// ============================================================================
-/**
- * RPC Client for programmatic access to the coding agent.
- *
- * Manages the agent subprocess, handles JSON-RPC protocol communication,
- * correlates requests/responses, and provides a fully-typed API.
- *
- * ============================================================================
- * LIFECYCLE
- * ============================================================================
- *
- * 1. Constructor: Create client with optional configuration
- *    const client = new RpcClient({ cliPath: "dist/cli.js" });
- *
- * 2. start(): Spawn agent process, wait for initialization
- *    await client.start(); // Agent ready to accept commands
- *
- * 3. Use: Send commands, subscribe to events
- *    await client.prompt("Your prompt");
- *    client.onEvent(handler);
- *
- * 4. stop(): Gracefully terminate subprocess
- *    await client.stop(); // Clean shutdown
- *
- * ============================================================================
- * STATE MACHINE
- * ============================================================================
- *
- * [NOT_STARTED]
- *   ↓ constructor()
- * [STOPPED]
- *   ↓ start()
- * [RUNNING] ← Can send commands, subscribe to events
- *   ↓ stop()
- * [STOPPED]
- *   ↓ (error during start)
- * [FAILED]
- *
- * ============================================================================
- * PROPERTY DESCRIPTIONS
- * ============================================================================
- *
- * process: ChildProcess | null
- *   The spawned agent subprocess.
- *   Non-null while running, null before start() or after stop().
- *   Access via process.stdin for writing commands.
- *   Access via process.stdout for reading responses/events.
- *
- * rl: readline.Interface | null
- *   Line reader for parsing JSON lines from agent stdout.
- *   Non-null while running.
- *   Used internally for line buffering and JSON parsing.
- *
- * eventListeners: RpcEventListener[]
- *   Array of callback functions subscribed to events.
- *   Added via onEvent(), removed via returned unsubscribe function.
- *   Called synchronously as events arrive.
- *   Can be modified during event handling.
- *
- * pendingRequests: Map<id, {resolve, reject}>
- *   Maps request ID → response handler.
- *   Used to correlate responses to commands.
- *   Entries added when command sent, removed when response received.
- *   30-second timeout per request.
- *
- * requestId: number
- *   Counter for generating unique request IDs.
- *   Incremented for each command sent.
- *   Format: "req_" + requestId
- *
- * stderr: string
- *   Accumulated stderr output from agent process.
- *   Appended as data received from process.stderr.
- *   Used for debugging client startup failures.
- *   Accessible via getStderr() method.
- *
- * options: RpcClientOptions
- *   Configuration passed to constructor.
- *   Used during start() to configure subprocess.
- *   Immutable after construction.
- *
- * ============================================================================
- */
-export class RpcClient {
-    /**
-     * Create a new RPC client.
-     *
-     * @param options - Configuration for the agent subprocess
-     *
-     * Configuration Options:
-     *   cliPath: Path to agent CLI entry point (default: "dist/cli.js")
-     *   cwd: Working directory for subprocess
-     *   env: Additional environment variables
-     *   provider: Model provider to use initially
-     *   model: Model ID to use initially
-     *   args: Additional CLI arguments
-     *
-     * Example:
-     *   const client = new RpcClient({
-     *     cliPath: "/opt/agent/cli.js",
-     *     env: { ANTHROPIC_API_KEY: "sk-..." },
-     *     provider: "anthropic",
-     *     model: "claude-3-5-sonnet"
-     *   });
-     */
-    constructor(options = {}) {
-        this.options = options;
-        this.process = null;
-        this.rl = null;
-        this.eventListeners = [];
-        this.pendingRequests = new Map();
-        this.requestId = 0;
-        this.stderr = "";
-    }
-    buildCliInvocation() {
-        const cliPath = this.options.cliPath ?? "dist/cli.js";
-        const args = ["--mode", "rpc"];
-        if (this.options.provider) {
-            args.push("--provider", this.options.provider);
-        }
-        if (this.options.model) {
-            args.push("--model", this.options.model);
-        }
-        if (this.options.args) {
-            args.push(...this.options.args);
-        }
-        return { cliPath, args };
-    }
-    attachProcessStreams() {
-        this.process?.stderr?.on("data", (data) => {
-            this.stderr += data.toString();
-        });
-        if (!this.process?.stdout) {
-            return;
-        }
-        this.rl = readline.createInterface({
-            input: this.process.stdout,
-            terminal: false,
-        });
-        this.rl.on("line", (line) => {
-            this.handleLine(line);
-        });
-    }
-    async waitForStartup() {
-        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}`);
-        }
-    }
-    async terminateProcess() {
-        if (!this.process) {
-            return;
-        }
-        this.rl?.close();
-        this.process.kill("SIGTERM");
-        await new Promise((resolve) => {
-            const timeout = setTimeout(() => {
-                this.process?.kill("SIGKILL");
-                resolve();
-            }, 1000);
-            this.process?.on("exit", () => {
-                clearTimeout(timeout);
-                resolve();
-            });
-        });
-        this.process = null;
-        this.rl = null;
-        this.pendingRequests.clear();
-    }
-    resolvePendingResponse(response) {
-        if (!response.id) {
-            return false;
-        }
-        const pending = this.pendingRequests.get(response.id);
-        if (!pending) {
-            return false;
-        }
-        this.pendingRequests.delete(response.id);
-        pending.resolve(response);
-        return true;
-    }
-    emitIncomingEvent(event) {
-        for (const listener of this.eventListeners) {
-            listener(event);
-        }
-    }
-    createCommandEnvelope(command) {
-        const id = `req_${++this.requestId}`;
-        return {
-            id,
-            payload: { ...command, id },
-        };
-    }
-    /**
-     * Start the RPC agent process.
-     *
-     * Spawns the agent subprocess in RPC mode and waits for initialization.
-     * Must be called before sending commands.
-     *
-     * Process Configuration:
-     *   - Command: node [cliPath] --mode rpc [additional args]
-     *   - Stdin: Piped (for sending commands)
-     *   - Stdout: Piped (for receiving responses/events)
-     *   - Stderr: Piped (for error collection)
-     *   - CWD: options.cwd or current working directory
-     *   - Env: process.env merged with options.env
-     *
-     * CLI Arguments:
-     *   --mode rpc (always included)
-     *   --provider [provider] (if options.provider set)
-     *   --model [model] (if options.model set)
-     *   [additional args] (from options.args)
-     *
-     * Initialization Steps:
-     *   1. Spawn subprocess with configuration
-     *   2. Set up stderr collection for debugging
-     *   3. Create readline interface on stdout
-     *   4. Wait 100ms for process initialization
-     *   5. Check if process exited early (error condition)
-     *   6. Set up event/response line handler
-     *   7. Resolve promise when ready
-     *
-     * Errors:
-     *   - Already started: "Client already started"
-     *   - Process exited immediately: "Agent process exited immediately..."
-     *     (Includes stderr output for debugging)
-     *
-     * Examples:
-     *   const client = new RpcClient();
-     *   try {
-     *     await client.start();
-     *     console.log("Agent started");
-     *   } catch (error) {
-     *     console.error("Failed to start:", error.message);
-     *     console.error("Stderr:", client.getStderr());
-     *   }
-     *
-     * Success Criteria:
-     *   - Subprocess spawned successfully
-     *   - Subprocess not exited (exitCode is null)
-     *   - Readline interface created
-     *   - Ready to send commands
-     *
-     * @throws Error if process already started
-     * @throws Error if subprocess exited immediately
-     */
-    async start() {
-        if (this.process) {
-            throw new Error("Client already started");
-        }
-        const { cliPath, args } = this.buildCliInvocation();
-        this.process = spawn("node", [cliPath, ...args], {
-            cwd: this.options.cwd,
-            env: { ...process.env, ...this.options.env },
-            stdio: ["pipe", "pipe", "pipe"],
-        });
-        this.attachProcessStreams();
-        await this.waitForStartup();
-    }
-    /**
-     * Stop the RPC agent process.
-     *
-     * Gracefully terminates the agent subprocess and cleans up resources.
-     * Safe to call even if client is not started.
-     *
-     * Shutdown Sequence:
-     *   1. Check if process running (return early if not)
-     *   2. Close readline interface (stops listening)
-     *   3. Send SIGTERM signal (graceful shutdown)
-     *   4. Set up 1-second timeout
-     *   5. Wait for process exit event
-     *   6. If timeout: send SIGKILL signal (force kill)
-     *   7. Clear process and rl references
-     *   8. Clear pending requests map
-     *
-     * Process States:
-     *   - Running: SIGTERM → wait for graceful exit
-     *   - Stuck: SIGTERM timeout → SIGKILL (force kill)
-     *   - Already stopped: return immediately
-     *   - Already exited: clean up references
-     *
-     * Resource Cleanup:
-     *   - process: set to null
-     *   - rl: closed and set to null
-     *   - pendingRequests: cleared (all rejected)
-     *   - eventListeners: preserved (can be reused on next start)
-     *
-     * Examples:
-     *   // Basic shutdown
-     *   await client.stop();
-     *
-     *   // Always stop in finally block
-     *   try {
-     *     await client.start();
-     *     await client.prompt("prompt");
-     *   } finally {
-     *     await client.stop();
-     *   }
-     *
-     *   // Stop is safe to call multiple times
-     *   await client.stop();
-     *   await client.stop(); // No error
-     *
-     * Timeout Behavior:
-     *   - SIGTERM: 1 second grace period
-     *   - After timeout: SIGKILL sent
-     *   - Ensures process eventually terminates
-     *   - Prevents hanging indefinitely
-     *
-     * Note: Event listeners are NOT cleared, allowing reuse of client.
-     * Create new client instance if you want fresh state.
-     *
-     * @returns Promise that resolves when process stopped
-     */
-    async stop() {
-        await this.terminateProcess();
-    }
-    /**
-     * Subscribe to agent events.
-     *
-     * Registers a callback to be called for each agent event.
-     * Events are delivered asynchronously as they arrive from the agent.
-     *
-     * Event Types:
-     *   - agent_start: Agent began processing
-     *   - message: User or assistant message
-     *   - tool_call: Agent called a tool
-     *   - tool_output: Tool returned output/result
-     *   - tool_error: Tool failed
-     *   - agent_end: Agent finished processing
-     *   - compaction_start: Context compaction began
-     *   - compaction_complete: Context compaction finished
-     *   - extension_ui_request: Extension needs user input
-     *   - extension_error: Extension threw error
-     *   - hook_error: Hook threw error
-     *
-     * Callback Behavior:
-     *   - Called synchronously when event parsed
-     *   - Multiple listeners all called for same event
-     *   - Exceptions in callback are logged but don't affect others
-     *   - Can be registered/unregistered during event handling
-     *
-     * Unsubscription:
-     *   - Returns unsubscribe function
-     *   - Call returned function to remove listener
-     *   - Safe to call multiple times
-     *
-     * Examples:
-     *   // Subscribe to all events
-     *   const unsubscribe = client.onEvent((event) => {
-     *     console.log("Event:", event.type);
-     *   });
-     *
-     *   // Unsubscribe later
-     *   unsubscribe();
-     *
-     *   // Filter by event type
-     *   client.onEvent((event) => {
-     *     if (event.type === "message" && event.role === "assistant") {
-     *       console.log("Assistant:", event.content[0].text);
-     *     }
-     *   });
-     *
-     *   // Track tool calls
-     *   client.onEvent((event) => {
-     *     if (event.type === "tool_call") {
-     *       console.log(`Tool: ${event.toolName}`);
-     *       console.log(`Input:`, event.toolInput);
-     *     }
-     *   });
-     *
-     *   // Multiple subscribers
-     *   const unsub1 = client.onEvent(handler1);
-     *   const unsub2 = client.onEvent(handler2);
-     *   // Both called for each event
-     *   unsub1(); // Remove first listener
-     *   // Only handler2 called now
-     *
-     * @param listener - Callback function for events
-     * @returns Unsubscribe function to remove listener
-     */
-    onEvent(listener) {
-        this.eventListeners.push(listener);
-        return () => {
-            const index = this.eventListeners.indexOf(listener);
-            if (index !== -1) {
-                this.eventListeners.splice(index, 1);
-            }
-        };
-    }
-    /**
-     * Get collected stderr output from agent process.
-     *
-     * Returns all stderr output accumulated from the agent subprocess.
-     * Useful for debugging startup failures or agent errors.
-     *
-     * Accumulated Stderr:
-     *   - Collected from process startup
-     *   - Includes initialization errors
-     *   - Agent logs and warnings
-     *   - Extension errors
-     *   - Unhandled exceptions
-     *
-     * Use Cases:
-     *   - Debug start() failures
-     *   - Diagnose connection issues
-     *   - Investigate agent crashes
-     *   - Extension debugging
-     *
-     * Examples:
-     *   // Debug startup failure
-     *   try {
-     *     await client.start();
-     *   } catch (error) {
-     *     console.error("Error:", error.message);
-     *     console.error("Agent stderr:", client.getStderr());
-     *   }
-     *
-     *   // Check for warnings during operation
-     *   await client.start();
-     *   await client.prompt("test");
-     *   const stderr = client.getStderr();
-     *   if (stderr.includes("WARNING")) {
-     *     console.warn("Agent warnings detected:", stderr);
-     *   }
-     *
-     * Note:
-     *   - Does NOT include stdout (responses/events)
-     *   - Accumulated text (not cleared per call)
-     *   - Can grow large if agent produces lots of stderr
-     *   - Call before stop() to get latest output
-     *   - Empty string if no stderr produced
-     *
-     * @returns String containing all stderr output
-     */
-    getStderr() {
-        return this.stderr;
-    }
-    // =========================================================================
-    // Command Methods
-    // =========================================================================
-    /**
-     * Send a prompt to the agent.
-     *
-     * Sends a new prompt to the agent and returns immediately.
-     * Events are streamed asynchronously (use onEvent() to listen).
-     * Use waitForIdle() or promptAndWait() to wait for completion.
-     *
-     * Execution Model:
-     *   1. Command sent to agent
-     *   2. Response received immediately (success: true)
-     *   3. Agent starts processing asynchronously
-     *   4. Events streamed as they occur
-     *   5. agent_end event signals completion
-     *
-     * Parameters:
-     *   message (required): The prompt text
-     *     - Can contain instructions, questions, code
-     *     - No special formatting required
-     *     - Supports @ file inclusion (handled by agent)
-     *
-     *   images (optional): Array of image content
-     *     - Format: { mimeType: "image/png", data: "base64" }
-     *     - Supported: PNG, JPEG, GIF, WebP
-     *     - Attached to message and sent to model
-     *
-     * Return Value:
-     *   Resolves when command sent (not when processing complete).
-     *   To wait for completion, use:
-     *     await client.prompt(message);
-     *     await client.waitForIdle();
-     *   Or use promptAndWait() for both in one call.
-     *
-     * Event Sequence:
-     *   1. Response: { success: true }
-     *   2. agent_start event
-     *   3. message event (user message)
-     *   4. message event (assistant response)
-     *   5. Optional: tool_call, tool_output events
-     *   6. agent_end event
-     *
-     * Error Handling:
-     *   - Validation errors thrown immediately
-     *   - Invalid arguments throw Error
-     *   - Agent execution errors in events
-     *
-     * Examples:
-     *   // Simple prompt
-     *   await client.prompt("What is 2+2?");
-     *
-     *   // Prompt with images
-     *   await client.prompt("Describe this image", [
-     *     { mimeType: "image/png", data: "base64-data" }
-     *   ]);
-     *
-     *   // Fire and forget
-     *   client.prompt("Background task").catch(console.error);
-     *
-     *   // With event listener
-     *   client.onEvent((event) => {
-     *     if (event.type === "agent_end") {
-     *       console.log("Prompt completed");
-     *     }
-     *   });
-     *   await client.prompt("Your prompt");
-     *
-     *   // Wait for completion
-     *   const eventsPromise = client.collectEvents();
-     *   await client.prompt("Your prompt");
-     *   const events = await eventsPromise;
-     *
-     * @param message - The prompt text to send
-     * @param images - Optional images to attach
-     * @throws Error if client not started or invalid input
-     */
-    async prompt(message, images) {
-        await this.send({ type: "prompt", message, images });
-    }
-    /**
-     * Queue a steering message to interrupt the agent mid-run.
-     */
-    async steer(message) {
-        await this.send({ type: "steer", message });
-    }
-    /**
-     * Queue a follow-up message to be processed after the agent finishes.
-     */
-    async followUp(message) {
-        await this.send({ type: "follow_up", message });
-    }
-    /**
-     * 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 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.
-     */
-    async compact(customInstructions) {
-        const response = await this.send({ type: "compact", customInstructions });
-        return this.getData(response);
-    }
-    /**
-     * Set auto-compaction enabled/disabled.
-     */
-    async setAutoCompaction(enabled) {
-        await this.send({ type: "set_auto_compaction", enabled });
-    }
-    /**
-     * Set auto-retry enabled/disabled.
-     */
-    async setAutoRetry(enabled) {
-        await this.send({ type: "set_auto_retry", enabled });
-    }
-    /**
-     * Abort in-progress retry.
-     */
-    async abortRetry() {
-        await this.send({ type: "abort_retry" });
-    }
-    /**
-     * Execute a bash command.
-     */
-    async bash(command) {
-        const response = await this.send({ type: "bash", command });
-        return this.getData(response);
-    }
-    /**
-     * Abort running bash command.
-     */
-    async abortBash() {
-        await this.send({ type: "abort_bash" });
-    }
-    /**
-     * Get session statistics.
-     */
-    async getSessionStats() {
-        const response = await this.send({ type: "get_session_stats" });
-        return this.getData(response);
-    }
-    /**
-     * Export session to HTML.
-     */
-    async exportHtml(outputPath) {
-        const response = await this.send({ type: "export_html", outputPath });
-        return this.getData(response);
-    }
-    /**
-     * Switch to a different session file.
-     * @returns Object with `cancelled: true` if an extension cancelled the switch
-     */
-    async switchSession(sessionPath) {
-        const response = await this.send({ type: "switch_session", sessionPath });
-        return this.getData(response);
-    }
-    /**
-     * Fork from a specific message.
-     * @returns Object with `text` (the message text) and `cancelled` (if extension cancelled)
-     */
-    async fork(entryId) {
-        const response = await this.send({ type: "fork", entryId });
-        return this.getData(response);
-    }
-    /**
-     * Get messages available for forking.
-     */
-    async getForkMessages() {
-        const response = await this.send({ type: "get_fork_messages" });
-        return this.getData(response).messages;
-    }
-    /**
-     * Get text of last assistant message.
-     */
-    async getLastAssistantText() {
-        const response = await this.send({ type: "get_last_assistant_text" });
-        return this.getData(response).text;
-    }
-    /**
-     * Get all messages in the session.
-     */
-    async getMessages() {
-        const response = await this.send({ type: "get_messages" });
-        return this.getData(response).messages;
-    }
-    // =========================================================================
-    // Helpers
-    // =========================================================================
-    /**
-     * Wait for agent to become idle (no streaming).
-     *
-     * Blocks until the agent finishes processing.
-     * Resolves when agent_end event received.
-     * Useful for waiting after prompt() before sending next command.
-     *
-     * Behavior:
-     *   - Listens for agent_end event
-     *   - Resolves immediately if event already received
-     *   - Rejects if timeout exceeded
-     *   - Automatically unsubscribes when done
-     *
-     * Timeout:
-     *   - Default: 60,000 ms (60 seconds)
-     *   - Can be customized per call
-     *   - Thrown as Error if exceeded
-     *   - Error includes stderr for debugging
-     *
-     * Usage Pattern:
-     *   await client.prompt("Your prompt");
-     *   await client.waitForIdle();
-     *   // Agent processing complete
-     *   const state = await client.getState();
-     *
-     * With Timeout:
-     *   await client.waitForIdle(120000); // 2 minutes
-     *   // For long-running operations
-     *
-     * Error Handling:
-     *   try {
-     *     await client.waitForIdle(5000);
-     *   } catch (error) {
-     *     console.error("Timeout:", error.message);
-     *   }
-     *
-     * Notes:
-     *   - Does not return any data
-     *   - Use collectEvents() to get event list
-     *   - Use onEvent() if you need individual events
-     *   - Safe to call multiple times concurrently
-     *
-     * @param timeout - Timeout in milliseconds (default: 60000)
-     * @returns Promise that resolves when agent_end event received
-     * @throws Error if timeout exceeded or client not started
-     */
-    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();
-                }
-            });
-        });
-    }
-    /**
-     * Collect all events until agent becomes idle.
-     *
-     * Listens for all events and collects them into an array.
-     * Resolves when agent_end event received.
-     * Returns complete event history for analysis/debugging.
-     *
-     * Behavior:
-     *   - Creates new listener for this collection only
-     *   - Accumulates all events in order
-     *   - Unsubscribes when agent_end received
-     *   - Other listeners still receive events
-     *
-     * Return Value:
-     *   Array of AgentEvent in chronological order:
-     *     1. agent_start
-     *     2. message (user)
-     *     3. message (assistant) or tool events
-     *     4. agent_end
-     *
-     * Timeout:
-     *   - Default: 60,000 ms (60 seconds)
-     *   - Customizable per call
-     *   - Error includes stderr for debugging
-     *
-     * Usage Pattern:
-     *   const eventsPromise = client.collectEvents();
-     *   await client.prompt("Your prompt");
-     *   const events = await eventsPromise;
-     *   events.forEach(e => console.log(e.type));
-     *
-     * Analysis Examples:
-     *   // Count tool calls
-     *   const toolCalls = events.filter(e => e.type === "tool_call").length;
-     *
-     *   // Get assistant messages
-     *   const responses = events
-     *     .filter(e => e.type === "message" && e.role === "assistant")
-     *     .map(e => e.content[0]?.text);
-     *
-     *   // Find errors
-     *   const errors = events.filter(e => e.type === "tool_error");
-     *
-     *   // Get compaction info
-     *   const compactions = events.filter(e =>
-     *     e.type === "compaction_start" || e.type === "compaction_complete"
-     *   );
-     *
-     * Multiple Collection:
-     *   // Safe to call multiple times
-     *   const events1 = await client.collectEvents();
-     *   const events2 = await client.collectEvents();
-     *   // Each gets complete event sequence
-     *
-     * Performance:
-     *   - Array allocation: O(n) where n = event count
-     *   - Each event appended: O(1)
-     *   - Full history available immediately after completion
-     *
-     * @param timeout - Timeout in milliseconds (default: 60000)
-     * @returns Promise resolving to array of all events
-     * @throws Error if timeout exceeded or client not started
-     */
-    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);
-                }
-            });
-        });
-    }
-    /**
-     * Send prompt and wait for completion in a single call.
-     *
-     * Convenience method combining prompt() + collectEvents().
-     * Sends prompt and returns all events from that execution.
-     * Cleaner than managing event collection separately.
-     *
-     * Behavior:
-     *   1. Start collecting events
-     *   2. Send prompt to agent
-     *   3. Wait for completion (agent_end event)
-     *   4. Return all collected events
-     *
-     * Equivalent To:
-     *   const eventsPromise = client.collectEvents(timeout);
-     *   await client.prompt(message, images);
-     *   return eventsPromise;
-     *
-     * Parameters:
-     *   message (required): Prompt text
-     *   images (optional): Array of image content
-     *   timeout (optional): Timeout in milliseconds (default: 60000)
-     *
-     * Return Value:
-     *   Array of all events from prompt execution in order:
-     *     - agent_start
-     *     - message events (user, assistant)
-     *     - tool events (if tools called)
-     *     - agent_end
-     *
-     * Usage Pattern:
-     *   const events = await client.promptAndWait("Your question");
-     *   console.log(`Got ${events.length} events`);
-     *
-     * Single Prompt Extraction:
-     *   const events = await client.promptAndWait("What is 2+2?");
-     *   const response = events
-     *     .filter(e => e.type === "message" && e.role === "assistant")
-     *     .map(e => e.content[0]?.text)
-     *     .join("\\n");
-     *   console.log("Response:", response);
-     *
-     * Tool Tracking:
-     *   const events = await client.promptAndWait("Find files in /tmp");
-     *   const tools = events
-     *     .filter(e => e.type === "tool_call")
-     *     .map(e => e.toolName);
-     *   console.log("Tools used:", tools);
-     *
-     * With Images:
-     *   const events = await client.promptAndWait(
-     *     "Analyze this image",
-     *     [{ mimeType: "image/png", data: "base64..." }]
-     *   );
-     *
-     * With Custom Timeout:
-     *   const events = await client.promptAndWait(
-     *     "Long running task",
-     *     undefined,
-     *     120000  // 2 minute timeout
-     *   );
-     *
-     * Sequential Prompts:
-     *   for (const prompt of prompts) {
-     *     const events = await client.promptAndWait(prompt);
-     *     processEvents(events);
-     *   }
-     *
-     * Error Handling:
-     *   try {
-     *     const events = await client.promptAndWait(prompt, undefined, 30000);
-     *   } catch (error) {
-     *     console.error("Failed:", error.message);
-     *     console.error("Debug info:", client.getStderr());
-     *   }
-     *
-     * Note:
-     *   - Simplest API for single prompt→response cycle
-     *   - Not suitable for steering/follow-up (those are fire-and-forget)
-     *   - Use prompt() + onEvent() for interactive scenarios
-     *
-     * @param message - Prompt text to send
-     * @param images - Optional image attachments
-     * @param timeout - Timeout in milliseconds (default: 60000)
-     * @returns Promise resolving to array of all events
-     * @throws Error if timeout exceeded or client not started
-     */
-    async promptAndWait(message, images, timeout = 60000) {
-        const eventsPromise = this.collectEvents(timeout);
-        await this.prompt(message, images);
-        return eventsPromise;
-    }
-    // =========================================================================
-    // Internal
-    // =========================================================================
-    handleLine(line) {
-        try {
-            const data = JSON.parse(line);
-            if (isRpcResponse(data) && this.resolvePendingResponse(data)) {
-                return;
-            }
-            this.emitIncomingEvent(data);
-        }
-        catch {
-            // Ignore non-JSON lines
-        }
-    }
-    async send(command) {
-        if (!this.process?.stdin) {
-            throw new Error("Client not started");
-        }
-        const { id, payload } = this.createCommandEnvelope(command);
-        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);
-            this.pendingRequests.set(id, {
-                resolve: (response) => {
-                    clearTimeout(timeout);
-                    resolve(response);
-                },
-                reject: (error) => {
-                    clearTimeout(timeout);
-                    reject(error);
-                },
-            });
-            this.process.stdin.write(`${JSON.stringify(payload)}\n`);
-        });
-    }
-    getData(response) {
-        if (!response.success) {
-            const errorResponse = response;
-            throw new Error(errorResponse.error);
-        }
-        // Type assertion: we trust response.data matches T based on the command sent.
-        // This is safe because each public method specifies the correct T for its command.
-        const successResponse = response;
-        return successResponse.data;
-    }
-}
-//# sourceMappingURL=rpc-client.js.map