attesso 0.3.1 → 0.4.1

package/README.md

@@ -1,6 +1,6 @@
-# attesso
+# Bounds
 
-A local, signed ledger of what your AI agents attempted, what was allowed, and what was refused. Any action, not only payments. No account, no server, no dependencies.
+Installed as `attesso`: a local, signed ledger of what your AI agents attempted, what was allowed, and what was refused. Free and unlimited on your own machine; $0.0002 per synced decision when the record has to travel. Any action, not only payments. No account, no server, no dependencies.
 
 ```sh
 npx attesso init
@@ -27,6 +27,47 @@ hermes-local-9552aa28437e88c0610a…  2058     455 (22%)  PATH_DENIED×455  3,92
 
 Actions are tool calls; refusals carry the reason; tokens are input plus output, with cache reads shown separately because they bill at a different rate and dwarf the rest. Cost comes from a `llm.session` entry the recorder writes from the agent's own usage record, never from a number the report invents. `--json` gives the same data for a dashboard.
 
+## Setup, explain, suggest
+
+```sh
+npx attesso setup          # detects ~/.hermes/config.yaml, .claude/, .cursor/;
+                           # writes the hook for Hermes, prints the snippet for the rest
+npx attesso setup --dry-run
+npx attesso explain 42     # entry #42: rule, the step that tainted the task, what to do
+npx attesso suggest        # rules the ledger's own counts justify
+```
+
+`setup` also writes an `AGENTS.md` block so the agent knows a veto is active, that a
+refusal is not retryable unchanged, and how to ask about a rule that looks wrong.
+`suggest` is how rules get discovered instead of configured: it counts identical
+calls (same tool, same arguments) and prints a rule with the count that justifies it.
+
+## Wire it into an agent
+
+`attesso hook` speaks the shell-hook contract that Claude Code, Cursor and Hermes
+already use: one tool call on stdin, exit 2 to refuse. Start in observe mode so the
+ledger records what the rules would have refused and nothing is blocked:
+
+```sh
+node bin/attesso.mjs --dir ~/.hermes/attesso-veto/ledger hook --observe
+```
+
+Hermes config (`~/.hermes/config.yaml`), or the same shape in any harness with hooks:
+
+```yaml
+hooks:
+  pre_tool_call:
+    - command: npx attesso --dir ~/.attesso hook
+      timeout: 10
+```
+
+Drop `--observe` when the refusal rate on your own work looks right: a deny then
+exits 2 with a message the agent reads, and the step never runs.
+
+For a long-lived harness, `attesso serve` answers the same questions over one
+process: write one JSON request per line, read one verdict per line. A decision
+costs an IPC round trip instead of a process spawn.
+
 ## What it records
 
 One signed line per proposed action:

package/bin/attesso.mjs

@@ -10,6 +10,9 @@ import { verifyChain } from './../src/ledger.mjs';
 import { formatMinor, toMinor } from './../src/policy.mjs';
 import { append, init, isInitialised, paths, readState } from './../src/store.mjs';
 import { buildReport, renderReport } from './../src/report.mjs';
+import { serve } from './../src/serve.mjs';
+import { decide } from './../src/hook.mjs';
+import { detectHarnesses, explain, suggest, wireHermes, writeAgentContext } from './../src/setup.mjs';
 
 const argv = process.argv.slice(2);
 const dirAt = argv.indexOf('--dir');
@@ -27,6 +30,11 @@ const USAGE = `attesso: a local, signed ledger of what your agents attempted
   attesso verify                     recompute the chain and report the first defect
   attesso show                       what was allowed, what was refused, and why
   attesso report [--json]            per task: actions, refusals with reasons, tokens and cost
+  attesso serve [--observe]          long-lived: one JSON request per line in, one verdict out
+  attesso hook [--observe]           harness hook: reads one tool call on stdin, exits 2 to refuse
+  attesso setup [--dry-run]          detect a harness, wire the hook, write the agent block
+  attesso explain <seq>              one entry in full: rule, tainting step, what to do
+  attesso suggest [--json]           rules the ledger's own counts justify
 
 Any action can be logged, not only payments. --subject is the thing acted on (a
 tool name, a payee, a repo). --task scopes the path, --trust marks where the
