acpreact 1.0.6 → 1.0.8

package/README.md

@@ -1,15 +1,25 @@
 # acpreact - ACP SDK
 
-A lightweight SDK for setting up tools and managing ACP protocol communication. Allows opencode and kilo CLI to call registered tools via the ACP protocol.
+A lightweight SDK for registering tools and running them via kilo CLI or opencode. Allows kilo and opencode to call registered tools via a custom JSON-RPC 2.0 protocol injected into the prompt.
 
 ## Features
 
 - **ACPProtocol**: Core ACP protocol implementation with JSON-RPC 2.0 support
 - **Tool Registration**: Register custom tools with descriptions and input schemas
 - **Tool Whitelist**: Built-in security model for controlling tool access
-- **Tool Execution**: Execute whitelisted tools with validation
+- **Tool Execution**: Execute whitelisted tools with validation and logging
+- **CLI Integration**: Works with kilo CLI and opencode via `process()` method
 - **ES Module**: Pure ES modules, no build step required
 
+## Prerequisites
+
+Install kilo CLI and/or opencode before using `process()`:
+
+```bash
+npm install -g @kilocode/cli    # for kilo
+npm install -g opencode-ai      # for opencode
+```
+
 ## Installation
 
 ```bash
@@ -18,52 +28,46 @@ npm install acpreact
 
 ## Quick Start
 
-### Creating an ACP Server with Custom Tools
+### Register Tools and Process with kilo CLI
 
 ```javascript
 import { ACPProtocol } from 'acpreact';
 
-const acp = new ACPProtocol();
+const acp = new ACPProtocol('You are a calculator assistant. Use the add tool when asked to add numbers.');
 
-// Register a custom tool
 acp.registerTool(
-  'weather',
-  'Get weather information for a location',
+  'add',
+  'Add two numbers together',
   {
     type: 'object',
     properties: {
-      location: { type: 'string', description: 'City name' }
+      a: { type: 'number', description: 'First number' },
+      b: { type: 'number', description: 'Second number' }
     },
-    required: ['location']
+    required: ['a', 'b']
   },
-  async (params) => {
-    return {
-      location: params.location,
-      temperature: 72,
-      condition: 'sunny'
-    };
-  }
+  async (params) => ({ sum: params.a + params.b })
 );
 
-// Initialize protocol response
-const response = acp.createInitializeResponse();
+const result = await acp.process('What is 15 + 27? Use the add tool.', { cli: 'kilo' });
+console.log(result.text);          // human-readable text response
+console.log(result.toolCalls);     // [{ tool: 'add', result: { sum: 42 } }]
+console.log(result.logs);          // tool call audit log
+```
+
+### Using opencode
 
-// Execute tool
-const result = await acp.callTool('weather', { location: 'San Francisco' });
-console.log(result);
+```javascript
+const result = await acp.process('What is 15 + 27? Use the add tool.', { cli: 'opencode' });
 ```
 
 ### Using System Instructions
 
-Pass a system instruction to the ACPProtocol constructor. The instruction will be included in the initialization response and communicated to opencode or kilo CLI:
-
 ```javascript
 import { ACPProtocol } from 'acpreact';
 
-const instruction = 'You are a helpful weather assistant. Always provide temperature in Fahrenheit.';
-const acp = new ACPProtocol(instruction);
+const acp = new ACPProtocol('You are a helpful weather assistant. Always provide temperature in Fahrenheit.');
 
-// Register tools as usual
 acp.registerTool(
   'weather',
   'Get weather information for a location',
@@ -74,85 +78,96 @@ acp.registerTool(
     },
     required: ['location']
   },
-  async (params) => {
-    return {
-      location: params.location,
-      temperature: 72,
-      condition: 'sunny'
-    };
-  }
+  async (params) => ({
+    location: params.location,
+    temperature: 72,
+    condition: 'sunny'
+  })
 );
 
