bare-agent 0.2.1 → 0.2.2

package/README.md

@@ -13,7 +13,7 @@
 
 # bare-agent
 
-**Agent orchestration in ~1500 lines. Zero required deps. MIT license.**
+**Agent orchestration in ~1700 lines. Zero required deps. MIT license.**
 
 Everything between "call the LLM" and "ship the agent" — loop, plan, remember, schedule, checkpoint. Each works alone. All compose together.
 
@@ -47,6 +47,7 @@ Three layers. You use the first two. You bring the third.
 | **Planner** | Goal -> step DAG | Structured output prompt, LLM returns JSON dependency graph |
 | **State** | Task lifecycle tracking | `pending -> running -> done \| failed`, persisted to JSON file |
 | **Stream** | Event streaming | One JSON object per line to stdout, pipe-friendly, any-language |
+| **Errors** | Typed error hierarchy | `BareAgentError` base, `ProviderError`, `ToolError`, `TimeoutError`, `CircuitOpenError` |
 
 ### Layer 2: EXECUTION — how the agent thinks, remembers, acts, and persist?
 
@@ -56,7 +57,9 @@ Three layers. You use the first two. You bring the third.
 | **Scheduler** | Time-triggered turns | Cron (`0 7 * * 1-5`), relative (`2h`, `30m`), persisted jobs |
 | **Memory** | Persist + search | SQLite FTS5 with BM25 (default), JSON file fallback (zero deps) |
 | **Checkpoint** | Human approval gate | You provide the transport — readline, Telegram, WebSocket |
-| **Retry** | Backoff on failure | Exponential/linear, retries on 429/5xx/network errors |
+| **Retry** | Backoff on failure | Exponential/linear with jitter, retries on 429/5xx/network errors |
+| **CircuitBreaker** | Fail-fast on repeated errors | Per-key threshold, auto half-open probe, `wrapProvider()` |
+| **Fallback** | Multi-provider resilience | Tries providers in order, AggregateError if all fail |
 
 ### Layer 3: ACTUATION — you provide this
 
