indusagi-coding-agent 0.1.28 → 0.1.30

package/docs/RPC-GUIDE.md

@@ -1,705 +0,0 @@
-# RPC Mode Complete Guide
-
-Comprehensive documentation for programmatic access via JSON-RPC 2.0 protocol.
-
----
-
-## RPC Authentication & Security
-
-### Authentication Methods
-
-**1. Token-Based Authentication**
-```json
-{
-  "id": "req-1",
-  "method": "prompt",
-  "params": {
-    "message": "What is 2+2?",
-    "token": "your_secret_token_here"
-  }
-}
-```
-
-**Token Generation:**
-```bash
-# Generate secure random token
-openssl rand -hex 32
-# Output: a1f2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
-
-# Store in config
-indusagi config set rpc-token a1f2c3d4e5f6g7h8i9j0k1l2m3n4o5p6
-```
-
-**2. Environment Variable**
-```bash
-export INDUSAGI_RPC_TOKEN="your_secret_token"
-indusagi --mode=rpc
-```
-
-**3. File-Based Token**
-```bash
-# Token stored in ~/.indusagi/rpc-token
-mkdir -p ~/.indusagi
-echo "your_secret_token" > ~/.indusagi/rpc-token
-chmod 600 ~/.indusagi/rpc-token
-```
-
-**4. Header-Based (HTTP)**
-```
-Authorization: Bearer your_secret_token
-```
-
-### Token Best Practices
-
-✅ **Do:**
-- Use 32+ byte tokens (minimum entropy)
-- Rotate tokens every 90 days
-- Store securely in environment/files
-- Log token usage for audit trails
-- Revoke compromised tokens immediately
-
-❌ **Don't:**
-- Commit tokens to version control
-- Use weak/predictable tokens
-- Share tokens via email/Slack
-- Log full tokens (log only hash)
-- Reuse same token across environments
-
-### Security Considerations
-
-**1. Connection Security**
-```javascript
-// Always use Unix sockets for local connections
-const socket = '/var/run/indusagi.sock';
-
-// Always use HTTPS for remote connections
-const url = 'https://agent.example.com:3000';
-
-// Never expose over HTTP publicly
-// ❌ DON'T: indusagi --rpc-port 3000 --rpc-host 0.0.0.0
-// ✅ DO:   indusagi --rpc-socket /var/run/indusagi.sock
-```
-
-**2. Rate Limiting**
-```javascript
-// Implement rate limiting on client side
-class RateLimitedRpcClient {
-  constructor(client, maxRequests = 10, windowMs = 1000) {
-    this.client = client;
-    this.maxRequests = maxRequests;
-    this.windowMs = windowMs;
-    this.requests = [];
-  }
-
-  async send(method, params) {
-    const now = Date.now();
-    this.requests = this.requests.filter(t => now - t < this.windowMs);
-    
-    if (this.requests.length >= this.maxRequests) {
-      throw new Error('Rate limit exceeded');
-    }
-    
-    this.requests.push(now);
-    return this.client.send(method, params);
-  }
-}
-```
-
-**3. Input Validation**
-```javascript
-// Always validate input before sending to RPC
-function validatePrompt(message) {
-  if (!message || typeof message !== 'string') {
-    throw new Error('Message must be a non-empty string');
-  }
-  if (message.length > 100000) {
-    throw new Error('Message exceeds maximum length');
-  }
-  return message;
-}
-
-const message = validatePrompt(userInput);
-await rpcClient.prompt(message);
-```
-
----
-
-## RPC Connection Handling
-
-### Connection Lifecycle
-
-```
-┌──────────────────────────────────────────────────┐
-│           RPC Connection Lifecycle               │
-├──────────────────────────────────────────────────┤
-│                                                  │
-│  1. CONNECTING                                   │
-│     ↓                                            │
-│  2. HANDSHAKE (authenticate, check version)     │
-│     ↓                                            │
-│  3. CONNECTED (ready to send commands)          │
-│     ↓                                            │
-│  4. REQUEST LOOP (send/receive)                 │
-│     ↓                                            │
-│  5. DISCONNECTING                               │
-│     ↓                                            │
-│  6. DISCONNECTED                                │
-│                                                  │
-│  ERROR: Can reconnect and replay pending reqs   │
-│                                                  │
-└──────────────────────────────────────────────────┘
-```
-
-### Reconnection Strategy
-
-**Exponential Backoff:**
-```javascript
-function calculateBackoff(attempt) {
-  const baseDelay = 100; // ms
-  const maxDelay = 30000; // 30 seconds
-  const delay = Math.min(baseDelay * Math.pow(2, attempt), maxDelay);
-  const jitter = Math.random() * delay * 0.1; // ±10% jitter
-  return delay + jitter;
-}
-
-// Attempt sequence:
-// 1st: ~100ms, 2nd: ~200ms, 3rd: ~400ms, 4th: ~800ms, ...
-// Max: 30000ms (30s)
-```
-
-**Implementation:**
-```javascript
-class RobustRpcClient {
-  async connect() {
-    let attempt = 0;
-    const maxAttempts = 10;
-    
-    while (attempt < maxAttempts) {
-      try {
-        await this._doConnect();
-        this.reconnectAttempt = 0; // Reset on success
-        return;
-      } catch (error) {
-        if (attempt < maxAttempts - 1) {
-          const delay = calculateBackoff(attempt);
-          console.log(`Reconnecting in ${delay}ms...`);
-          await new Promise(r => setTimeout(r, delay));
-          attempt++;
-        } else {
-          throw new Error(`Failed to connect after ${maxAttempts} attempts`);
-        }
-      }
-    }
-  }
-}
-```
-
-### Event Subscription
-
-**Subscribing to Events:**
-```json
-{
-  "id": "sub-1",
-  "method": "subscribe",
-  "params": {
-    "events": ["agent_start", "message_start", "message_end", "tool_*"]
-  }
-}
-```
-
-**Response:**
-```json
-{
-  "id": "sub-1",
-  "result": {
-    "subscription_id": "sub-abc-123",
-    "active": true
-  }
-}
-```
-
-**Receiving Events:**
-```json
-{
-  "method": "event",
-  "params": {
-    "subscription_id": "sub-abc-123",
-    "type": "agent_start",
-    "timestamp": 1677000000000
-  }
-}
-```
-
-### Handling Disconnections
-
-```javascript
-class ReconnectingClient {
-  constructor(options) {
-    this.options = options;
-    this.socket = null;
-    this.pendingRequests = new Map();
-    this.isConnected = false;
-  }
-
-  async send(method, params) {
-    // Queue request if not connected
-    if (!this.isConnected) {
-      return new Promise((resolve, reject) => {
-        const requestId = uuid();
-        this.pendingRequests.set(requestId, {
-          method,
-          params,
-          resolve,
-          reject,
-          timestamp: Date.now()
-        });
-        
-        // Timeout after 30 seconds
-        setTimeout(() => {
-          this.pendingRequests.delete(requestId);
-          reject(new Error('Request timeout'));
-        }, 30000);
-      });
-    }
-
-    return this._sendRequest(method, params);
-  }
-
-  async onReconnect() {
-    // Replay pending requests
-    const pending = Array.from(this.pendingRequests.values());
-    this.pendingRequests.clear();
-
-    for (const req of pending) {
-      try {
-        const result = await this._sendRequest(req.method, req.params);
-        req.resolve(result);
-      } catch (error) {
-        req.reject(error);
-      }
-    }
-  }
-
-  onDisconnect() {
-    this.isConnected = false;
-    // Pending requests will be replayed on reconnect
-  }
-}
-```
-
----
-
-## RPC Client Examples
-
-### Node.js Client Implementation
-
-**Complete Example:**
-```javascript
-const net = require('net');
-const { v4: uuid } = require('uuid');
-
-class IndusagiRpcClient {
-  constructor(options = {}) {
-    this.socket = options.socket || '/var/run/indusagi.sock';
-    this.timeout = options.timeout || 30000;
-    this.connection = null;
-    this.requestMap = new Map();
-    this.eventHandlers = new Map();
-  }
-
-  async connect() {
-    return new Promise((resolve, reject) => {
-      this.connection = net.createConnection(this.socket, () => {
-        this.connection.on('data', (data) => this._handleData(data));
-        this.connection.on('error', (err) => this._handleError(err));
-        this.connection.on('close', () => this._handleClose());
-        resolve();
-      });
-      
-      this.connection.on('error', reject);
-      
-      setTimeout(() => {
-        if (!this.connection.connecting) return;
-        reject(new Error('Connection timeout'));
-      }, this.timeout);
-    });
-  }
-
-  async prompt(message, options = {}) {
-    return this._send('prompt', { message, ...options });
-  }
-
-  async setModel(model) {
-    return this._send('model.set', { model });
-  }
-
-  async compact() {
-    return this._send('compact', {});
-  }
-
-  async subscribe(events) {
-    return this._send('subscribe', { events });
-  }
-
-  on(eventType, handler) {
-    if (!this.eventHandlers.has(eventType)) {
-      this.eventHandlers.set(eventType, []);
-    }
-    this.eventHandlers.get(eventType).push(handler);
-  }
-
-  _send(method, params) {
-    return new Promise((resolve, reject) => {
-      const id = uuid();
-      const request = { jsonrpc: '2.0', id, method, params };
-
-      const timeoutId = setTimeout(() => {
-        this.requestMap.delete(id);
-        reject(new Error(`Request timeout: ${method}`));
-      }, this.timeout);
-
-      this.requestMap.set(id, { resolve, reject, timeoutId });
-
-      try {
-        this.connection.write(JSON.stringify(request) + '\n');
-      } catch (error) {
-        this.requestMap.delete(id);
-        clearTimeout(timeoutId);
-        reject(error);
-      }
-    });
-  }
-
-  _handleData(data) {
-    const lines = data.toString().split('\n');
-    for (const line of lines) {
-      if (!line.trim()) continue;
-      try {
-        const msg = JSON.parse(line);
-        if (msg.id && this.requestMap.has(msg.id)) {
-          const { resolve, reject, timeoutId } = this.requestMap.get(msg.id);
-          this.requestMap.delete(msg.id);
-          clearTimeout(timeoutId);
-
-          if (msg.error) {
-            reject(new Error(msg.error.message));
-          } else {
-            resolve(msg.result);
-          }
-        } else if (msg.method === 'event') {
-          this._emitEvent(msg.params);
-        }
-      } catch (error) {
-        console.error('Failed to parse RPC response:', error);
-      }
-    }
-  }
-
-  _emitEvent(event) {
-    const handlers = this.eventHandlers.get(event.type) || [];
-    for (const handler of handlers) {
-      try {
-        handler(event);
-      } catch (error) {
-        console.error('Error in event handler:', error);
-      }
-    }
-  }
-
-  _handleError(error) {
-    console.error('RPC connection error:', error);
-    // Implement reconnection logic
-  }
-
-  _handleClose() {
-    console.log('RPC connection closed');
-    // Clean up pending requests
-    for (const { reject, timeoutId } of this.requestMap.values()) {
-      clearTimeout(timeoutId);
-      reject(new Error('Connection closed'));
-    }
-    this.requestMap.clear();
-  }
-
-  disconnect() {
-    return new Promise((resolve) => {
-      if (this.connection) {
-        this.connection.end(resolve);
-      } else {
-        resolve();
-      }
-    });
-  }
-}
-
-module.exports = IndusagiRpcClient;
-```
-
-### Usage Pattern
-
-```javascript
-const IndusagiRpcClient = require('./rpc-client');
-
-async function main() {
-  const client = new IndusagiRpcClient({
-    socket: '/var/run/indusagi.sock'
-  });
-
-  try {
-    // Connect
-    await client.connect();
-    console.log('Connected to indusagi RPC server');
-
-    // Subscribe to events
-    await client.subscribe(['agent_start', 'message_*', 'tool_*']);
-
-    // Listen for events
-    client.on('agent_start', (event) => {
-      console.log('Agent started:', event);
-    });
-
-    client.on('message_start', (event) => {
-      console.log('Message:', event.content?.slice(0, 50));
-    });
-
-    // Send prompt
-    const result = await client.prompt('What is 2+2?');
-    console.log('Result:', result);
-
-  } finally {
-    await client.disconnect();
-  }
-}
-
-main().catch(console.error);
-```
-
-### Python Client Example
-
-```python
-import socket
-import json
-import uuid
-from typing import Dict, Any, Optional
-
-class IndusagiRpcClient:
-    def __init__(self, socket_path: str = '/var/run/indusagi.sock'):
-        self.socket_path = socket_path
-        self.socket = None
-        self.request_map = {}
-        self.event_handlers = {}
-
-    def connect(self):
-        self.socket = socket.socket(socket.AF_UNIX, socket.SOCK_STREAM)
-        self.socket.connect(self.socket_path)
-
-    def prompt(self, message: str, **options) -> Dict[str, Any]:
-        return self._send('prompt', {'message': message, **options})
-
-    def set_model(self, model: str) -> Dict[str, Any]:
-        return self._send('model.set', {'model': model})
-
-    def compact(self) -> Dict[str, Any]:
-        return self._send('compact', {})
-
-    def _send(self, method: str, params: Dict[str, Any]) -> Dict[str, Any]:
-        request_id = str(uuid.uuid4())
-        request = {
-            'jsonrpc': '2.0',
-            'id': request_id,
-            'method': method,
-            'params': params
-        }
-
-        self.socket.sendall((json.dumps(request) + '\n').encode())
-
-        # Wait for response
-        response_data = b''
-        while True:
-            data = self.socket.recv(4096)
-            if not data:
-                break
-            response_data += data
-            if b'\n' in response_data:
-                break
-
-        response = json.loads(response_data.decode().strip())
-
-        if 'error' in response:
-            raise Exception(response['error']['message'])
-
-        return response.get('result')
-
-    def disconnect(self):
-        if self.socket:
-            self.socket.close()
-
-# Usage
-client = IndusagiRpcClient()
-client.connect()
-result = client.prompt('What is 2+2?')
-print(result)
-client.disconnect()
-```
-
----
-
-## RPC Error Handling
-
-### Common Error Scenarios
-
-**1. Authentication Failure**
-```json
-{
-  "jsonrpc": "2.0",
-  "error": {
-    "code": -32005,
-    "message": "Authentication required",
-    "data": {
-      "expected": "valid token",
-      "received": "missing or invalid"
-    }
-  }
-}
-```
-
-**Handling:**
-```javascript
-try {
-  await client.prompt('test');
-} catch (error) {
-  if (error.code === -32005) {
-    console.log('Auth failed, check RPC_TOKEN');
-    // Re-authenticate or refresh token
-  }
-}
-```
-
-**2. Model Unavailable**
-```json
-{
-  "code": -32003,
-  "message": "Model gpt-4 is unavailable",
-  "data": {
-    "retriable": true,
-    "retry_after": 60
-  }
-}
-```
-
-**Handling:**
-```javascript
-async function promptWithRetry(message, maxAttempts = 3) {
-  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
-    try {
-      return await client.prompt(message);
-    } catch (error) {
-      if (error.code === -32003 && error.data?.retriable) {
-        const delay = error.data.retry_after || (attempt * 10) * 1000;
-        console.log(`Retrying in ${delay}ms...`);
-        await new Promise(r => setTimeout(r, delay));
-      } else {
-        throw error;
-      }
-    }
-  }
-}
-```
-
-**3. Timeout**
-```javascript
-async function promptWithTimeout(message, timeoutMs = 30000) {
-  return Promise.race([
-    client.prompt(message),
-    new Promise((_, reject) => 
-      setTimeout(() => reject(new Error('Timeout')), timeoutMs)
-    )
-  ]);
-}
-```
-
----
-
-## Advanced Patterns
-
-### Pattern: Batch Processing
-
-```javascript
-async function batchProcess(items) {
-  const client = new IndusagiRpcClient();
-  await client.connect();
-
-  const results = [];
-  for (const item of items) {
-    const result = await client.prompt(`Process: ${item}`);
-    results.push(result);
-  }
-
-  await client.disconnect();
-  return results;
-}
-```
-
-### Pattern: Event-Driven Processing
-
-```javascript
-async function processWithEvents() {
-  const client = new IndusagiRpcClient();
-  await client.connect();
-
-  const messages = [];
-  client.on('message_start', (e) => {
-    messages.push({ role: e.role, content: '' });
-  });
-
-  client.on('message_chunk', (e) => {
-    if (messages.length > 0) {
-      messages[messages.length - 1].content += e.chunk;
-    }
-  });
-
-  client.on('message_end', (e) => {
-    console.log('Message complete');
-  });
-
-  await client.prompt('Generate a poem');
-  await client.disconnect();
-
-  return messages;
-}
-```
-
-### Pattern: Session Management
-
-```javascript
-async function persistentSession() {
-  const client = new IndusagiRpcClient();
-  await client.connect();
-
-  // Create session
-  const session = await client.send('session.create', {
-    name: 'my-session',
-    model: 'gpt-4'
-  });
-
-  // Continue in session
-  await client.send('prompt', {
-    message: 'First question',
-    session_id: session.id
-  });
-
-  await client.send('prompt', {
-    message: 'Follow-up',
-    session_id: session.id
-  });
-
-  // Export session
-  const html = await client.send('session.export', {
-    session_id: session.id,
-    format: 'html'
-  });
-
-  fs.writeFileSync('session.html', html);
-  await client.disconnect();
-}
-```