-// The instruction is included in the initialization response
-const response = acp.createInitializeResponse();
-console.log(response.result.instruction);
-// Output: "You are a helpful weather assistant. Always provide temperature in Fahrenheit."
+const result = await acp.process('What is the weather in San Francisco?', { cli: 'kilo' });
+console.log(result.text);       // text response (tool call JSON filtered out)
+console.log(result.toolCalls);  // [{ tool: 'weather', result: { location: 'San Francisco', ... } }]
 ```
 
 ## API
 
 ### ACPProtocol
 
-Main class for setting up ACP protocol communication.
+Main class for ACP protocol communication.
 
 **Constructor:**
 
-- `new ACPProtocol(instruction)`: Initialize the protocol
-  - `instruction` (optional): String - system instruction to communicate to opencode or kilo CLI
+- `new ACPProtocol(instruction?)`: Initialize the protocol
+  - `instruction` (optional): String - system instruction prepended to every prompt sent to the CLI
 
 **Methods:**
 
 - `registerTool(name, description, inputSchema, handler)`: Register a custom tool
   - `name`: String - tool identifier
-  - `description`: String - tool description
+  - `description`: String - tool description shown to the model
   - `inputSchema`: Object - JSON Schema for tool inputs
   - `handler`: Async function - receives params object, returns result
   - Returns: Tool definition object
 
-- `createInitializeResponse()`: Generate protocol initialization response
+- `async process(text, options?)`: Send a prompt to kilo or opencode and execute any tool calls
+  - `text`: String - the user prompt
+  - `options.cli`: `'kilo'` (default) or `'opencode'`
+  - `options.model`: String - model in `provider/model` format (uses CLI default if omitted)
+  - Returns: `{ text, rawOutput, toolCalls, logs }` or `{ text, rawOutput, error, logs }` on parse failure
+
+- `createInitializeResponse()`: Generate ACP protocol initialization response with registered tools
+
+- `createJsonRpcRequest(method, params)`: Create JSON-RPC 2.0 request object
 
-- `createJsonRpcRequest(method, params)`: Create JSON-RPC request object
+- `createJsonRpcResponse(id, result)`: Create JSON-RPC 2.0 response object
 
-- `createJsonRpcResponse(id, result)`: Create JSON-RPC response object
+- `createJsonRpcError(id, error)`: Create JSON-RPC 2.0 error object (accepts Error or string)
 
-- `createJsonRpcError(id, error)`: Create JSON-RPC error object
+- `validateToolCall(toolName)`: Check if tool is whitelisted, returns `{ allowed, error? }`
 
-- `validateToolCall(toolName)`: Check if tool is whitelisted
+- `async callTool(toolName, params)`: Execute a registered tool directly
 
-- `async callTool(toolName, params)`: Execute a registered tool
+- `parseTextOutput(output)`: Parse human-readable text from CLI JSON output (filters tool call JSON)
+
+- `parseToolCalls(output)`: Parse JSON-RPC tool calls from CLI output, deduplicated by id+method
 
 **Properties:**
 
-- `instruction`: String (optional) - system instruction communicated to opencode or kilo CLI
+- `instruction`: String (optional) - system instruction prepended to prompts
 - `toolWhitelist`: Set of registered tool names
-- `toolCallLog`: Array of executed tool calls with timestamps
-- `rejectedCallLog`: Array of rejected tool attempts
+- `toolCallLog`: Array of executed tool calls with timestamps and results
+- `rejectedCallLog`: Array of rejected tool attempts with reasons
+
+## How It Works
+
+`process()` injects the registered tool list and JSON-RPC call format into the prompt, invokes the CLI, and parses any JSON-RPC tool calls from the output. Matched tool calls are executed locally and their results returned.
+
+The model outputs tool calls as JSON-RPC lines:
+```
+{"jsonrpc":"2.0","id":1,"method":"tools/add","params":{"a":15,"b":27}}
+```
+
+These are parsed, executed, and returned in `result.toolCalls`. The `text` field contains only human-readable model output with tool call JSON filtered out.
 
 ## Example: Multiple Tools
 
 ```javascript
 import { ACPProtocol } from 'acpreact';
 
