bare-agent 0.2.2 → 0.3.1

package/README.md

@@ -4,260 +4,81 @@
                                                     │  ╠╩╗╠═╣╠╦╝╠╣  ╠═╣║ ╦╠╣ ║║║ ║    │
                                                     │  ╚═╝╩ ╩╩╚═╚═╝ ╩ ╩╚═╝╚═╝╝╚╝ ╩    │
                                                     │   think ──→ act ──→ observe     │
-                                                    │     ↑                  │        │ 
+                                                    │     ↑                  │        │
                                                     │     └──────────────────┘        │
                                                     ╰──╮──────────────────────────────╯
                                                        ╰── the brain, without the bloat
-                                                       
-```
 
-# bare-agent
+```
 
 **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.
+Lightweight enough to understand completely. Complete enough to not reinvent wheels. Not a framework, not 50,000 lines of opinions — just composable building blocks for agents.
 
-```
+## Quick start
+
+```bash
 npm install bare-agent
 ```
 
----
-
-## Why this exists
-
-You want to build an agent. You have two choices:
-
-1. **Write it from scratch** — 250+ lines of boilerplate. Tool calling loop, retries, provider normalization, memory, state tracking. Everyone reinvents this.
-2. **Adopt a framework** — 50,000 lines, 200 deps, middleware chains, lifecycle hooks, plugin systems. 95% of it is irrelevant to your use case.
-
-**bare-agent is the middle ground.** Small enough to read in an afternoon. Complete enough that you stop reimplementing the same patterns. Each piece works alone — take what you need, ignore the rest.
-
-Not a framework. Not an SDK. Just composable building blocks for agents.
-
----
-
-## Architecture
-
-Three layers. You use the first two. You bring the third.
-
-### Layer 1: ORCHESTRATION — who does what? in what order? what when things go wrong?
-
-| Component | What it does | How |
-|---|---|---|
-| **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?
-
-| Component | What it does | How |
-|---|---|---|
-| **Loop** | Think -> act -> observe | Calls OpenAI/Anthropic/Ollama, executes tools, loops until text |
-| **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 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
+**1. Give your AI assistant the integration guide**
 
 ```
-bare-agent provides the brain. You provide the hands.
-Your tools plug into the Loop as functions:
-
-REST APIs       Gmail, Spotify, Calendar, any HTTP endpoint
-MCP servers     any MCP-compatible tool server
-CLI commands    termux-api, ffmpeg, git, shell scripts
-Browser         Playwright, Puppeteer
-UI automation   ADB, accessibility APIs
+Read bareagent.context.md from node_modules/bare-agent/bareagent.context.md
 ```
 
-bare-agent does not ship tools. Your tools plug into the Loop as functions — `{ name, description, parameters, execute }`. The library handles orchestration. You handle action.
-
-### What bare-agent does NOT do
-
-| Not included | Why | Use instead |
-|---|---|---|
-| Tool implementations | Actuation is your domain | Your APIs, MCP servers, CLI commands |
-| Web UI / dashboard | AG-UI protocol exists | CopilotKit, or build your own |
-| Authentication | Every app has different auth | Wrap Checkpoint with your auth |
-| Browser automation | Separate concern, too heavy | Playwright, Puppeteer (as a tool) |
-| Multi-tenant isolation | Platform problem, not agent problem | Build on top with scope filtering |
-| Agent-to-agent protocol | A2A exists for this | Use A2A SDK when needed |
-
----
-
-## Quick start
-
-### Minimal — 10 lines, one LLM call with tools
-
-```javascript
-const { Loop } = require('bare-agent');
-const { OpenAIProvider } = require('bare-agent/providers');
-
-const loop = new Loop({
-  provider: new OpenAIProvider({ apiKey: process.env.OPENAI_API_KEY }),
-});
+This single file contains component selection, wiring recipes, API signatures, and gotchas — everything an agent needs to use the library correctly.
 
-const result = await loop.run([
-  { role: 'user', content: 'What is the weather in Berlin?' }
-], [weatherTool]);
+**2. Describe what you want**
 
