godpowers 0.15.0

package/lib/agent-browser-driver.js

@@ -0,0 +1,215 @@
+/**
+ * Agent Browser Driver
+ *
+ * Wraps the vercel-labs/agent-browser CLI for use as a browser backend
+ * in the runtime verification pipeline. Native Rust binary, headless by
+ * default, accessibility-tree-first interaction model.
+ *
+ * Source: https://github.com/vercel-labs/agent-browser (MIT)
+ *
+ * The driver presents a uniform interface (goto, click, type, expect,
+ * styles, screenshot, close) that runtime-audit and runtime-test consume
+ * regardless of which backend is active.
+ *
+ * Headless contract: agent-browser is headless by default. We never pass
+ * any flag that would change that.
+ *
+ * Public API:
+ *   openSession(opts) -> Promise<void>
+ *   newPage() -> Promise<page-handle>  // Driver acts as both browser and page
+ *   goto(url) -> Promise<void>
+ *   click(selector) -> Promise<void>
+ *   type(selector, text) -> Promise<void>
+ *   fill(selector, text) -> Promise<void>
+ *   isVisible(selector) -> Promise<boolean>
+ *   getStyles(selector) -> Promise<object>
+ *   screenshot(filePath, opts) -> Promise<string>
+ *   evaluate(fn, ...args) -> Promise<any>  // limited support via `eval`
+ *   snapshot() -> Promise<string>           // accessibility tree
+ *   close() -> Promise<void>
+ *   isInstalled() -> bool
+ */
+
+const { execSync } = require('child_process');
+const path = require('path');
+
+/**
+ * Detect agent-browser presence (mirror of bridge.isAgentBrowserInstalled).
+ */
+function isInstalled() {
+  try {
+    execSync('agent-browser --version', {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 5000
+    });
+    return true;
+  } catch (e1) {
+    try {
+      execSync('npx --no-install agent-browser --version', {
+        stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: 5000
+      });
+      return true;
+    } catch (e2) {
+      return false;
+    }
+  }
+}
+
+/**
+ * Run an agent-browser CLI command and return stdout.
+ * Throws on non-zero exit. Times out after 30s default.
+ */
+function run(args, opts = {}) {
+  const cmd = Array.isArray(args) ? args : [args];
+  // Quote arguments containing spaces (best-effort)
+  const argString = cmd.map(a => {
+    const s = String(a);
+    if (/\s/.test(s) && !s.startsWith('"')) return `"${s.replace(/"/g, '\\"')}"`;
+    return s;
+  }).join(' ');
+  const fullCmd = `agent-browser ${argString}`;
+  return execSync(fullCmd, {
+    stdio: ['ignore', 'pipe', 'pipe'],
+    timeout: opts.timeout || 30000,
+    cwd: opts.cwd || process.cwd(),
+    encoding: 'utf8'
+  });
+}
+
+let activeSession = null;
+
+/**
+ * Open a session. agent-browser maintains the browser process between commands.
+ * We mark the driver as having an active session.
+ */
+async function openSession(opts = {}) {
+  if (activeSession) return; // already open
+  // `agent-browser open` with no args launches without navigation
+  try {
+    run(['open'], { cwd: opts.cwd });
+    activeSession = { startedAt: Date.now(), opts };
+  } catch (e) {
+    activeSession = null;
+    throw new Error(`agent-browser open failed: ${e.message}`);
+  }
+}
+
+/**
+ * The driver itself acts as the page handle (single session model).
+ */
+async function newPage() {
+  return module.exports;
+}
+
+async function goto(url) {
+  run(['open', url]);
+}
+
+async function click(selector) {
+  // If selector starts with @ (snapshot ref), use as-is. Otherwise try as CSS.
+  run(['click', selector]);
+}
+
+async function type(selector, text) {
+  run(['type', selector, text]);
+}
+
+async function fill(selector, text) {
+  run(['fill', selector, text]);
+}
+
+async function isVisible(selector) {
+  try {
+    const out = run(['is', 'visible', selector]);
+    return /true/i.test(out);
+  } catch (e) {
+    return false;
+  }
+}
+
+async function getStyles(selector) {
+  try {
+    const out = run(['get', 'styles', selector]);
+    try {
+      return JSON.parse(out);
+    } catch (parseErr) {
+      // CLI returns a key:value lines format on some versions; best-effort parse
+      const result = {};
+      for (const line of out.split('\n')) {
+        const m = line.match(/^([\w-]+):\s*(.+)$/);
+        if (m) result[m[1]] = m[2].trim();
+      }
+      return result;
+    }
+  } catch (e) {
+    return null;
+  }
+}
+
+async function screenshot(filePath, opts = {}) {
+  const args = ['screenshot', filePath];
+  if (opts.fullPage) args.push('--full');
+  run(args);
+  return filePath;
+}
+
+async function evaluate(fn, ...args) {
+  // CLI mode: serialize JS expression. agent-browser supports `eval <js>`.
+  // We can't pass functions directly; only JS expression strings.
+  let expr;
+  if (typeof fn === 'string') {
+    expr = fn;
+  } else if (typeof fn === 'function') {
+    // Best-effort: stringify the function and immediately invoke
+    const fnStr = fn.toString();
+    expr = `(${fnStr})(${args.map(a => JSON.stringify(a)).join(', ')})`;
+  } else {
+    throw new Error('evaluate expects a string or function');
+  }
+  const out = run(['eval', expr]);
+  try {
+    return JSON.parse(out);
+  } catch (e) {
+    return out;
+  }
+}
+
+async function snapshot() {
+  return run(['snapshot']);
+}
+
+async function close() {
+  try {
+    run(['close']);
+  } catch (e) {
+    // Already closed
+  }
+  activeSession = null;
+}
+
+/**
+ * Match the bridge's expected `browser.newPage` and `browser.close`
+ * interface so the higher-level audit/test code can treat agent-browser
+ * the same as Playwright.
+ */
+module.exports = {
+  isInstalled,
+  openSession,
+  newPage,
+  goto,
+  click,
+  type,
+  fill,
+  isVisible,
+  getStyles,
+  screenshot,
+  evaluate,
+  snapshot,
+  close,
+  // Expose run for testing
+  _run: run,
+  // Expose session state
+  _session: () => activeSession,
+  _setSession: (s) => { activeSession = s; }
+};