-const acp = new ACPProtocol();
+const acp = new ACPProtocol('You are a data assistant.');
 
-// Register database tool
 acp.registerTool(
   'query_database',
   'Query the application database',
   {
     type: 'object',
-    properties: {
-      query: { type: 'string' }
-    },
+    properties: { query: { type: 'string' } },
     required: ['query']
   },
-  async (params) => {
-    // Your database logic here
-    return { data: [] };
-  }
+  async (params) => ({ data: [] })
 );
 
-// Register API tool
 acp.registerTool(
   'call_api',
   'Call an external API',
@@ -164,15 +179,12 @@ acp.registerTool(
     },
     required: ['endpoint', 'method']
   },
-  async (params) => {
-    // Your API logic here
-    return { response: {} };
-  }
+  async (params) => ({ response: {} })
 );
 
-// Initialize and use
 const initResponse = acp.createInitializeResponse();
-console.log(initResponse.result.agentCapabilities);
+console.log(initResponse.result.tools.length); // 2
+console.log(initResponse.result.agentCapabilities); // { toolCalling: true, streaming: false }
 ```
 
 ## License

package/core.js

@@ -1,5 +1,6 @@
 import { spawn } from 'child_process';
 import { EventEmitter } from 'events';
+import { parseTextOutput, parseToolCalls } from './parser.js';
 
 class ACPProtocol extends EventEmitter {
   constructor(instruction) {
@@ -12,25 +13,12 @@ class ACPProtocol extends EventEmitter {
     this.toolCallLog = [];
     this.rejectedCallLog = [];
     this.tools = {};
-    this.cliProcess = null;
-    this.pendingRequests = new Map();
-    this.buffer = '';
-    this.initialized = false;
-    this.sessionId = null;
   }
 
   generateRequestId() {
     return ++this.messageId;
   }
 
-  createJsonRpcResponse(id, result) {
-    return { jsonrpc: "2.0", id, result };
-  }
-
-  createJsonRpcError(id, error) {
-    return { jsonrpc: "2.0", id, error: { code: -32603, message: error } };
-  }
-
   registerTool(name, description, inputSchema, handler) {
     this.toolWhitelist.add(name);
     this.tools[name] = handler;
@@ -40,252 +28,150 @@ class ACPProtocol extends EventEmitter {
   }
 
   getToolsList() {
-    return Array.from(this.toolWhitelist).map(toolName => ({
-      name: toolName,
-      description: this.toolDescriptions[toolName],
-      inputSchema: this.toolSchemas[toolName],
+    return Array.from(this.toolWhitelist).map(name => ({
+      name,
+      description: this.toolDescriptions[name],
+      inputSchema: this.toolSchemas[name],
     }));
   }
 
   getToolsPrompt() {
     const tools = this.getToolsList();
     if (tools.length === 0) return '';
-    
-    let prompt = '\n\nYou have access to the following tools. You MUST use these tools to respond:\n\n';
+    let prompt = '\n\nYou have access to the following tools. You MUST use these tools to interact:\n\n';
     for (const tool of tools) {
       prompt += `## Tool: ${tool.name}\n${tool.description}\n`;
       prompt += `Parameters: ${JSON.stringify(tool.inputSchema, null, 2)}\n`;
-      prompt += `To call this tool, output a JSON-RPC request like:\n`;
-      prompt += `{"jsonrpc":"2.0","id":<unique_id>,"method":"tools/${tool.name}","params":{<parameters>}}\n\n`;
+      prompt += `To call this tool, output a JSON-RPC request on a single line:\n`;
+      prompt += `{"jsonrpc":"2.0","id":<number>,"method":"tools/${tool.name}","params":{<parameters>}}\n\n`;
     }
-    prompt += 'IMPORTANT: Always respond by calling a tool with a JSON-RPC request. Do not just output text.\n';
+    prompt += 'IMPORTANT: When you need to use a tool, output ONLY the JSON-RPC request, nothing else.\n';
     return prompt;
   }
 