-console.log(result.text);
 ```
+I need an agent that:
+- Takes a user goal and breaks it into steps
+- Runs steps in parallel where possible
+- Retries failed steps twice
+- Streams progress as JSONL events
 
-### With human approval — 30 lines
-
-```javascript
-const { Loop, Checkpoint } = require('bare-agent');
-const { AnthropicProvider } = require('bare-agent/providers');
-
-const checkpoint = new Checkpoint({
-  tools: ['send_email'],
-  send: (q) => console.log(`[APPROVE?] ${q}`),
-  waitForReply: () => new Promise(resolve =>
-    process.stdin.once('data', d => resolve(d.toString().trim()))
-  ),
-});
-
-const loop = new Loop({
-  provider: new AnthropicProvider({ apiKey: process.env.ANTHROPIC_API_KEY }),
-  checkpoint,
-});
-
-const result = await loop.run([
-  { role: 'user', content: 'Email mom that I will be late' }
-], [emailTool]);
+Use bare-agent. The integration guide is in bareagent.context.md.
 ```
 
-### Full autonomous agent — 40 lines
-
-```javascript
-const { Loop, Planner, StateMachine, Scheduler,
-        Memory, Checkpoint, Stream, Retry } = require('bare-agent');
-const { AnthropicProvider } = require('bare-agent/providers');
-const { SQLiteStore } = require('bare-agent/stores');
-
-const provider = new AnthropicProvider({
-  apiKey: process.env.ANTHROPIC_API_KEY,
-  model: 'claude-haiku-4-5-20251001',
-});
-
-const loop = new Loop({
-  provider,
-  planner: new Planner({ provider }),
-  state: new StateMachine({ file: './tasks.json' }),
-  memory: new Memory({ store: new SQLiteStore('./agent.db') }),
-  checkpoint: new Checkpoint({
-    tools: ['purchase', 'send_email'],
-    send: (q) => telegram.send(chatId, q),
-    waitForReply: () => new Promise(r => telegram.once('message', r)),
-  }),
-  stream: new Stream({ transport: 'jsonl' }),
-  retry: new Retry({ maxAttempts: 3, backoff: 'exponential' }),
-});
-
-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' }
-]);
-```
+That's it. The context doc is structured for LLM consumption — your agent reads it once and knows how to wire every component.
 
 ---
 
-## LLM Providers
+## What's inside
 
-All implement one method: `generate(messages, tools, options) -> { text, toolCalls, usage }`.
+Every piece works alone — take what you need, ignore the rest.
 
-| Provider | Covers |
+| Component | What it does |
 |---|---|
-| **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
-
-| Store | Deps | Search |
-|---|---|---|
-| **SQLite FTS5** | `better-sqlite3` (peer dep) | Full-text search with BM25 ranking |
-| **JSON file** | None | Substring matching |
-| **Bring your own** | None | Implement 4 methods for Postgres, Redis, etc. |
-
----
-
-## Cross-language usage
-
-bare-agent runs as a subprocess. Communicate via JSONL on stdin/stdout. Works from any language.
+| **Loop** | Think → act → observe → repeat. Calls any LLM, executes your tools, loops until done. Throws on error by default |
+| **Planner** | Break a goal into a step DAG via LLM. Built-in caching (`cacheTTL`) |
+| **runPlan** | Execute steps in parallel waves. Dependency-aware, failure propagation, per-step retry |
+| **Retry** | Exponential/linear backoff with jitter. Respects `err.retryable` |
+| **CircuitBreaker** | Fail fast after N errors. Auto-recovers after cooldown. Per-key isolation |
+| **Fallback** | Try providers in order — if one is down, next one picks up. Transparent to Loop |
+| **Memory** | Persist and search context. SQLite with FTS (default) or zero-dep JSON file |
+| **StateMachine** | Task lifecycle tracking with event hooks. `pending → running → done / failed / waiting / cancelled` |
+| **Checkpoint** | Human approval gate. You provide the transport — terminal, Telegram, Slack, whatever |
+| **Scheduler** | Cron (`0 9 * * 1-5`) or relative (`2h`, `30m`). Persisted jobs survive restarts |
+| **Stream** | Structured event emitter. Pipe as JSONL, subscribe in-process, or custom transport |
+| **Errors** | Typed hierarchy — `ProviderError`, `ToolError`, `TimeoutError`, `MaxRoundsError`, `CircuitOpenError` |
 
-```python
-import subprocess, json
+**Providers:** OpenAI-compatible (OpenAI, OpenRouter, Groq, vLLM, LM Studio), Anthropic, Ollama, CLIPipe (any CLI tool via stdin/stdout with real-time streaming), Fallback, or bring your own (one method: `generate`). All return the same shape — swap freely.
 
