acpreact 1.0.7 → 1.1.1

package/README.md

@@ -1,15 +1,27 @@
 # 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, opencode, or gemini. Supports multi-service fallback with automatic rate-limit detection, per-provider cooldowns, and transparent failover across a service stack.
 
 ## 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, opencode, and gemini via `process()` method
+- **Multi-Service Fallback**: Automatically falls back through a service stack on rate limits
+- **Rate-Limit Detection**: Detects 429, quota errors, and RESOURCE_EXHAUSTED per provider
 - **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 +30,116 @@ 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
+### Multi-Service Fallback
 
-Pass a system instruction to the ACPProtocol constructor. The instruction will be included in the initialization response and communicated to opencode or kilo CLI:
+Pass a `services` array to the constructor to enable automatic fallback across providers. On rate limits, the engine marks the current service unavailable and continues to the next:
 
 ```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 calculator.', [
+  { cli: 'kilo' },
+  { cli: 'opencode' },
+  { cli: 'gemini' },
+]);
+
+acp.registerTool('add', 'Add two numbers', { type: 'object', properties: { a: { type: 'number' }, b: { type: 'number' } }, required: ['a', 'b'] }, async ({ a, b }) => ({ sum: a + b }));
+
+const result = await acp.process('What is 15 + 27? Use the add tool.');
+```
+
+Override services per call:
+
+```javascript
+const result = await acp.process('prompt', {
+  services: [{ cli: 'opencode' }, { cli: 'kilo' }],
+});
+```
+
+Multiple profiles per provider (useful for separate API key accounts):
+
+```javascript
+const acp = new ACPProtocol('instruction', [
+  { cli: 'kilo', profile: 'account-a' },
+  { cli: 'kilo', profile: 'account-b' },
+  { cli: 'opencode' },
+]);
+```
+
+### createServiceStack
+
+Build a typed service stack for use with `FallbackEngine` directly:
+
+```javascript
+import { createServiceStack, FallbackEngine } from 'acpreact';
+
+const stack = createServiceStack([
+  { cli: 'kilo', profile: 'work' },
+  { cli: 'opencode' },
+  { cli: 'gemini' },
+]);
+
+const engine = new FallbackEngine(stack);
+```
+
+### Fallback Events
+
+`ACPProtocol` (and `FallbackEngine`) emit events during fallback:
+
+```javascript
+acp.on('rate-limited', ({ name, profileId, cooldownMs }) => {
+  console.log(`${name}(${profileId}) rate-limited for ${cooldownMs}ms`);
+});
+
+acp.on('fallback', ({ from, to }) => {
+  console.log(`Falling back from ${from.name} to ${to.name}`);
+});
+
+acp.on('success', ({ name, profileId, attempted }) => {
+  console.log(`Succeeded on ${name}(${profileId}) after ${attempted} attempt(s)`);
+});
+```
+
+### Using System Instructions
+
+```javascript
+import { ACPProtocol } from 'acpreact';
+
+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 +150,100 @@ 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?, services?)`: Initialize the protocol
+  - `instruction` (optional): String - system instruction prepended to every prompt sent to the CLI
+  - `services` (optional): Array of `{ cli, profile?, model? }` - instance-level default service stack for multi-service fallback
 
 **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 a CLI and execute any tool calls