+  createInitializeResponse() {
+    return {
+      jsonrpc: '2.0',
+      id: 1,
+      result: {
+        tools: this.getToolsList(),
+        instruction: this.instruction,
+        agentCapabilities: { toolCalling: true, streaming: false },
+      },
+    };
+  }
+
+  createJsonRpcRequest(method, params) {
+    return { jsonrpc: '2.0', id: this.generateRequestId(), method, params };
+  }
+
+  createJsonRpcResponse(id, result) {
+    return { jsonrpc: '2.0', id, result };
+  }
+
+  createJsonRpcError(id, error) {
+    return {
+      jsonrpc: '2.0',
+      id,
+      error: {
+        code: error?.code ?? -32000,
+        message: error instanceof Error ? error.message : String(error),
+      },
+    };
+  }
+
   validateToolCall(toolName) {
     if (!this.toolWhitelist.has(toolName)) {
       const availableTools = Array.from(this.toolWhitelist);
-      const error = `Tool not available. Available: ${availableTools.join(', ')}`;
       this.rejectedCallLog.push({
         timestamp: new Date().toISOString(),
         attemptedTool: toolName,
         reason: 'Not in whitelist',
         availableTools,
       });
-      return { allowed: false, error };
+      return { allowed: false, error: `Tool not available. Available: ${availableTools.join(', ')}` };
     }
     return { allowed: true };
   }
 
   async callTool(toolName, params) {
     const validation = this.validateToolCall(toolName);
-    if (!validation.allowed) {
-      throw new Error(validation.error);
-    }
-
-    this.toolCallLog.push({
-      timestamp: new Date().toISOString(),
-      toolName,
-      params,
-      status: 'executing',
-    });
-
-    if (this.tools[toolName]) {
-      const result = await this.tools[toolName](params);
-      const lastLog = this.toolCallLog[this.toolCallLog.length - 1];
-      lastLog.status = 'completed';
-      lastLog.result = result;
-      return result;
-    }
-    throw new Error(`Unknown tool: ${toolName}`);
-  }
-
-  async start(cli = 'kilo') {
-    if (this.cliProcess) return this.sessionId;
-
-    return new Promise((resolve, reject) => {
-      this.cliProcess = spawn('script', ['-q', '-c', `${cli} acp`, '/dev/null'], {
-        stdio: ['pipe', 'pipe', 'pipe'],
-        cwd: process.cwd(),
-        env: { ...process.env, TERM: 'dumb' },
-      });
-
-      this.cliProcess.stdout.on('data', (data) => {
-        this.buffer += data.toString();
-        this.processBuffer();
-      });
-
-      this.cliProcess.stderr.on('data', (data) => {
-        this.emit('stderr', data.toString());
-      });
-
-      this.cliProcess.on('error', (error) => {
-        this.emit('error', error);
-        reject(error);
-      });
-
-      this.cliProcess.on('close', (code) => {
-        this.emit('close', code);
-        this.cliProcess = null;
-        this.initialized = false;
-        this.sessionId = null;
-      });
-
-      const timeout = setTimeout(() => {
-        reject(new Error('ACP initialization timeout'));
-      }, 30000);
+    if (!validation.allowed) throw new Error(validation.error);
 
-      this.once('ready', () => {
-        clearTimeout(timeout);
-        resolve(this.sessionId);
-      });
+    const entry = { timestamp: new Date().toISOString(), toolName, params, status: 'executing' };
+    this.toolCallLog.push(entry);
 
-      setTimeout(() => this.createSession(), 500);
-    });
+    if (!this.tools[toolName]) throw new Error(`Unknown tool: ${toolName}`);
+    const result = await this.tools[toolName](params);
+    entry.status = 'completed';
+    entry.result = result;
+    return result;
   }
 
