bare-agent 0.1.1 → 0.2.1

package/README.md

@@ -13,7 +13,7 @@
 
 # bare-agent
 
-**Agent orchestration in ~800 lines. Zero required deps. MIT license.**
+**Agent orchestration in ~1500 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.
 
@@ -217,12 +217,19 @@ 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:  ~820
+total lines:  ~1500
 ```
 
 ## Status
 
-Early development. Core components built and validated through POCs. See [project plan](docs/01-product/prd.md) for the full design.
+**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:
+
+- **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.
+
+See [project plan](docs/01-product/prd.md) for the full design. See [CHANGELOG.md](CHANGELOG.md) for release history.
 
 ## License
 

package/index.js

@@ -8,6 +8,7 @@ const { Checkpoint } = require('./src/checkpoint');
 const { Memory } = require('./src/memory');
 const { Stream } = require('./src/stream');
 const { Retry } = require('./src/retry');
+const { runPlan } = require('./src/run-plan');
 
 module.exports = {
   Loop,
@@ -18,4 +19,5 @@ module.exports = {
   Memory,
   Stream,
   Retry,
+  runPlan,
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "bare-agent",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "files": [
     "index.js",
     "src/",
@@ -20,7 +20,8 @@
   "exports": {
     ".": "./index.js",
     "./providers": "./src/providers.js",
-    "./stores": "./src/stores.js"
+    "./stores": "./src/stores.js",
+    "./transports": "./src/transports.js"
   },
   "engines": {
     "node": ">=18"

package/src/loop.js

@@ -9,6 +9,7 @@ class Loop {
    * @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.
+   * @param {object} [options.store] - Store instance for validate() health check.
    * @throws {Error} `[Loop] requires a provider` — when options.provider is missing.
    */
   constructor(options = {}) {
@@ -22,6 +23,7 @@ class Loop {
     this.onToolCall = options.onToolCall || null;
     this.onText = options.onText || null;
     this.onError = options.onError || null;
+    this.store = options.store || null;
     this._stopped = false;
     this._history = []; // for chat() stateful mode
   }
@@ -146,6 +148,69 @@ class Loop {
     return { text: '', toolCalls: [], usage: lastUsage, error: warning };
   }
 
+  /**
+   * Health check — validates provider, store, and tools without throwing.
+   * @param {Array<object>} [tools=[]] - Tool definitions to validate.
+   * @returns {Promise<{provider: {ok: boolean, error?: string}, store: {ok: boolean, error?: string, skipped: boolean}, tools: {ok: boolean, errors?: string[]}}>}
+   * Never throws — all failures captured in return value.
+   */
+  async validate(tools = []) {
+    const result = {
+      provider: { ok: false },
+      store: { ok: false, skipped: false },
+      tools: { ok: true },
+    };
+
+    // Provider check
+    try {
+      await this.provider.generate([{ role: 'user', content: 'respond with ok' }], [], {});
+      result.provider.ok = true;
+    } catch (err) {
+      result.provider.error = err.message;
+    }
+
+    // Store check
+    if (!this.store) {
+      result.store.ok = true;
+      result.store.skipped = true;
+    } else {
+      try {
+        const testKey = `__validate_${Date.now()}`;
+        await this.store.store(testKey, { test: true });
+        const got = await this.store.get(testKey);
+        if (got === null || got === undefined) {
+          result.store.error = 'store.get returned null for test key';
+        } else {
+          await this.store.delete(testKey);
+          result.store.ok = true;
+        }
+      } catch (err) {
+        result.store.error = err.message;
+      }
+    }
+
+    // Tools check
+    const toolErrors = [];
+    for (const tool of tools) {
+      if (typeof tool.name !== 'string' || !tool.name) {
+        toolErrors.push(`Tool is missing a name (got ${JSON.stringify(tool.name)})`);
+        continue;
+      }
+      if (typeof tool.execute !== 'function') {
+        toolErrors.push(`Tool "${tool.name}" is missing an execute() function`);
+      }
+      if (tool.parameters !== undefined && (typeof tool.parameters !== 'object' || tool.parameters === null)) {
+        toolErrors.push(`Tool "${tool.name}" has invalid parameters — expected an object, got ${typeof tool.parameters}`);
+      }
+    }
+    if (toolErrors.length > 0) {
+      result.tools.ok = false;
+      result.tools.errors = toolErrors;
+    }
+
+    return result;
+  }
+
   async chat(text, tools = [], options = {}) {
     this._history.push({ role: 'user', content: text });
     const result = await this.run(this._history, tools, options);

package/src/provider-clipipe.js

@@ -0,0 +1,128 @@
+'use strict';
+
+const { spawn } = require('child_process');
+
+class CLIPipeProvider {
+  /**
+   * Provider that pipes prompts to a CLI command via stdin and reads stdout.
+   * @param {object} options
+   * @param {string} options.command - CLI command to spawn (required).
+   * @param {string[]} [options.args=[]] - Arguments to pass to the command.
+   * @param {string} [options.cwd] - Working directory for the child process.
+   * @param {object} [options.env] - Environment variables for the child process.
+   * @param {number} [options.timeout=30000] - Timeout in milliseconds.
+   * @param {string} [options.systemPromptFlag] - CLI flag for system prompt (e.g. '--system'). When set, system messages are extracted and passed via this flag instead of stdin.
+   * @throws {Error} `[CLIPipeProvider] requires command` — when options.command is missing.
+   */
+  constructor(options = {}) {
+    if (!options.command) throw new Error('[CLIPipeProvider] requires command');
+    this.command = options.command;
+    this.args = options.args || [];
+    this.cwd = options.cwd || undefined;
+    this.env = options.env || undefined;
+    this.timeout = options.timeout ?? 30000;
+    this.systemPromptFlag = options.systemPromptFlag || null;
+  }
+
+  /**
+   * Generate a response by piping messages to the CLI command.
+   * @param {Array<object>} messages - Conversation messages in OpenAI format.
+   * @param {Array<object>} [tools=[]] - Unused (CLI commands don't support tools).
+   * @param {object} [options={}] - Unused.
+   * @returns {Promise<{text: string, toolCalls: Array, usage: object}>}
+   * @throws {Error} `[CLIPipeProvider] failed to spawn "cmd": ...` — when the command cannot be found or executed.
+   * @throws {Error} `[CLIPipeProvider] process exited with code N: ...` — on non-zero exit.
+   * @throws {Error} `[CLIPipeProvider] timed out after Nms` — when the process exceeds timeout.
+   * @throws {Error} `[CLIPipeProvider] process produced no output` — when stdout is empty.
+   */
+  async generate(messages, tools = [], options = {}) {
+    let extraArgs = [];
+    let promptMessages = messages;
+
+    if (this.systemPromptFlag) {
+      const systemMessages = messages.filter(m => m.role === 'system');
+      if (systemMessages.length > 0) {
+        const systemContent = systemMessages.map(m => m.content).join('\n\n');
+        extraArgs = [this.systemPromptFlag, systemContent];
+        promptMessages = messages.filter(m => m.role !== 'system');
+      }
+    }
+
+    const prompt = this._formatPrompt(promptMessages);
+    const text = await this._spawn(prompt, extraArgs);
+    return {
+      text,
+      toolCalls: [],
+      usage: { inputTokens: 0, outputTokens: 0 },
+    };
+  }
+
+  /**
+   * Convert OpenAI-format messages to a plain text prompt.
+   * @param {Array<object>} messages
+   * @returns {string}
+   */
+  _formatPrompt(messages) {
+    return messages.map(m => {
+      const role = m.role.charAt(0).toUpperCase() + m.role.slice(1);
+      return `${role}: ${m.content}`;
+    }).join('\n') + '\n';
+  }
+
+  /**
+   * Spawn the CLI process, pipe prompt to stdin, collect stdout.
+   * @param {string} prompt
+   * @param {string[]} [extraArgs=[]] - Additional args prepended to this.args.
+   * @returns {Promise<string>}
+   */
+  _spawn(prompt, extraArgs = []) {
+    return new Promise((resolve, reject) => {
+      const child = spawn(this.command, [...this.args, ...extraArgs], {
+        cwd: this.cwd,
+        env: this.env,
+        stdio: ['pipe', 'pipe', 'pipe'],
+      });
+
+      let stdout = '';
+      let stderr = '';
+      let killed = false;
+
+      child.stdout.on('data', d => { stdout += d; });
+      child.stderr.on('data', d => { stderr += d; });
+
+      child.on('error', err => {
+        reject(new Error(`[CLIPipeProvider] failed to spawn "${this.command}": ${err.message}`));
+      });
+
+      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()}`));
+        }
+        const text = stdout.trim();
+        if (!text) {
+          return reject(new Error('[CLIPipeProvider] process produced no output'));
+        }
+        resolve(text);
+      });
+
+      // Timeout handling
+      const timer = setTimeout(() => {
+        killed = true;
+        child.kill('SIGTERM');
+        setTimeout(() => {
+          try { child.kill('SIGKILL'); } catch (_) {}
+        }, 1000);
+        reject(new Error(`[CLIPipeProvider] timed out after ${this.timeout}ms`));
+      }, this.timeout);
+
+      child.on('close', () => clearTimeout(timer));
+
+      // Write prompt to stdin — catch errors silently (process may exit early)
+      child.stdin.on('error', () => {});
+      child.stdin.end(prompt);
+    });
+  }
+}
+
+module.exports = { CLIPipeProvider };

