attesso 0.6.1 → 0.7.0

package/README.md

@@ -1,6 +1,6 @@
 # Bounds
 
-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.00085 per synced decision when the record has to travel. Any action, not only payments. No account, no hosted backend, 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.00085 per synced decision when the record has to travel. Any action, not only payments. No account for local use, no runtime dependencies; hosted sync is the paid tier.
 
 ```sh
 npx attesso init
@@ -29,6 +29,25 @@ The server binds `127.0.0.1`, mints a per-process token, and serves the page fro
 the installed package. It has no account, no hosted data, and no dependency on a
 snapshot file. `Ctrl-C` stops it.
 
+## Hosted sync
+
+Hosted sync is the paid tier: it mirrors the next decisions into the Attesso
+workspace so the hosted view can follow them from any machine. The local ledger
+stays the source of truth. The command sends at most 50 rows per run, advances a
+cursor under `.attesso/sync.json` only after the server confirms, and never sends
+arguments or credentials:
+
+```sh
+export ATTESSO_SYNC_URL=https://api.attesso.com
+export ATTESSO_API_KEY=att_live_...
+npx attesso sync --dry-run
+npx attesso sync
+```
+
+The API key must belong to an entitled live workspace. A retry after a failed
+request is safe: the server deduplicates by device and sequence, and the local
+cursor does not move until the batch is accepted.
+
 ## The overview
 
 `attesso report` is the view that answers what the thing cost and what it stopped, per task:

package/bin/attesso.mjs

@@ -29,6 +29,7 @@ import { resolve } from 'node:path';
 import { CAPABILITIES, TRUST_LEVELS, validateRules } from './../src/rules.mjs';
 import { validatePathsConfig } from './../src/fs-paths.mjs';
 import { startUi } from './../src/ui/server.mjs';
+import { sync } from './../src/sync.mjs';
 
 const argv = process.argv.slice(2);
 const dirAt = argv.indexOf('--dir');
@@ -76,6 +77,9 @@ const USAGE = `attesso: a local, signed ledger of what your agents attempted
   attesso mode [observe|enforce|off]  read or set the active hook mode
   attesso paths [--json|--set FILE]   read or replace the filesystem scope
   attesso ui [--port N] [--no-open]    local control surface for the signed ledger
+  attesso sync [--url URL] [--limit N] [--json] [--dry-run]
+                                     send the next decisions to the hosted mirror
+                                     (key from ATTESSO_API_KEY; never printed)
   attesso explain <seq>              one entry in full: rule, tainting step, what to do
   attesso suggest [--json]           rules the ledger's own counts justify
   attesso tools pin --manifest PATH  pin the tool definitions a decision was made under
@@ -620,6 +624,26 @@ switch (command) {
     }
     break;
   }
