indusagi-coding-agent 0.1.22 → 0.1.24

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

@@ -1,8 +1,361 @@
 /**
- * RPC protocol types for headless operation.
+ * RPC PROTOCOL SPECIFICATION & TYPE DEFINITIONS
  *
- * Commands are sent as JSON lines on stdin.
- * Responses and events are emitted as JSON lines on stdout.
+ * ============================================================================
+ * OVERVIEW
+ * ============================================================================
+ *
+ * This module defines the complete JSON-RPC 2.0 protocol for headless access
+ * to the coding agent. The protocol supports:
+ *
+ * - Asynchronous command execution with streaming responses
+ * - Full session state management and querying
+ * - Real-time event subscriptions
+ * - Extension UI request/response handling
+ * - Error recovery and graceful degradation
+ *
+ * Communication Model:
+ *   - Stdin: Commands as newline-delimited JSON
+ *   - Stdout: Responses and events as newline-delimited JSON
+ *   - Bidirectional: Client sends commands, server sends responses/events
+ *   - No ordering guarantee: Events from different commands may interleave
+ *
+ * ============================================================================
+ * PROTOCOL BASICS
+ * ============================================================================
+ *
+ * Command Format (Client to Server):
+ * ───────────────────────────────────────────────────────────────────────
+ * {
+ *   "id": "unique-identifier",     // Optional: for correlating responses
+ *   "type": "command-name",         // Required: command type
+ *   ...command-specific fields...
+ * }
+ *
+ * Response Format (Server to Client):
+ * ───────────────────────────────────────────────────────────────────────
+ * SUCCESS:
+ * {
+ *   "id": "unique-identifier",     // Matches command ID if provided
+ *   "type": "response",
+ *   "command": "command-name",     // Which command this responds to
+ *   "success": true,
+ *   "data": {...}                  // Optional: command-specific data
+ * }
+ *
+ * ERROR:
+ * {
+ *   "id": "unique-identifier",
+ *   "type": "response",
+ *   "command": "command-name",
+ *   "success": false,
+ *   "error": "Human-readable error message"
+ * }
+ *
+ * Event Format (Server to Client - Streaming):
+ * ───────────────────────────────────────────────────────────────────────
+ * Events are sent asynchronously and independently of command responses:
+ *
+ * {
+ *   "type": "agent_start",
+ *   "model": { "provider": "...", "id": "..." }
+ * }
+ *
+ * {
+ *   "type": "message",
+ *   "role": "user" | "assistant",
+ *   "content": [...]
+ * }
+ *
+ * {
+ *   "type": "tool_call",
+ *   "toolName": "bash",
+ *   "toolInput": { "command": "..." }
+ * }
+ *
+ * ... More events ...
+ *
+ * {
+ *   "type": "agent_end"
+ * }
+ *
+ * ============================================================================
+ * COMMAND CATEGORIES & TYPES
+ * ============================================================================
+ *
+ * 1. PROMPTING COMMANDS
+ *    ──────────────────
+ *    Control agent execution and conversation flow.
+ *
+ *    - prompt: Send a new prompt with optional images
+ *    - steer: Interrupt and steer current response (queued)
+ *    - follow_up: Queue message for after current response
+ *    - abort: Cancel current operation
+ *    - new_session: Start fresh session with optional parent tracking
+ *
+ * 2. STATE COMMANDS
+ *    ──────────────
+ *    Query and introspect session state.
+ *
+ *    - get_state: Retrieve full session state snapshot
+ *    - get_messages: Get all messages in conversation
+ *    - get_session_stats: Token usage, message count, etc.
+ *    - get_last_assistant_text: Quick access to latest response
+ *
+ * 3. MODEL COMMANDS
+ *    ──────────────
+ *    Configure and switch AI models.
+ *
+ *    - set_model: Switch to specific model by provider/id
+ *    - cycle_model: Switch to next available model
+ *    - get_available_models: List all models from registry
+ *
+ * 4. THINKING COMMANDS
+ *    ──────────────────
+ *    Control model reasoning/thinking behavior.
+ *
+ *    - set_thinking_level: Set budget (none, auto, max)
+ *    - cycle_thinking_level: Rotate through levels
+ *
+ * 5. QUEUE MODE COMMANDS
+ *    ───────────────────
+ *    Configure how multiple inputs are processed.
+ *
+ *    - set_steering_mode: How steering msgs are handled
+ *    - set_follow_up_mode: How follow-ups are processed
+ *
+ * 6. COMPACTION COMMANDS
+ *    ───────────────────
+ *    Manage context window via message summarization.
+ *
+ *    - compact: Manually trigger compaction
+ *    - set_auto_compaction: Enable/disable auto-compaction
+ *
+ * 7. RETRY COMMANDS
+ *    ──────────────
+ *    Control automatic retry behavior.
+ *
+ *    - set_auto_retry: Enable/disable auto-retry
+ *    - abort_retry: Cancel in-flight retry operation
+ *
+ * 8. BASH COMMANDS
+ *    ────────────
+ *    Execute shell commands directly (synchronous).
+ *
+ *    - bash: Execute command and get stdout/stderr
+ *    - abort_bash: Kill running command
+ *
+ * 9. SESSION COMMANDS
+ *    ────────────────
+ *    Session management and persistence.
+ *
+ *    - export_html: Export session to HTML file
+ *    - switch_session: Load different session file
+ *    - fork: Create new session from branch point
+ *    - get_fork_messages: Get available branch points
+ *
+ * ============================================================================
+ * SESSION STATE STRUCTURE
+ * ============================================================================
+ *
+ * RpcSessionState is a snapshot of the session at a point in time:
+ *
+ * {
+ *   "model": {                      // Current model info
+ *     "provider": "anthropic",      // Model provider ID
+ *     "id": "claude-3-5-sonnet",    // Model ID
+ *     "contextWindow": 200000,      // Token limit
+ *     "reasoning": true             // Has reasoning capability
+ *   },
+ *   "thinkingLevel": "auto",        // "none" | "auto" | "max"
+ *   "isStreaming": false,           // Agent currently processing
+ *   "isCompacting": false,          // Auto-compaction in progress
+ *   "steeringMode": "all",          // "all" | "one-at-a-time"
+ *   "followUpMode": "all",          // "all" | "one-at-a-time"
+ *   "sessionFile": "...path...",    // Full path to session JSONL
+ *   "sessionId": "abc123",          // Short session ID
+ *   "autoCompactionEnabled": true,  // Auto-compact on context pressure
+ *   "messageCount": 42,             // Total messages in session
+ *   "pendingMessageCount": 0        // Messages queued but not processed
+ * }
+ *
+ * ============================================================================
+ * ERROR HANDLING & ERROR CODES
+ * ============================================================================
+ *
+ * Response Errors:
+ *   All command errors returned via success: false with error field.
+ *   No exceptions thrown - all errors recoverable.
+ *
+ * Standard Error Codes (JSON-RPC 2.0):
+ *   -32700  Parse error: Malformed JSON in command
+ *   -32600  Invalid Request: Required field missing
+ *   -32601  Method not found: Unknown command type
+ *   -32602  Invalid params: Parameter value invalid for command
+ *   -32603  Internal error: Server error during processing
+ *
+ * Custom Error Codes (Reserved range -32000 to -32099):
+ *   -32000  Session error: Session file corrupted or inaccessible
+ *   -32001  Model error: Model not found or unavailable
+ *   -32002  Tool error: Tool execution failed
+ *   -32003  Timeout: Operation exceeded time limit
+ *   -32004  Abort: Operation aborted by user/system
+ *   -32005  Invalid state: Operation invalid in current state
+ *
+ * Error Response Example:
+ *   {
+ *     "id": "req-123",
+ *     "type": "response",
+ *     "command": "set_model",
+ *     "success": false,
+ *     "error": "Model not found: anthropic/claude-99"
+ *   }
+ *
+ * ============================================================================
+ * EXTENSION UI REQUEST/RESPONSE PROTOCOL
+ * ============================================================================
+ *
+ * When extensions need user input, they emit extension_ui_request events:
+ *
+ * Extension UI Request (Server to Client):
+ * ───────────────────────────────────────────────────────────────────────
+ * {
+ *   "type": "extension_ui_request",
+ *   "id": "ui-uuid",                // Correlation ID
+ *   "method": "select" | "confirm" | "input" | "editor" | ...,
+ *   ...method-specific fields...
+ * }
+ *
+ * Extension UI Response (Client to Server):
+ * ───────────────────────────────────────────────────────────────────────
+ * {
+ *   "type": "extension_ui_response",
+ *   "id": "ui-uuid",                // Matches request ID
+ *   "value": "..."                  // Method-specific response
+ * }
+ *
+ * OR (for cancelled/aborted dialogs):
+ * {
+ *   "type": "extension_ui_response",
+ *   "id": "ui-uuid",
+ *   "cancelled": true
+ * }
+ *
+ * Supported UI Methods:
+ *
+ * select(title, options):
+ *   Request: { method: "select", title: "...", options: [...], timeout?: ms }
+ *   Response: { value: "selected-option" } or { cancelled: true }
+ *   Usage: Extension offers user a choice
+ *
+ * confirm(title, message):
+ *   Request: { method: "confirm", title: "...", message: "...", timeout?: ms }
+ *   Response: { confirmed: boolean } or { cancelled: true }
+ *   Usage: Extension requests yes/no confirmation
+ *
+ * input(title, placeholder):
+ *   Request: { method: "input", title: "...", placeholder: "...", timeout?: ms }
+ *   Response: { value: "user-input" } or { cancelled: true }
+ *   Usage: Extension requests text input
+ *
+ * editor(title, prefill):
+ *   Request: { method: "editor", title: "...", prefill: "..." }
+ *   Response: { value: "edited-text" } or { cancelled: true }
+ *   Usage: Extension opens editor for multi-line editing
+ *
+ * notify(message, type):
+ *   Request: { method: "notify", message: "...", notifyType: "info"|"warning"|"error" }
+ *   No response required (fire-and-forget)
+ *   Usage: Extension sends notification to user
+ *
+ * setStatus(key, text):
+ *   Request: { method: "setStatus", statusKey: "...", statusText: "..." }
+ *   No response required (fire-and-forget)
+ *   Usage: Extension updates status line in UI
+ *
+ * setWidget(key, lines, placement):
+ *   Request: { method: "setWidget", widgetKey: "...", widgetLines: [...], widgetPlacement: "..." }
+ *   No response required (fire-and-forget)
+ *   Usage: Extension updates custom widget display
+ *
+ * setTitle(title):
+ *   Request: { method: "setTitle", title: "..." }
+ *   No response required (fire-and-forget)
+ *   Usage: Extension sets terminal/window title
+ *
+ * setEditorText(text):
+ *   Request: { method: "set_editor_text", text: "..." }
+ *   No response required (fire-and-forget)
+ *   Usage: Extension modifies editor content
+ *
+ * ============================================================================
+ * ASYNCHRONOUS BEHAVIOR & EVENT ORDERING
+ * ============================================================================
+ *
+ * Key Points:
+ *   1. Commands complete immediately with response (success: true/false)
+ *   2. Events stream asynchronously after command response
+ *   3. No ordering guarantee between different command's events
+ *   4. Within a single command, events are ordered
+ *
+ * Example Timeline:
+ *   Client: { "id": "req-1", "type": "prompt", "message": "Hello" }
+ *   Server: { "id": "req-1", "type": "response", "command": "prompt", "success": true }
+ *   Server: { "type": "agent_start", "model": {...} }
+ *   Server: { "type": "message", "role": "user", "content": [...] }
+ *   Server: { "type": "agent_end" }
+ *
+ *   Client: { "id": "req-2", "type": "get_state" }
+ *   Server: { "id": "req-2", "type": "response", "command": "get_state", "success": true, "data": {...} }
+ *
+ * ============================================================================
+ * MESSAGE CONTENT STRUCTURE
+ * ============================================================================
+ *
+ * Messages contain arrays of content blocks:
+ *
+ * Text Content:
+ *   {
+ *     "type": "text",
+ *     "text": "The actual message text"
+ *   }
+ *
+ * Image Content:
+ *   {
+ *     "type": "image",
+ *     "mimeType": "image/png" | "image/jpeg" | "image/gif" | "image/webp",
+ *     "data": "base64-encoded-image-data"
+ *   }
+ *
+ * Tool Use (in assistant messages):
+ *   {
+ *     "type": "tool_use",
+ *     "id": "tool-use-123",
+ *     "name": "bash",
+ *     "input": { "command": "ls -la" }
+ *   }
+ *
+ * Tool Result (in user messages):
+ *   {
+ *     "type": "tool_result",
+ *     "toolUseId": "tool-use-123",
+ *     "content": [
+ *       { "type": "text", "text": "stdout content" }
+ *     ],
+ *     "isError": false
+ *   }
+ *
+ * ============================================================================
+ * BASED ON PROTOCOL IMPLEMENTATION
+ * ============================================================================
+ *
+ * These type definitions implement the complete RPC protocol for the coding
+ * agent. They ensure type safety on both client and server, support IDE
+ * autocomplete, and serve as documentation of the protocol contract.
+ *
+ * Use RpcCommand and RpcCommand union for sending commands.
+ * Use RpcResponse union for handling responses.
+ * Use RpcExtensionUIRequest/Response for extension dialogs.
  */
 export {};
 //# sourceMappingURL=rpc-types.js.map

package/dist/modes/rpc/rpc-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"rpc-types.js","sourceRoot":"","sources":["../../../src/modes/rpc/rpc-types.ts"],"names":[],"mappings":"AAAA;;;;;GAKG"}
+{"version":3,"file":"rpc-types.js","sourceRoot":"","sources":["../../../src/modes/rpc/rpc-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsWG"}