-proc = subprocess.Popen(
-    ['npx', 'bare-agent', '--jsonl'],
-    stdin=subprocess.PIPE, stdout=subprocess.PIPE, text=True
-)
+**Tools:** Any function is a tool. REST APIs, MCP servers, CLI commands, browser automation, shell scripts — if it's a function, it works.
 
-proc.stdin.write(json.dumps({
-    "method": "run",
-    "params": {"goal": "What is 2+2?"}
-}) + '\n')
-proc.stdin.flush()
+**Cross-language:** Runs as a subprocess. Communicate via JSONL on stdin/stdout from Python, Go, Rust, or anything that can spawn a process.
 
-for line in proc.stdout:
-    event = json.loads(line)
-    if event['type'] == 'loop:done':
-        print(event['data']['text'])
-        break
-```
-
-Same pattern works from Go, Rust, Java, Ruby — any language that can spawn a process and read lines.
+**Deps:** 0 required. Optional: `cron-parser` (cron expressions), `better-sqlite3` (SQLite store).
 
 ---
 
-## Dependencies
-
-```
-required:     0
-optional:     cron-parser (for cron expressions in scheduler)
-peer:         better-sqlite3 (for SQLite memory store)
-total lines:  ~1700
-```
-
-## Status
-
-**Production-validated.** bare-agent powers the SOAR2 pipeline in [Aurora](https://github.com/hamr0/aurora), replacing ~400 lines of hand-rolled agent orchestration with ~60 lines of bare-agent wiring. In production use, bare-agent eliminated:
+## Production-validated
 
-- **Boilerplate** — Tool-calling loop, provider normalization, retry logic, and state tracking that every agent project reinvents. Aurora's SOAR2 pipeline dropped from custom loop + manual state management to `Loop + Planner + runPlan + StateMachine`.
-- **Fragile glue code** — Manual wave execution, dependency resolution, and error propagation replaced by `runPlan` with built-in parallelism and failure cascading.
-- **Provider lock-in** — Switching from OpenAI to Anthropic to CLIPipe required zero orchestration changes — just swap the provider constructor.
-- **Debugging friction** — Structured `[ComponentName]` error prefixes and `Stream` events made failures traceable in minutes instead of hours.
+bare-agent powers the SOAR2 pipeline in [Aurora](https://github.com/hamr0/aurora), replacing ~400 lines of hand-rolled orchestration with ~60 lines of bare-agent wiring — zero workarounds, zero framework plumbing, 100% domain logic.
 
-See [project plan](docs/01-product/prd.md) for the full design. See [CHANGELOG.md](CHANGELOG.md) for release history.
+For wiring recipes and API details, see the **[Integration Guide](bareagent.context.md)** (LLM-optimized). For the full human guide — usage patterns, composition examples, and what bare-agent deliberately doesn't build in (with recipes to do it yourself), see the **[Usage Guide](docs/02-features/usage-guide.md)**. For error reference, see **[Error Guide](docs/02-features/errors.md)**. For release history, see **[CHANGELOG](CHANGELOG.md)**.
 
 ## License
 

package/index.js

@@ -17,6 +17,7 @@ const {
   TimeoutError,
   ValidationError,
   CircuitOpenError,
+  MaxRoundsError,
 } = require('./src/errors');
 
 module.exports = {
@@ -36,4 +37,5 @@ module.exports = {
   TimeoutError,
   ValidationError,
   CircuitOpenError,
+  MaxRoundsError,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-agent",
-  "version": "0.2.2",
+  "version": "0.3.1",
   "files": [
     "index.js",
     "src/",
@@ -39,7 +39,7 @@
     "cron-parser": "^4.9.0"
   },
   "peerDependencies": {
-    "better-sqlite3": "^12.6.2"
+    "better-sqlite3": ">=9.0.0"
   },
   "peerDependenciesMeta": {
     "better-sqlite3": {

package/src/errors.js

@@ -43,6 +43,12 @@ class CircuitOpenError extends BareAgentError {
   }
 }
 
+class MaxRoundsError extends BareAgentError {
+  constructor(message, opts = {}) {
+    super(message || 'Loop exceeded maximum rounds', { code: 'MAX_ROUNDS', retryable: false, ...opts });
+  }
+}
+
 module.exports = {
   BareAgentError,
   ProviderError,
@@ -50,4 +56,5 @@ module.exports = {
   TimeoutError,
   ValidationError,
   CircuitOpenError,
+  MaxRoundsError,
 };

package/src/loop.js

@@ -1,6 +1,6 @@
 'use strict';
 
-const { ToolError } = require('./errors');
+const { ToolError, MaxRoundsError } = require('./errors');
 
 class Loop {
   /**
@@ -25,6 +25,7 @@ class Loop {
     this.onToolCall = options.onToolCall || null;
     this.onText = options.onText || null;
     this.onError = options.onError || null;
+    this.throwOnError = options.throwOnError !== undefined ? options.throwOnError : true;
     this.store = options.store || null;
     this._stopped = false;
     this._history = []; // for chat() stateful mode
@@ -78,6 +79,7 @@ class Loop {
       } catch (err) {
         this.stream?.emit({ type: 'loop:error', data: { error: err.message, round } });
         this.onError?.(err);
+        if (this.throwOnError) throw err;
         return { text: '', toolCalls: [], usage: lastUsage, error: err.message };
       }
 
@@ -148,6 +150,7 @@ class Loop {
     // maxRounds exceeded
     const warning = `[Loop] ended after ${this.maxRounds} rounds without final response`;
     this.stream?.emit({ type: 'loop:done', data: { text: '', warning } });
+    if (this.throwOnError) throw new MaxRoundsError(warning);
     return { text: '', toolCalls: [], usage: lastUsage, error: warning };
   }
 

package/src/planner.js

@@ -25,6 +25,8 @@ class Planner {
     if (!options.provider) throw new Error('[Planner] requires a provider');
     this.provider = options.provider;
     this.prompt = options.prompt || PLAN_PROMPT;
+    this._cacheTTL = options.cacheTTL || 0;
+    this._cache = new Map();
   }
 
   /**
@@ -37,6 +39,14 @@ class Planner {
    * @throws {Error} `[Planner] step missing id or action` — when a step lacks required fields.
    */
   async plan(goal, context = {}) {
+    if (this._cacheTTL > 0) {
+      const cacheKey = goal + '|' + (context.info || '');
+      const cached = this._cache.get(cacheKey);
+      if (cached && Date.now() < cached.expiresAt) {
+        return cached.result;
+      }
+    }
+
     const messages = [
       { role: 'system', content: this.prompt },
     ];
@@ -50,7 +60,18 @@ class Planner {
       temperature: 0,
     });
 
-    return this._parse(result.text);
+    const steps = this._parse(result.text);
+
+    if (this._cacheTTL > 0) {
+      const cacheKey = goal + '|' + (context.info || '');
+      this._cache.set(cacheKey, { result: steps, expiresAt: Date.now() + this._cacheTTL });
+    }
+
+    return steps;
+  }
+
+  clearCache() {
+    this._cache.clear();
   }
 
   _parse(text) {

package/src/provider-clipipe.js

@@ -23,6 +23,7 @@ class CLIPipeProvider {
     this.env = options.env || undefined;
     this.timeout = options.timeout ?? 30000;
     this.systemPromptFlag = options.systemPromptFlag || null;
+    this.onChunk = options.onChunk || null;
   }
 
   /**
@@ -88,7 +89,7 @@ class CLIPipeProvider {
       let stderr = '';
       let killed = false;
 
-      child.stdout.on('data', d => { stdout += d; });
+      child.stdout.on('data', d => { stdout += d; this.onChunk?.(d.toString()); });
       child.stderr.on('data', d => { stderr += d; });
 
       child.on('error', err => {