bare-agent 0.1.1 → 0.2.0

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.0",
   "files": [
     "index.js",
     "src/",

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,113 @@
+'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.
+   * @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;
+  }
+
+  /**
+   * 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 = {}) {
+    const prompt = this._formatPrompt(messages);
+    const text = await this._spawn(prompt);
+    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
+   * @returns {Promise<string>}
+   */
+  _spawn(prompt) {
+    return new Promise((resolve, reject) => {
+      const child = spawn(this.command, this.args, {
+        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,116 @@
+'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.
+ * @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 } = options;
+
+  // 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);
+
+    // 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 };