+  case 'sync': {
+    try {
+      const options = flags(rest);
+      const requested = options.limit === undefined ? 50 : Number(options.limit);
+      const result = await sync({
+        dir: DIR,
+        url: typeof options.url === 'string' ? options.url : process.env.ATTESSO_SYNC_URL,
+        key: typeof options.key === 'string' ? options.key : process.env.ATTESSO_API_KEY,
+        limit: requested,
+        dryRun: rest.includes('--dry-run'),
+      });
+      if (options.json) console.log(JSON.stringify(result, null, 2));
+      else if (result.dry_run) console.log(`sync dry run: ${result.entries} decision(s) ready`);
+      else console.log(`sync: ${result.accepted} accepted, ${result.skipped} already present, ${result.metered} metered; last #${result.last_seq}`);
+    } catch (error) {
+      console.error(`sync: ${error.message}`);
+      process.exit(2);
+    }
+    break;
+  }
   case 'ui': {
     try {
       const options = flags(rest);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "attesso",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "Bounds: decide an AI agent's next tool call before it runs, with a signed record. Free and unlimited locally, $0.00085 per synced decision.",
   "license": "Apache-2.0",
   "type": "module",

package/src/sync.mjs

@@ -0,0 +1,114 @@
+// Hosted sync: upload the next bounded window of local decisions to Attesso.
+// The local ledger stays authoritative; this only mirrors summary rows and
+// advances a durable cursor after the server confirms the batch.
+import { existsSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { entryHash } from './ledger.mjs';
+import { forEachEntrySync } from './stream.mjs';
+import { paths, readKey } from './store.mjs';
+
+export const SYNC_VERSION = 1;
+export const DEFAULT_LIMIT = 50;
+
+export function syncPath(dir) {
+  return join(dir, 'sync.json');
+}
+
+export function readSyncState(dir) {
+  const file = syncPath(dir);
+  if (!existsSync(file)) return { version: SYNC_VERSION, last_seq: 0 };
+  const value = JSON.parse(readFileSync(file, 'utf8'));
+  if (value.version !== SYNC_VERSION || !Number.isSafeInteger(value.last_seq) || value.last_seq < 0) {
+    throw new Error('sync state is invalid');
+  }
+  return value;
+}
+
+function writeSyncState(dir, lastSeq, deviceId) {
+  const file = syncPath(dir);
+  const temporary = `${file}.${process.pid}.tmp`;
+  writeFileSync(temporary, `${JSON.stringify({ version: SYNC_VERSION, device_id: deviceId, last_seq: lastSeq }, null, 2)}\n`, { mode: 0o600 });
+  renameSync(temporary, file);
+}
+
+function endpoint(base) {
+  const parsed = new URL(base);
+  if (parsed.protocol !== 'https:' && parsed.hostname !== '127.0.0.1' && parsed.hostname !== 'localhost') {
+    throw new Error('sync url must use HTTPS, except on localhost');
+  }
+  const path = parsed.pathname.replace(/\/+$/, '');
+  parsed.pathname = path.endsWith('/v1/bounds/sync') ? path : `${path}/v1/bounds/sync`;
+  return parsed.toString();
+}
+
+export async function sync({
+  dir,
+  url,
+  key,
+  limit = DEFAULT_LIMIT,
+  dryRun = false,
+  fetchImpl = fetch,
+} = {}) {
+  if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+    throw new Error('limit must be an integer from 1 to 100');
+  }
+  const ledgerPath = paths(dir).ledger;
+  if (!existsSync(ledgerPath)) throw new Error('no ledger to sync');
+  if (!url) throw new Error('sync url is required');
+  if (!key && !dryRun) throw new Error('sync API key is required');
+  const deviceId = readKey(dir).kid;
+  if (typeof deviceId !== 'string' || !/^[A-Za-z0-9._:-]{1,64}$/.test(deviceId)) {
+    throw new Error('ledger key id is not a valid device id');
+  }
+  const state = readSyncState(dir);
+  const entries = [];
+  forEachEntrySync(ledgerPath, (entry) => {
+    if (entry.seq <= state.last_seq) return;
+    if (entries.length >= limit) return false;
+    entries.push({
+      seq: entry.seq,
+      occurred_at: entry.at,
+      action: entry.action,
+      subject: entry.subject ?? null,
+      capability: entry.capability ?? null,
+      decision: entry.decision,
+      code: entry.code,
+      task: entry.task ?? null,
+      entry_hash: entryHash(entry),
+    });
+  });
+  if (entries.length === 0) {
+    return { accepted: 0, skipped: 0, metered: 0, last_seq: state.last_seq, device_id: deviceId };
+  }
+  const body = { device_id: deviceId, entries };
+  if (dryRun) {
+    return { accepted: 0, skipped: 0, metered: 0, last_seq: state.last_seq, device_id: deviceId, dry_run: true, entries: entries.length };
+  }
+  const response = await fetchImpl(endpoint(url), {
+    method: 'POST',
+    headers: {
+      Authorization: `Bearer ${key}`,
+      'Content-Type': 'application/json',
+    },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(20_000),
+  });
+  let payload;
+  try {
+    payload = await response.json();
+  } catch {
+    throw new Error(`sync failed with status ${response.status}`);
+  }
+  if (!response.ok) {
+    throw new Error(`sync failed with status ${response.status}`);
+  }
+  const accepted = Number(payload.accepted);
+  const skipped = Number(payload.skipped);
+  const metered = Number(payload.metered);
+  if (![accepted, skipped, metered].every(Number.isSafeInteger) || accepted < 0 || skipped < 0 || metered < 0) {
+    throw new Error('sync response is invalid');
+  }
+  const lastSeq = entries[entries.length - 1].seq;
+  writeSyncState(dir, lastSeq, deviceId);
+  return { accepted, skipped, metered, last_seq: lastSeq, device_id: deviceId };
+}