bare-agent 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,229 @@
+```
+                                                    ╭─────────────────────────────────╮
+                                                    │  ╔╗ ╔═╗╦═╗╔═╗ ╔═╗╔═╗╔═╗╔╗╔╔╦╗   │
+                                                    │  ╠╩╗╠═╣╠╦╝╠╣  ╠═╣║ ╦╠╣ ║║║ ║    │
+                                                    │  ╚═╝╩ ╩╩╚═╚═╝ ╩ ╩╚═╝╚═╝╝╚╝ ╩    │
+                                                    │   think ──→ act ──→ observe     │
+                                                    │     ↑                  │        │ 
+                                                    │     └──────────────────┘        │
+                                                    ╰──╮──────────────────────────────╯
+                                                       ╰── the brain, without the bloat
+                                                       
+```
+
+# bare-agent
+
+**Agent orchestration in ~800 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.
+
+```
+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 |
+
+### 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, retries on 429/5xx/network errors |
+
+### Layer 3: ACTUATION — you provide this
+
+```
+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
+```
+
+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 }),
+});
+
+const result = await loop.run([
+  { role: 'user', content: 'What is the weather in Berlin?' }
+], [weatherTool]);
+
+console.log(result.text);
+```
+
+### 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]);
+```
+
+### 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');
+```
+
+---
+
+## LLM Providers
+
+Three built-in. 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 |
+| **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.
+
+```python
+import subprocess, json
+
+proc = subprocess.Popen(
+    ['npx', 'bare-agent', '--jsonl'],
+    stdin=subprocess.PIPE, stdout=subprocess.PIPE, text=True
+)
+
+proc.stdin.write(json.dumps({
+    "method": "run",
+    "params": {"goal": "What is 2+2?"}
+}) + '\n')
+proc.stdin.flush()
+
+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.
+
+---
+
+## Dependencies
+
+```
+required:     0
+optional:     cron-parser (for cron expressions in scheduler)
+peer:         better-sqlite3 (for SQLite memory store)
+total lines:  ~820
+```
+
+## Status
+
+Early development. Core components built and validated through POCs. See [project plan](docs/01-product/prd.md) for the full design.
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+'use strict';
+
+const { createInterface } = require('node:readline');
+const { Loop } = require('../src/loop');
+const { Stream } = require('../src/stream');
+const { JsonlTransport } = require('../src/transport-jsonl');
+
+const args = process.argv.slice(2);
+const flag = (name) => {
+  const i = args.indexOf(`--${name}`);
+  return i >= 0 ? args[i + 1] : undefined;
+};
+
+const providerName = flag('provider') || 'openai';
+const model = flag('model');
+
+function createProvider() {
+  if (providerName === 'openai') {
+    const { OpenAIProvider } = require('../src/provider-openai');
+    return new OpenAIProvider({
+      apiKey: process.env.OPENAI_API_KEY,
+      ...(model && { model }),
+    });
+  }
+  if (providerName === 'anthropic') {
+    const { AnthropicProvider } = require('../src/provider-anthropic');
+    return new AnthropicProvider({
+      apiKey: process.env.ANTHROPIC_API_KEY,
+      ...(model && { model }),
+    });
+  }
+  if (providerName === 'ollama') {
+    const { OllamaProvider } = require('../src/provider-ollama');
+    return new OllamaProvider({
+      ...(model && { model }),
+      ...(flag('url') && { url: flag('url') }),
+    });
+  }
+  process.stderr.write(`Unknown provider: ${providerName}\n`);
+  process.exit(1);
+}
+
+const stream = new Stream({ transport: new JsonlTransport() });
+const loop = new Loop({ provider: createProvider(), stream });
+
+let pending = 0;
+let closing = false;
+
+const rl = createInterface({ input: process.stdin });
+rl.on('line', async (line) => {
+  pending++;
+  try {
+    const req = JSON.parse(line);
+    const messages = req.params?.messages || [
+      { role: 'user', content: req.params?.goal || '' },
+    ];
+    const result = await loop.run(messages, []);
+    stream.emit({ type: 'result', data: result });
+  } catch (err) {
+    stream.emit({ type: 'error', data: { error: err.message } });
+  } finally {
+    pending--;
+    if (closing && pending === 0) process.exit(0);
+  }
+});
+
+rl.on('close', () => {
+  closing = true;
+  if (pending === 0) process.exit(0);
+});

package/index.js

@@ -1 +1,21 @@
-// bare-agent — lightweight agent orchestration
+'use strict';
+
+const { Loop } = require('./src/loop');
+const { Planner } = require('./src/planner');
+const { StateMachine } = require('./src/state');
+const { Scheduler } = require('./src/scheduler');
+const { Checkpoint } = require('./src/checkpoint');
+const { Memory } = require('./src/memory');
+const { Stream } = require('./src/stream');
+const { Retry } = require('./src/retry');
+
+module.exports = {
+  Loop,
+  Planner,
+  StateMachine,
+  Scheduler,
+  Checkpoint,
+  Memory,
+  Stream,
+  Retry,
+};

package/package.json

@@ -1,16 +1,51 @@
 {
   "name": "bare-agent",
-  "version": "0.1.0",
-  "description": "Lightweight, composable agent orchestration. ~800 lines, 0 required deps. Use what you need, ignore the rest.",
+  "version": "0.1.1",
+  "files": [
+    "index.js",
+    "src/",
+    "bin/"
+  ],
+  "description": "Lightweight, composable agent orchestration. ~800 lines, 0 required deps.",
   "license": "MIT",
-  "author": "amrhas82",
-  "keywords": ["agent", "llm", "orchestration", "ai", "tool-calling", "planner", "lightweight"],
+  "author": "hamr0",
   "repository": {
     "type": "git",
-    "url": "https://github.com/amrhas82/bare-agent"
+    "url": "git+https://github.com/hamr0/bareagent.git"
   },
   "main": "index.js",
+  "bin": {
+    "bare-agent": "./bin/cli.js"
+  },
+  "exports": {
+    ".": "./index.js",
+    "./providers": "./src/providers.js",
+    "./stores": "./src/stores.js"
+  },
   "engines": {
     "node": ">=18"
+  },
+  "keywords": [
+    "agent",
+    "llm",
+    "orchestration",
+    "ai",
+    "tool-calling",
+    "planner",
+    "lightweight"
+  ],
+  "optionalDependencies": {
+    "cron-parser": "^4.9.0"
+  },
+  "peerDependencies": {
+    "better-sqlite3": "^12.6.2"
+  },
+  "peerDependenciesMeta": {
+    "better-sqlite3": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "test": "node --test test/**/*.test.js"
   }
 }

package/src/checkpoint.js

@@ -0,0 +1,33 @@
+'use strict';
+
+class Checkpoint {
+  constructor(options = {}) {
+    this.tools = new Set(options.tools || []);
+    this.send = options.send || null;
+    this.waitForReply = options.waitForReply || null;
+    this.shouldAskFn = options.shouldAsk || null; // custom predicate override
+  }
+
+  shouldAsk(toolName, args) {
+    if (this.shouldAskFn) return this.shouldAskFn(toolName, args);
+    return this.tools.has(toolName);
+  }
+
+  /**
+   * Send a question and wait for a reply.
+   * @param {string} question - The approval question to send.
+   * @param {object} [context={}] - Context passed to send and waitForReply.
+   * @returns {Promise<string|null>} The user's reply, or null.
+   * @throws {Error} `[Checkpoint] send and waitForReply callbacks required` — when callbacks are missing.
+   */
+  async ask(question, context = {}) {
+    if (!this.send || !this.waitForReply) {
+      throw new Error('[Checkpoint] send and waitForReply callbacks required');
+    }
+    await this.send(question, context);
+    const reply = await this.waitForReply(context);
+    return reply ?? null;
+  }
+}
+
+module.exports = { Checkpoint };

package/src/loop.js

@@ -0,0 +1,163 @@
+'use strict';
+
+class Loop {
+  /**
+   * @param {object} options
+   * @param {object} options.provider - LLM provider (must implement generate()).
+   * @param {number} [options.maxRounds=5] - Maximum think/act/observe cycles.
+   * @param {string} [options.system] - System prompt prepended to messages.
+   * @param {object} [options.checkpoint] - Checkpoint instance for human-in-the-loop.
+   * @param {object} [options.retry] - Retry instance for backoff on failures.
+   * @param {object} [options.stream] - Stream instance for event emission.
+   * @throws {Error} `[Loop] requires a provider` — when options.provider is missing.
+   */
+  constructor(options = {}) {
+    if (!options.provider) throw new Error('[Loop] requires a provider');
+    this.provider = options.provider;
+    this.maxRounds = options.maxRounds || 5;
+    this.system = options.system || null;
+    this.checkpoint = options.checkpoint || null;
+    this.retry = options.retry || null;
+    this.stream = options.stream || null;
+    this.onToolCall = options.onToolCall || null;
+    this.onText = options.onText || null;
+    this.onError = options.onError || null;
+    this._stopped = false;
+    this._history = []; // for chat() stateful mode
+  }
+
+  /**
+   * Run the think/act/observe loop.
+   * @param {Array<object>} messages - Conversation messages in OpenAI format.
+   * @param {Array<object>} [tools=[]] - Tool definitions with name, execute, description, parameters.
+   * @param {object} [options={}] - Per-run overrides (system, temperature, etc.).
+   * @returns {Promise<{text: string, toolCalls: Array, usage: object, error: string|null}>}
+   * @throws {Error} `[Loop] Tool is missing a name` — when a tool has no name or a non-string name.
+   * @throws {Error} `[Loop] Tool "X" is missing an execute() function` — when execute is not a function.
+   * @throws {Error} `[Loop] Tool "X" has invalid parameters` — when parameters is not an object.
+   */
+  async run(messages, tools = [], options = {}) {
+    this._stopped = false;
+    const system = options.system || this.system;
+    const msgs = system
+      ? [{ role: 'system', content: system }, ...messages]
+      : [...messages];
+    const toolMap = new Map(tools.map(t => [t.name, t]));
+
+    // Validate tools at wire time
+    for (const tool of tools) {
+      if (typeof tool.name !== 'string' || !tool.name) {
+        throw new Error(`[Loop] Tool is missing a name (got ${JSON.stringify(tool.name)}). Every tool must have a non-empty string name.`);
+      }
+      if (typeof tool.execute !== 'function') {
+        throw new Error(`[Loop] Tool "${tool.name}" is missing an execute() function.`);
+      }
+      if (tool.description !== undefined && typeof tool.description !== 'string') {
+        console.warn(`[Loop] Tool "${tool.name}" has a non-string description — providers may ignore it.`);
+      }
+      if (tool.parameters !== undefined && (typeof tool.parameters !== 'object' || tool.parameters === null)) {
+        throw new Error(`[Loop] Tool "${tool.name}" has invalid parameters — expected an object, got ${typeof tool.parameters}.`);
+      }
+    }
+
+    this.stream?.emit({ type: 'loop:start', data: { messageCount: msgs.length } });
+
+    let lastUsage = { inputTokens: 0, outputTokens: 0 };
+
+    for (let round = 0; round < this.maxRounds; round++) {
+      if (this._stopped) break;
+
+      let result;
+      try {
+        const generate = () => this.provider.generate(msgs, tools, options);
+        result = this.retry ? await this.retry.call(generate) : await generate();
+      } catch (err) {
+        this.stream?.emit({ type: 'loop:error', data: { error: err.message, round } });
+        this.onError?.(err);
+        return { text: '', toolCalls: [], usage: lastUsage, error: err.message };
+      }
+
+      lastUsage = result.usage || lastUsage;
+
+      // No tool calls — LLM gave a final text response
+      if (!result.toolCalls || result.toolCalls.length === 0) {
+        this.stream?.emit({ type: 'loop:text', data: { text: result.text } });
+        this.onText?.(result.text);
+        this.stream?.emit({ type: 'loop:done', data: { text: result.text, usage: lastUsage } });
+        return { text: result.text, toolCalls: [], usage: lastUsage, error: null };
+      }
+
+      // Execute tool calls
+      msgs.push({
+        role: 'assistant',
+        content: result.text || null,
+        tool_calls: result.toolCalls.map(tc => ({
+          id: tc.id,
+          type: 'function',
+          function: { name: tc.name, arguments: JSON.stringify(tc.arguments) },
+        })),
+      });
+
+      for (const tc of result.toolCalls) {
+        if (this._stopped) break;
+
+        const tool = toolMap.get(tc.name);
+        if (!tool) {
+          const errMsg = `[Loop] Unknown tool: ${tc.name}`;
+          msgs.push({ role: 'tool', tool_call_id: tc.id, content: errMsg });
+          this.stream?.emit({ type: 'loop:tool_result', data: { tool: tc.name, error: errMsg } });
+          continue;
+        }
+
+        // Checkpoint — ask for approval before executing
+        if (this.checkpoint?.shouldAsk(tc.name, tc.arguments)) {
+          this.stream?.emit({ type: 'checkpoint:ask', data: { tool: tc.name, args: tc.arguments } });
+          const reply = await this.checkpoint.ask(
+            `Approve ${tc.name}(${JSON.stringify(tc.arguments)})?`,
+            { tool: tc.name, args: tc.arguments }
+          );
+          this.stream?.emit({ type: 'checkpoint:reply', data: { reply } });
+          if (!reply || reply.toLowerCase() === 'no' || reply.toLowerCase() === 'n') {
+            msgs.push({ role: 'tool', tool_call_id: tc.id, content: 'User denied this action.' });
+            continue;
+          }
+        }
+
+        this.stream?.emit({ type: 'loop:tool_call', data: { tool: tc.name, args: tc.arguments } });
+        this.onToolCall?.(tc.name, tc.arguments);
+
+        try {
+          const execute = () => tool.execute(tc.arguments);
+          const toolResult = this.retry ? await this.retry.call(execute) : await execute();
+          const content = typeof toolResult === 'string' ? toolResult : JSON.stringify(toolResult);
+          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}`;
+          msgs.push({ role: 'tool', tool_call_id: tc.id, content: errMsg });
+          this.stream?.emit({ type: 'loop:tool_result', data: { tool: tc.name, error: errMsg } });
+        }
+      }
+    }
+
+    // maxRounds exceeded
+    const warning = `[Loop] ended after ${this.maxRounds} rounds without final response`;
+    this.stream?.emit({ type: 'loop:done', data: { text: '', warning } });
+    return { text: '', toolCalls: [], usage: lastUsage, error: warning };
+  }
+
+  async chat(text, tools = [], options = {}) {
+    this._history.push({ role: 'user', content: text });
+    const result = await this.run(this._history, tools, options);
+    if (result.text) {
+      this._history.push({ role: 'assistant', content: result.text });
+    }
+    return result;
+  }
+
+  stop() {
+    this._stopped = true;
+  }
+}
+
+module.exports = { Loop };