@@ -159,17 +162,42 @@ const loop = new Loop({
 await loop.runGoal('Book my Berlin trip for next Tuesday');
 ```
 
+### Resilient multi-provider — circuit breaker + fallback + jitter
+
+```javascript
+const { Loop, Retry, CircuitBreaker } = require('bare-agent');
+const { OpenAI, Anthropic, Fallback } = require('bare-agent/providers');
+
+const cb = new CircuitBreaker({ threshold: 3, resetAfter: 30000 });
+
+const provider = new Fallback([
+  cb.wrapProvider(new OpenAI({ apiKey: process.env.OPENAI_API_KEY }), 'openai'),
+  cb.wrapProvider(new Anthropic({ apiKey: process.env.ANTHROPIC_API_KEY }), 'anthropic'),
+]);
+
+const loop = new Loop({
+  provider,
+  retry: new Retry({ maxAttempts: 3, jitter: 'full' }),
+});
+
+const result = await loop.run([
+  { role: 'user', content: 'Summarize today\'s news' }
+]);
+```
+
 ---
 
 ## LLM Providers
 
-Three built-in. All implement one method: `generate(messages, tools, options) -> { text, toolCalls, usage }`.
+All implement one method: `generate(messages, tools, options) -> { text, toolCalls, usage }`.
 
 | Provider | Covers |
 |---|---|
 | **OpenAI** | OpenAI, OpenRouter, Together, Groq, vLLM, LM Studio — any OpenAI-compatible endpoint |
 | **Anthropic** | Claude models via native API |
 | **Ollama** | Local models, no API key needed |
+| **CLIPipe** | Any CLI tool via stdin/stdout (claude, ollama run, etc.) |
+| **Fallback** | Tries multiple providers in order — transparent to Loop |
 | **Bring your own** | Implement `generate()` — one method, full control |
 
 ## Storage
@@ -217,7 +245,7 @@ Same pattern works from Go, Rust, Java, Ruby — any language that can spawn a p
 required:     0
 optional:     cron-parser (for cron expressions in scheduler)
 peer:         better-sqlite3 (for SQLite memory store)
-total lines:  ~1500
+total lines:  ~1700
 ```
 
 ## Status

package/index.js

@@ -9,6 +9,15 @@ const { Memory } = require('./src/memory');
 const { Stream } = require('./src/stream');
 const { Retry } = require('./src/retry');
 const { runPlan } = require('./src/run-plan');
+const { CircuitBreaker } = require('./src/circuit-breaker');
+const {
+  BareAgentError,
+  ProviderError,
+  ToolError,
+  TimeoutError,
+  ValidationError,
+  CircuitOpenError,
+} = require('./src/errors');
 
 module.exports = {
   Loop,
@@ -20,4 +29,11 @@ module.exports = {
   Stream,
   Retry,
   runPlan,
+  CircuitBreaker,
+  BareAgentError,
+  ProviderError,
+  ToolError,
+  TimeoutError,
+  ValidationError,
+  CircuitOpenError,
 };

package/package.json

@@ -1,12 +1,12 @@
 {
   "name": "bare-agent",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "files": [
     "index.js",
     "src/",
     "bin/"
   ],
-  "description": "Lightweight, composable agent orchestration. ~800 lines, 0 required deps.",
+  "description": "Lightweight, composable agent orchestration. ~1700 lines, 0 required deps.",
   "license": "MIT",
   "author": "hamr0",
   "repository": {

package/src/circuit-breaker.js

@@ -0,0 +1,112 @@
+'use strict';
+
+const { CircuitOpenError } = require('./errors');
+
+class CircuitBreaker {
+  /**
+   * @param {object} [options={}]
+   * @param {number} [options.threshold=5] - Failures before opening.
+   * @param {number} [options.resetAfter=60000] - Ms before half-open probe.
+   * @param {function} [options.onStateChange] - Callback(key, from, to).
+   */
+  constructor(options = {}) {
+    this.threshold = options.threshold || 5;
+    this.resetAfter = options.resetAfter || 60000;
+    this.onStateChange = options.onStateChange || null;
+    this._keys = new Map();
+  }
+
+  _getEntry(key) {
+    if (!this._keys.has(key)) {
+      this._keys.set(key, { state: 'closed', failures: 0, openedAt: 0, generation: 0 });
+    }
+    return this._keys.get(key);
+  }
+
+  _setState(entry, key, newState) {
+    const from = entry.state;
+    if (from === newState) return;
+    entry.state = newState;
+    this.onStateChange?.(key, from, newState);
+  }
+
+  /**
+   * Execute fn through the circuit breaker.
+   * @param {function} fn - Async function to call.
+   * @param {string} [key='default'] - Circuit key for per-key isolation.
+   * @returns {Promise<*>}
+   * @throws {CircuitOpenError} When circuit is open.
+   */
+  async call(fn, key = 'default') {
+    const entry = this._getEntry(key);
+
+    if (entry.state === 'open') {
+      if (Date.now() - entry.openedAt >= this.resetAfter) {
+        this._setState(entry, key, 'half-open');
+        entry.generation++;
+      } else {
+        throw new CircuitOpenError(`Circuit "${key}" is open`);
+      }
+    }
+
+    const gen = entry.generation;
+
+    try {
+      const result = await fn();
+      // Only close if still same generation (prevents stale half-open races)
+      if (entry.generation === gen) {
+        entry.failures = 0;
+        if (entry.state === 'half-open') {
+          this._setState(entry, key, 'closed');
+        }
+      }
+      return result;
+    } catch (err) {
+      if (entry.generation === gen) {
+        entry.failures++;
+        if (entry.state === 'half-open') {
+          entry.openedAt = Date.now();
+          this._setState(entry, key, 'open');
+        } else if (entry.failures >= this.threshold) {
+          entry.openedAt = Date.now();
+          this._setState(entry, key, 'open');
+        }
+      }
+      throw err;
+    }
+  }
+
+  /**
+   * Get current state for a key.
+   * @param {string} [key='default']
+   * @returns {'closed'|'open'|'half-open'}
+   */
+  getState(key = 'default') {
+    return this._getEntry(key).state;
+  }
+
+  /**
+   * Force reset a key to closed.
+   * @param {string} [key='default']
+   */
+  reset(key = 'default') {
+    const entry = this._getEntry(key);
+    entry.failures = 0;
+    entry.openedAt = 0;
+    this._setState(entry, key, 'closed');
+  }
+
+  /**
+   * Wrap a provider so generate() goes through the circuit breaker.
+   * @param {object} provider - Provider with generate().
+   * @param {string} [key] - Circuit key.
+   * @returns {object} Wrapped provider with generate().
+   */
+  wrapProvider(provider, key) {
+    return {
+      generate: (...args) => this.call(() => provider.generate(...args), key),
+    };
+  }
+}
+
+module.exports = { CircuitBreaker };

package/src/errors.js

@@ -0,0 +1,53 @@
+'use strict';
+
+class BareAgentError extends Error {
+  constructor(message, { code, retryable = false, context = {} } = {}) {
+    super(message);
+    this.name = this.constructor.name;
+    this.code = code || undefined;
+    this.retryable = retryable;
+    this.context = context;
+  }
+}
+
+class ProviderError extends BareAgentError {
+  constructor(message, { status, body, context = {} } = {}) {
+    const retryable = status === 429 || (status >= 500 && status <= 504);
+    super(message, { code: 'PROVIDER_ERROR', retryable, context });
+    this.status = status;
+    this.body = body;
+  }
+}
+
+class ToolError extends BareAgentError {
+  constructor(message, opts = {}) {
+    super(message, { code: 'TOOL_ERROR', retryable: false, ...opts });
+  }
+}
+
+class TimeoutError extends BareAgentError {
+  constructor(message, opts = {}) {
+    super(message || 'Operation timed out', { code: 'ETIMEDOUT', retryable: true, ...opts });
+  }
+}
+
+class ValidationError extends BareAgentError {
+  constructor(message, opts = {}) {
+    super(message, { code: 'VALIDATION_ERROR', retryable: false, ...opts });
+  }
+}
+
+class CircuitOpenError extends BareAgentError {
+  constructor(message, opts = {}) {
+    super(message || 'Circuit breaker is open', { code: 'CIRCUIT_OPEN', retryable: true, ...opts });
+  }
+}
+
+module.exports = {
+  BareAgentError,
+  ProviderError,
+  ToolError,
+  TimeoutError,
+  ValidationError,
+  CircuitOpenError,
+};

package/src/loop.js

@@ -1,5 +1,7 @@
 'use strict';
 
+const { ToolError } = require('./errors');
+
 class Loop {
   /**
    * @param {object} options
@@ -135,7 +137,8 @@ class Loop {
           msgs.push({ role: 'tool', tool_call_id: tc.id, content });
           this.stream?.emit({ type: 'loop:tool_result', data: { tool: tc.name, result: content } });
         } catch (err) {
-          const errMsg = `[Loop] Tool error: ${err.message}`;
+          const toolErr = err instanceof ToolError ? err : new ToolError(err.message, { context: { tool: tc.name } });
+          const errMsg = `[Loop] Tool error: ${toolErr.message}`;
           msgs.push({ role: 'tool', tool_call_id: tc.id, content: errMsg });
           this.stream?.emit({ type: 'loop:tool_result', data: { tool: tc.name, error: errMsg } });
         }

package/src/provider-anthropic.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const https = require('https');
+const { ProviderError } = require('./errors');
 
 class AnthropicProvider {
   /**
@@ -123,10 +124,10 @@ class AnthropicProvider {
           try {
             const parsed = JSON.parse(chunks);
             if (res.statusCode >= 400) {
-              const err = new Error(`[AnthropicProvider] ${parsed.error?.message || `HTTP ${res.statusCode}`}`);
-              err.status = res.statusCode;
-              err.body = parsed;
-              return reject(err);
+              return reject(new ProviderError(
+                `[AnthropicProvider] ${parsed.error?.message || `HTTP ${res.statusCode}`}`,
+                { status: res.statusCode, body: parsed }
+              ));
             }
             resolve(parsed);
           } catch (e) {

package/src/provider-clipipe.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const { spawn } = require('child_process');
+const { ProviderError } = require('./errors');
 
 class CLIPipeProvider {
   /**
@@ -91,17 +92,17 @@ class CLIPipeProvider {
       child.stderr.on('data', d => { stderr += d; });
 
       child.on('error', err => {
-        reject(new Error(`[CLIPipeProvider] failed to spawn "${this.command}": ${err.message}`));
+        reject(new ProviderError(`[CLIPipeProvider] failed to spawn "${this.command}": ${err.message}`, { status: 0 }));
       });
 
       child.on('close', code => {
         if (killed) return; // timeout already rejected
         if (code !== 0) {
-          return reject(new Error(`[CLIPipeProvider] process exited with code ${code}: ${stderr.trim()}`));
+          return reject(new ProviderError(`[CLIPipeProvider] process exited with code ${code}: ${stderr.trim()}`, { status: code }));
         }
         const text = stdout.trim();
         if (!text) {
-          return reject(new Error('[CLIPipeProvider] process produced no output'));
+          return reject(new ProviderError('[CLIPipeProvider] process produced no output', { status: 0 }));
         }
         resolve(text);
       });
@@ -113,7 +114,7 @@ class CLIPipeProvider {
         setTimeout(() => {
           try { child.kill('SIGKILL'); } catch (_) {}
         }, 1000);
-        reject(new Error(`[CLIPipeProvider] timed out after ${this.timeout}ms`));
+        reject(new ProviderError(`[CLIPipeProvider] timed out after ${this.timeout}ms`, { status: 0 }));
       }, this.timeout);
 
       child.on('close', () => clearTimeout(timer));

package/src/provider-fallback.js

@@ -0,0 +1,48 @@
+'use strict';
+
+class FallbackProvider {
+  /**
+   * Provider that tries multiple providers in order.
+   * @param {Array<object>} providers - Ordered list of providers with generate().
+   * @param {object} [options={}]
+   * @param {function} [options.shouldFallback] - (error, index) => boolean. Return false to stop.
+   * @param {function} [options.onFallback] - (error, fromIndex, toIndex) callback.
+   * @throws {Error} `[FallbackProvider] requires at least one provider` — when providers is empty.
+   */
+  constructor(providers, options = {}) {
+    if (!Array.isArray(providers) || providers.length === 0) {
+      throw new Error('[FallbackProvider] requires at least one provider');
+    }
+    this.providers = providers;
+    this.shouldFallback = options.shouldFallback || (() => true);
+    this.onFallback = options.onFallback || null;
+  }
+
+  /**
+   * Generate using first available provider.
+   * @param {Array<object>} messages
+   * @param {Array<object>} [tools=[]]
+   * @param {object} [options={}]
+   * @returns {Promise<{text: string, toolCalls: Array, usage: object}>}
+   * @throws {AggregateError} When all providers fail.
+   */
+  async generate(messages, tools = [], options = {}) {
+    const errors = [];
+
+    for (let i = 0; i < this.providers.length; i++) {
+      try {
+        return await this.providers[i].generate(messages, tools, options);
+      } catch (err) {
+        errors.push(err);
+        if (i < this.providers.length - 1) {
+          if (!this.shouldFallback(err, i)) throw err;
+          this.onFallback?.(err, i, i + 1);
+        }
+      }
+    }
+
+    throw new AggregateError(errors, '[FallbackProvider] all providers failed');
+  }
+}
+
+module.exports = { FallbackProvider };

package/src/provider-ollama.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const http = require('http');
+const { ProviderError } = require('./errors');
 
 class OllamaProvider {
   constructor(options = {}) {
@@ -67,9 +68,10 @@ class OllamaProvider {
           try {
             const parsed = JSON.parse(chunks);
             if (res.statusCode >= 400) {
-              const err = new Error(`[OllamaProvider] ${parsed.error || `HTTP ${res.statusCode}`}`);
-              err.status = res.statusCode;
-              return reject(err);
+              return reject(new ProviderError(
+                `[OllamaProvider] ${parsed.error || `HTTP ${res.statusCode}`}`,
+                { status: res.statusCode, body: parsed }
+              ));
             }
             resolve(parsed);
           } catch (e) {

package/src/provider-openai.js

@@ -2,6 +2,7 @@
 
 const https = require('https');
 const http = require('http');
+const { ProviderError } = require('./errors');
 
 class OpenAIProvider {
   constructor(options = {}) {
@@ -70,10 +71,10 @@ class OpenAIProvider {
           try {
             const parsed = JSON.parse(chunks);
             if (res.statusCode >= 400) {
-              const err = new Error(`[OpenAIProvider] ${parsed.error?.message || `HTTP ${res.statusCode}`}`);
-              err.status = res.statusCode;
-              err.body = parsed;
-              return reject(err);
+              return reject(new ProviderError(
+                `[OpenAIProvider] ${parsed.error?.message || `HTTP ${res.statusCode}`}`,
+                { status: res.statusCode, body: parsed }
+              ));
             }
             resolve(parsed);
           } catch (e) {

package/src/providers.js

@@ -4,10 +4,12 @@ const { OpenAIProvider } = require('./provider-openai');
 const { AnthropicProvider } = require('./provider-anthropic');
 const { OllamaProvider } = require('./provider-ollama');
 const { CLIPipeProvider } = require('./provider-clipipe');
+const { FallbackProvider } = require('./provider-fallback');
 
 module.exports = {
   OpenAI: OpenAIProvider,
   Anthropic: AnthropicProvider,
   Ollama: OllamaProvider,
   CLIPipe: CLIPipeProvider,
+  Fallback: FallbackProvider,
 };

package/src/retry.js

@@ -1,6 +1,10 @@
 'use strict';
 
+const { TimeoutError } = require('./errors');
+
 const DEFAULT_RETRY_ON = (err) => {
+  if (err.retryable === true) return true;
+  if (err.retryable === false) return false;
   const status = err.status || err.statusCode;
   if (status === 429 || (status >= 500 && status <= 504)) return true;
   const code = err.code;
@@ -14,6 +18,7 @@ class Retry {
     this.backoff = options.backoff || 'exponential';
     this.timeout = options.timeout || 60000;
     this.retryOn = options.retryOn || DEFAULT_RETRY_ON;
+    this.jitter = options.jitter !== undefined ? options.jitter : false;
   }
 
   /**
@@ -21,7 +26,7 @@ class Retry {
    * @param {() => Promise<*>} fn - Async function to execute.
    * @param {object} [options={}] - Per-call overrides for maxAttempts, retryOn, timeout.
    * @returns {Promise<*>} The result of fn().
-   * @throws {Error} `[Retry] Timeout` — when an individual attempt exceeds the timeout.
+   * @throws {TimeoutError} When an individual attempt exceeds the timeout.
    * @throws {Error} Rethrows the last error when maxAttempts is exhausted or error is not retryable.
    */
   async call(fn, options = {}) {
@@ -32,7 +37,7 @@ class Retry {
     for (let attempt = 1; attempt <= max; attempt++) {
       try {
         const result = await (timeout
-          ? Promise.race([fn(), new Promise((_, rej) => setTimeout(() => rej(Object.assign(new Error('[Retry] Timeout'), { code: 'ETIMEDOUT' })), timeout))])
+          ? Promise.race([fn(), new Promise((_, rej) => setTimeout(() => rej(new TimeoutError('[Retry] Timeout')), timeout))])
           : fn());
         return result;
       } catch (err) {
@@ -44,9 +49,30 @@ class Retry {
   }
 
   _delay(attempt) {
-    if (typeof this.backoff === 'number') return this.backoff;
-    if (this.backoff === 'linear') return attempt * 1000;
-    return Math.min(2 ** (attempt - 1) * 1000, 30000); // exponential, cap 30s
+    let base;
+    if (typeof this.backoff === 'number') {
+      base = this.backoff;
+    } else if (this.backoff === 'linear') {
+      base = attempt * 1000;
+    } else {
+      base = Math.min(2 ** (attempt - 1) * 1000, 30000); // exponential, cap 30s
+    }
+    return this._applyJitter(base);
+  }
+
+  _applyJitter(base) {
+    if (this.jitter === false || this.jitter === 0) return base;
+    if (this.jitter === 'full') {
+      return Math.floor(Math.random() * base);
+    }
+    if (this.jitter === 'equal') {
+      return Math.floor(base / 2 + Math.random() * (base / 2));
+    }
+    if (typeof this.jitter === 'number') {
+      const spread = base * this.jitter;
+      return Math.floor(base - spread + Math.random() * spread);
+    }
+    return base;
   }
 }
 

package/src/run-plan.js

@@ -48,7 +48,7 @@ async function runPlan(steps, executeFn, options = {}) {
     }
   }
 
-  const { concurrency = Infinity, stateMachine, onStepStart, onStepDone, onStepFail, onWaveStart } = options;
+  const { concurrency = Infinity, stateMachine, onStepStart, onStepDone, onStepFail, onWaveStart, stepRetry } = options;
 
   let waveNumber = 0;
 
@@ -95,7 +95,9 @@ async function runPlan(steps, executeFn, options = {}) {
       onStepStart?.(step);
 
       try {
-        const result = await executeFn(step);
+        const result = stepRetry
+          ? await stepRetry.call(() => executeFn(step))
+          : await executeFn(step);
         entry.status = 'done';
         entry.result = result;
         stateMachine?.transition(step.id, 'complete', result);