@shomra/agent 0.3.9 → 0.3.11

package/discovery.mjs

@@ -21,6 +21,7 @@ import path from 'node:path';
 import os from 'node:os';
 import { execFileSync } from 'node:child_process';
 import { scanAiUsage, rollupAiUsage, isAiUsageScannable, AI_USAGE_CATEGORY_LABEL } from './ai-usage.mjs';
+import { clampAsset } from './wire-limits.mjs';
 import { readVendorPosture, canonicalGrant } from './agent-posture.mjs';
 
 const HOME = os.homedir();
@@ -953,11 +954,20 @@ export function discoverAll(roots = [process.cwd()], opts = {}) {
     ...discoverCodingAgents(scanRoots),
     ...discoverModelKeys(),
   ];
+  // ⚠ CLAMPED BEFORE DEDUP, and before anything leaves this function. A report is
+  // validated all-or-nothing, so ONE over-long field — an MCP server launched by
+  // an inline `node -e '<1675 chars>'` is the case that found this — rejects the
+  // whole payload and costs the machine its entire inventory. Clamping first also
+  // means the dedup key below is the key the backend will see, so a value that
+  // was abbreviated on the wire cannot dedup differently here than it does there.
+  // See wire-limits.mjs for why truncation carries a fingerprint.
+  const clamped = all.map(clampAsset);
+
   // Final dedup by (type, identifier) — a runtime can be found by both dir and
   // process; an env key can also appear in a .env file.
   const seen = new Set();
   const out = [];
