indusagi-coding-agent 0.1.23 → 0.1.25

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

@@ -1,14 +1,467 @@
 /**
- * RPC Client for programmatic access to the coding agent.
+ * 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
+ * ============================================================================
  *
- * Spawns the agent in RPC mode and provides a typed API for all operations.
+ * 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";
 // ============================================================================
 // 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;
@@ -20,6 +473,56 @@ export class RpcClient {
     }
     /**
      * 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) {
@@ -61,6 +564,58 @@ export class RpcClient {
     }
     /**
      * 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() {
         if (!this.process)
@@ -84,6 +639,67 @@ export class RpcClient {
     }
     /**
      * 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);
@@ -95,7 +711,49 @@ export class RpcClient {
         };
     }
     /**
-     * Get collected stderr output (useful for debugging).
+     * 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;
@@ -105,8 +763,77 @@ export class RpcClient {
     // =========================================================================
     /**
      * Send a prompt to the agent.
-     * Returns immediately after sending; use onEvent() to receive streaming events.
-     * Use waitForIdle() to wait for completion.
+     *
+     * 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 });
@@ -285,7 +1012,49 @@ export class RpcClient {
     // =========================================================================
     /**
      * Wait for agent to become idle (no streaming).
-     * Resolves when agent_end event is received.
+     *
+     * 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) => {
@@ -303,7 +1072,67 @@ export class RpcClient {
         });
     }
     /**
-     * Collect events until agent becomes idle.
+     * 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) => {
@@ -323,7 +1152,91 @@ export class RpcClient {
         });
     }
     /**
-     * Send prompt and wait for completion, returning all 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);