+  - `text`: String - the user prompt
+  - `options.cli`: `'kilo'` (default), `'opencode'`, or `'gemini'` — used when `options.services` not set
+  - `options.services`: Array of `{ cli, profile?, model? }` — enables multi-service fallback for this call; takes precedence over `options.cli`
+  - `options.model`: String - model in `provider/model` format (uses CLI default if omitted)
+  - `options.timeout`: Number - per-attempt timeout in ms (default 120000)
+  - Returns: `{ text, rawOutput, toolCalls, logs }` or `{ text, rawOutput, error, logs }` on parse failure
+  - Throws `AggregateError` when all services in the stack are exhausted
+
+- `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 +255,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,8 +1,44 @@
 import { spawn } from 'child_process';
 import { EventEmitter } from 'events';
+import { parseTextOutput, parseToolCalls } from './parser.js';
+import { ServiceRegistry, createServiceStack, buildArgs } from './services.js';
+import { FallbackEngine } from './fallback.js';
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+function attachOutputs(err, output, errorOutput) {
+  err.output = output;
+  err.stderr = errorOutput;
+  return err;
+}
+
+function spawnService(entry, prompt, options, callbacks) {
+  return new Promise((resolve, reject) => {
+    const binary = entry.config?.binary || entry.name;
+    const args = entry.config?.buildArgs
+      ? entry.config.buildArgs(prompt, options)
+      : buildArgs(entry.name, prompt, options);
+    let output = '', errorOutput = '';
+    const child = spawn(binary, args, { stdio: ['pipe', 'pipe', 'pipe'], cwd: process.cwd(), env: { ...process.env } });
+    child.stdin.end();
+    child.stdout.on('data', (d) => { const c = d.toString(); output += c; callbacks?.onOutput?.(c); });
+    child.stderr.on('data', (d) => { const c = d.toString(); errorOutput += c; callbacks?.onStderr?.(c); });
+    const timer = setTimeout(() => {
+      child.kill();
+      reject(attachOutputs(new Error(`Timeout after ${DEFAULT_TIMEOUT_MS}ms`), output, errorOutput));
+    }, options?.timeout ?? DEFAULT_TIMEOUT_MS);
+    child.on('close', (code) => {
+      clearTimeout(timer);
+      if (code !== 0 && code !== null && !output)
+        return reject(attachOutputs(new Error(`${binary} exited with code ${code}: ${errorOutput}`), output, errorOutput));
+      resolve({ rawOutput: output, stderr: errorOutput, code });
+    });
+    child.on('error', (err) => { clearTimeout(timer); reject(attachOutputs(err, output, errorOutput)); });
+  });
+}
 
 class ACPProtocol extends EventEmitter {
-  constructor(instruction) {
+  constructor(instruction, services) {
     super();
     this.messageId = 0;
     this.instruction = instruction;
@@ -12,11 +48,19 @@ class ACPProtocol extends EventEmitter {
     this.toolCallLog = [];
     this.rejectedCallLog = [];
     this.tools = {};
+    this.registry = new ServiceRegistry();
+    if (services) {
+      for (const svc of services) {
+        this.registry.registerService(svc.cli || svc.name, svc);
+      }
+    }
+    this.fallback = new FallbackEngine([]);
+    this.fallback.on('rate-limited', (e) => this.emit('rate-limited', e));
+    this.fallback.on('fallback', (e) => this.emit('fallback', e));
+    this.fallback.on('success', (e) => this.emit('success', e));
   }
 
-  generateRequestId() {
-    return ++this.messageId;
-  }
+  generateRequestId() { return ++this.messageId; }
 
   registerTool(name, description, inputSchema, handler) {
     this.toolWhitelist.add(name);
@@ -27,17 +71,16 @@ 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 interact:\n\n';
     for (const tool of tools) {
       prompt += `## Tool: ${tool.name}\n${tool.description}\n`;
@@ -49,178 +92,88 @@ class ACPProtocol extends EventEmitter {
     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 };