-  for (const a of all) {
+  for (const a of clamped) {
     const key = `${a.type}::${a.identifier || a.name}`;
     if (seen.has(key)) continue;
     seen.add(key);

package/guard-ledger.mjs

@@ -0,0 +1,239 @@
+/**
+ * ─── THE FAIL-OPEN LEDGER (client half) ─────────────────────────────────────
+ *
+ * ── Why this exists ─────────────────────────────────────────────────────────
+ *
+ * The pre-tool-call guard FAILS OPEN, and it has to: an agent that hard-stops
+ * because a SaaS backend is unreachable is an agent nobody keeps installed. The
+ * breaker in `shomra.mjs` makes that cheap — once the backend times out, the
+ * next calls skip the round-trip entirely for a cooldown window.
+ *
+ * ⚠ THE CONSEQUENCE IS THAT AN OUTAGE IS INVISIBLE ON THE SERVER. Every runtime
+ * claim Shomra makes counts rows the backend WROTE, so a breaker-open window
+ * produces no rows at all — byte-for-byte what a quiet, clean window produces.
+ * "The guard was down for six hours" and "the guard saw nothing dangerous" are
+ * the same evidence, and a reader takes the reassuring one.
+ *
+ * This module is the other end of `src/gate/enforcement-availability.ts` in the
+ * backend. It remembers what this machine did while it was blind, and hands it
+ * over on the next call that gets through — turning an absence of evidence into
+ * evidence of an absence.
+ *
+ * ── ⚠ THE RULES ─────────────────────────────────────────────────────────────
+ *
+ * 1. **The envelope is sent ALWAYS, even empty.** Its PRESENCE is what tells the
+ *    backend this client is CAPABLE of reporting an outage. An old client sends
+ *    nothing, and nothing is also what a healthy client would send if this were
+ *    "optimised" to omit the empty case — at which point every healthy estate
+ *    becomes indistinguishable from an unobservable one. That change would look
+ *    like a bandwidth win in review. It is the whole feature.
+ *
+ * 2. **Only calls that WOULD have been screened are counted.** A call the guard
+ *    deliberately never escalates (benign, locally cleared, not policy-relevant
+ *    — the bulk of them) is a stated design boundary, not a gap. Counting those
+ *    would report every healthy machine as ~90% blind and the number would be
+ *    ignored within a week.
+ *
+ * 3. **Counts are LOWER BOUNDS and are allowed to be.** Hooks run as concurrent
+ *    short-lived processes, so two of them can read-modify-write this file at
+ *    once and lose an increment. The backend already treats every count here as
+ *    a floor for exactly this reason. ⚠ Do not "fix" that by making the writes
+ *    heavier — a lock on the firewall's hot path costs more than the precision
+ *    is worth, and the number is a floor either way.
+ *
+ * 4. **A window we cannot attest the END of closes as `null`, never as now().**
+ *    If this machine slept, crashed, or was rebooted mid-outage, the window on
+ *    disk is stale and we genuinely do not know when it ended. `closedAt: null`
+ *    is the backend's "we were never told it ended" — which it grades as
+ *    unmeasurable rather than as a zero-length blip.
+ *
+ * 5. **Nothing is ever DROPPED to stay under the cap.** Over the limit, the
+ *    oldest windows MERGE into one aggregate that keeps their summed counts and
+ *    spans their range. Truncating the list instead would silently delete
+ *    evidence of blindness, which is the one direction this file must never
+ *    fail in.
+ *
+ * PURE state machine + thin file I/O, split so the state rules are testable
+ * without a filesystem (`tests/guard-ledger.test.mjs`).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Max gaps in one envelope. Matches `@ArrayMaxSize(50)` on the backend DTO. */
+export const MAX_GAPS = 50;
+
+/**
+ * How long an open window may sit on disk before we stop claiming to know when
+ * it ended. Six hours: comfortably longer than any real outage a 30s breaker
+ * cooldown produces, and short enough that a laptop closed overnight does not
+ * come back claiming a 14-hour measured blackout.
+ */
+export const STALE_WINDOW_MS = 6 * 60 * 60 * 1000;
+
+/** The empty ledger. */
+export const emptyLedger = () => ({ open: null, pending: [] });
+
+/* ── The state machine (pure) ───────────────────────────────────────────── */
+
+/**
+ * Begin a window, or leave an already-open one alone.
+ *
+ * ⚠ IDEMPOTENT ON PURPOSE. The breaker trips on every failed call, not just the
+ * first, so a naive implementation would start a fresh window per call and
+ * report a 200-call outage as 200 one-call outages — each with a tiny count,
+ * none of them showing the real shape. The FIRST failure owns the window.
+ */
+export function openWindow(state, { at, reason }) {
+  const s = state ?? emptyLedger();
+  if (s.open) return s;
+  return { ...s, open: { openedAt: at, reason: String(reason || 'unknown').slice(0, 200), unscreened: 0, local: 0 } };
+}
+
+/**
+ * Record one call that ran without a server verdict.
+ *
+ * `kind` is `'local'` when the on-machine Tier-0 engine screened it (a weaker
+ * screen — no org policy, no identity, no flow, no supply chain, no intent) and
+ * `'unscreened'` when nothing did.
+ *
+ * ⚠ IT OPENS A WINDOW IF NONE IS OPEN. A count with nowhere to live would be
+ * dropped, and the paths that skip the round-trip (`breakerOpen()`) do not
+ * themselves fail, so they never call `openWindow` on their own.
+ */
+export function countCall(state, { at, kind, reason }) {
+  const s = openWindow(state, { at, reason: reason || 'breaker-open' });
+  const open = { ...s.open };
+  if (kind === 'unscreened') open.unscreened += 1;
+  else open.local += 1;
+  return { ...s, open };
+}
+
+/**
+ * End the open window and move it to the outbox.
+ *
+ * ⚠ A window that recorded NOTHING is discarded rather than reported. A breaker
+ * that tripped on a call and healed before the next one cost no coverage, and a
+ * zero-call gap row would be noise that makes the real ones harder to see.
+ */
+export function closeWindow(state, { at, staleMs = STALE_WINDOW_MS } = {}) {
+  const s = state ?? emptyLedger();
+  if (!s.open) return s;
+  const { openedAt, reason, unscreened, local } = s.open;
+  if (!unscreened && !local) return { ...s, open: null };
+  // Rule 4: too old to attest an end for.
+  const stale = at - openedAt > staleMs;
+  const gap = {
+    opened_at: new Date(openedAt).toISOString(),
+    ...(stale ? {} : { closed_at: new Date(at).toISOString() }),
+    unscreened_calls: unscreened,
+    locally_decided_calls: local,
+    reason: stale ? `${reason} (end not observed)` : reason,
+  };
+  return { open: null, pending: compact([...s.pending, gap]) };
+}
+
+/**
+ * Rule 5 — keep the list bounded WITHOUT losing counts.
+ *
+ * ⚠ The merged row deliberately carries `closed_at` only when every window it
+ * absorbed had one. An aggregate spanning a window we could not attest the end
+ * of is itself unattestable, and inventing a boundary for it would launder an
+ * unmeasurable outage into a measured one.
+ */
+export function compact(gaps, max = MAX_GAPS) {
+  if (gaps.length <= max) return gaps;
+  const overflow = gaps.slice(0, gaps.length - max + 1);
+  const kept = gaps.slice(gaps.length - max + 1);
+  const anyOpen = overflow.some((g) => !g.closed_at);
+  const lastClose = overflow.reduce((acc, g) => (g.closed_at && (!acc || g.closed_at > acc) ? g.closed_at : acc), null);
+  const merged = {
+    opened_at: overflow[0].opened_at,
+    ...(anyOpen || !lastClose ? {} : { closed_at: lastClose }),
+    unscreened_calls: overflow.reduce((n, g) => n + (g.unscreened_calls || 0), 0),
+    locally_decided_calls: overflow.reduce((n, g) => n + (g.locally_decided_calls || 0), 0),
+    reason: `${overflow.length} earlier windows, merged`,
+  };
+  return [merged, ...kept];
+}
+
+/**
+ * The envelope to attach to a request.
+ *
+ * ⚠ ALWAYS AN OBJECT, and `gaps` is always an array — see rule 1. Returning
+ * `undefined` when there is nothing to report is the single change that would
+ * silently break the whole design.
+ */
+export function envelope(state, { version } = {}) {
+  const s = state ?? emptyLedger();
+  return { gaps: s.pending.slice(0, MAX_GAPS), ...(version ? { client_version: String(version).slice(0, 40) } : {}) };
+}
+
+/**
+ * Drop the gaps a request confirmed delivery of.
+ *
+ * ⚠ Matched by `opened_at`, not by index or by count. A concurrent hook process
+ * can append a new gap between building the envelope and acking it, and an
+ * index-based drop would silently discard that one unreported. Re-sending a gap
+ * the backend already has is free — it dedupes on (org, machine, openedAt).
+ */
+export function ack(state, sent) {
+  const s = state ?? emptyLedger();
+  const done = new Set((sent ?? []).map((g) => g.opened_at));
+  return { ...s, pending: s.pending.filter((g) => !done.has(g.opened_at)) };
+}
+
+/* ── File I/O (thin) ────────────────────────────────────────────────────── */
+
+/**
+ * ⚠ EVERY OPERATION BELOW IS BEST-EFFORT AND SWALLOWS. This runs inside the
+ * PreToolUse hook: a ledger that threw would break a tool call the guard had
+ * already correctly allowed, which is a worse outcome than losing a count. The
+ * counts are lower bounds by rule 3 regardless.
+ */
+export function makeLedgerStore(configDir, { version } = {}) {
+  const file = path.join(configDir, 'guard-ledger.json');
+
+  const read = () => {
+    try {
+      const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+      return { open: raw.open ?? null, pending: Array.isArray(raw.pending) ? raw.pending : [] };
+    } catch {
+      return emptyLedger();
+    }
+  };
+
+  const write = (state) => {
+    try {
+      fs.mkdirSync(configDir, { recursive: true });
+      // ⚠ Atomic rename, not a bare write. Two hook processes writing this file
+      // concurrently can lose an increment (rule 3, accepted) — but a torn file
+      // would lose the WHOLE ledger, including windows already closed and
+      // waiting to be reported. `.tmp` is per-process so the two cannot collide.
+      const tmp = `${file}.${process.pid}.tmp`;
+      fs.writeFileSync(tmp, JSON.stringify(state));
+      fs.renameSync(tmp, file);
+    } catch {
+      /* best-effort */
+    }
+  };
+
+  const update = (fn) => {
+    const next = fn(read());
+    write(next);
+    return next;
+  };
+
+  return {
+    file,
+    read,
+    write,
+    /** A call ran with no server verdict. */
+    count: (kind, reason) => update((s) => countCall(s, { at: Date.now(), kind, reason })),
+    /** The backend answered — close any window and hand back what to send. */
+    close: () => update((s) => closeWindow(s, { at: Date.now() })),
+    /** The envelope for this request. Always present (rule 1). */
+    envelope: () => envelope(read(), { version }),
+    /** Confirm delivery. */
+    ack: (sent) => update((s) => ack(s, sent)),
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shomra/agent",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "description": "Shomra — adversarial assurance for AI agents, as a local-first CLI. Blocks dangerous tool-calls before they run, attacks your own guardrails to prove they hold, and gates AI artifacts in your editor and CI.",
   "type": "module",
   "bin": {
@@ -16,6 +16,7 @@
     "shomra.mjs",
     "discovery.mjs",
     "guard-signals.mjs",
+    "guard-ledger.mjs",
     "code-sast.mjs",
     "model-refs.mjs",
     "ai-usage.mjs",