acpreact 1.0.8 → 1.1.1

package/README.md

@@ -1,6 +1,6 @@
 # acpreact - ACP SDK
 
-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.
+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
 
@@ -8,7 +8,9 @@ A lightweight SDK for registering tools and running them via kilo CLI or opencod
 - **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 and logging
-- **CLI Integration**: Works with kilo CLI and opencode via `process()` method
+- **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
@@ -61,6 +63,76 @@ console.log(result.logs);          // tool call audit log
 const result = await acp.process('What is 15 + 27? Use the add tool.', { cli: 'opencode' });
 ```
 
+### Multi-Service Fallback
+
+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 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
@@ -98,8 +170,9 @@ Main class for ACP protocol communication.
 
 **Constructor:**
 
-- `new ACPProtocol(instruction?)`: Initialize the protocol
+- `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:**
 
@@ -110,11 +183,14 @@ Main class for ACP protocol communication.
   - `handler`: Async function - receives params object, returns result
   - Returns: Tool definition object
 
-- `async process(text, options?)`: Send a prompt to kilo or opencode and execute any tool calls
+- `async process(text, options?)`: Send a prompt to a CLI and execute any tool calls
   - `text`: String - the user prompt
-  - `options.cli`: `'kilo'` (default) or `'opencode'`
+  - `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
 

package/core.js

@@ -1,9 +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;
@@ -13,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);
@@ -51,8 +94,7 @@ class ACPProtocol extends EventEmitter {
 
   createInitializeResponse() {
     return {
-      jsonrpc: '2.0',
-      id: 1,
+      jsonrpc: '2.0', id: 1,
       result: {
         tools: this.getToolsList(),
         instruction: this.instruction,
@@ -65,30 +107,19 @@ class ACPProtocol extends EventEmitter {
     return { jsonrpc: '2.0', id: this.generateRequestId(), method, params };
   }
 
-  createJsonRpcResponse(id, result) {
-    return { jsonrpc: '2.0', id, result };
-  }
+  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),
-      },
+      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);
-      this.rejectedCallLog.push({
-        timestamp: new Date().toISOString(),
-        attemptedTool: toolName,
-        reason: 'Not in whitelist',
-        availableTools,
-      });
+      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 };
@@ -97,10 +128,8 @@ class ACPProtocol extends EventEmitter {
   async callTool(toolName, params) {
     const validation = this.validateToolCall(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';
@@ -108,67 +137,43 @@ class ACPProtocol extends EventEmitter {
     return result;
   }
 
-  parseTextOutput(output) {
-    return parseTextOutput(output);
-  }
-
-  parseToolCalls(output) {
-    return parseToolCalls(output);
-  }
+  parseTextOutput(output) { return parseTextOutput(output); }
+  parseToolCalls(output) { return parseToolCalls(output); }
 
   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}`;
 
-    const args = ['run', '--format', 'json'];
-    if (cli === 'kilo') args.push('--auto');
-    if (model) args.push('--model', model);
-    args.push(fullPrompt);
-
-    return new Promise((resolve, reject) => {
-      let output = '';
-      let errorOutput = '';
-
-      const child = spawn(cli, args, {
-        stdio: ['pipe', 'pipe', 'pipe'],
-        cwd: process.cwd(),
-        env: { ...process.env },
-      });
-
-      child.stdin.end();
-      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;
-        }
-        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 });
-        }
-      });
+    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: {} }];
+    }
 
-      child.on('error', (error) => {
-        reject(new Error(`Failed to spawn ${cli}: ${error.message}`));
-      });
+    this.fallback._stack = stack;
 
-      setTimeout(() => { child.kill(); reject(new Error('Timeout')); }, 120000);
-    });
+    const { rawOutput } = await this.fallback.run(spawnService, fullPrompt, options);
+
+    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.8",
+  "version": "1.1.1",
   "type": "module",
   "main": "index.js",
   "description": "ACP SDK for monitoring and reacting to chat conversations",

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 };