indusagi-coding-agent 0.1.41 → 0.1.42

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

@@ -0,0 +1,1229 @@
+/**
+ * RPC Mode - Network API for programmatic access to the coding agent
+ *
+ * ============================================================================
+ * PURPOSE
+ * ============================================================================
+ *
+ * Provides a headless JSON-RPC 2.0 interface for embedding the agent in
+ * other applications or accessing it via network. Enables programmatic
+ * control of the agent without terminal UI, suitable for:
+ *
+ * - IDE plugins and editor extensions
+ * - Web applications and dashboards
+ * - Automated workflows and orchestration
+ * - Mobile or desktop app backends
+ * - Testing and development tools
+ * - Multi-client session management
+ *
+ * ============================================================================
+ * PROTOCOL: JSON-RPC 2.0 WITH EXTENSIONS
+ * ============================================================================
+ *
+ * Communication Model:
+ *   - Stdin: JSON lines with RpcCommand objects
+ *   - Stdout: JSON lines with RpcResponse and AgentSessionEvent objects
+ *   - Bidirectional: Client sends commands, server sends responses/events
+ *   - Asynchronous: Events streamed independently of command responses
+ *
+ * Command Format:
+ *   {
+ *     "id": "req-123",                  // Optional correlation ID (string or number)
+ *     "type": "prompt",                 // Command type
+ *     "message": "What is 2+2?",        // Command-specific fields
+ *     "images": [...]                   // Optional images
+ *   }
+ *
+ * Response Format:
+ *   {
+ *     "id": "req-123",                  // Matches command ID
+ *     "type": "response",
+ *     "command": "prompt",              // Which command this responds to
+ *     "success": true,
+ *     "data": {...}                     // Optional success data
+ *   }
+ *   OR
+ *   {
+ *     "id": "req-123",
+ *     "type": "response",
+ *     "command": "prompt",
+ *     "success": false,
+ *     "error": "Model not found"
+ *   }
+ *
+ * Event Format (streamed asynchronously):
+ *   {
+ *     "type": "agent_start",
+ *     "model": {...}
+ *   }
+ *   {
+ *     "type": "message",
+ *     "role": "assistant",
+ *     "content": [...]
+ *   }
+ *   {
+ *     "type": "tool_call",
+ *     "toolName": "bash",
+ *     "toolInput": {"command": "ls"}
+ *   }
+ *   ... More events ...
+ *
+ * Extension UI Request Format:
+ *   {
+ *     "type": "extension_ui_request",
+ *     "id": "ui-456",
+ *     "method": "select",               // UI method: select, confirm, input, etc.
+ *     "title": "Select option",
+ *     "options": ["Option 1", "Option 2"]
+ *   }
+ *
+ * Extension UI Response Format (client must send):
+ *   {
+ *     "type": "extension_ui_response",
+ *     "id": "ui-456",
+ *     "value": "Option 1"               // Response depends on method
+ *   }
+ *   OR (for cancelled dialogs):
+ *   {
+ *     "type": "extension_ui_response",
+ *     "id": "ui-456",
+ *     "cancelled": true
+ *   }
+ *
+ * ============================================================================
+ * SERVER LIFECYCLE
+ * ============================================================================
+ *
+ * Startup Phase:
+ *   1. Process starts in RPC mode (via --mode rpc flag)
+ *   2. AgentSession initialized (loads model, tools, extensions)
+ *   3. Extensions initialized with RPC-based ExtensionUIContext
+ *   4. Event subscription set up
+ *   5. Readline interface starts listening on stdin
+ *   6. Server ready to accept commands
+ *
+ * Command Processing Loop:
+ *   1. Read JSON line from stdin
+ *   2. If extension_ui_response: resolve pending extension UI request
+ *   3. If RpcCommand: validate, route to handler, send response
+ *   4. Continue listening for next command
+ *
+ * Streaming Events:
+ *   - As agent processes commands, events streamed to stdout asynchronously
+ *   - Client receives both responses (for correlation) and events (for updates)
+ *   - No ordering guarantee between events from different commands (if sent quickly)
+ *
+ * Shutdown Phase:
+ *   - Extension sends session_shutdown event (optional)
+ *   - Extension shutdown handlers run
+ *   - Process exits with code 0
+ *   - Client should close readline interface
+ *
+ * ============================================================================
+ * AVAILABLE COMMANDS
+ * ============================================================================
+ *
+ * Prompting Commands:
+ *   prompt(message, images, streamingBehavior)
+ *     → Executes agent loop with prompt
+ *     → Returns success or error
+ *     → Streams events asynchronously
+ *
+ *   steer(message)
+ *     → Queue message to steer current agent response
+ *     → Only valid while agent streaming
+ *
+ *   follow_up(message)
+ *     → Queue follow-up prompt for after current response
+ *     → Buffers until current response complete
+ *
+ *   abort()
+ *     → Cancel current streaming/processing
+ *     → Cleans up pending operations
+ *
+ * State Commands:
+ *   get_state()
+ *     → Returns current session state
+ *     → Includes model, messages count, streaming status
+ *
+ *   get_messages()
+ *     → Returns all messages in session
+ *
+ * Model Commands:
+ *   set_model(provider, modelId)
+ *     → Switch to different model
+ *
+ *   cycle_model()
+ *     → Switch to next scoped model or available model
+ *
+ *   get_available_models()
+ *     → List all available models
+ *
+ * Thinking Commands:
+ *   set_thinking_level(level)
+ *     → Set thinking budget: "none", "auto", "max"
+ *
+ *   cycle_thinking_level()
+ *     → Cycle through thinking levels
+ *
+ * Queue Mode Commands:
+ *   set_steering_mode(mode)
+ *     → Set steering behavior: "immediate", "queued"
+ *
+ *   set_follow_up_mode(mode)
+ *     → Set follow-up behavior: "immediate", "queued"
+ *
+ * Compaction Commands:
+ *   compact(customInstructions)
+ *     → Manually compact session context
+ *     → Returns compaction summary
+ *
+ *   set_auto_compaction(enabled)
+ *     → Enable/disable auto compaction
+ *
+ * Bash Commands:
+ *   bash(command)
+ *     → Execute bash command synchronously
+ *     → Returns stdout, stderr, exit code
+ *
+ *   abort_bash()
+ *     → Kill running bash command
+ *
+ * Session Commands:
+ *   get_session_stats()
+ *     → Returns token usage, message count, etc.
+ *
+ *   export_html(outputPath)
+ *     → Export session to HTML file
+ *
+ *   switch_session(sessionPath)
+ *     → Load different session file
+ *
+ *   fork(entryId)
+ *     → Create new session from branch point
+ *
+ * ============================================================================
+ * ERROR HANDLING
+ * ============================================================================
+ *
+ * Response Errors:
+ *   All errors returned in success: false responses with error field
+ *   No exceptions thrown (graceful error handling)
+ *
+ * Error Categories:
+ *   - Invalid command/arguments → success: false
+ *   - Model not found → success: false
+ *   - Session not found → success: false
+ *   - Tool execution error → returned in event
+ *   - API error → returned in stop_reason: "error" event
+ *
+ * Extension UI Errors:
+ *   - Dialog timeout → default value returned
+ *   - Signal abort → default value returned
+ *   - Client disconnect → no response (pending request hangs)
+ *
+ * ============================================================================
+ * EXTENSION SYSTEM IN RPC MODE
+ * ============================================================================
+ *
+ * Extension UI Context:
+ *   - Dialog methods (select, confirm, input) emit extension_ui_request
+ *   - Client must respond with extension_ui_response
+ *   - Supports timeouts and abort signals
+ *
+ * Supported UI Methods:
+ *   - select(title, options, opts) → option value or undefined
+ *   - confirm(title, message, opts) → boolean
+ *   - input(title, placeholder, opts) → string or undefined
+ *   - notify(message, type) → fire-and-forget
+ *   - setStatus(key, text) → fire-and-forget
+ *   - setWidget(key, content) → fire-and-forget (string arrays only)
+ *   - setTitle(title) → fire-and-forget
+ *   - editor(title, prefill) → edited text or undefined
+ *
+ * Unsupported UI Methods (RPC mode limitations):
+ *   - setWorkingMessage() → no TUI loader access
+ *   - setWidget(factory) → factory functions not supported
+ *   - setFooter(factory) → requires TUI access
+ *   - setHeader(factory) → requires TUI access
+ *   - custom() → requires TUI access
+ *   - setEditorComponent() → requires TUI access
+ *   - Theme switching → read-only access only
+ *
+ * Extension Hooks:
+ *   - before_prompt: Runs before agent execution
+ *   - after_prompt: Runs after agent execution
+ *   - session_shutdown: Runs on shutdown signal
+ *   - on_error: Extension error handler
+ *
+ * ============================================================================
+ * CLIENT IMPLEMENTATION EXAMPLE
+ * ============================================================================
+ *
+ * const { spawn } = require('child_process');
+ *
+ * const server = spawn('indusagi', ['--mode', 'rpc']);
+ * const readline = require('readline').createInterface({
+ *   input: server.stdout,
+ *   output: process.stdout,
+ *   terminal: false
+ * });
+ *
+ * let nextId = 1;
+ * const pending = new Map();
+ *
+ * readline.on('line', (line) => {
+ *   const obj = JSON.parse(line);
+ *   if (obj.type === 'response') {
+ *     const resolve = pending.get(obj.id);
+ *     if (resolve) {
+ *       resolve(obj);
+ *       pending.delete(obj.id);
+ *     }
+ *   } else if (obj.type === 'extension_ui_request') {
+ *     // Handle UI request from extension
+ *     server.stdin.write(JSON.stringify({
+ *       type: 'extension_ui_response',
+ *       id: obj.id,
+ *       value: 'user selection'
+ *     }) + '\n');
+ *   } else {
+ *     // Handle event (agent_start, message, tool_call, etc.)
+ *     console.log('Event:', obj.type);
+ *   }
+ * });
+ *
+ * // Send a prompt
+ * const id = String(nextId++);
+ * server.stdin.write(JSON.stringify({
+ *   id,
+ *   type: 'prompt',
+ *   message: 'What is 2+2?'
+ * }) + '\n');
+ *
+ * pending.set(id, (response) => {
+ *   console.log('Response:', response);
+ * });
+ *
+ * ============================================================================
+ * BASED ON RPC SERVER IMPLEMENTATION
+ * ============================================================================
+ *
+ * This RPC mode provides a robust, JSON-based interface for programmatic
+ * access to the agent. It follows JSON-RPC 2.0 conventions with extensions
+ * for streaming events and asynchronous extension UI.
+ *
+ * Use cases:
+ * - Backend API for web applications
+ * - IDE plugin integration
+ * - Workflow orchestration
+ * - Multi-tenant agent service
+ * - Development and testing
+ */
+import * as crypto from "node:crypto";
+import * as readline from "readline";
+import { theme } from "../terminal-ui/theme/theme.js";
+import { isRpcExtensionUiResponse, } from "./rpc-types.js";
+/**
+ * Run in RPC (Remote Procedure Call) mode.
+ * Establishes a JSON-RPC 2.0 based server for programmatic access to the coding agent.
+ * Listens for JSON commands on stdin, outputs events and responses on stdout.
+ *
+ * ============================================================================
+ * FUNCTION SIGNATURE
+ * ============================================================================
+ *
+ * async runRpcMode(session: AgentSession): Promise<never>
+ *
+ * Note: Never returns - process loop runs indefinitely until stdin closes.
+ *
+ * ============================================================================
+ * COMMAND PROCESSING LOOP
+ * ============================================================================
+ *
+ * Overview:
+ *   1. Initialize server and set up event subscriptions
+ *   2. Create readline interface on stdin
+ *   3. For each line:
+ *      a. Parse JSON to get command or extension UI response
+ *      b. If extension_ui_response: resolve pending UI request
+ *      c. If RpcCommand: route to handler, send response
+ *      d. Continue listening (no blocking)
+ *   4. Events stream continuously as agent processes
+ *   5. Check for shutdown signal after each command
+ *
+ * Processing Model:
+ *   - Commands are fire-and-forget (response sent, then events stream)
+ *   - No ordering guarantee between different commands' events
+ *   - Multiple commands can be queued and processed serially
+ *   - Events stream asynchronously throughout processing
+ *
+ * ============================================================================
+ * STARTUP INITIALIZATION
+ * ============================================================================
+ *
+ * Extension Setup:
+ *   1. Check if extensionRunner exists in session
+ *   2. Create RPC-based ExtensionUIContext (emits ui_request events)
+ *   3. Bind extensions with:
+ *      - Custom UI context (no TUI access - dialogs via RPC)
+ *      - Command context actions (session control)
+ *      - Error handlers (logged, not fatal)
+ *      - Shutdown handler (sets shutdownRequested flag)
+ *
+ * Session Subscription:
+ *   1. Subscribe to all session events
+ *   2. Forward all events to client via output()
+ *   3. Enables client to reconstruct session state
+ *
+ * Readline Setup:
+ *   1. Create interface on process.stdin
+ *   2. Set terminal: false (don't read from TTY)
+ *   3. Listen for 'line' events
+ *   4. Stay alive indefinitely (Promise never resolves)
+ *
+ * ============================================================================
+ * COMMAND HANDLERS (30+ Commands)
+ * ============================================================================
+ *
+ * PROMPTING COMMANDS (4 handlers)
+ * ──────────────────────────────────────────────────────────────────────
+ *
+ * prompt(message: string, images?: ImageContent[], streamingBehavior?: "steer" | "followUp")
+ *   Purpose: Send a new prompt to the agent
+ *   Input:
+ *     - message (required): The prompt text
+ *     - images (optional): Array of image content (PNG, JPEG, GIF, WebP)
+ *     - streamingBehavior: "steer" (interrupt), "followUp" (queue after)
+ *   Response: { success: true } immediately
+ *   Events: agent_start → messages → tool_calls → agent_end (streamed)
+ *   Exit Code on Error: 1
+ *   Example:
+ *     Client: {"id":"1","type":"prompt","message":"What is 2+2?"}
+ *     Server: {"id":"1","type":"response","command":"prompt","success":true}
+ *     Server: {"type":"agent_start",...}
+ *     Server: {"type":"message","role":"assistant",...}
+ *     Server: {"type":"agent_end"}
+ *
+ * steer(message: string)
+ *   Purpose: Interrupt current streaming response and steer it
+ *   Input:
+ *     - message (required): Steering instruction
+ *   Response: { success: true }
+ *   Behavior: Only valid while agent streaming (otherwise queued)
+ *   Use Case: "Stop using bash, use node instead"
+ *   Example:
+ *     Client: {"id":"2","type":"steer","message":"Use Python instead"}
+ *     Server: {"id":"2","type":"response","command":"steer","success":true}
+ *
+ * follow_up(message: string)
+ *   Purpose: Queue message to be processed after current response
+ *   Input:
+ *     - message (required): Follow-up prompt
+ *   Response: { success: true }
+ *   Behavior: Buffered, processed when agent becomes idle
+ *   Use Case: Pipelining multiple prompts without waiting
+ *   Example:
+ *     Client: {"id":"3","type":"follow_up","message":"Now optimize it"}
+ *     Server: {"id":"3","type":"response","command":"follow_up","success":true}
+ *
+ * abort()
+ *   Purpose: Cancel current operation
+ *   Response: { success: true }
+ *   Effect: Stops streaming, cleans up pending operations
+ *   Use Case: User hit Ctrl+C or timeout reached
+ *   Example:
+ *     Client: {"id":"4","type":"abort"}
+ *     Server: {"id":"4","type":"response","command":"abort","success":true}
+ *
+ * new_session(parentSession?: string)
+ *   Purpose: Start new session, optionally tracking parent
+ *   Input:
+ *     - parentSession (optional): Path to parent session for lineage
+ *   Response: { success: true, data: { cancelled: boolean } }
+ *   Effect: Creates new session file, clears message history
+ *   Use Case: Starting fresh conversation branch
+ *   Example:
+ *     Client: {"id":"5","type":"new_session"}
+ *     Server: {"id":"5","type":"response","command":"new_session","success":true,"data":{"cancelled":false}}
+ *
+ * STATE COMMANDS (3 handlers)
+ * ──────────────────────────────────────────────────────────────────────
+ *
+ * get_state()
+ *   Purpose: Query current session state snapshot
+ *   Response: { success: true, data: RpcSessionState }
+ *   Returns:
+ *     - model: Current model info (provider, id, context window)
+ *     - thinkingLevel: "none" | "auto" | "max"
+ *     - isStreaming: Agent currently processing
+ *     - isCompacting: Auto-compaction in progress
+ *     - steeringMode: "all" | "one-at-a-time"
+ *     - followUpMode: "all" | "one-at-a-time"
+ *     - sessionFile: Full path to session JSONL
+ *     - sessionId: Short session ID
+ *     - autoCompactionEnabled: Auto-compact setting
+ *     - messageCount: Total messages in session
+ *     - pendingMessageCount: Queued but not processed
+ *   Use Case: Client UI state display, status checks
+ *   Example:
+ *     Client: {"id":"6","type":"get_state"}
+ *     Server: {"id":"6","type":"response","command":"get_state","success":true,"data":{...}}
+ *
+ * get_messages()
+ *   Purpose: Retrieve all messages in conversation
+ *   Response: { success: true, data: { messages: AgentMessage[] } }
+ *   Returns: Complete message history with content, roles, stop reasons
+ *   Use Case: Reconstructing session state, exporting conversation
+ *   Note: Use carefully if session is very large (many tokens)
+ *   Example:
+ *     Client: {"id":"7","type":"get_messages"}
+ *     Server: {"id":"7","type":"response","command":"get_messages","success":true,"data":{...}}
+ *
+ * get_last_assistant_text()
+ *   Purpose: Quick access to most recent assistant response
+ *   Response: { success: true, data: { text: string | null } }
+ *   Returns: Only text content (ignores images/tool use)
+ *   Use Case: Getting latest response without full state
+ *   Example:
+ *     Client: {"id":"8","type":"get_last_assistant_text"}
+ *     Server: {"id":"8","type":"response",...,"data":{"text":"The answer is 4"}}
+ *
+ * MODEL COMMANDS (3 handlers)
+ * ──────────────────────────────────────────────────────────────────────
+ *
+ * set_model(provider: string, modelId: string)
+ *   Purpose: Switch to specific model
+ *   Input:
+ *     - provider: "anthropic", "openai", "google", etc.
+ *     - modelId: Model identifier ("claude-3-5-sonnet", "gpt-4", etc.)
+ *   Response: { success: true, data: Model } on success
+ *            OR { success: false, error: "Model not found" }
+ *   Effect: Changes active model for subsequent prompts
+ *   Validation: Checks model exists in registry
+ *   Use Case: Programmatic model selection based on capability
+ *   Example:
+ *     Client: {"id":"9","type":"set_model","provider":"anthropic","modelId":"claude-3-5-sonnet"}
+ *     Server: {"id":"9","type":"response",...,"success":true,"data":{"provider":"anthropic",...}}
+ *
+ * cycle_model()
+ *   Purpose: Switch to next scoped model or available model
+ *   Response: { success: true, data: Model } if cycled
+ *            OR { success: true, data: null } if only one model
+ *   Use Case: User cycles through available options
+ *   Example:
+ *     Client: {"id":"10","type":"cycle_model"}
+ *     Server: {"id":"10","type":"response",...,"data":{"model":{...},"thinkingLevel":"auto"}}
+ *
+ * get_available_models()
+ *   Purpose: List all models available to user
+ *   Response: { success: true, data: { models: Model[] } }
+ *   Returns: Array of all models from provider registry
+ *   Use Case: Client UI model selector, capability checking
+ *   Example:
+ *     Client: {"id":"11","type":"get_available_models"}
+ *     Server: {"id":"11","type":"response",...,"data":{"models":[...]}}
+ *
+ * THINKING COMMANDS (2 handlers)
+ * ──────────────────────────────────────────────────────────────────────
+ *
+ * set_thinking_level(level: ThinkingLevel)
+ *   Purpose: Control model reasoning/thinking
+ *   Input:
+ *     - level: "none" (no thinking) | "auto" (adaptive) | "max" (max budget)
+ *   Response: { success: true }
+ *   Effect: Changes thinking for subsequent prompts
+ *   Supported Models: Only models with reasoning capability
+ *   Use Case: Trading latency for reasoning quality
+ *   Example:
+ *     Client: {"id":"12","type":"set_thinking_level","level":"max"}
+ *     Server: {"id":"12","type":"response","command":"set_thinking_level","success":true}
+ *
+ * cycle_thinking_level()
+ *   Purpose: Rotate through thinking levels
+ *   Cycle: "none" → "auto" → "max" → "none" ...
+ *   Response: { success: true, data: { level: ThinkingLevel } } or null if unsupported
+ *   Example:
+ *     Client: {"id":"13","type":"cycle_thinking_level"}
+ *     Server: {"id":"13","type":"response",...,"data":{"level":"auto"}}
+ *
+ * QUEUE MODE COMMANDS (2 handlers)
+ * ──────────────────────────────────────────────────────────────────────
+ *
+ * set_steering_mode(mode: "all" | "one-at-a-time")
+ *   Purpose: Configure how steering messages are processed
+ *   Input:
+ *     - "all": Process all steering messages as queue
+ *     - "one-at-a-time": Process steering sequentially
+ *   Response: { success: true }
+ *   Example:
+ *     Client: {"id":"14","type":"set_steering_mode","mode":"all"}
+ *     Server: {"id":"14","type":"response","command":"set_steering_mode","success":true}
+ *
+ * set_follow_up_mode(mode: "all" | "one-at-a-time")
+ *   Purpose: Configure how follow-up messages are processed
+ *   Input:
+ *     - "all": Process all follow-ups in sequence
+ *     - "one-at-a-time": Process one, then wait
+ *   Response: { success: true }
+ *   Example:
+ *     Client: {"id":"15","type":"set_follow_up_mode","mode":"one-at-a-time"}
+ *     Server: {"id":"15","type":"response","command":"set_follow_up_mode","success":true}
+ *
+ * COMPACTION COMMANDS (2 handlers)
+ * ──────────────────────────────────────────────────────────────────────
+ *
+ * compact(customInstructions?: string)
+ *   Purpose: Manually trigger context compaction
+ *   Input:
+ *     - customInstructions (optional): Special instructions for compaction
+ *   Response: { success: true, data: CompactionResult }
+ *   Returns:
+ *     - removedMessages: Count of messages removed
+ *     - summary: Summarized context
+ *     - tokensRecovered: Token count freed
+ *   Effect: Summarizes old messages, frees context for new content
+ *   Use Case: Manual compaction when approaching context limit
+ *   Example:
+ *     Client: {"id":"16","type":"compact","customInstructions":"Keep technical details"}
+ *     Server: {"id":"16","type":"response",...,"data":{"removedMessages":5,"summary":"..."}}
+ *
+ * set_auto_compaction(enabled: boolean)
+ *   Purpose: Enable/disable automatic compaction
+ *   Response: { success: true }
+ *   Effect: When enabled, auto-compacts when approaching context limit
+ *   Default: Typically enabled
+ *   Example:
+ *     Client: {"id":"17","type":"set_auto_compaction","enabled":true}
+ *     Server: {"id":"17","type":"response","command":"set_auto_compaction","success":true}
+ *
+ * RETRY COMMANDS (2 handlers)
+ * ──────────────────────────────────────────────────────────────────────
+ *
+ * set_auto_retry(enabled: boolean)
+ *   Purpose: Enable/disable automatic retry on error
+ *   Response: { success: true }
+ *   Effect: When enabled, automatically retries failed operations
+ *   Example:
+ *     Client: {"id":"18","type":"set_auto_retry","enabled":true}
+ *     Server: {"id":"18","type":"response","command":"set_auto_retry","success":true}
+ *
+ * abort_retry()
+ *   Purpose: Cancel in-flight retry operation
+ *   Response: { success: true }
+ *   Example:
+ *     Client: {"id":"19","type":"abort_retry"}
+ *     Server: {"id":"19","type":"response","command":"abort_retry","success":true}
+ *
+ * BASH COMMANDS (2 handlers)
+ * ──────────────────────────────────────────────────────────────────────
+ *
+ * bash(command: string)
+ *   Purpose: Execute shell command directly (outside agent)
+ *   Input:
+ *     - command: Shell command to execute
+ *   Response: { success: true, data: BashResult }
+ *   Returns:
+ *     - stdout: Standard output
+ *     - stderr: Standard error output
+ *     - exitCode: Exit code (0 = success)
+ *     - timedOut: Whether execution timed out
+ *   Execution: Synchronous, waits for completion
+ *   Use Case: Direct shell access from client, utility operations
+ *   Example:
+ *     Client: {"id":"20","type":"bash","command":"ls -la"}
+ *     Server: {"id":"20","type":"response",...,"data":{"stdout":"...","stderr":"","exitCode":0}}
+ *
+ * abort_bash()
+ *   Purpose: Kill running bash command
+ *   Response: { success: true }
+ *   Effect: Immediately terminates bash subprocess
+ *   Example:
+ *     Client: {"id":"21","type":"abort_bash"}
+ *     Server: {"id":"21","type":"response","command":"abort_bash","success":true}
+ *
+ * SESSION MANAGEMENT COMMANDS (7 handlers)
+ * ──────────────────────────────────────────────────────────────────────
+ *
+ * get_session_stats()
+ *   Purpose: Get detailed session statistics
+ *   Response: { success: true, data: SessionStats }
+ *   Returns:
+ *     - messageCount: Total messages
+ *     - totalTokensUsed: Cumulative token usage
+ *     - estimatedCost: Cost estimate
+ *     - sessionDuration: Time since creation
+ *     - toolUsageCount: Tool invocations
+ *   Use Case: Usage tracking, monitoring, billing
+ *   Example:
+ *     Client: {"id":"22","type":"get_session_stats"}
+ *     Server: {"id":"22","type":"response",...,"data":{"messageCount":42,...}}
+ *
+ * export_html(outputPath?: string)
+ *   Purpose: Export session to HTML file
+ *   Input:
+ *     - outputPath (optional): Where to save HTML (default: auto-generated)
+ *   Response: { success: true, data: { path: string } }
+ *   Returns: Path where HTML was written
+ *   Use Case: Sharing conversations, archiving, documentation
+ *   Example:
+ *     Client: {"id":"23","type":"export_html","outputPath":"/tmp/session.html"}
+ *     Server: {"id":"23","type":"response",...,"data":{"path":"/tmp/session.html"}}
+ *
+ * switch_session(sessionPath: string)
+ *   Purpose: Load different session file
+ *   Input:
+ *     - sessionPath: Path to .jsonl session file
+ *   Response: { success: true, data: { cancelled: boolean } }
+ *   Effect: Closes current session, loads new one
+ *   Validation: File must exist and be valid session JSONL
+ *   Example:
+ *     Client: {"id":"24","type":"switch_session","sessionPath":"~/.indusagi/sessions/old.jsonl"}
+ *     Server: {"id":"24","type":"response",...,"data":{"cancelled":false}}
+ *
+ * fork(entryId: string)
+ *   Purpose: Create new session from branch point
+ *   Input:
+ *     - entryId: Message ID to branch from
+ *   Response: { success: true, data: { text: string, cancelled: boolean } }
+ *   Returns: Text at branch point
+ *   Effect: New session created with messages up to branch point
+ *   Use Case: Exploring alternative conversation paths
+ *   Example:
+ *     Client: {"id":"25","type":"fork","entryId":"msg-42"}
+ *     Server: {"id":"25","type":"response",...,"data":{"text":"...","cancelled":false}}
+ *
+ * get_fork_messages()
+ *   Purpose: Get messages available for branching
+ *   Response: { success: true, data: { messages: Array<{entryId, text}> } }
+ *   Returns: List of message IDs and summaries
+ *   Use Case: UI showing available branch points
+ *   Example:
+ *     Client: {"id":"26","type":"get_fork_messages"}
+ *     Server: {"id":"26","type":"response",...,"data":{"messages":[...]}}
+ *
+ * ============================================================================
+ * EXTENSION UI REQUEST/RESPONSE HANDLING
+ * ============================================================================
+ *
+ * When extensions request user input, the protocol uses bidirectional
+ * extension_ui_request/response messages:
+ *
+ * Server sends extension_ui_request when extension needs input:
+ *   {
+ *     "type": "extension_ui_request",
+ *     "id": "ui-uuid",
+ *     "method": "select" | "confirm" | "input" | "editor" | "notify" | ...
+ *     ...method-specific fields...
+ *   }
+ *
+ * Client responds with extension_ui_response:
+ *   {
+ *     "type": "extension_ui_response",
+ *     "id": "ui-uuid",
+ *     "value": "..."  // or "confirmed": true or "cancelled": true
+ *   }
+ *
+ * Supported Methods:
+ *   - select(title, options): User picks option
+ *   - confirm(title, message): Yes/no confirmation
+ *   - input(title, placeholder): Text input
+ *   - editor(title, prefill): Multi-line editor
+ *   - notify(message, type): Info/warning/error notification (no response)
+ *   - setStatus(key, text): Update status line (no response)
+ *   - setWidget(key, lines): Update widget display (no response)
+ *   - setTitle(title): Set terminal title (no response)
+ *   - setEditorText(text): Set editor content (no response)
+ *
+ * Timeout Handling:
+ *   - If client doesn't respond within timeout, default value used
+ *   - Dialog cancelled, handler receives undefined/false
+ *   - Server continues processing
+ *
+ * ============================================================================
+ * SHUTDOWN PROTOCOL
+ * ============================================================================
+ *
+ * Graceful Shutdown:
+ *   1. Extension sends "shutdown_requested" signal (internal)
+ *   2. After next idle point (between commands)
+ *   3. Server emits session_shutdown event (via extension runner)
+ *   4. Readline closed, process exits cleanly with code 0
+ *
+ * Abnormal Shutdown:
+ *   - Stdin closes: readline 'close' event triggers process exit
+ *   - Ctrl+C: SIGINT handler stops server
+ *   - SIGTERM: Server performs cleanup then exits
+ *
+ * ============================================================================
+ * ERROR HANDLING STRATEGIES
+ * ============================================================================
+ *
+ * Command Errors:
+ *   - All caught and returned as { success: false, error: "message" }
+ *   - No exceptions thrown to client
+ *   - Process continues, ready for next command
+ *
+ * Extension Errors:
+ *   - Logged to stderr with format: "Extension error (path): message"
+ *   - Emitted as hook_error or extension_error event
+ *   - Don't crash server, handler registered errors
+ *
+ * Async Event Errors:
+ *   - Agent events from streaming: included in events
+ *   - Stop reason "error" in message event
+ *   - Client can subscribe to events for error details
+ *
+ * Unrecoverable Errors:
+ *   - Process exits with code 1
+ *   - Client should detect process termination
+ *   - Reconnect and start new session
+ *
+ * ============================================================================
+ * IMPLEMENTATION NOTES
+ * ============================================================================
+ *
+ * Event Emission:
+ *   - Subscription set up at startup
+ *   - All events output via output() function
+ *   - Events stream even during command processing
+ *   - No backpressure or queuing (stdout assumed fast)
+ *
+ * Request Correlation:
+ *   - Each command gets unique ID (optional, generated if missing)
+ *   - Response includes same ID for correlation
+ *   - Client can match responses to requests by ID
+ *   - Extension UI requests also use UUID for correlation
+ *
+ * State Safety:
+ *   - Session state is thread-safe (no multi-threading)
+ *   - Readline ensures single-threaded execution
+ *   - Events stream after response to ensure ordering
+ *
+ * ============================================================================
+ * BASED ON RPC SERVER IMPLEMENTATION
+ * ============================================================================
+ *
+ * This function implements the complete JSON-RPC 2.0 protocol with
+ * extensions for streaming events and asynchronous extension UI.
+ * It provides a robust, type-safe interface for programmatic access.
+ *
+ * Use with RpcClient for type-safe client implementation.
+ * Or implement custom client using the protocol specification.
+ */
+export async function runRpcMode(session) {
+    const output = (obj) => {
+        console.log(JSON.stringify(obj));
+    };
+    const success = (id, command, data) => {
+        if (data === undefined) {
+            return { id, type: "response", command, success: true };
+        }
+        return { id, type: "response", command, success: true, data };
+    };
+    const error = (id, command, message) => {
+        return { id, type: "response", command, success: false, error: message };
+    };
+    // Pending extension UI requests waiting for response
+    const pendingExtensionRequests = new Map();
+    // Shutdown request flag
+    let shutdownRequested = false;
+    const nextUiRequestId = () => crypto.randomUUID();
+    const emitUiRequest = (request) => {
+        const id = nextUiRequestId();
+        output({ type: "extension_ui_request", id, ...request });
+        return id;
+    };
+    const resolveExtensionUiResponse = (response) => {
+        const pending = pendingExtensionRequests.get(response.id);
+        if (!pending) {
+            return false;
+        }
+        pendingExtensionRequests.delete(response.id);
+        pending.resolve(response);
+        return true;
+    };
+    /** Helper for dialog methods with signal/timeout support */
+    function createDialogPromise(opts, defaultValue, request, parseResponse) {
+        if (opts?.signal?.aborted)
+            return Promise.resolve(defaultValue);
+        const id = nextUiRequestId();
+        return new Promise((resolve, reject) => {
+            let timeoutId;
+            const cleanup = () => {
+                if (timeoutId)
+                    clearTimeout(timeoutId);
+                opts?.signal?.removeEventListener("abort", onAbort);
+                pendingExtensionRequests.delete(id);
+            };
+            const onAbort = () => {
+                cleanup();
+                resolve(defaultValue);
+            };
+            opts?.signal?.addEventListener("abort", onAbort, { once: true });
+            if (opts?.timeout) {
+                timeoutId = setTimeout(() => {
+                    cleanup();
+                    resolve(defaultValue);
+                }, opts.timeout);
+            }
+            pendingExtensionRequests.set(id, {
+                resolve: (response) => {
+                    cleanup();
+                    resolve(parseResponse(response));
+                },
+                reject,
+            });
+            output({ type: "extension_ui_request", id, ...request });
+        });
+    }
+    /**
+     * Create an extension UI context that uses the RPC protocol.
+     */
+    const createExtensionUIContext = () => ({
+        select: (title, options, opts) => createDialogPromise(opts, undefined, { method: "select", title, options, timeout: opts?.timeout }, (r) => "cancelled" in r && r.cancelled ? undefined : "value" in r ? r.value : undefined),
+        confirm: (title, message, opts) => createDialogPromise(opts, false, { method: "confirm", title, message, timeout: opts?.timeout }, (r) => "cancelled" in r && r.cancelled ? false : "confirmed" in r ? r.confirmed : false),
+        input: (title, placeholder, opts) => createDialogPromise(opts, undefined, { method: "input", title, placeholder, timeout: opts?.timeout }, (r) => "cancelled" in r && r.cancelled ? undefined : "value" in r ? r.value : undefined),
+        notify(message, type) {
+            emitUiRequest({ method: "notify", message, notifyType: type });
+        },
+        setStatus(key, text) {
+            emitUiRequest({ method: "setStatus", statusKey: key, statusText: text });
+        },
+        setWorkingMessage(_message) {
+            // Working message not supported in RPC mode - requires TUI loader access
+        },
+        setWidget(key, content, options) {
+            if (content === undefined || Array.isArray(content)) {
+                emitUiRequest({
+                    method: "setWidget",
+                    widgetKey: key,
+                    widgetLines: content,
+                    widgetPlacement: options?.placement,
+                });
+            }
+        },
+        setFooter(_factory) {
+            // Custom footer not supported in RPC mode - requires TUI access
+        },
+        setHeader(_factory) {
+            // Custom header not supported in RPC mode - requires TUI access
+        },
+        setTitle(title) {
+            emitUiRequest({ method: "setTitle", title });
+        },
+        async custom() {
+            // Custom UI not supported in RPC mode
+            return undefined;
+        },
+        setEditorText(text) {
+            emitUiRequest({ method: "set_editor_text", text });
+        },
+        getEditorText() {
+            // Synchronous method can't wait for RPC response
+            // Host should track editor state locally if needed
+            return "";
+        },
+        async editor(title, prefill) {
+            const id = crypto.randomUUID();
+            return new Promise((resolve, reject) => {
+                pendingExtensionRequests.set(id, {
+                    resolve: (response) => {
+                        if ("cancelled" in response && response.cancelled) {
+                            resolve(undefined);
+                        }
+                        else if ("value" in response) {
+                            resolve(response.value);
+                        }
+                        else {
+                            resolve(undefined);
+                        }
+                    },
+                    reject,
+                });
+                output({ type: "extension_ui_request", id, method: "editor", title, prefill });
+            });
+        },
+        setEditorComponent() {
+            // Custom editor components not supported in RPC mode
+        },
+        get theme() {
+            return theme;
+        },
+        getAllThemes() {
+            return [];
+        },
+        getTheme(_name) {
+            return undefined;
+        },
+        setTheme(_theme) {
+            // Theme switching not supported in RPC mode
+            return { success: false, error: "Theme switching not supported in RPC mode" };
+        },
+    });
+    // Set up extensions with RPC-based UI context
+    const extensionRunner = session.extensionRunner;
+    if (extensionRunner) {
+        await session.bindExtensions({
+            uiContext: createExtensionUIContext(),
+            commandContextActions: {
+                waitForIdle: () => session.agent.waitForIdle(),
+                newSession: async (options) => {
+                    const success = await session.newSession({ parentSession: options?.parentSession });
+                    if (success && options?.setup) {
+                        await options.setup(session.sessionManager);
+                    }
+                    return { cancelled: !success };
+                },
+                fork: async (entryId) => {
+                    const result = await session.fork(entryId);
+                    return { cancelled: result.cancelled };
+                },
+                navigateTree: async (targetId, options) => {
+                    const result = await session.navigateTree(targetId, {
+                        summarize: options?.summarize,
+                        customInstructions: options?.customInstructions,
+                        replaceInstructions: options?.replaceInstructions,
+                        label: options?.label,
+                    });
+                    return { cancelled: result.cancelled };
+                },
+            },
+            shutdownHandler: () => {
+                shutdownRequested = true;
+            },
+            onError: (err) => {
+                output({ type: "extension_error", extensionPath: err.extensionPath, event: err.event, error: err.error });
+            },
+            onHookError: (err) => {
+                output({
+                    type: "hook_error",
+                    hookPath: err.hookPath,
+                    hookName: err.hookName,
+                    error: err.error,
+                    stack: err.stack,
+                });
+            },
+        });
+    }
+    // Output all agent events as JSON
+    session.subscribe((event) => {
+        output(event);
+    });
+    // Handle a single command
+    const handleCommand = async (command) => {
+        const id = command.id;
+        switch (command.type) {
+            // =================================================================
+            // Prompting
+            // =================================================================
+            case "prompt": {
+                // Don't await - events will stream
+                // Extension commands are executed immediately, file prompt templates are expanded
+                // If streaming and streamingBehavior specified, queues via steer/followUp
+                session
+                    .prompt(command.message, {
+                    images: command.images,
+                    streamingBehavior: command.streamingBehavior,
+                    source: "rpc",
+                })
+                    .catch((e) => output(error(id, "prompt", e.message)));
+                return success(id, "prompt");
+            }
+            case "steer": {
+                await session.steer(command.message);
+                return success(id, "steer");
+            }
+            case "follow_up": {
+                await session.followUp(command.message);
+                return success(id, "follow_up");
+            }
+            case "abort": {
+                await session.abort();
+                return success(id, "abort");
+            }
+            case "new_session": {
+                const options = command.parentSession ? { parentSession: command.parentSession } : undefined;
+                const cancelled = !(await session.newSession(options));
+                return success(id, "new_session", { cancelled });
+            }
+            // =================================================================
+            // State
+            // =================================================================
+            case "get_state": {
+                const state = {
+                    model: session.model,
+                    thinkingLevel: session.thinkingLevel,
+                    isStreaming: session.isStreaming,
+                    isCompacting: session.isCompacting,
+                    steeringMode: session.steeringMode,
+                    followUpMode: session.followUpMode,
+                    sessionFile: session.sessionFile,
+                    sessionId: session.sessionId,
+                    autoCompactionEnabled: session.autoCompactionEnabled,
+                    messageCount: session.messages.length,
+                    pendingMessageCount: session.pendingMessageCount,
+                };
+                return success(id, "get_state", state);
+            }
+            // =================================================================
+            // Model
+            // =================================================================
+            case "set_model": {
+                const models = await session.modelRegistry.getAvailable();
+                const model = models.find((m) => m.provider === command.provider && m.id === command.modelId);
+                if (!model) {
+                    return error(id, "set_model", `Model not found: ${command.provider}/${command.modelId}`);
+                }
+                await session.setModel(model);
+                return success(id, "set_model", model);
+            }
+            case "cycle_model": {
+                const result = await session.cycleModel();
+                if (!result) {
+                    return success(id, "cycle_model", null);
+                }
+                return success(id, "cycle_model", result);
+            }
+            case "get_available_models": {
+                const models = await session.modelRegistry.getAvailable();
+                return success(id, "get_available_models", { models });
+            }
+            // =================================================================
+            // Thinking
+            // =================================================================
+            case "set_thinking_level": {
+                session.setThinkingLevel(command.level);
+                return success(id, "set_thinking_level");
+            }
+            case "cycle_thinking_level": {
+                const level = session.cycleThinkingLevel();
+                if (!level) {
+                    return success(id, "cycle_thinking_level", null);
+                }
+                return success(id, "cycle_thinking_level", { level });
+            }
+            // =================================================================
+            // Queue Modes
+            // =================================================================
+            case "set_steering_mode": {
+                session.setSteeringMode(command.mode);
+                return success(id, "set_steering_mode");
+            }
+            case "set_follow_up_mode": {
+                session.setFollowUpMode(command.mode);
+                return success(id, "set_follow_up_mode");
+            }
+            // =================================================================
+            // Compaction
+            // =================================================================
+            case "compact": {
+                const result = await session.compact(command.customInstructions);
+                return success(id, "compact", result);
+            }
+            case "set_auto_compaction": {
+                session.setAutoCompactionEnabled(command.enabled);
+                return success(id, "set_auto_compaction");
+            }
+            // =================================================================
+            // Retry
+            // =================================================================
+            case "set_auto_retry": {
+                session.setAutoRetryEnabled(command.enabled);
+                return success(id, "set_auto_retry");
+            }
+            case "abort_retry": {
+                session.abortRetry();
+                return success(id, "abort_retry");
+            }
+            // =================================================================
+            // Bash
+            // =================================================================
+            case "bash": {
+                const result = await session.executeBash(command.command);
+                return success(id, "bash", result);
+            }
+            case "abort_bash": {
+                session.abortBash();
+                return success(id, "abort_bash");
+            }
+            // =================================================================
+            // Session
+            // =================================================================
+            case "get_session_stats": {
+                const stats = session.getSessionStats();
+                return success(id, "get_session_stats", stats);
+            }
+            case "export_html": {
+                const path = await session.exportToHtml(command.outputPath);
+                return success(id, "export_html", { path });
+            }
+            case "switch_session": {
+                const cancelled = !(await session.switchSession(command.sessionPath));
+                return success(id, "switch_session", { cancelled });
+            }
+            case "fork": {
+                const result = await session.fork(command.entryId);
+                return success(id, "fork", { text: result.selectedText, cancelled: result.cancelled });
+            }
+            case "get_fork_messages": {
+                const messages = session.getUserMessagesForForking();
+                return success(id, "get_fork_messages", { messages });
+            }
+            case "get_last_assistant_text": {
+                const text = session.getLastAssistantText();
+                return success(id, "get_last_assistant_text", { text });
+            }
+            // =================================================================
+            // Messages
+            // =================================================================
+            case "get_messages": {
+                return success(id, "get_messages", { messages: session.messages });
+            }
+            default: {
+                const unknownCommand = command;
+                return error(undefined, unknownCommand.type, `Unknown command: ${unknownCommand.type}`);
+            }
+        }
+    };
+    /**
+     * Check if shutdown was requested and perform shutdown if so.
+     * Called after handling each command when waiting for the next command.
+     */
+    async function checkShutdownRequested() {
+        if (!shutdownRequested)
+            return;
+        const currentRunner = session.extensionRunner;
+        if (currentRunner?.hasHandlers("session_shutdown")) {
+            await currentRunner.emit({ type: "session_shutdown" });
+        }
+        // Close readline interface to stop waiting for input
+        rl.close();
+        process.exit(0);
+    }
+    // Listen for JSON input
+    const rl = readline.createInterface({
+        input: process.stdin,
+        output: process.stdout,
+        terminal: false,
+    });
+    rl.on("line", async (line) => {
+        try {
+            const parsed = JSON.parse(line);
+            if (isRpcExtensionUiResponse(parsed)) {
+                resolveExtensionUiResponse(parsed);
+                return;
+            }
+            const command = parsed;
+            const response = await handleCommand(command);
+            output(response);
+            await checkShutdownRequested();
+        }
+        catch (e) {
+            output(error(undefined, "parse", `Failed to parse command: ${e.message}`));
+        }
+    });
+    // Keep process alive forever
+    return new Promise(() => { });
+}
+//# sourceMappingURL=rpc-mode.js.map