+      this.rejectedCallLog.push({ timestamp: new Date().toISOString(), attemptedTool: toolName, reason: 'Not in whitelist', availableTools });
+      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}`);
+    if (!validation.allowed) throw new Error(validation.error);
+    const entry = { timestamp: new Date().toISOString(), toolName, params, status: 'executing' };
+    this.toolCallLog.push(entry);
+    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;
   }
 
-  parseTextOutput(output) {
-    let text = '';
-    const lines = output.split('\n');
-    
-    for (const line of lines) {
-      const trimmed = line.trim();
-      if (!trimmed) continue;
-      
-      try {
-        const json = JSON.parse(trimmed);
-        if (json.type === 'text' && json.part?.text) {
-          text += json.part.text;
-        }
-      } catch {}
-    }
-    
-    return text;
-  }
-
-  parseToolCalls(output) {
-    const calls = [];
-    
-    const textContent = this.parseTextOutput(output);
-    
-    for (const line of textContent.split('\n')) {
-      const trimmed = line.trim();
-      if (!trimmed) continue;
-      
-      try {
-        const json = JSON.parse(trimmed);
-        if (json.jsonrpc === '2.0' && json.method?.startsWith('tools/') && json.params) {
-          calls.push({ 
-            id: json.id,
-            method: json.method, 
-            params: json.params 
-          });
-        }
-      } catch {}
-    }
-    
-    const lines = output.split('\n');
-    for (const line of lines) {
-      const trimmed = line.trim();
-      if (!trimmed) continue;
-      
-      try {
-        const json = JSON.parse(trimmed);
-        if (json.jsonrpc === '2.0' && json.method?.startsWith('tools/') && json.params) {
-          calls.push({ 
-            id: json.id,
-            method: json.method, 
-            params: json.params 
-          });
-        }
-      } catch {}
-    }
-    
-    return calls;
-  }
+  parseTextOutput(output) { return parseTextOutput(output); }
+  parseToolCalls(output) { return parseToolCalls(output); }
 
   async process(text, options = {}) {
-    const cli = options.cli || 'kilo';
-    const model = options.model || 'kilo/z-ai/glm-5:free';
-    
-    const fullPrompt = this.instruction 
+    const fullPrompt = this.instruction
       ? `${this.instruction}${this.getToolsPrompt()}\n\n---\n\n${text}`
       : `${this.getToolsPrompt()}\n\n---\n\n${text}`;
 
-    const escapedPrompt = fullPrompt.replace(/"/g, '\\"').replace(/\n/g, ' ');
-    
-    return new Promise((resolve, reject) => {
-      let output = '';
-      let errorOutput = '';
-
-      const child = spawn('script', ['-q', '-c', 
-        `${cli} run --auto --model ${model} --format json "${escapedPrompt}"`, 
-        '/dev/null'
-      ], {
-        stdio: ['pipe', 'pipe', 'pipe'],
-        cwd: process.cwd(),
-        env: { ...process.env, TERM: 'dumb' },
-      });
-
-      child.stdout.on('data', (data) => {
-        output += data.toString();
-      });
-
-      child.stderr.on('data', (data) => {
-        errorOutput += data.toString();
-      });
-
-      child.on('close', async (code) => {
-        if (code !== 0 && code !== null && !output) {
-          reject(new Error(`CLI exited with code ${code}: ${errorOutput}`));
-          return;
-        }
+    let stack;
+    if (options.services) {
+      stack = createServiceStack(options.services);
+    } else if (options.cli) {
+      stack = [{ name: options.cli, profileId: '__default__', config: {} }];
+    } else {
+      stack = this.registry.getAll().length > 0
+        ? this.registry.getAvailable()
+        : [{ name: 'kilo', profileId: '__default__', config: {} }];
+    }
 
-        try {
-          const toolCalls = this.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: this.parseTextOutput(output),
-            rawOutput: output,
-            toolCalls: results,
-            logs: this.toolCallLog
-          });
-        } catch (e) {
-          resolve({
-            text: this.parseTextOutput(output),
-            rawOutput: output,
-            error: e.message,
-            logs: this.toolCallLog
-          });
-        }
-      });
+    this.fallback._stack = stack;
 
-      child.on('error', (error) => {
-        reject(new Error(`Failed to spawn ${cli}: ${error.message}`));
-      });
+    const { rawOutput } = await this.fallback.run(spawnService, fullPrompt, options);
 
-      setTimeout(() => {
-        child.kill();
-        reject(new Error('Timeout'));
-      }, 120000);
-    });
+    try {
+      const toolCalls = parseToolCalls(rawOutput);
+      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 });
+        }
+      }
+      return { text: parseTextOutput(rawOutput), rawOutput, toolCalls: results, logs: this.toolCallLog };
+    } catch (e) {
+      return { text: parseTextOutput(rawOutput), rawOutput, error: e.message, logs: this.toolCallLog };
+    }
   }
 
   stop() {}

package/fallback.js

@@ -0,0 +1,66 @@
+import { EventEmitter } from 'events';
+import { isRateLimited, DEFAULT_COOLDOWN_MS } from './services.js';
+
+class FallbackEngine extends EventEmitter {
+  constructor(serviceStack = []) {
+    super();
+    this._stack = serviceStack;
+  }
+
+  async run(spawnFn, text, options = {}) {
+    if (this._stack.length === 0) {
+      throw new Error('FallbackEngine: service stack is empty');
+    }
+
+    const errors = [];
+    let attempted = 0;
+
+    for (const entry of this._stack) {
+      const { name, profileId } = entry;
+      attempted++;
+
+      let result;
+      let spawnError;
+      let output = '';
+      let stderr = '';
+
+      try {
+        result = await spawnFn(entry, text, options, {
+          onOutput: (chunk) => { output += chunk; },
+          onStderr: (chunk) => { stderr += chunk; },
+        });
+      } catch (err) {
+        spawnError = err;
+        output = err.output || '';
+        stderr = err.stderr || '';
+      }
+
+      const rlCheck = isRateLimited(name, output, stderr);
+      const isMissing = spawnError?.code === 'ENOENT';
+
+      if (!spawnError && !rlCheck.rateLimited) {
+        this.emit('success', { name, profileId, attempted });
+        return result;
+      }
+
+      if (rlCheck.rateLimited || isMissing) {
+        const cooldownMs = rlCheck.retryAfterMs ?? DEFAULT_COOLDOWN_MS;
+        this.emit('rate-limited', { name, profileId, cooldownMs, error: spawnError?.message });
+        errors.push({ name, profileId, rateLimited: true, retryAfterMs: cooldownMs, error: spawnError?.message });
+        const remaining = this._stack.slice(attempted);
+        if (remaining.length > 0) this.emit('fallback', { from: { name, profileId }, to: remaining[0] });
+        continue;
+      }
+
+      throw spawnError || new Error(`Service ${name} failed: ${output}${stderr}`);
+    }
+
+    const summary = errors.map(e => `${e.name}(${e.profileId}): rate-limited`).join(', ');
+    throw new AggregateError(
+      errors.map(e => Object.assign(new Error(`${e.name} rate-limited`), e)),
+      `All services exhausted: ${summary}`
+    );
+  }
+}
+
+export { FallbackEngine };

package/index.js

@@ -1,28 +1,49 @@
 import { ACPProtocol } from './core.js';
+import { ServiceRegistry, isRateLimited, createServiceStack } from './services.js';
+import { FallbackEngine } from './fallback.js';
 
-export { ACPProtocol };
+export { ACPProtocol, ServiceRegistry, FallbackEngine, isRateLimited, createServiceStack };
 
 /*
- * acpreact - ACP SDK for registering tools
+ * acpreact - ACP SDK for registering tools with multi-service fallback
  *
- * Basic usage:
+ * Basic usage (single service, backward compatible):
  *   import { ACPProtocol } from 'acpreact';
+ *   const acp = new ACPProtocol('Your instruction');
+ *   const result = await acp.process('prompt', { cli: 'kilo' });
  *
- * Create ACP Protocol instance:
- *   const acp = new ACPProtocol();
+ * Multi-service fallback — pass a services array to the constructor:
+ *   const acp = new ACPProtocol('Your instruction', [
+ *     { cli: 'kilo' },
+ *     { cli: 'opencode' },
+ *     { cli: 'gemini' },
+ *   ]);
+ *   const result = await acp.process('prompt');
  *
- * Register custom tools:
- *   acp.registerTool('my_tool', 'Tool description', {
- *     type: 'object',
- *     properties: { query: { type: 'string' } },
- *     required: ['query']
- *   }, async (params) => {
- *     return { result: 'processed' };
+ * Per-call override:
+ *   const result = await acp.process('prompt', {
+ *     services: [{ cli: 'opencode' }, { cli: 'kilo' }],
  *   });
  *
- * Initialize protocol:
- *   const response = acp.createInitializeResponse();
+ * Custom ACP-compatible provider:
+ *   acp.registry.registerService('my-agent', {
+ *     binary: 'my-agent',
+ *     buildArgs: (prompt, opts) => ['run', prompt],
+ *   });
+ *
+ * Multiple profiles per provider (different logins):
+ *   const acp = new ACPProtocol('instruction', [
+ *     { cli: 'kilo', profile: 'account-a' },
+ *     { cli: 'kilo', profile: 'account-b' },
+ *     { cli: 'opencode', profile: 'account-c' },
+ *   ]);
+ *
+ * Listen to fallback events:
+ *   acp.on('rate-limited', ({ name, profileId, cooldownMs }) => { ... });
+ *   acp.on('fallback', ({ from, to }) => { ... });
+ *   acp.on('success', ({ name, profileId, attempted }) => { ... });
  *
- * Execute tool:
- *   const result = await acp.callTool('my_tool', { query: 'test' });
+ * Build a service stack manually:
+ *   import { createServiceStack, ServiceRegistry, FallbackEngine } from 'acpreact';
+ *   const stack = createServiceStack([{ cli: 'kilo' }, { cli: 'gemini' }]);
  */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "acpreact",
-  "version": "1.0.7",
+  "version": "1.1.1",
   "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 };

package/services.js

@@ -0,0 +1,139 @@
+import { EventEmitter } from 'events';
+
+const DEFAULT_COOLDOWN_MS = 60_000;
+
+const RATE_LIMIT_PATTERNS = {
+  common: [
+    /\b429\b/,
+    /rate.?limit/i,
+    /quota.?exceeded/i,
+    /too.?many.?requests/i,
+  ],
+  gemini: [/RESOURCE_EXHAUSTED/],
+  kilo: [],
+  opencode: [],
+};
+
+const RETRY_AFTER_PATTERN = /retry.?after[:\s]+(\d+)/i;
+
+const BUILTIN_ARG_BUILDERS = {
+  kilo: (prompt, options) => {
+    const args = ['run', '--format', 'json', '--auto'];
+    if (options?.model) args.push('--model', options.model);
+    args.push(prompt);
+    return args;
+  },
+  opencode: (prompt, options) => {
+    const args = ['run', '--format', 'json'];
+    if (options?.model) args.push('--model', options.model);
+    args.push(prompt);
+    return args;
+  },
+  gemini: (prompt, options) => {
+    const args = ['run'];
+    if (options?.model) args.push('--model', options.model);
+    args.push(prompt);
+    return args;
+  },
+};
+
+function buildArgs(providerName, prompt, options) {
+  const builder = BUILTIN_ARG_BUILDERS[providerName];
+  if (builder) return builder(prompt, options);
+  const args = ['run'];
+  if (options?.model) args.push('--model', options.model);
+  args.push(prompt);
+  return args;
+}
+
+function isRateLimited(providerName, output = '', stderr = '') {
+  const combined = `${output}\n${stderr}`;
+  const patterns = [
+    ...RATE_LIMIT_PATTERNS.common,
+    ...(RATE_LIMIT_PATTERNS[providerName] || []),
+  ];
+
+  let rateLimited = false;
+  let retryAfterMs;
+
+  for (const pattern of patterns) {
+    if (pattern.test(combined)) {
+      rateLimited = true;
+      break;
+    }
+  }
+
+  if (rateLimited) {
+    const match = combined.match(RETRY_AFTER_PATTERN);
+    if (match) retryAfterMs = parseInt(match[1], 10) * 1000;
+  }
+
+  return retryAfterMs !== undefined ? { rateLimited, retryAfterMs } : { rateLimited };
+}
+
+function createServiceStack(configs) {
+  return configs.map(cfg => ({
+    name: cfg.cli || cfg.name,
+    profileId: cfg.profile ?? '__default__',
+    config: cfg,
+  }));
+}
+
+class ServiceRegistry extends EventEmitter {
+  constructor() {
+    super();
+    this._services = [];
+    this._cooldowns = new Map();
+  }
+
+  _cooldownKey(name, profileId) {
+    return `${name}::${profileId ?? '__default__'}`;
+  }
+
+  registerService(name, config = {}) {
+    const profileId = config.profile ?? '__default__';
+    const existing = this._services.findIndex(
+      s => s.name === name && s.profileId === profileId
+    );
+    const entry = { name, profileId, config };
+    if (existing >= 0) {
+      this._services[existing] = entry;
+    } else {
+      this._services.push(entry);
+    }
+    this._cooldowns.delete(this._cooldownKey(name, profileId));
+    return this;
+  }
+
+  markRateLimited(name, profileId, cooldownMs = DEFAULT_COOLDOWN_MS) {
+    const key = this._cooldownKey(name, profileId ?? '__default__');
+    const expiry = cooldownMs === 0 ? 0 : Date.now() + cooldownMs;
+    this._cooldowns.set(key, expiry);
+    this.emit('rate-limited', { name, profileId, cooldownMs, expiry });
+  }
+
+  clearCooldown(name, profileId) {
+    this._cooldowns.delete(this._cooldownKey(name, profileId ?? '__default__'));
+  }
+
+  isAvailable(name, profileId) {
+    const key = this._cooldownKey(name, profileId ?? '__default__');
+    if (!this._cooldowns.has(key)) return true;
+    const expiry = this._cooldowns.get(key);
+    if (expiry === 0 || Date.now() >= expiry) {
+      this._cooldowns.delete(key);
+      return true;
+    }
+    return false;
+  }
+
+  getAvailable() {
+    return this._services.filter(s => this.isAvailable(s.name, s.profileId));
+  }
+
+  getAll() {
+    return [...this._services];
+  }
+}
+
+export { ServiceRegistry, isRateLimited, createServiceStack, buildArgs, DEFAULT_COOLDOWN_MS };