@@ -219,6 +227,97 @@ switch (command) {
   case 'show':
     show();
     break;
+  case 'setup': {
+    const dryRun = rest.includes('--dry-run');
+    const harnesses = detectHarnesses();
+    const cli = process.argv[1];
+    const agent = writeAgentContext(DIR, { dryRun });
+    console.log(`agent context: ${agent.changed ? (dryRun ? 'would update' : 'updated') : 'already current'} ${agent.path}`);
+    if (harnesses.length === 0) {
+      console.log('no harness config found in this directory or ~/.hermes');
+      console.log('wire any harness with this contract: run `attesso hook` as a pre_tool_call hook; exit 2 refuses.');
+    }
+    for (const harness of harnesses) {
+      if (harness.key !== 'hermes') {
+        console.log(`${harness.key}: found ${harness.path}; snippet for its pre_tool_call hook:`);
+        console.log(`  ${cli} --dir ${DIR} hook --observe`);
+        continue;
+      }
+      const result = wireHermes(cli, DIR, { dryRun, path: harness.path });
+      console.log(`hermes: ${result.applied ? (dryRun ? 'would wire' : 'wired') : result.reason}`);
+      if (result.snippet && !result.applied) console.log(result.snippet);
+    }
+    break;
+  }
+  case 'explain': {
+    requireLedger();
+    const seq = rest[0];
+    if (!seq) {
+      console.error('attesso explain <seq>');
+      process.exit(1);
+    }
+    const detail = explain(DIR, seq, readState(DIR));
+    if (!detail.found) {
+      console.error(`no entry #${seq} in this ledger`);
+      process.exit(1);
+    }
+    console.log(JSON.stringify(detail, null, 2));
+    break;
+  }
+  case 'suggest': {
+    requireLedger();
+    const proposal = suggest(DIR, readState(DIR));
+    if (rest.includes('--json')) {
+      console.log(JSON.stringify(proposal, null, 2));
+    } else if (proposal.repeats.length === 0) {
+      console.log('no repeats yet: nothing the ledger can justify narrowing');
+    } else {
+      for (const repeat of proposal.repeats) {
+        console.log(`${repeat.id}: ${repeat.why}`);
+        console.log(`  ${JSON.stringify(repeat.rule)}`);
+      }
+    }
+    break;
+  }
+  case 'hook': {
+    requireLedger();
+    const run = decide({ append, dir: DIR, observe: rest.includes('--observe') });
+    let raw = '';
+    process.stdin.setEncoding('utf8');
+    process.stdin.on('data', (chunk) => {
+      raw += chunk;
+    });
+    process.stdin.on('end', () => {
+      let payload;
+      try {
+        payload = JSON.parse(raw || '{}');
+      } catch {
+        console.error('attesso hook: stdin was not JSON, so no decision was made');
+        process.exit(1);
+      }
+      try {
+        const result = run(payload);
+        if (result.exitCode !== 0) {
+          process.stdout.write(`${JSON.stringify({ decision: 'block', message: result.body.message, code: result.body.code })}\n`);
+          process.exit(2);
+        }
+        process.stdout.write(`${JSON.stringify({ decision: result.body.decision, code: result.body.code })}\n`);
+      } catch (error) {
+        // An unwritable ledger is an outage, not a policy decision: say so and
+        // exit 1 so a fail-closed harness can tell the two apart.
+        console.error(`attesso hook: ${error.message}`);
+        process.exit(1);
+      }
+    });
+    break;
+  }
+  case 'serve':
+    requireLedger();
+    serve(DIR, { observe: rest.includes('--observe') }).catch((error) => {
+      console.error(`attesso serve: ${error.message}`);
+      process.exit(1);
+    });
+    break;
   case 'report': {
     requireLedger();
     const report = buildReport(DIR);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "attesso",
-  "version": "0.3.1",
-  "description": "A local, signed ledger of what your AI agents attempted, what was allowed, and what was refused.",
+  "version": "0.4.1",
+  "description": "Bounds: decide an AI agent's next tool call before it runs. Free and unlimited locally, $0.0002 per synced decision.",
   "license": "Apache-2.0",
   "type": "module",
   "bin": {

package/src/hook.mjs

@@ -0,0 +1,76 @@
+import { createHash } from 'node:crypto';
+import { canonical } from './canonical.mjs';
+
+// One decision for a harness hook. Reads the shell-hook payload on stdin
+// ({hook_event_name, tool_name, tool_input, session_id, ...}, the shape Claude
+// Code, Cursor and Hermes all use) and answers in the same contract: exit 2 with
+// a message refuses, exit 0 lets the call run.
+//
+// The mapping from a tool name to (action, capability, trust) is the only
+// harness-specific knowledge here, so every harness shares one policy engine.
+const EXECUTE = new Set(['terminal', 'execute_code', 'process_manage', 'shell', 'bash']);
+const WRITE = new Set(['write_file', 'patch', 'skill_manage', 'str_replace_editor', 'edit']);
+const UNTRUSTED_READ = new Set([
+  'browser_exec',
+  'web_search',
+  'web_extract',
+  'firecrawl',
+  'firecrawl_scrape',
+  'firecrawl_search',
+  'firecrawl_crawl',
+  'firecrawl_map',
+  'firecrawl_extract',
+  'firecrawl_deep_research',
+  'deepseek-search',
+  'ds',
+]);
+
+export function classifyTool(toolName) {
+  const name = String(toolName ?? '').trim();
+  if (UNTRUSTED_READ.has(name)) return { action: 'web.read', capability: 'read', trust: 'untrusted' };
+  if (EXECUTE.has(name)) return { action: 'shell.execute', capability: 'execute', trust: 'internal' };
+  if (WRITE.has(name)) return { action: 'file.write', capability: 'execute', trust: 'internal' };
+  if (/send|mail|post|publish/i.test(name)) return { action: 'message.send', capability: 'send', trust: 'internal' };
+  return { action: 'tool.call', capability: 'read', trust: 'internal' };
+}
+
+// A repeat is the same tool with the same arguments, so the fingerprint of the
+// arguments is what the rule compares. Storing the digest, never the payload: an
+// argument can hold a secret, and the ledger is meant to be shareable.
+export function argsFingerprint(toolInput) {
+  return createHash('sha256').update(canonical(toolInput ?? {})).digest('base64url').slice(0, 16);
+}
+
+export function requestFromPayload(payload) {
+  const { action, capability, trust } = classifyTool(payload.tool_name);
+  return {
+    action,
+    subject: payload.tool_name ?? null,
+    task: payload.session_id ?? 'unknown',
+    trust,
+    capability,
+    meta: { args_hash: argsFingerprint(payload.tool_input) },
+  };
+}
+
+export function decide({ append, dir, observe }) {
+  return (payload) => {
+    const entry = append(dir, requestFromPayload(payload));
+    const refused = entry.decision !== 'ALLOW';
+    return {
+      exitCode: refused && !observe ? 2 : 0,
+      body: {
+        // The harness obeys `decision`, so observe mode must answer allow even
+        // when the verdict is DENY: the ledger keeps the verdict, work continues.
+        decision: refused && !observe ? 'block' : 'allow',
+        verdict: entry.decision,
+        code: entry.code,
+        enforced: refused && !observe,
+        seq: entry.seq,
+        message: entry.meta?.rule
+          ? `Attesso refused ${payload.tool_name}: ${entry.code} by ${entry.meta.rule} (step #${entry.meta.tainted_by} tainted this task). Entry #${entry.seq} in the signed ledger.`
+          : `Attesso refused ${payload.tool_name}: ${entry.code}. Entry #${entry.seq} in the signed ledger.`,
+      },
+    };
+  };
+}

package/src/rules.mjs

@@ -21,7 +21,7 @@ export function validateRules(rules) {
   for (const rule of rules.rules) {
     if (typeof rule.id !== 'string' || rule.id === '') fail('every rule needs an id');
     const deny = rule.deny ?? {};
-    const denies = deny.capabilities ?? (deny.capability ? [deny.capability] : []);
+    const denies = deny.all ? CAPABILITIES : (deny.capabilities ?? (deny.capability ? [deny.capability] : []));
     if (denies.length === 0) fail(`rule ${rule.id} denies nothing`);
     for (const capability of denies) {
       if (!CAPABILITIES.includes(capability)) fail(`rule ${rule.id} denies unknown capability ${capability}`);
@@ -31,9 +31,15 @@ export function validateRules(rules) {
     if (trigger.capability && !CAPABILITIES.includes(trigger.capability)) {
       fail(`rule ${rule.id} triggers on unknown capability ${trigger.capability}`);
     }
-    if (trigger.trust === undefined && trigger.capability === undefined) {
+    const counts = rule.max_steps !== undefined || rule.max_repeats !== undefined;
+    if (!counts && trigger.trust === undefined && trigger.capability === undefined) {
       fail(`rule ${rule.id} has no path condition`);
     }
+    for (const field of ['max_steps', 'max_repeats']) {
+      if (rule[field] !== undefined && (!Number.isInteger(rule[field]) || rule[field] < 1)) {
+        fail(`rule ${rule.id} needs a whole ${field} of at least 1`);
+      }
+    }
     if (trigger.within_minutes !== undefined && (!Number.isInteger(trigger.within_minutes) || trigger.within_minutes < 0)) {
       fail(`rule ${rule.id} needs whole minutes for within_minutes`);
     }
@@ -47,13 +53,32 @@ export function evaluatePath(rules, history, proposal, now = new Date()) {
   if (!rules) return null;
   for (const rule of rules.rules ?? []) {
     const deny = rule.deny ?? {};
-    const denied = deny.capabilities ?? (deny.capability ? [deny.capability] : []);
+    const denied = deny.all ? CAPABILITIES : (deny.capabilities ?? (deny.capability ? [deny.capability] : []));
     if (proposal.capability && !denied.includes(proposal.capability)) continue;
+
+    // A ceiling on the task itself. This is the rule that stops a runaway loop,
+    // which is where an agent's money actually goes missing.
+    if (rule.max_steps !== undefined && history.length >= rule.max_steps) {
+      return { decision: 'DENY', code: 'STEP_LIMIT', rule: rule.id, tainted_by: history.length };
+    }
+    if (rule.max_repeats !== undefined) {
+      const repeats = history.filter(
+        (entry) => entry.subject === proposal.subject && entry.meta?.args_hash === proposal.meta?.args_hash,
+      );
+      if (repeats.length >= rule.max_repeats) {
+        return { decision: 'DENY', code: 'REPEAT_LIMIT', rule: rule.id, tainted_by: repeats[0].seq };
+      }
+    }
     const trigger = rule.if_path ?? {};
+    // Counting rules have no trigger of their own; without this they would fall
+    // through to the path matcher and deny the second call for no reason.
+    if (trigger.trust === undefined && trigger.capability === undefined) continue;
     const window = (trigger.within_minutes ?? 0) * 60_000;
     const hit = [...history].reverse().find((entry) => {
       if (trigger.trust && entry.trust !== trigger.trust) return false;
       if (trigger.capability && entry.capability !== trigger.capability) return false;
+      if (trigger.subject && entry.subject !== trigger.subject) return false;
+      if (trigger.same_arguments && entry.meta?.args_hash !== proposal.meta?.args_hash) return false;
       if (window > 0 && now.getTime() - Date.parse(entry.at) > window) return false;
       return true;
     });

package/src/serve.mjs

@@ -0,0 +1,50 @@
+// A long-lived decision daemon: any harness writes one JSON request per line and
+// reads one verdict per line. The harness keeps the process for its whole
+// session, so a decision costs an IPC round trip instead of a process spawn.
+//
+// A refusal is recorded either way; `enforced` says whether the caller may
+// proceed, which is what makes observe mode trustworthy: the ledger keeps the
+// verdict, the agent keeps working.
+import { createInterface } from 'node:readline';
+import { append } from './store.mjs';
+
+const parse = (line) => {
+  try {
+    return JSON.parse(line);
+  } catch {
+    return null;
+  }
+};
+
+export function serve(dir, { observe = false, input = process.stdin, output = process.stdout } = {}) {
+  const rl = createInterface({ input, crlfDelay: Infinity });
+  rl.on('line', (line) => {
+    const request = parse(line);
+    if (!request) {
+      output.write(`${JSON.stringify({ error: 'request is not JSON' })}\n`);
+      return;
+    }
+    let entry;
+    try {
+      entry = append(dir, request);
+    } catch (error) {
+      // Never answer with a policy verdict when the record could not be written:
+      // an unwritable ledger is an outage, not a decision.
+      output.write(`${JSON.stringify({ id: request.id ?? null, error: String(error.message ?? error) })}\n`);
+      return;
+    }
+    output.write(
+      `${JSON.stringify({
+        id: request.id ?? null,
+        decision: entry.decision,
+        code: entry.code,
+        reason: entry.meta?.rule
+          ? `${entry.meta.rule} (tainted by step #${entry.meta.tainted_by})`
+          : null,
+        enforced: entry.decision === 'ALLOW' || observe ? false : true,
+        seq: entry.seq,
+      })}\n`,
+    );
+  });
+  return new Promise((resolve) => rl.on('close', resolve));
+}

package/src/setup.mjs

@@ -0,0 +1,142 @@
+// Setup, explain and suggest: the three commands that make the loop feel like it
+// configures itself.
+//
+//   setup    detect a harness, wire the hook, leave a short block the agent reads
+//   explain  one ledger entry in full, including what tainted the path
+//   suggest  rules the ledger's own counts justify, ready to accept
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const AGENT_BLOCK = `<!-- attesso:start -->
+A veto is active on your tool calls. When a call is refused you get a tool error naming
+the rule and the step that tainted the task. Do not retry a refused call unchanged:
+read \`attesso explain <seq>\`, take another path, or ask the user whether the rule is
+wrong. To see rules the ledger supports, run \`attesso suggest\`.
+<!-- attesso:end -->`;
+
+function stripAgentBlock(text) {
+  return text.replace(/<!-- attesso:start -->[\s\S]*?<!-- attesso:end -->\n?/g, '');
+}
+
+export function writeAgentContext(dir, { dryRun = false } = {}) {
+  const path = join(process.cwd(), 'AGENTS.md');
+  const existing = existsSync(path) ? readFileSync(path, 'utf8') : '';
+  const next = `${stripAgentBlock(existing).trimEnd()}\n\n${AGENT_BLOCK}\n`;
+  if (dryRun) return { path, changed: next !== existing, preview: AGENT_BLOCK };
+  if (next !== existing) writeFileSync(path, next.startsWith('\n') ? next.slice(1) : next);
+  return { path, changed: next !== existing };
+}
+
+function hermesConfig() {
+  return join(homedir(), '.hermes', 'config.yaml');
+}
+
+const HOOK_BLOCK = (cli, dir) => `hooks:
+  pre_tool_call:
+    - command: ${cli} --dir ${dir} hook --observe
+      timeout: 10
+`;
+
+export function detectHarnesses({ home = homedir(), cwd = process.cwd() } = {}) {
+  const found = [];
+  const hermes = join(home, '.hermes', 'config.yaml');
+  if (existsSync(hermes)) found.push({ key: 'hermes', path: hermes });
+  const claude = join(cwd, '.claude', 'settings.json');
+  if (existsSync(claude)) found.push({ key: 'claude-code', path: claude });
+  const cursor = join(cwd, '.cursor', 'hooks.json');
+  if (existsSync(cursor)) found.push({ key: 'cursor', path: cursor });
+  return found;
+}
+
+// Hermes is the one harness we verify end to end today, so it is the only one we
+// modify. For the others we print the snippet: writing a config format we have not
+// tested against the real product would be a guess, and a guess in a config file is
+// worse than a line of instructions.
+export function wireHermes(cli, dir, { dryRun = false, path = hermesConfig() } = {}) {
+  if (!existsSync(path)) return { applied: false, reason: 'no Hermes config at ~/.hermes/config.yaml' };
+  const text = readFileSync(path, 'utf8');
+  if (/attesso.*hook/.test(text)) return { applied: false, reason: 'already wired' };
+  if (/^hooks:/m.test(text)) {
+    return { applied: false, reason: 'config already has a hooks: block, merge by hand', snippet: HOOK_BLOCK(cli, dir) };
+  }
+  const next = text.replace(/^approvals:/m, `${HOOK_BLOCK(cli, dir)}approvals:`);
+  if (next === text) return { applied: false, reason: 'no anchor to insert before; add the block by hand', snippet: HOOK_BLOCK(cli, dir) };
+  if (!dryRun) {
+    renameSync(path, `${path}.bak`);
+    writeFileSync(path, next);
+  }
+  return { applied: !dryRun, path, snippet: HOOK_BLOCK(cli, dir) };
+}
+
+export function explain(dir, seq, { entries }) {
+  const entry = entries.find((candidate) => candidate.seq === Number(seq));
+  if (!entry) return { found: false, seq };
+  const taintedBy = entry.meta?.tainted_by;
+  const source = taintedBy ? entries.find((candidate) => candidate.seq === taintedBy) : null;
+  return {
+    found: true,
+    seq: entry.seq,
+    action: entry.action,
+    subject: entry.subject,
+    capability: entry.capability,
+    trust: entry.trust,
+    verdict: entry.decision,
+    code: entry.code,
+    rule: entry.meta?.rule ?? null,
+    task: entry.task ?? null,
+    tainted_by: source ? { seq: source.seq, action: source.action, subject: source.subject, trust: source.trust } : null,
+    advice:
+      entry.decision === 'ALLOW'
+        ? 'Nothing to fix: this call was allowed.'
+        : entry.meta?.rule
+          ? `The task read ${source?.subject ?? 'untrusted content'} at step #${taintedBy}. Take another path, or narrow ${entry.meta.rule}.`
+          : 'The call broke the policy, not a path rule. Check the amount, payee or window.',
+  };
+}
+
+const signature = (entry) => `${entry.action}\u0000${entry.subject ?? ''}\u0000${entry.meta?.args_hash ?? ''}`;
+
+export function suggest(dir, { entries, minRepeats = 3 }) {
+  const within = entries.filter((entry) => entry.decision === 'ALLOW');
+  const counts = new Map();
+  for (const entry of within) {
+    const key = `${entry.task ?? ''}\u0000${signature(entry)}`;
+    counts.set(key, (counts.get(key) ?? 0) + 1);
+  }
+  const repeats = [...counts.entries()]
+    .filter(([, count]) => count >= minRepeats)
+    .sort((left, right) => right[1] - left[1])
+    .slice(0, 3)
+    .map(([key, count]) => {
+      const [task, action, subject] = key.split('\u0000');
+      const id = `no-repeat-${subject || action}`.replace(/[^a-z0-9-]/gi, '-').toLowerCase();
+      const capability = capabilityOf(entries, action, subject);
+      return {
+        id,
+        count,
+        task: task || null,
+        rule: {
+          id,
+          deny: { capabilities: [capability] },
+          if_path: { capability, subject, same_arguments: true, within_minutes: 30 },
+        },
+        why: `${count} identical ${action} calls with the same arguments in one task`,
+      };
+    });
+  return { repeats, refusals: refusalSummary(entries) };
+}
+
+function capabilityOf(entries, action, subject) {
+  const match = [...entries].reverse().find((entry) => entry.action === action && (entry.subject ?? '') === subject);
+  return match?.capability ?? 'read';
+}
+
+function refusalSummary(entries) {
+  const counts = new Map();
+  for (const entry of entries) {
+    if (entry.decision === 'ALLOW') continue;
+    counts.set(entry.code, (counts.get(entry.code) ?? 0) + 1);
+  }
+  return [...counts.entries()].map(([code, count]) => ({ code, count })).sort((left, right) => right.count - left.count);
+}