bare-agent 0.12.0 → 0.12.2

package/examples/wake.sh

@@ -0,0 +1,84 @@
+#!/usr/bin/env bash
+# examples/wake.sh — reference scheduler for bareagent's defer queue.
+#
+# This is a *reference*, not a primitive. Copy into your project and modify.
+# See examples/wake.md for the cron entry and customization points.
+#
+# What this script does:
+#   1. Reads the JSONL defer queue file.
+#   2. Folds status-update lines per id (latest wins) using jq.
+#   3. For each pending record whose `when` <= now: appends a "fired" status
+#      line to the queue (atomic JSONL append), then invokes
+#      `bareagent --config <orchestrator>` with the inner action as stdin.
+#   4. Uses flock(1) to prevent overlapping wake invocations.
+#
+# The fired action goes through bareguard's gate AGAIN at fire time — full
+# pipeline against the inner action, separate from the emit-time check.
+# (Two gate.check calls, two distinct audit lines, reconstructable via
+# parent_run_id.)
+
+set -euo pipefail
+
+QUEUE="${BAREAGENT_DEFER_QUEUE:-./bareagent-defers.jsonl}"
+ORCHESTRATOR_CONFIG="${ORCHESTRATOR_CONFIG:-./orchestrator.json}"
+LOCKFILE="${LOCKFILE:-/tmp/bareagent-wake.lock}"
+LOG_DIR="${BAREAGENT_WAKE_LOG_DIR:-/tmp/bareagent-wake}"
+
+mkdir -p "$LOG_DIR"
+
+NOW=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+
+# Single-instance: bail if another wake is running.
+exec 9>"$LOCKFILE"
+if ! flock -n 9; then
+  echo "[wake $NOW] another instance running, exiting" >&2
+  exit 0
+fi
+
+# No queue file = nothing to do.
+if [ ! -f "$QUEUE" ]; then
+  exit 0
+fi
+
+# Reconstruct status by folding all lines per id (latest wins) and filter
+# to records whose `when` <= now AND status == "pending". One JSON object
+# per output line.
+PENDING=$(jq -n -c '
+  reduce inputs as $r ({};
+    .[$r.id] |= (. // {}) + $r
+  )
+  | to_entries
+  | map(.value)
+  | map(select(.status == "pending" and .when <= "'"$NOW"'"))
+  | .[]
+' < "$QUEUE")
+
+if [ -z "$PENDING" ]; then
+  exit 0
+fi
+
+echo "$PENDING" | while IFS= read -r record; do
+  [ -z "$record" ] && continue
+
+  ID=$(echo "$record" | jq -r '.id')
+  ACTION=$(echo "$record" | jq -c '.action')
+
+  # Append "fired" status line first (defer queue is append-only).
+  printf '{"id":"%s","status":"fired","ts":"%s"}\n' "$ID" "$NOW" >> "$QUEUE"
+
+  # Invoke bareagent with the deferred action as stdin input.
+  # Run in background — wake script doesn't wait for completion.
+  ( echo "$ACTION" | bare-agent --config "$ORCHESTRATOR_CONFIG" \
+      >> "$LOG_DIR/fired-$ID.log" 2>&1
+    rc=$?
+    if [ $rc -ne 0 ]; then
+      printf '{"id":"%s","status":"failed","ts":"%s","exit_code":%d}\n' \
+        "$ID" "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" "$rc" >> "$QUEUE"
+    else
+      printf '{"id":"%s","status":"done","ts":"%s"}\n' \
+        "$ID" "$(date -u +"%Y-%m-%dT%H:%M:%SZ")" >> "$QUEUE"
+    fi
+  ) &
+done
+
+wait

package/examples/with-bareguard.mjs

@@ -0,0 +1,65 @@
+// examples/with-bareguard.mjs
+//
+// End-to-end: bareagent Loop + bareguard Gate.
+// Runs a small LLM loop with budget cap, fs scope, audit log, and humanChannel.
+//
+// Run:  OPENAI_API_KEY=... node examples/with-bareguard.mjs
+//
+// What this demonstrates:
+//   - Single-gate governance: every tool call traverses gate.check; every
+//     result reaches gate.record (via wrapTools).
+//   - Budget halt: if accumulated cost exceeds maxCostUsd, gate halts the loop.
+//   - Audit log: one JSONL line per gated event at ./bareagent-audit.jsonl.
+//   - humanChannel: required by bareguard. Here we auto-deny asks; in real use
+//     wire it to a chat platform, terminal prompt, etc.
+
+import { Gate } from 'bareguard';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const { Loop, wireGate } = require('bare-agent');
+const { OpenAI } = require('bare-agent/providers');
+const { createShellTools } = require('bare-agent/tools');
+
+// 1. Build the gate. Every primitive is optional with sensible defaults.
+const gate = new Gate({
+  budget: { maxCostUsd: 0.10 },           // hard USD cap
+  limits: { maxTurns: 20 },                // safety net on think/act cycles
+  fs:     { readScope: ['/tmp', '~/'] },   // shell_read / shell_grep allowed roots
+  bash:   { allow: ['ls', 'cat', 'echo', 'pwd'] },  // argv[0] allowlist for shell_run
+  audit:  { path: './bareagent-audit.jsonl' },
+  // Required by bareguard: any ask/halt event flows through here.
+  // Auto-deny is the safest default for headless use; in real apps, wire to
+  // a Telegram/Slack/terminal prompt and return { decision: 'allow' | 'deny' }.
+  humanChannel: async (event) => {
+    console.warn(`[humanChannel] ${event.kind}: ${event.rule} — auto-denying`);
+    return { decision: 'deny' };
+  },
+});
+await gate.init();
+
+// 2. Wire the gate into Loop's policy slot and wrap tools so gate.record fires.
+const { policy, wrapTools } = wireGate(gate);
+
+// 3. Standard bareagent setup.
+const provider = new OpenAI({
+  apiKey: process.env.OPENAI_API_KEY,
+  model: 'gpt-4o-mini',
+});
+const { tools } = createShellTools();
+
+const loop = new Loop({
+  provider,
+  policy,
+  onError: (err, meta) => console.error(`[onError ${meta.source}]`, err.message),
+});
+
+// 4. Run.
+const result = await loop.run(
+  [{ role: 'user', content: 'List the contents of /tmp using shell_run with argv ["ls", "/tmp"].' }],
+  wrapTools(tools),
+);
+
+console.log('---');
+console.log('text:', result.text);
+console.log('cost:', result.cost?.toFixed(6) ?? 'n/a');
+console.log('audit log → ./bareagent-audit.jsonl');

package/package.json

@@ -1,13 +1,15 @@
 {
   "name": "bare-agent",
-  "version": "0.12.0",
+  "version": "0.12.2",
   "files": [
     "index.js",
     "index.d.ts",
+    "bareagent.context.md",
     "src/",
     "bin/",
     "tools/",
     "types/",
+    "examples/",
     "LICENSE",
     "NOTICE"
   ],
@@ -91,6 +93,7 @@
   "scripts": {
     "test": "node --test --test-force-exit test/**/*.test.js",
     "typecheck": "tsc --noEmit",
+    "prebuild:types": "node scripts/clean-types.js",
     "build:types": "tsc",
     "prepublishOnly": "npm run build:types"
   },

package/src/providers.d.ts

@@ -3,4 +3,4 @@ import { AnthropicProvider } from "./provider-anthropic";
 import { OllamaProvider } from "./provider-ollama";
 import { CLIPipeProvider } from "./provider-clipipe";
 import { FallbackProvider } from "./provider-fallback";
-export { OpenAIProvider as OpenAI, AnthropicProvider as Anthropic, OllamaProvider as Ollama, CLIPipeProvider as CLIPipe, FallbackProvider as Fallback };
+export { OpenAIProvider as OpenAI, AnthropicProvider as Anthropic, OllamaProvider as Ollama, CLIPipeProvider as CLIPipe, FallbackProvider as Fallback, OpenAIProvider, AnthropicProvider, OllamaProvider, CLIPipeProvider, FallbackProvider };

package/src/providers.js

@@ -7,9 +7,17 @@ const { CLIPipeProvider } = require('./provider-clipipe');
 const { FallbackProvider } = require('./provider-fallback');
 
 module.exports = {
+  // Short names (canonical — used throughout docs and the integration guide)
   OpenAI: OpenAIProvider,
   Anthropic: AnthropicProvider,
   Ollama: OllamaProvider,
   CLIPipe: CLIPipeProvider,
   Fallback: FallbackProvider,
+  // *Provider aliases match the class names in source/stack traces, so
+  // `const { OpenAIProvider } = require('bare-agent/providers')` also works.
+  OpenAIProvider,
+  AnthropicProvider,
+  OllamaProvider,
+  CLIPipeProvider,
+  FallbackProvider,
 };