@probelabs/probe 0.6.0-rc100

package/src/agent/acp/README.md

@@ -0,0 +1,347 @@
+# Agent Client Protocol (ACP) Implementation
+
+This directory contains the implementation of the Agent Client Protocol (ACP) for the Probe AI agent. ACP is a standardized protocol for communication between code editors and AI coding agents, developed by Zed Industries.
+
+## Overview
+
+The ACP implementation enables Probe to work as an AI coding agent compatible with ACP-enabled editors like Zed and Neovim. It provides a JSON-RPC 2.0 based communication protocol with rich features including:
+
+- Session management for conversation contexts
+- Tool execution with lifecycle tracking  
+- Streaming responses and notifications
+- Permission system for code modifications
+- Rich content types (text, images, resources)
+
+## Architecture
+
+### Core Components
+
+- **`types.js`** - Protocol constants, types, and utility functions
+- **`connection.js`** - JSON-RPC 2.0 communication over stdio
+- **`server.js`** - Main ACP server implementation with session management
+- **`tools.js`** - Tool integration and execution lifecycle management
+- **`index.js`** - Module exports
+
+### Protocol Flow
+
+1. **Initialization**: Client negotiates protocol version and capabilities
+2. **Session Management**: Create/load conversation contexts  
+3. **Tool Execution**: Execute code search/analysis tools with progress tracking
+4. **AI Interaction**: Process user prompts using ProbeAgent
+5. **Cleanup**: Handle disconnection and resource cleanup
+
+## Usage
+
+### Starting ACP Server
+
+```bash
+# Start as ACP server
+probe agent --acp
+
+# With custom configuration
+probe agent --acp --provider anthropic --path ./src --allow-edit
+```
+
+### Environment Variables
+
+```bash
+ANTHROPIC_API_KEY=your_key_here
+OPENAI_API_KEY=your_key_here  
+GOOGLE_API_KEY=your_key_here
+DEBUG=1  # Enable debug logging
+```
+
+## Protocol Messages
+
+### Initialize Request
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "initialize",
+  "params": {
+    "protocolVersion": "1"
+  },
+  "id": 1
+}
+```
+
+### Initialize Response
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "result": {
+    "protocolVersion": "1",
+    "serverInfo": {
+      "name": "probe-agent-acp",
+      "version": "1.0.0",
+      "description": "Probe AI agent with code search capabilities"
+    },
+    "capabilities": {
+      "tools": [
+        {
+          "name": "search",
+          "description": "Search for code patterns and content",
+          "kind": "search"
+        }
+      ],
+      "sessionManagement": true,
+      "streaming": true,
+      "permissions": false
+    }
+  }
+}
+```
+
+### New Session Request
+
+```json
+{
+  "jsonrpc": "2.0", 
+  "method": "newSession",
+  "params": {
+    "sessionId": "optional-custom-id",
+    "mode": "normal"
+  },
+  "id": 2
+}
+```
+
+### Prompt Request
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "prompt", 
+  "params": {
+    "sessionId": "session-123",
+    "message": "How does authentication work in this codebase?"
+  },
+  "id": 3
+}
+```
+
+### Prompt Response
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 3,
+  "result": {
+    "content": [
+      {
+        "type": "text",
+        "text": "Authentication in this codebase uses JWT tokens..."
+      }
+    ],
+    "sessionId": "session-123",
+    "timestamp": "2025-01-15T10:30:00Z"
+  }
+}
+```
+
+## Tool Integration
+
+### Available Tools
+
+1. **Search Tool** (`search`)
+   - Flexible text search with stemming
+   - Supports regex patterns and elastic search syntax
+   - Parameters: `query`, `path`, `max_results`, `allow_tests`
+
+2. **Query Tool** (`query`) 
+   - AST-based structural pattern matching
+   - Language-aware code structure search
+   - Parameters: `pattern`, `path`, `language`, `max_results`
+
+3. **Extract Tool** (`extract`)
+   - Extract specific code blocks from files
+   - Line-based extraction with context
+   - Parameters: `files`, `context_lines`, `allow_tests`, `format`
+
+### Tool Call Lifecycle
+
+Tools execute with full lifecycle tracking:
+
+1. **Pending** - Tool call queued for execution
+2. **In Progress** - Tool is actively executing  
+3. **Completed** - Tool finished successfully with results
+4. **Failed** - Tool execution failed with error
+
+Progress is communicated via notifications:
+
+```json
+{
+  "jsonrpc": "2.0",
+  "method": "toolCallProgress",
+  "params": {
+    "sessionId": "session-123",
+    "toolCallId": "tool-456", 
+    "status": "completed",
+    "result": "search results here..."
+  }
+}
+```
+
+## Session Management
+
+### Session Types
+
+- **Normal Mode**: Standard AI interaction
+- **Planning Mode**: Strategic planning and design discussions
+
+### Session Features
+
+- Persistent conversation history
+- Tool call tracking and status
+- Session metadata (creation time, last update)
+- Resource cleanup on disconnect
+
+### Session Operations
+
+```javascript
+// Create new session
+await server.handleNewSession({
+  sessionId: 'custom-id',  // optional
+  mode: 'normal'           // optional
+});
+
+// Load existing session  
+await server.handleLoadSession({
+  sessionId: 'existing-id'
+});
+
+// Set session mode
+await server.handleSetSessionMode({
+  sessionId: 'session-id',
+  mode: 'planning'
+});
+```
+
+## Error Handling
+
+The implementation follows JSON-RPC 2.0 error handling:
+
+### Standard Error Codes
+
+- `-32700` Parse Error - Invalid JSON
+- `-32600` Invalid Request - Invalid JSON-RPC format  
+- `-32601` Method Not Found - Unknown method
+- `-32602` Invalid Params - Invalid parameters
+- `-32603` Internal Error - Server error
+
+### Custom Error Codes
+
+- `-32001` Unsupported Protocol Version
+- `-32002` Session Not Found
+- `-32003` Permission Denied  
+- `-32004` Tool Execution Failed
+
+### Error Response Example
+
+```json
+{
+  "jsonrpc": "2.0",
+  "id": 1,
+  "error": {
+    "code": -32602,
+    "message": "Invalid params: sessionId required",
+    "data": {
+      "received": {},
+      "expected": "object with sessionId field"
+    }
+  }
+}
+```
+
+## Testing
+
+The implementation includes comprehensive tests:
+
+- **Unit Tests** - Individual component testing
+- **Integration Tests** - Full protocol flow testing  
+- **Error Handling Tests** - Edge cases and error conditions
+- **Mock Testing** - Isolated testing with mocked dependencies
+
+Run tests:
+
+```bash
+npm test npm/src/agent/acp/
+```
+
+## Development
+
+### Adding New Methods
+
+1. Add method constant to `types.js`
+2. Implement handler in `server.js`
+3. Add to request routing in `handleRequest()`
+4. Write tests for the new method
+
+### Adding New Tools
+
+1. Implement tool in ProbeAgent's tool system
+2. Add tool definition to `ACPToolManager.getToolDefinitions()`
+3. Add execution case in `executeProbeTool()` 
+4. Update capabilities in server
+
+### Debugging
+
+Enable debug mode for detailed logging:
+
+```bash
+DEBUG=1 probe agent --acp
+```
+
+Debug logs include:
+- Message send/receive 
+- Tool execution progress
+- Session lifecycle events
+- Error details and stack traces
+
+## Compatibility
+
+### Protocol Versions
+
+- **ACP v1** - Full support for core protocol features
+- Backwards compatible with future minor versions
+- Forward compatible design for protocol evolution
+
+### Editor Integration
+
+- **Zed** - Native ACP support
+- **Neovim** - Via ACP plugins (CodeCompanion, Avante.nvim)  
+- **VS Code** - Potential future support
+- **Other Editors** - Any editor implementing ACP client
+
+### AI Model Support
+
+- **Anthropic Claude** - Full support (Haiku, Sonnet, Opus)
+- **OpenAI GPT** - Full support (GPT-4, GPT-4 Turbo)
+- **Google Gemini** - Full support (Pro, Ultra)
+- Model selection via `--provider` and `--model` flags
+
+## Migration from MCP
+
+For users migrating from MCP to ACP:
+
+### Similarities
+- Both use JSON-RPC for communication
+- Similar tool execution concepts  
+- Maintain conversation context
+
+### Key Differences  
+- ACP has richer session management
+- Tool lifecycle tracking with status updates
+- More granular permission system
+- Enhanced content types and metadata
+
+### Migration Steps
+1. Update client to use ACP protocol
+2. Change startup flag from `--mcp` to `--acp`
+3. Adapt to new message formats (mostly compatible)
+4. Leverage enhanced session and tool features
+
+The ACP implementation maintains feature parity with MCP while adding enhanced capabilities for modern AI-assisted coding workflows.

