attesso 0.4.0 → 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,21 @@ 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

package/bin/attesso.mjs

@@ -12,6 +12,7 @@ import { append, init, isInitialised, paths, readState } from './../src/store.mj
 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');
@@ -31,6 +32,9 @@ const USAGE = `attesso: a local, signed ledger of what your agents attempted
   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
@@ -223,6 +227,58 @@ 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') });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "attesso",
-  "version": "0.4.0",
-  "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

@@ -1,3 +1,6 @@
+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
@@ -31,6 +34,13 @@ export function classifyTool(toolName) {
   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 {
@@ -39,6 +49,7 @@ export function requestFromPayload(payload) {
     task: payload.session_id ?? 'unknown',
     trust,
     capability,
+    meta: { args_hash: argsFingerprint(payload.tool_input) },
   };
 }
 

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/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);
+}