-  processBuffer() {
-    const lines = this.buffer.split('\n');
-    this.buffer = lines.pop() || '';
-
-    for (const line of lines) {
-      const trimmed = line.trim();
-      if (!trimmed) continue;
-      this.handleMessage(trimmed);
-    }
+  parseTextOutput(output) {
+    return parseTextOutput(output);
   }
 
-  handleMessage(line) {
-    let msg;
-    try {
-      msg = JSON.parse(line);
-    } catch {
-      return;
-    }
-
-    if (msg.method === 'initialize') {
-      this.send(this.createInitializeResponse(msg.id));
-      this.initialized = true;
-    } else if (msg.id !== undefined && msg.result !== undefined) {
-      const resolver = this.pendingRequests.get(msg.id);
-      if (resolver) {
-        this.pendingRequests.delete(msg.id);
-        resolver(msg.result);
-      }
-      if (msg.id === 1 && msg.result?.sessionId) {
-        this.sessionId = msg.result.sessionId;
-        this.emit('ready');
-      }
-    } else if (msg.id !== undefined && msg.error !== undefined) {
-      const resolver = this.pendingRequests.get(msg.id);
-      if (resolver) {
-        this.pendingRequests.delete(msg.id);
-        resolver({ error: msg.error });
-      }
-    } else if (msg.method?.startsWith('tools/')) {
-      const toolName = msg.method.replace('tools/', '');
-      this.handleToolCall(msg.id, toolName, msg.params);
-    } else if (msg.method === 'session/update') {
-      this.emit('update', msg.params);
-    }
+  parseToolCalls(output) {
+    return parseToolCalls(output);
   }
 
-  async handleToolCall(id, toolName, params) {
-    try {
-      const result = await this.callTool(toolName, params);
-      this.send(this.createJsonRpcResponse(id, result));
-    } catch (e) {
-      this.send(this.createJsonRpcError(id, e.message));
-    }
-  }
+  async process(text, options = {}) {
+    const cli = options.cli || 'kilo';
+    const model = options.model;
+    const fullPrompt = this.instruction
+      ? `${this.instruction}${this.getToolsPrompt()}\n\n---\n\n${text}`
+      : `${this.getToolsPrompt()}\n\n---\n\n${text}`;
 
-  send(msg) {
-    if (this.cliProcess && this.cliProcess.stdin.writable) {
-      this.cliProcess.stdin.write(JSON.stringify(msg) + '\n');
-    }
-  }
+    const args = ['run', '--format', 'json'];
+    if (cli === 'kilo') args.push('--auto');
+    if (model) args.push('--model', model);
+    args.push(fullPrompt);
 
-  createInitializeResponse(id) {
-    return {
-      jsonrpc: "2.0",
-      id,
-      result: {
-        protocolVersion: 1,
-        capabilities: { tools: this.getToolsList() },
-        serverInfo: { name: 'acpreact', version: '1.0.0' },
-        instruction: this.instruction,
-      }
-    };
-  }
+    return new Promise((resolve, reject) => {
+      let output = '';
+      let errorOutput = '';
 
-  createSession() {
-    this.send({
-      jsonrpc: "2.0",
-      id: 1,
-      method: "session/new",
-      params: {
+      const child = spawn(cli, args, {
+        stdio: ['pipe', 'pipe', 'pipe'],
         cwd: process.cwd(),
-        mcpServers: [],
-      },
-    });
-  }
+        env: { ...process.env },
+      });
 
-  async sendPrompt(content) {
-    if (!this.sessionId) {
-      throw new Error('No session. Call start() first.');
-    }
+      child.stdin.end();
+      child.stdout.on('data', (data) => { output += data.toString(); });
+      child.stderr.on('data', (data) => { errorOutput += data.toString(); });
 
-    const reqId = this.generateRequestId();
-    const fullPrompt = this.instruction 
-      ? `${this.instruction}${this.getToolsPrompt()}\n\n---\n\n${content}`
-      : `${this.getToolsPrompt()}\n\n---\n\n${content}`;
+      child.on('close', async (code) => {
+        if (code !== 0 && code !== null && !output) {
+          reject(new Error(`CLI exited with code ${code}: ${errorOutput}`));
+          return;
+        }
+        try {
+          const toolCalls = parseToolCalls(output);
+          const results = [];
+          for (const call of toolCalls) {
+            const toolName = call.method.replace('tools/', '');
+            if (this.toolWhitelist.has(toolName)) {
+              const result = await this.callTool(toolName, call.params);
+              results.push({ tool: toolName, result });
+            }
+          }
+          resolve({ text: parseTextOutput(output), rawOutput: output, toolCalls: results, logs: this.toolCallLog });
+        } catch (e) {
+          resolve({ text: parseTextOutput(output), rawOutput: output, error: e.message, logs: this.toolCallLog });
+        }
+      });
 
-    return new Promise((resolve) => {
-      this.pendingRequests.set(reqId, resolve);
-      this.send({
-        jsonrpc: "2.0",
-        id: reqId,
-        method: "session/prompt",
-        params: {
-          sessionId: this.sessionId,
-          prompt: [{ type: "text", text: fullPrompt }],
-        },
+      child.on('error', (error) => {
+        reject(new Error(`Failed to spawn ${cli}: ${error.message}`));
       });
 
-      setTimeout(() => {
-        if (this.pendingRequests.has(reqId)) {
-          this.pendingRequests.delete(reqId);
-          resolve({ timeout: true });
-        }
-      }, 120000);
+      setTimeout(() => { child.kill(); reject(new Error('Timeout')); }, 120000);
     });
   }
 
-  async process(text, options = {}) {
-    const cli = options.cli || 'kilo';
-
-    if (!this.cliProcess) {
-      await this.start(cli);
-    }
-
-    const result = await this.sendPrompt(text);
-
-    return {
-      text,
-      result,
-      toolCalls: this.toolCallLog.slice(-10),
-      logs: this.toolCallLog,
-    };
-  }
-
-  stop() {
-    if (this.cliProcess) {
-      this.cliProcess.kill();
-      this.cliProcess = null;
-    }
-    this.initialized = false;
-    this.sessionId = null;
-  }
+  stop() {}
 }
 
 export { ACPProtocol };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acpreact",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "type": "module",
   "main": "index.js",
   "description": "ACP SDK for monitoring and reacting to chat conversations",

package/parser.js

@@ -0,0 +1,58 @@
+function parseTextOutput(output) {
+  let text = '';
+  for (const line of output.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const json = JSON.parse(trimmed);
+      if (json.type === 'text' && json.part?.text) {
+        const partText = json.part.text;
+        try {
+          const inner = JSON.parse(partText.trim());
+          if (inner.jsonrpc === '2.0' && inner.method?.startsWith('tools/')) continue;
+        } catch {}
+        text += partText;
+      }
+    } catch {}
+  }
+  return text;
+}
+
+function parseToolCalls(output) {
+  const seen = new Set();
+  const calls = [];
+
+  const tryAdd = (candidate) => {
+    const trimmed = candidate.trim();
+    if (!trimmed) return;
+    try {
+      const json = JSON.parse(trimmed);
+      if (json.jsonrpc === '2.0' && json.method?.startsWith('tools/') && json.params) {
+        const key = `${json.id}:${json.method}`;
+        if (!seen.has(key)) {
+          seen.add(key);
+          calls.push({ id: json.id, method: json.method, params: json.params });
+        }
+      }
+    } catch {}
+  };
+
+  for (const line of output.split('\n')) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    try {
+      const json = JSON.parse(trimmed);
+      if (json.type === 'text' && json.part?.text) {
+        for (const inner of json.part.text.split('\n')) tryAdd(inner);
+      } else {
+        tryAdd(trimmed);
+      }
+    } catch {
+      tryAdd(trimmed);
+    }
+  }
+
+  return calls;
+}
+
+export { parseTextOutput, parseToolCalls };