package/src/memory.js

@@ -0,0 +1,46 @@
+'use strict';
+
+/**
+ * Persistence + search across turns and sessions.
+ * Thin wrapper that delegates to a swappable store.
+ *
+ * Interface:
+ *   store(content, metadata)   → id
+ *   search(query, options)     → [{ id, content, metadata, score }]
+ *   get(id)                    → { content, metadata }
+ *   delete(id)                 → void
+ *
+ * Stores (swappable):
+ *   SQLite FTS5 — store-sqlite.js (peer dep: better-sqlite3)
+ *   JSON file   — store-jsonfile.js (zero deps)
+ *   Bring your own: implement { store, search, get, delete }
+ */
+class Memory {
+  /**
+   * @param {object} options
+   * @param {object} options.store - Store backend (must implement store/search/get/delete).
+   * @throws {Error} `[Memory] requires options.store` — when options.store is missing.
+   */
+  constructor(options = {}) {
+    if (!options.store) throw new Error('[Memory] requires options.store');
+    this._store = options.store;
+  }
+
+  store(content, metadata = {}) {
+    return this._store.store(content, metadata);
+  }
+
+  search(query, options = {}) {
+    return this._store.search(query, options);
+  }
+
+  get(id) {
+    return this._store.get(id);
+  }
+
+  delete(id) {
+    return this._store.delete(id);
+  }
+}
+
+module.exports = { Memory };