indusagi-coding-agent 0.1.58 → 0.1.60

package/dist/interfaces/service-api/rpc-mode.d.ts

@@ -1,813 +0,0 @@
-/**
- * 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 type { AgentSession } from "../../runtime/agent-session.js";
-export type { RpcCommand, RpcExtensionUIRequest, RpcExtensionUIResponse, RpcResponse, RpcSessionState, } 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 declare function runRpcMode(session: AgentSession): Promise<never>;
-//# sourceMappingURL=rpc-mode.d.ts.map