package/src/providers.js

@@ -3,9 +3,11 @@
 const { OpenAIProvider } = require('./provider-openai');
 const { AnthropicProvider } = require('./provider-anthropic');
 const { OllamaProvider } = require('./provider-ollama');
+const { CLIPipeProvider } = require('./provider-clipipe');
 
 module.exports = {
   OpenAI: OpenAIProvider,
   Anthropic: AnthropicProvider,
   Ollama: OllamaProvider,
+  CLIPipe: CLIPipeProvider,
 };

package/src/run-plan.js

@@ -0,0 +1,122 @@
+'use strict';
+
+/**
+ * Execute a step DAG with wave-based parallelism.
+ * @param {Array<{id: string, action: string, dependsOn?: string[]}>} steps - Steps from Planner.
+ * @param {function} executeFn - Async function called for each step: (step) => result.
+ * @param {object} [options={}]
+ * @param {number} [options.concurrency=Infinity] - Max parallel steps per wave.
+ * @param {object} [options.stateMachine] - StateMachine instance for lifecycle tracking.
+ * @param {function} [options.onStepStart] - Callback(step) fired when a step begins.
+ * @param {function} [options.onStepDone] - Callback(step, result) fired on success.
+ * @param {function} [options.onStepFail] - Callback(step, error) fired on failure.
+ * @param {function} [options.onWaveStart] - Callback(waveNumber, steps) fired before each wave executes.
+ * @returns {Promise<Array<{id: string, status: string, result?: *, error?: string}>>}
+ * @throws {Error} `[runPlan] steps must be a non-empty array` — when steps is not a non-empty array.
+ * @throws {Error} `[runPlan] executeFn must be a function` — when executeFn is not a function.
+ * @throws {Error} `[runPlan] duplicate step id: "X"` — when two steps share an id.
+ * @throws {Error} `[runPlan] step "X" depends on unknown step "Y"` — when dependsOn references missing id.
+ */
+async function runPlan(steps, executeFn, options = {}) {
+  if (!Array.isArray(steps) || steps.length === 0) {
+    throw new Error('[runPlan] steps must be a non-empty array');
+  }
+  if (typeof executeFn !== 'function') {
+    throw new Error('[runPlan] executeFn must be a function');
+  }
+
+  // Build tracking map (don't mutate input)
+  const tracking = new Map();
+  for (const step of steps) {
+    if (tracking.has(step.id)) {
+      throw new Error(`[runPlan] duplicate step id: "${step.id}"`);
+    }
+    tracking.set(step.id, {
+      step: { ...step },
+      status: 'pending',
+      result: undefined,
+      error: undefined,
+    });
+  }
+
+  // Validate dependencies
+  for (const step of steps) {
+    for (const dep of (step.dependsOn || [])) {
+      if (!tracking.has(dep)) {
+        throw new Error(`[runPlan] step "${step.id}" depends on unknown step "${dep}"`);
+      }
+    }
+  }
+
+  const { concurrency = Infinity, stateMachine, onStepStart, onStepDone, onStepFail, onWaveStart } = options;
+
+  let waveNumber = 0;
+
+  // Wave loop
+  while (true) {
+    // Propagate dependency failures
+    for (const [id, entry] of tracking) {
+      if (entry.status !== 'pending') continue;
+      for (const dep of (entry.step.dependsOn || [])) {
+        const depEntry = tracking.get(dep);
+        if (depEntry.status === 'failed') {
+          entry.status = 'failed';
+          entry.error = `dependency '${dep}' failed`;
+          stateMachine?.transition(id, 'start');
+          stateMachine?.transition(id, 'fail', entry.error);
+          onStepFail?.(entry.step, new Error(entry.error));
+          break;
+        }
+      }
+    }
+
+    // Find ready steps: pending + all deps done
+    const ready = [];
+    for (const [id, entry] of tracking) {
+      if (entry.status !== 'pending') continue;
+      const deps = entry.step.dependsOn || [];
+      const allDone = deps.every(dep => tracking.get(dep).status === 'done');
+      if (allDone) ready.push(entry);
+    }
+
+    if (ready.length === 0) break;
+
+    // Apply concurrency limit
+    const wave = ready.slice(0, concurrency);
+
+    waveNumber++;
+    onWaveStart?.(waveNumber, wave.map(e => e.step));
+
+    // Execute wave
+    await Promise.all(wave.map(async entry => {
+      const { step } = entry;
+      entry.status = 'running';
+      stateMachine?.transition(step.id, 'start');
+      onStepStart?.(step);
+
+      try {
+        const result = await executeFn(step);
+        entry.status = 'done';
+        entry.result = result;
+        stateMachine?.transition(step.id, 'complete', result);
+        onStepDone?.(step, result);
+      } catch (err) {
+        entry.status = 'failed';
+        entry.error = err.message;
+        stateMachine?.transition(step.id, 'fail', err.message);
+        onStepFail?.(step, err);
+      }
+    }));
+  }
+
+  // Return results in original order
+  return steps.map(s => {
+    const entry = tracking.get(s.id);
+    const out = { id: s.id, status: entry.status };
+    if (entry.result !== undefined) out.result = entry.result;
+    if (entry.error !== undefined) out.error = entry.error;
+    return out;
+  });
+}
+
+module.exports = { runPlan };

package/src/transports.js

@@ -0,0 +1,3 @@
+'use strict';
+const { JsonlTransport } = require('./transport-jsonl');
+module.exports = { JsonlTransport };