package/lib/agent-cache.js

@@ -0,0 +1,194 @@
+/**
+ * Agent Cache - opt-in cache of agent outputs keyed by deterministic
+ * input hash. Cache hit = no spawn, no tokens spent.
+ *
+ * Cache key = sha256(agent_name + agent_version + sorted-inputs JSON +
+ *                    state_hash + project_mode)
+ *
+ * Storage: .godpowers/cache/<keyPrefix>/<fullKey>.json
+ * Each entry: {
+ *   key, agent, agent_version, model, ts,
+ *   inputs_hash, state_hash,
+ *   output: <artifact text or structured result>,
+ *   tokens: { in, out },
+ *   ttl_ms,
+ *   expires
+ * }
+ *
+ * Cache is OPT-IN. The orchestrator only consults it when
+ * intent.yaml.budgets.cache === true, or `/god-mode --cache` is set.
+ *
+ * Invalidation:
+ *   - TTL expiration (default 24 hours)
+ *   - state.json hash mismatch (downstream input changed)
+ *   - agent version mismatch (agent was updated)
+ *   - manual: /god-cache-clear (all) or by agent name
+ *
+ * Public API:
+ *   cacheDir(projectRoot) -> string
+ *   key(agent, version, inputs, stateHash) -> string
+ *   get(projectRoot, key) -> entry | null
+ *   put(projectRoot, key, entry) -> path
+ *   has(projectRoot, key) -> bool (and not expired)
+ *   clear(projectRoot, opts) -> { removed: number }
+ *   stats(projectRoot) -> { count, totalBytes, oldestTs }
+ */
+
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+
+const DEFAULT_TTL_MS = 24 * 60 * 60 * 1000; // 24 hours
+
+function cacheDir(projectRoot) {
+  return path.join(projectRoot, '.godpowers', 'cache');
+}
+
+/**
+ * Deterministically compute a cache key.
+ *
+ * inputs is normalized: top-level keys sorted, nested objects sorted
+ * recursively, undefined dropped. Same inputs => same key.
+ */
+function key(agent, agent_version, inputs, stateHash) {
+  const stable = sortKeys(inputs || {});
+  const payload = JSON.stringify({
+    agent: agent || '',
+    agent_version: agent_version || '',
+    state_hash: stateHash || '',
+    inputs: stable
+  });
+  return crypto.createHash('sha256').update(payload).digest('hex');
+}
+
+function sortKeys(obj) {
+  if (Array.isArray(obj)) return obj.map(sortKeys);
+  if (obj && typeof obj === 'object') {
+    const out = {};
+    for (const k of Object.keys(obj).sort()) {
+      if (obj[k] === undefined) continue;
+      out[k] = sortKeys(obj[k]);
+    }
+    return out;
+  }
+  return obj;
+}
+
+function entryPath(projectRoot, k) {
+  // Shard by first 2 chars of key to keep dirs flat
+  return path.join(cacheDir(projectRoot), k.slice(0, 2), `${k}.json`);
+}
+
+function isExpired(entry, now) {
+  if (!entry || !entry.expires) return true;
+  return (now || Date.now()) > Date.parse(entry.expires);
+}
+
+/**
+ * Read a cache entry. Returns null on miss or expired.
+ */
+function get(projectRoot, k) {
+  const p = entryPath(projectRoot, k);
+  if (!fs.existsSync(p)) return null;
+  let entry;
+  try { entry = JSON.parse(fs.readFileSync(p, 'utf8')); }
+  catch (e) { return null; }
+  if (isExpired(entry)) return null;
+  return entry;
+}
+
+function has(projectRoot, k) {
+  return get(projectRoot, k) != null;
+}
+
+/**
+ * Write a cache entry. Returns the file path.
+ */
+function put(projectRoot, k, entry) {
+  const p = entryPath(projectRoot, k);
+  fs.mkdirSync(path.dirname(p), { recursive: true });
+  const ttl = entry.ttl_ms || DEFAULT_TTL_MS;
+  const full = {
+    key: k,
+    ts: new Date().toISOString(),
+    expires: new Date(Date.now() + ttl).toISOString(),
+    ttl_ms: ttl,
+    ...entry
+  };
+  fs.writeFileSync(p, JSON.stringify(full, null, 2));
+  return p;
+}
+
+/**
+ * Clear cache. opts:
+ *   { all: bool, agent: string, expiredOnly: bool, olderThanMs: number }
+ *
+ * Returns { removed: <count>, kept: <count> }.
+ */
+function clear(projectRoot, opts = {}) {
+  const dir = cacheDir(projectRoot);
+  if (!fs.existsSync(dir)) return { removed: 0, kept: 0 };
+
+  let removed = 0;
+  let kept = 0;
+  const now = Date.now();
+  for (const shard of fs.readdirSync(dir)) {
+    const shardPath = path.join(dir, shard);
+    if (!fs.statSync(shardPath).isDirectory()) continue;
+    for (const fname of fs.readdirSync(shardPath)) {
+      const fpath = path.join(shardPath, fname);
+      let entry;
+      try { entry = JSON.parse(fs.readFileSync(fpath, 'utf8')); }
+      catch (e) { fs.unlinkSync(fpath); removed++; continue; }
+      let shouldRemove = false;
+      if (opts.all) shouldRemove = true;
+      else if (opts.agent && entry.agent === opts.agent) shouldRemove = true;
+      else if (opts.expiredOnly && isExpired(entry, now)) shouldRemove = true;
+      else if (opts.olderThanMs && (now - Date.parse(entry.ts)) > opts.olderThanMs) shouldRemove = true;
+      if (shouldRemove) { fs.unlinkSync(fpath); removed++; }
+      else kept++;
+    }
+    // Remove empty shard dirs
+    if (fs.readdirSync(shardPath).length === 0) fs.rmdirSync(shardPath);
+  }
+  return { removed, kept };
+}
+
+/**
+ * Stats: count, total bytes, oldest entry timestamp.
+ */
+function stats(projectRoot) {
+  const dir = cacheDir(projectRoot);
+  if (!fs.existsSync(dir)) return { count: 0, totalBytes: 0, oldestTs: null };
+
+  let count = 0;
+  let totalBytes = 0;
+  let oldestTs = null;
+  for (const shard of fs.readdirSync(dir)) {
+    const shardPath = path.join(dir, shard);
+    if (!fs.statSync(shardPath).isDirectory()) continue;
+    for (const fname of fs.readdirSync(shardPath)) {
+      const fpath = path.join(shardPath, fname);
+      const stat = fs.statSync(fpath);
+      totalBytes += stat.size;
+      count += 1;
+      try {
+        const entry = JSON.parse(fs.readFileSync(fpath, 'utf8'));
+        if (!oldestTs || entry.ts < oldestTs) oldestTs = entry.ts;
+      } catch (e) { /* skip */ }
+    }
+  }
+  return { count, totalBytes, oldestTs };
+}
+
+module.exports = {
+  cacheDir,
+  key,
+  get,
+  put,
+  has,
+  clear,
+  stats,
+  isExpired,
+  DEFAULT_TTL_MS
+};