package/src/agent/acp/connection.js

@@ -0,0 +1,237 @@
+// ACP Connection - handles JSON-RPC 2.0 communication over stdio
+import { EventEmitter } from 'events';
+import { validateMessage, createResponse, createError, ErrorCode } from './types.js';
+
+/**
+ * ACP Connection class for handling bidirectional JSON-RPC communication
+ */
+export class ACPConnection extends EventEmitter {
+  constructor(inputStream = process.stdin, outputStream = process.stdout) {
+    super();
+    
+    this.inputStream = inputStream;
+    this.outputStream = outputStream;
+    this.buffer = '';
+    this.messageId = 1;
+    this.pendingRequests = new Map();
+    this.isConnected = false;
+    this.debug = process.env.DEBUG === '1';
+    
+    this.setupStreams();
+  }
+  
+  /**
+   * Setup input/output streams
+   */
+  setupStreams() {
+    this.inputStream.setEncoding('utf8');
+    this.inputStream.on('data', this.handleData.bind(this));
+    this.inputStream.on('end', () => {
+      this.isConnected = false;
+      this.emit('disconnect');
+    });
+    
+    this.inputStream.on('error', (error) => {
+      if (this.debug) {
+        console.error('[ACP] Input stream error:', error);
+      }
+      this.emit('error', error);
+    });
+    
+    this.outputStream.on('error', (error) => {
+      if (this.debug) {
+        console.error('[ACP] Output stream error:', error);
+      }
+      this.emit('error', error);
+    });
+  }
+  
+  /**
+   * Start the connection
+   */
+  start() {
+    this.isConnected = true;
+    this.emit('connect');
+    
+    if (this.debug) {
+      console.error('[ACP] Connection started');
+    }
+  }
+  
+  /**
+   * Handle incoming data
+   */
+  handleData(chunk) {
+    this.buffer += chunk;
+    
+    // Process complete messages (separated by newlines)
+    const lines = this.buffer.split('\n');
+    this.buffer = lines.pop() || ''; // Keep incomplete line in buffer
+    
+    for (const line of lines) {
+      if (line.trim()) {
+        try {
+          const message = JSON.parse(line);
+          this.handleMessage(message);
+        } catch (error) {
+          if (this.debug) {
+            console.error('[ACP] Failed to parse message:', line, error);
+          }
+          this.sendError(null, ErrorCode.PARSE_ERROR, 'Parse error');
+        }
+      }
+    }
+  }
+  
+  /**
+   * Handle a parsed JSON-RPC message
+   */
+  handleMessage(message) {
+    const validation = validateMessage(message);
+    if (!validation.valid) {
+      if (this.debug) {
+        console.error('[ACP] Invalid message:', validation.error, message);
+      }
+      this.sendError(message.id || null, ErrorCode.INVALID_REQUEST, validation.error);
+      return;
+    }
+    
+    if (this.debug) {
+      console.error('[ACP] Received message:', JSON.stringify(message));
+    }
+    
+    // Handle response to our request
+    if (message.id && (message.result !== undefined || message.error !== undefined)) {
+      this.handleResponse(message);
+      return;
+    }
+    
+    // Handle request or notification
+    if (message.method) {
+      if (message.id !== undefined) {
+        // Request - needs response
+        this.emit('request', message);
+      } else {
+        // Notification - no response needed
+        this.emit('notification', message);
+      }
+    }
+  }
+  
+  /**
+   * Handle response to our request
+   */
+  handleResponse(message) {
+    const { id, result, error } = message;
+    const pendingRequest = this.pendingRequests.get(id);
+    
+    if (pendingRequest) {
+      this.pendingRequests.delete(id);
+      
+      if (error) {
+        pendingRequest.reject(new Error(`RPC Error ${error.code}: ${error.message}`));
+      } else {
+        pendingRequest.resolve(result);
+      }
+    } else if (this.debug) {
+      console.error('[ACP] Received response for unknown request ID:', id);
+    }
+  }
+  
+  /**
+   * Send a message
+   */
+  sendMessage(message) {
+    if (!this.isConnected) {
+      throw new Error('Connection not established');
+    }
+    
+    const json = JSON.stringify(message);
+    
+    if (this.debug) {
+      console.error('[ACP] Sending message:', json);
+    }
+    
+    this.outputStream.write(json + '\n');
+  }
+  
+  /**
+   * Send a request and wait for response
+   */
+  async sendRequest(method, params = null) {
+    const id = this.messageId++;
+    const message = {
+      jsonrpc: '2.0',
+      method,
+      id
+    };
+    
+    if (params !== null) {
+      message.params = params;
+    }
+    
+    return new Promise((resolve, reject) => {
+      // Store the pending request
+      this.pendingRequests.set(id, { resolve, reject });
+      
+      // Send the message
+      this.sendMessage(message);
+      
+      // Set timeout
+      setTimeout(() => {
+        if (this.pendingRequests.has(id)) {
+          this.pendingRequests.delete(id);
+          reject(new Error('Request timeout'));
+        }
+      }, 30000); // 30 second timeout
+    });
+  }
+  
+  /**
+   * Send a notification (no response expected)
+   */
+  sendNotification(method, params = null) {
+    const message = {
+      jsonrpc: '2.0',
+      method
+    };
+    
+    if (params !== null) {
+      message.params = params;
+    }
+    
+    this.sendMessage(message);
+  }
+  
+  /**
+   * Send a response to a request
+   */
+  sendResponse(id, result) {
+    const response = createResponse(id, result);
+    this.sendMessage(response);
+  }
+  
+  /**
+   * Send an error response
+   */
+  sendError(id, code, message, data = null) {
+    const error = createError(code, message, data);
+    const response = createResponse(id, null, error);
+    this.sendMessage(response);
+  }
+  
+  /**
+   * Close the connection
+   */
+  close() {
+    this.isConnected = false;
+    
+    // Reject all pending requests
+    for (const [id, pendingRequest] of this.pendingRequests) {
+      pendingRequest.reject(new Error('Connection closed'));
+    }
+    this.pendingRequests.clear();
+    
+    this.emit('disconnect');
+  }
+}