package/lib/agent-validator.js

@@ -0,0 +1,275 @@
+/**
+ * Agent Validator
+ *
+ * Parses each `agents/*.md` and validates contract structure.
+ *
+ * Backward-compatible by design: most issues surface as `warning` so
+ * existing agents pass on day one. Only structural breakage (broken
+ * hand-off targets, dual-ownership of output paths) escalates to
+ * `error`.
+ *
+ * Public API:
+ *   parseAgentFile(filePath) -> { name, frontmatter, sections, raw }
+ *   validateAgent(agent, opts) -> [findings]
+ *   findHandoffTargets(agent) -> [...names]
+ *   findOutputPaths(agent) -> [...paths]
+ *   auditAll(projectRoot, opts) -> { results, summary }
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const REQUIRED_FRONTMATTER = ['name', 'description'];
+const RECOMMENDED_FRONTMATTER = ['tools'];
+const RECOMMENDED_SECTIONS = ['Have-Nots', 'Inputs', 'Outputs', 'Handoff'];
+
+/**
+ * Parse a single agent .md file. Extract YAML frontmatter and section
+ * headings (# / ## / ###).
+ */
+function parseAgentFile(filePath) {
+  const raw = fs.readFileSync(filePath, 'utf8');
+  const result = {
+    path: filePath,
+    name: path.basename(filePath, '.md'),
+    frontmatter: {},
+    sections: {},  // heading -> body string
+    raw
+  };
+
+  // Frontmatter block: --- ... ---
+  if (raw.startsWith('---')) {
+    const end = raw.indexOf('\n---', 3);
+    if (end > 0) {
+      const fmBlock = raw.slice(3, end).trim();
+      // Parse simple YAML (key: value, key: |, etc.)
+      let currentMultiline = null;
+      for (const line of fmBlock.split('\n')) {
+        if (currentMultiline) {
+          if (line.startsWith(' ') || line.startsWith('\t')) {
+            result.frontmatter[currentMultiline] += '\n' + line.trim();
+            continue;
+          }
+          currentMultiline = null;
+        }
+        const m = line.match(/^([\w-]+):\s*(.*)$/);
+        if (m) {
+          if (m[2] === '|' || m[2] === '>') {
+            currentMultiline = m[1];
+            result.frontmatter[m[1]] = '';
+          } else {
+            result.frontmatter[m[1]] = m[2].trim();
+          }
+        }
+      }
+    }
+  }
+
+  // Sections: lines starting with # / ## / ###
+  const lines = raw.split('\n');
+  let currentHeading = null;
+  let currentBody = [];
+  for (const line of lines) {
+    const m = line.match(/^(#{1,4})\s+(.+?)\s*$/);
+    if (m) {
+      if (currentHeading) {
+        result.sections[currentHeading] = currentBody.join('\n').trim();
+      }
+      currentHeading = m[2].trim();
+      currentBody = [];
+    } else if (currentHeading) {
+      currentBody.push(line);
+    }
+  }
+  if (currentHeading) {
+    result.sections[currentHeading] = currentBody.join('\n').trim();
+  }
+
+  return result;
+}
+
+/**
+ * Validate one parsed agent. Returns findings.
+ */
+function validateAgent(agent, opts = {}) {
+  const findings = [];
+
+  // Required frontmatter
+  for (const field of REQUIRED_FRONTMATTER) {
+    if (!agent.frontmatter[field]) {
+      findings.push({
+        severity: 'error',
+        kind: 'missing-required-frontmatter',
+        agent: agent.name,
+        message: `Missing required frontmatter field: \`${field}\``
+      });
+    }
+  }
+
+  // Recommended frontmatter
+  for (const field of RECOMMENDED_FRONTMATTER) {
+    if (!agent.frontmatter[field]) {
+      findings.push({
+        severity: 'warning',
+        kind: 'missing-recommended-frontmatter',
+        agent: agent.name,
+        message: `Missing recommended frontmatter field: \`${field}\``
+      });
+    }
+  }
+
+  // Recommended sections (case-insensitive substring match)
+  const sectionTitles = Object.keys(agent.sections).map(s => s.toLowerCase());
+  for (const section of RECOMMENDED_SECTIONS) {
+    const lower = section.toLowerCase();
+    const found = sectionTitles.some(t =>
+      t === lower || t.includes(lower) || (lower === 'handoff' && t.includes('hand'))
+    );
+    if (!found) {
+      findings.push({
+        severity: 'info',
+        kind: 'missing-recommended-section',
+        agent: agent.name,
+        message: `Missing recommended section: \`## ${section}\``,
+        suggestion: `Add a "${section}" section documenting the contract.`
+      });
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Extract claimed hand-off targets (other agents this agent spawns).
+ */
+function findHandoffTargets(agent) {
+  const targets = new Set();
+  // Look for "spawn god-x", "Spawned by:", "spawns: [god-y, god-z]"
+  const text = agent.raw;
+
+  // "Spawned by:" indicates UPSTREAM (who spawns me); skip
+  // We want DOWNSTREAM: who do I spawn?
+
+  const spawnRegex = /spawn(?:s|ed|ing)?\s+(?:a\s+)?(?:fresh\s+)?`?(god-[\w-]+)`?/gi;
+  let m;
+  while ((m = spawnRegex.exec(text)) !== null) {
+    targets.add(m[1]);
+  }
+  return [...targets];
+}
+
+/**
+ * Extract output paths the agent claims to write.
+ */
+function findOutputPaths(agent) {
+  const paths = new Set();
+  const text = agent.raw;
+
+  // .godpowers/*.md or .godpowers/*.json
+  const dotPathRegex = /(?:writes?|appends?|updates?)[\s\S]{0,80}?(\.godpowers\/[\w\/.-]+\.(?:md|json|jsonl|yaml))/gi;
+  let m;
+  while ((m = dotPathRegex.exec(text)) !== null) {
+    paths.add(m[1]);
+  }
+
+  // Project-root files (DESIGN.md, PRODUCT.md, AGENTS.md, etc.)
+  const rootRegex = /(?:writes?|appends?|updates?)[\s\S]{0,80}?\b([A-Z]+\.md)\b/g;
+  while ((m = rootRegex.exec(text)) !== null) {
+    paths.add(m[1]);
+  }
+
+  return [...paths];
+}
+
+/**
+ * Cross-agent validation: dual-ownership of output paths, unresolved
+ * hand-off targets.
+ */
+function crossValidate(agents, opts = {}) {
+  const findings = [];
+  const validAgentNames = new Set(agents.map(a => a.name));
+  const outputOwners = {};  // path -> [agent.name, ...]
+
+  for (const agent of agents) {
+    // Hand-off targets must exist
+    for (const target of findHandoffTargets(agent)) {
+      if (!validAgentNames.has(target)) {
+        findings.push({
+          severity: 'warning',
+          kind: 'unresolved-handoff',
+          agent: agent.name,
+          message: `Agent claims to spawn \`${target}\` but no such agent file exists.`
+        });
+      }
+    }
+
+    // Track output paths
+    for (const out of findOutputPaths(agent)) {
+      if (!outputOwners[out]) outputOwners[out] = [];
+      if (!outputOwners[out].includes(agent.name)) {
+        outputOwners[out].push(agent.name);
+      }
+    }
+  }
+
+  // Dual-ownership check (warn for paths claimed by 3+ agents; the
+  // orchestrator + reconciler + author triumvirate is normal pattern)
+  for (const [outPath, owners] of Object.entries(outputOwners)) {
+    if (owners.length >= 4) {
+      findings.push({
+        severity: 'warning',
+        kind: 'multi-ownership',
+        path: outPath,
+        owners,
+        message: `Output \`${outPath}\` is claimed by ${owners.length} agents: ${owners.join(', ')}. Verify the boundaries are clean.`
+      });
+    }
+  }
+
+  return findings;
+}
+
+/**
+ * Walk agents/ and audit all.
+ */
+function auditAll(projectRoot, opts = {}) {
+  const agentsDir = path.join(projectRoot, 'agents');
+  if (!fs.existsSync(agentsDir)) {
+    return { results: [], summary: { errors: 0, warnings: 0, infos: 0 } };
+  }
+  const files = fs.readdirSync(agentsDir).filter(f => f.endsWith('.md'));
+  const agents = files.map(f => parseAgentFile(path.join(agentsDir, f)));
+
+  const allFindings = [];
+  const results = [];
+  for (const agent of agents) {
+    const f = validateAgent(agent, opts);
+    results.push({ agent: agent.name, findings: f });
+    allFindings.push(...f);
+  }
+  // Cross-agent
+  const crossFindings = crossValidate(agents, opts);
+  allFindings.push(...crossFindings);
+
+  const summary = {
+    errors: allFindings.filter(f => f.severity === 'error').length,
+    warnings: allFindings.filter(f => f.severity === 'warning').length,
+    infos: allFindings.filter(f => f.severity === 'info').length,
+    crossFindings,
+    agentCount: agents.length
+  };
+
+  return { results, summary, allFindings };
+}
+
+module.exports = {
+  parseAgentFile,
+  validateAgent,
+  findHandoffTargets,
+  findOutputPaths,
+  crossValidate,
+  auditAll,
+  REQUIRED_FRONTMATTER,
+  RECOMMENDED_FRONTMATTER,
+  RECOMMENDED_SECTIONS
+};