@metamynd/agentsafe-guard 0.2.0 → 0.3.1

package/README.md

@@ -15,6 +15,22 @@ compliance team edits in the dashboard, changeable live with no redeploy.
   `policy-core` the gate runs (MAGP §9.2 cooperative mode) — identical inputs give the identical
   verdict, with no network round-trip. See §4.
 
+## Try it first — no account, no network
+
+```bash
+npx @metamynd/agentsafe-guard demo
+```
+
+Runs the policy engine in-process against a sample bundle and prints the verdict for a
+dozen tool calls — allow, observe, block, escalate, quarantine — including the ones that
+matter most: an agent that lies about its own spend in unsigned context, and a quarantined
+agent refused before any rule is read. It mints an ephemeral key, never opens a socket, and
+needs nothing from MetaMynd. Exits non-zero if any verdict disagrees with the policy, so
+it doubles as a smoke test of the installed package.
+
+You need an account only for what can't be enforced client-side: live policy edits,
+cumulative spend caps, human escalation, and anchored evidence.
+
 ## Install
 
 ```bash
@@ -217,6 +233,30 @@ Or wrap a tool to gate it against a local bundle (fails closed like `guardTool`)
 const gated = guard.guardToolLocal('flight-purchase', bookFlight, mapArgs, { standards, sops, mandate });
 ```
 
+### Execution adapters (dry-run / sandbox) — SAFR §19
+
+By default a permitted (`allow`/`observe`) tool runs its real handler. An **ExecutionAdapter**
+interposes between the verdict and the side-effect, so the *same* governed decision can be run
+live, **simulated (dry-run)**, or routed to a sandbox — without changing the handler or the gate.
+A blocked/escalated action still throws `GovernanceBlocked` before any adapter is consulted.
+
+```js
+import { dryRunExecutionAdapter } from '@metamynd/agentsafe-guard';
+
+// Guard-wide (or set AGENTSAFE_EXECUTION_MODE=dry-run):
+const guard = createGuard({ api, agentDid, agentKey, executionAdapter: dryRunExecutionAdapter });
+
+// …or per tool (overrides the guard default):
+const preview = guard.guardTool('flight-purchase', bookFlight, mapArgs, { executionAdapter: dryRunExecutionAdapter });
+await preview({ amount: 100 }); // → { dryRun: true, action, decision, authorizationId, args } — bookFlight NEVER runs
+
+// Custom adapter: run the real handler, or substitute it. `proceed()` invokes handler(args, decision).
+const sandboxed = (ctx) => ctx.action === 'flight-purchase' ? sandboxBook(ctx.args) : ctx.proceed();
+```
+
+Contract: `async ({ action, args, decision, proceed }) => result`. Call `proceed()` to execute for
+real; return without it to substitute the side-effect. Self-check: `node execution-adapter.smoke.mjs`.
+
 Signed request fields (`amount`, `merchant`) are always applied over the unsigned `context`, so a
 forged context key can never shadow them (MAGP §6.4.2). Run the self-check:
 

package/agentsafe-guard.mjs

@@ -10,10 +10,52 @@
 // The agent's private key is a Hedera Ed25519 DER key (the AGENT_KEY the seed prints).
 import crypto from 'node:crypto';
 import { readFileSync } from 'node:fs';
-import { evaluate, buildAuthMessage, applySignedLast } from './policy-core.mjs';
+import { evaluate, buildAuthMessage, applySignedLast, operatingModeGate } from './policy-core.mjs';
 import { verifyDidSignature } from './magp-did.mjs';
 import { checkSettlementBinding } from './x402.mjs';
 
+/**
+ * ExecutionAdapter (SAFR §19, Phase-4 PR-4) — the seam between a PERMITTING verdict
+ * (allow / observe) and the real side-effect. Before this, a guarded tool called its
+ * handler directly, so the only outcomes were "execute for real" or "throw". An adapter
+ * interposes so the SAME governed decision can be run live, SIMULATED (dry-run), or routed
+ * to a sandbox — without touching the tool handler or the gate.
+ *
+ * Contract: `async (execCtx) => result`, where
+ *   execCtx = { action, args, decision, proceed }
+ *   proceed() runs the real handler (handler(args, decision)) and returns its result.
+ * An adapter that calls `proceed()` executes for real; one that returns WITHOUT calling it
+ * substitutes the side-effect. Adapters run ONLY after the guard has permitted the action —
+ * a block/escalate still throws GovernanceBlocked before any adapter is consulted.
+ */
+
+/** The default: execute the real handler unchanged. */
+export const liveExecutionAdapter = (ctx) => ctx.proceed();
+
+/**
+ * Simulate the side-effect: do NOT call the handler, return a describe-only result. Lets an
+ * agent exercise a fully-governed flow (identity → mandate → controls → verdict) with no real
+ * booking/payment/write — for staging, canaries, and OBSERVE-mode dry-runs.
+ */
+export const dryRunExecutionAdapter = (ctx) => ({
+  dryRun: true,
+  action: ctx.action,
+  decision: ctx.decision?.decision ?? null,
+  reasonCode: ctx.decision?.reasonCode ?? null,
+  authorizationId: ctx.decision?.authorizationId ?? null,
+  args: ctx.args,
+});
+
+/**
+ * Process-default adapter from `AGENTSAFE_EXECUTION_MODE` ('live' | 'dry-run'). Returns null
+ * when unset/live so the caller's own default (live) applies — behavior-neutral by default.
+ */
+export function executionAdapterFromEnv(env = (typeof process !== 'undefined' ? process.env : {})) {
+  const mode = String(env.AGENTSAFE_EXECUTION_MODE ?? '').toLowerCase().trim();
+  if (mode === 'dry-run' || mode === 'dryrun') return dryRunExecutionAdapter;
+  return null;
+}
+
 /**
  * @param {{ api: string, agentDid: string, agentKey: string }} cfg
  *   api      e.g. "http://localhost:9926/api/v1" or "https://metamynd.ai/api/v1"
@@ -48,6 +90,9 @@ export function createGuard(opts = {}) {
   const agentKey = opts.agentKey ?? cfg?.agentKey;
   if (!api || !agentDid || !agentKey) throw new Error('createGuard requires { api, agentDid, agentKey } — directly, or via { config } / { configPath } / createGuardFromConfig()');
   const base = api.replace(/\/$/, '');
+  // ExecutionAdapter seam (SAFR §19): an explicit opt wins, else the AGENTSAFE_EXECUTION_MODE env,
+  // else live. Applies to every guarded tool unless a tool passes its own adapter.
+  const defaultExecutionAdapter = opts.executionAdapter ?? executionAdapterFromEnv() ?? liveExecutionAdapter;
   const privateKey = crypto.createPrivateKey({ key: Buffer.from(agentKey, 'hex'), format: 'der', type: 'pkcs8' });
 
   // Ed25519 over the exact canonical message the backend verifies.
@@ -87,11 +132,13 @@ export function createGuard(opts = {}) {
    * agent's authorization trustlessly against the agent's policy bundle (§9.3). Same shape
    * `authorize()` posts to the gate; a fresh nonce each call.
    */
-  function buildSignedRequest({ action, amount = 0, currency = 'USD', merchant = '', context = {} }) {
+  function buildSignedRequest({ action, amount = 0, currency = 'USD', merchant = '', context = {}, trace, materiality }) {
     const nonce = crypto.randomUUID();
     const issuedAt = new Date().toISOString();
     const message = buildAuthMessage({ agentDid, action, amount, currency, merchant, nonce, issuedAt });
-    return { agentDid, action, amount, currency, merchant, itinerary: context, nonce, issuedAt, signature: sign(message) };
+    // trace/materiality are GovernanceEnvelope fields (SAFR §5) — unsigned metadata; the
+    // signed message stays the action subset, so verification is unchanged.
+    return { agentDid, action, amount, currency, merchant, itinerary: context, trace, materiality, nonce, issuedAt, signature: sign(message) };
   }
 
   /**
@@ -99,7 +146,7 @@ export function createGuard(opts = {}) {
    * returns { decision:'allow'|'block'|'escalate', reasonCode, authorizationId, remaining }.
    * A network/gate failure returns a fail-CLOSED block so the agent can't proceed blind.
    */
-  async function authorize({ action, amount = 0, currency = 'USD', merchant = '', context = {} }) {
+  async function authorize({ action, amount = 0, currency = 'USD', merchant = '', context = {}, trace, materiality }) {
     const nonce = crypto.randomUUID();
     const issuedAt = new Date().toISOString();
     // Build the canonical signed message with policy-core so the guard and the
@@ -109,7 +156,9 @@ export function createGuard(opts = {}) {
       const res = await fetch(`${base}/policy/mandate/authorize`, {
         method: 'POST',
         headers: { 'Content-Type': 'application/json' },
-        body: JSON.stringify({ agentDid, action, amount, currency, merchant, itinerary: context, nonce, issuedAt, signature: sign(message) }),
+        // trace/materiality (SAFR §5 envelope) ride as unsigned metadata; JSON.stringify
+        // drops them when undefined, so an agent that omits them sends the legacy body.
+        body: JSON.stringify({ agentDid, action, amount, currency, merchant, itinerary: context, trace, materiality, nonce, issuedAt, signature: sign(message) }),
       });
       const body = await res.json().catch(() => null);
       return body?.data ?? { decision: 'block', reasonCode: `GATE_HTTP_${res.status}` };
@@ -147,12 +196,29 @@ export function createGuard(opts = {}) {
    * @param {{action:string,amount?:number,merchant?:string,context?:object,cumulativeSpend?:number,now?:string}} p.request
    * @returns {{decision:'allow'|'block'|'escalate',reasonCode:string|null,authorizationId:null,remaining:null,proofRef:null}}
    */
-  function evaluateLocally({ standards = [], sops = [], mandate, request }) {
+  function evaluateLocally({ contained = null, operatingMode = null, standards = [], sops = [], mandate, request }) {
+    // Push containment (Phase 2.3): a server-CONTAINED agent is denied at the EDGE,
+    // before any rule eval. `contained` rides alongside the signed bundle as a SIBLING
+    // response field (never inside the signed payload, so the bundle signature stays
+    // valid) and is refreshed on the `policy:changed` push, reaching the guard in ~1s.
+    if (contained && contained.status) {
+      const decision = contained.status === 'quarantined' ? 'quarantine' : 'suspend';
+      const reasonCode = contained.status === 'quarantined' ? 'AGENT_QUARANTINED' : 'AGENT_SUSPENDED';
+      return { decision, reasonCode, authorizationId: null, remaining: null, proofRef: null };
+    }
     const { action, amount = 0, merchant = '', context = {}, cumulativeSpend = amount, now } = request;
+    // Operating-mode autonomy ladder (Phase 2.5b): the trust-driven posture rides as a
+    // SIBLING (like `contained`) and biases the edge verdict identically to the gate.
+    // READ_ONLY denies a value-bearing action up-front; SUPERVISED/RESTRICTED only
+    // ESCALATE, applied to the verdict below so a rule block/escalate still outranks it.
+    const modeGate = operatingModeGate(operatingMode?.mode, { amount, riskLevel: context?.riskLevel });
+    if (modeGate.decision === 'block') {
+      return { decision: 'block', reasonCode: modeGate.reasonCode, authorizationId: null, remaining: null, proofRef: null };
+    }
     // Signed fields (action/agentDid/amount, mm:* operands) are applied LAST so an
     // unsigned context key can never shadow them (spec §6.4.2) — the same invariant
     // the gate enforces, via the same policy-core helper.
-    return evaluate({
+    const verdict = evaluate({
       standards,
       sops,
       mandate,
@@ -169,6 +235,13 @@ export function createGuard(opts = {}) {
           }
         : undefined,
     });
+    // Mode ESCALATE floor: only lifts an otherwise-PERMIT (allow or observe) to human
+    // review (never softens a stricter verdict) — most-restrictive-wins, mirroring the
+    // backend gate exactly (escalate outranks observe, so a flag never masks it).
+    if ((verdict.decision === 'allow' || verdict.decision === 'observe') && modeGate.decision === 'escalate') {
+      return { ...verdict, decision: 'escalate', reasonCode: modeGate.reasonCode };
+    }
+    return verdict;
   }
 
   /** Fetch + cache the agent's signed policy bundle (refreshed per its maxStaleness). */
@@ -179,6 +252,10 @@ export function createGuard(opts = {}) {
     const body = await res.json().catch(() => null);
     const b = body?.data ?? body;
     if (!b || (!b.mandates && !b.sops && !b.standards)) throw new Error(`invalid policy bundle from ${bundleUrl}`);
+    // Live containment + operating mode ride as SIBLINGS of the signed bundle (never
+    // inside it, so the signature stays valid); stash them on the in-memory copy.
+    b.contained = body?.contained ?? null;
+    b.operatingMode = body?.operatingMode ?? null;
     _bundle = b;
     _bundleAt = now;
     _bundleMaxAgeMs = _durationMs(b.maxStaleness) ?? _bundleMaxAgeMs;
@@ -188,6 +265,8 @@ export function createGuard(opts = {}) {
   /** Map a fetched bundle into the shape evaluateLocally expects, for one action. */
   function _bundleFor(b, action) {
     return {
+      contained: b.contained ?? null,
+      operatingMode: b.operatingMode ?? null,
       standards: (b.standards ?? []).map((s) => ({ standardKey: s.id ?? s.standardKey ?? 'standard', document: s.document })).filter((s) => s.document),
       sops: (b.sops ?? []).map((s) => ({ standardKey: s.id ?? s.sopId ?? 'sop', document: s.document })).filter((s) => s.document),
       mandate: ((b.mandates ?? []).find((m) => m.action === action) ?? (b.mandates ?? [])[0])?.document,
@@ -251,9 +330,11 @@ export function createGuard(opts = {}) {
       if (!anchor?.sigDigest || !sig || _sha256(sig) !== anchor.sigDigest) return authorize(input);
     }
     const local = evaluateLocally({ ..._bundleFor(b, action), request: input });
-    if (local.decision !== 'allow') return local; // decided locally, no network
-    if (amount > 0 && sealValueActions) return authorize(input); // seal value action remotely
-    return local; // non-value allow — local is sufficient
+    // allow/observe both PERMIT; block/escalate/contain are decided locally with no network.
+    const permits = local.decision === 'allow' || local.decision === 'observe';
+    if (!permits) return local; // denied/escalated locally, no network
+    if (amount > 0 && sealValueActions) return authorize(input); // seal value action remotely (allow or observe)
+    return local; // non-value permit — local is sufficient
   }
 
   /** Mode-aware decision used by guardTool: 'local' (default) or 'remote'. */
@@ -319,7 +400,8 @@ export function createGuard(opts = {}) {
    * @param {(args:any)=>{amount?:number,merchant?:string,context?:object}} mapArgs
    * @param {object|((args:any)=>object|Promise<object>)} getBundle  { standards, sops, mandate } (or a resolver)
    */
-  function guardToolLocal(action, handler, mapArgs = (a) => a, getBundle = {}) {
+  function guardToolLocal(action, handler, mapArgs = (a) => a, getBundle = {}, toolOpts = {}) {
+    const adapter = toolOpts.executionAdapter ?? defaultExecutionAdapter;
     return async (args) => {
       let decision;
       try {
@@ -329,13 +411,19 @@ export function createGuard(opts = {}) {
       } catch (err) {
         decision = { decision: 'block', reasonCode: 'LOCAL_EVAL_ERROR', error: String(err?.message ?? err) };
       }
-      if (decision.decision !== 'allow') {
+      // allow/observe both PERMIT execution; observe is permit-but-flag (SAFR §11) — the
+      // handler receives the `decision` so a caller can surface/log the observation.
+      if (decision.decision !== 'allow' && decision.decision !== 'observe') {
         const err = new Error(`AgentSafe ${decision.decision.toUpperCase()} "${action}": ${decision.reasonCode}`);
         err.name = 'GovernanceBlocked';
         err.governance = decision;
         throw err;
       }
-      return handler(args, decision);
+      if (decision.decision === 'observe') {
+        console.warn(`[agentsafe] OBSERVE "${action}": ${decision.reasonCode} — permitted under monitoring`);
+      }
+      // ExecutionAdapter seam (§19): the adapter runs the real handler (proceed) or substitutes it.
+      return adapter({ action, args, decision, proceed: () => handler(args, decision) });
     };
   }
 
@@ -350,16 +438,23 @@ export function createGuard(opts = {}) {
    * @param {(args:any)=>{amount?:number,currency?:string,merchant?:string,context?:object}} mapArgs
    *   maps the tool's call args to the gate inputs (amount/merchant + the context the rules need)
    */
-  function guardTool(action, handler, mapArgs = (a) => a) {
+  function guardTool(action, handler, mapArgs = (a) => a, toolOpts = {}) {
+    const adapter = toolOpts.executionAdapter ?? defaultExecutionAdapter;
     return async (args) => {
       const decision = await check({ action, ...mapArgs(args) });
-      if (decision.decision !== 'allow') {
+      // allow/observe both PERMIT execution; observe is permit-but-flag (SAFR §11) — the
+      // handler receives the `decision` so a caller can surface/log the observation.
+      if (decision.decision !== 'allow' && decision.decision !== 'observe') {
         const err = new Error(`AgentSafe ${decision.decision.toUpperCase()} "${action}": ${decision.reasonCode}`);
         err.name = 'GovernanceBlocked';
         err.governance = decision;
         throw err;
       }
-      return handler(args, decision);
+      if (decision.decision === 'observe') {
+        console.warn(`[agentsafe] OBSERVE "${action}": ${decision.reasonCode} — permitted under monitoring`);
+      }
+      // ExecutionAdapter seam (§19): the adapter runs the real handler (proceed) or substitutes it.
+      return adapter({ action, args, decision, proceed: () => handler(args, decision) });
     };
   }
 
@@ -443,6 +538,37 @@ export function createGuard(opts = {}) {
     }
   }
 
+  /**
+   * Effect-safety runtime (E2): report the external-effect lifecycle so an AMBIGUOUS
+   * connector outcome never becomes a blind capture/void. Call effectDispatching() just
+   * before the side-effecting call, effectDispatched() when the connector accepts, and —
+   * critically — effectUnknown() when the response is lost/timed out (instead of guessing).
+   * Once UNKNOWN, capture/void are refused by the gate until the effect is reconciled.
+   */
+  async function _effectPost(authorizationId, kind, payload = {}) {
+    try {
+      const res = await fetch(`${base}/policy/mandate/authorize/${encodeURIComponent(authorizationId)}/effect/${kind}`, {
+        method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(payload),
+      });
+      const body = await res.json().catch(() => null);
+      return body?.data ?? { ok: false, reasonCode: `GATE_HTTP_${res.status}` };
+    } catch (err) {
+      return { ok: false, reasonCode: 'GATE_UNREACHABLE', error: String(err?.message ?? err) };
+    }
+  }
+  const effectDispatching = (authorizationId) => _effectPost(authorizationId, 'dispatching');
+  const effectDispatched = (authorizationId, remoteRef) => _effectPost(authorizationId, 'dispatched', { remoteRef });
+  const effectUnknown = (authorizationId, reason) => _effectPost(authorizationId, 'unknown', { reason });
+  async function effectStatus(authorizationId) {
+    try {
+      const res = await fetch(`${base}/policy/mandate/authorize/${encodeURIComponent(authorizationId)}/effect`);
+      const body = await res.json().catch(() => null);
+      return body?.data ?? { effectState: null, reasonCode: `GATE_HTTP_${res.status}` };
+    } catch (err) {
+      return { effectState: 'unreachable', reasonCode: 'GATE_UNREACHABLE', error: String(err?.message ?? err) };
+    }
+  }
+
   /**
    * BYOK proof-of-possession (onboarding proposal #4). For an agent that brought its OWN key,
    * MetaMynd issued the identity with a one-time `challenge` and left the key UNVERIFIED — the gate
@@ -476,5 +602,5 @@ export function createGuard(opts = {}) {
     return sign(challenge);
   }
 
-  return { authorize, authorizeLocal, check, loadBundle, policyAnchor: _currentAnchor, watchPolicy, mode, verifyOnChain, buildSignedRequest, capture, guardTool, evaluateLocally, guardToolLocal, handshake, preparePayment, escalationStatus, verifyKey, signChallenge, agentDid };
+  return { authorize, authorizeLocal, check, loadBundle, policyAnchor: _currentAnchor, watchPolicy, mode, verifyOnChain, buildSignedRequest, capture, guardTool, evaluateLocally, guardToolLocal, handshake, preparePayment, escalationStatus, effectDispatching, effectDispatched, effectUnknown, effectStatus, verifyKey, signChallenge, agentDid, executionAdapter: defaultExecutionAdapter };
 }

package/cli.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// cli.mjs — the package's only executable. Its whole job is to make the offline
+// demo reachable without cloning anything:
+//
+//   npx @metamynd/agentsafe-guard demo
+//
+// Kept deliberately thin: no argument parser, no dependencies, no network.
+const [, , cmd] = process.argv;
+
+if (cmd === 'demo') {
+  await import('./demo.mjs');
+} else if (!cmd || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+  console.log(`
+  @metamynd/agentsafe-guard — runtime governance for Node AI agents
+
+  Usage
+    npx @metamynd/agentsafe-guard demo     Run the offline policy demo
+                                           (no account, no API key, no network)
+
+  In your agent
+    import { createGuard } from '@metamynd/agentsafe-guard';
+
+  Docs   https://www.npmjs.com/package/@metamynd/agentsafe-guard
+  Hosted https://metamynd.ai
+`);
+} else {
+  console.error(`Unknown command: ${cmd}\nTry: npx @metamynd/agentsafe-guard demo`);
+  process.exit(1);
+}

package/demo.mjs

@@ -0,0 +1,161 @@
+// demo.mjs — the no-account, no-network tour of the guard.
+//
+//   npx @metamynd/agentsafe-guard demo
+//
+// Everything here runs locally: an ephemeral Ed25519 key, an inline policy bundle,
+// and `policy-core` — the same evaluator bytes the hosted gate runs. No MetaMynd
+// account, no API key, no Hedera, no outbound request (the `api` URL below is
+// deliberately unroutable, and nothing ever calls it).
+//
+// Exits 0 when every verdict matches what the policy says it should be, 1 otherwise —
+// so this doubles as a smoke test of the shipped package.
+import crypto from 'node:crypto';
+import { createGuard } from './agentsafe-guard.mjs';
+
+const c = (code, s) => (process.stdout.isTTY ? `\u001b[${code}m${s}\u001b[0m` : s);
+const bold = (s) => c('1', s);
+const dim = (s) => c('2', s);
+const head = (s) => console.log(`\n${bold(s)}\n${dim('─'.repeat(s.length))}`);
+
+// Colour per decision — but never colour ALONE: the verdict is always spelled out.
+const paint = { allow: '32', observe: '36', escalate: '33', block: '31', quarantine: '35' };
+const verdict = (d) => c(paint[d] ?? '0', d.toUpperCase().padEnd(10));
+
+const { privateKey } = crypto.generateKeyPairSync('ed25519');
+const guard = createGuard({
+  api: 'http://unused.local/api/v1', // never contacted — this demo is entirely local
+  agentDid: 'did:hedera:testnet:z6MkDemo_0.0.1',
+  agentKey: privateKey.export({ format: 'der', type: 'pkcs8' }).toString('hex'),
+});
+
+// The policy an owner would author in the dashboard, as the agent receives it:
+// one enforced Standard, one SOP, and an ODRL mandate.
+const bundle = {
+  standards: [
+    {
+      standardKey: 'eu-ai-act',
+      document: {
+        molecules: [
+          {
+            id: 'risk',
+            combinator: 'any',
+            atoms: [{ id: 'r', predicate: 'risk-at-or-above', config: { level: 'high' } }],
+            decision: 'escalate',
+            reasonCode: 'RISK_REVIEW',
+          },
+        ],
+      },
+    },
+  ],
+  sops: [
+    {
+      standardKey: 'sop:travel',
+      document: {
+        molecules: [
+          {
+            id: 'watch',
+            combinator: 'any',
+            atoms: [{ id: 'w', predicate: 'amount-over', config: { limit: 200 } }],
+            decision: 'observe',
+            reasonCode: 'WATCH_LARGE',
+          },
+          {
+            id: 'cap',
+            combinator: 'any',
+            atoms: [{ id: 'a', predicate: 'amount-over', config: { limit: 500 } }],
+            decision: 'block',
+            reasonCode: 'SOP_SPEND_CAP',
+          },
+          {
+            id: 'contain',
+            combinator: 'any',
+            atoms: [{ id: 'q', predicate: 'amount-over', config: { limit: 5000 } }],
+            decision: 'quarantine',
+            reasonCode: 'GROSS_OVERSPEND',
+          },
+        ],
+      },
+    },
+  ],
+  mandate: {
+    permission: [
+      {
+        target: 'flight-purchase',
+        constraint: [
+          { leftOperand: 'mm:payAmount', operator: 'lteq', rightOperand: 1000 },
+          { leftOperand: 'mm:cumulativeSpend', operator: 'lteq', rightOperand: 1000 },
+          { leftOperand: 'mm:merchant', operator: 'isAnyOf', rightOperand: ['amadeus'] },
+        ],
+      },
+    ],
+  },
+};
+
+let failed = 0;
+const check = (ok) => { if (!ok) failed++; return ok ? dim('ok') : c('31', 'FAIL'); };
+
+const run = (label, request, expect, extra = {}) => {
+  const v = guard.evaluateLocally({ ...bundle, ...extra, request });
+  const ok = v.decision === expect[0] && v.reasonCode === expect[1];
+  console.log(`  ${verdict(v.decision)} ${String(v.reasonCode).padEnd(22)} ${label}  ${check(ok)}`);
+};
+
+console.log(bold('\nAgentSafe Guard — local policy evaluation'));
+console.log(dim('No account, no API key, no network. Same policy-core the hosted gate runs.'));
+
+head('The policy this agent is under');
+console.log(`  Standard ${dim('eu-ai-act')}    risk ≥ high                 → escalate`);
+console.log(`  SOP      ${dim('sop:travel')}   amount > 200                → observe   ${dim('(permit, but flag)')}`);
+console.log(`                        amount > 500                → block`);
+console.log(`                        amount > 5000               → quarantine ${dim('(contain the agent)')}`);
+console.log(`  Mandate  ${dim('ODRL')}         merchant ∈ [amadeus], ≤ 1000 per action and in total`);
+
+head('A tool call, evaluated against it');
+run('$100 to amadeus, low risk', { action: 'flight-purchase', amount: 100, merchant: 'amadeus', context: { riskLevel: 'low' } }, ['allow', 'AUTHORIZED']);
+run('$300 — over the watch line', { action: 'flight-purchase', amount: 300, merchant: 'amadeus', context: { riskLevel: 'low' } }, ['observe', 'WATCH_LARGE']);
+run('$600 — over the SOP cap', { action: 'flight-purchase', amount: 600, merchant: 'amadeus', context: { riskLevel: 'low' } }, ['block', 'SOP_SPEND_CAP']);
+run('$100 but flagged high risk', { action: 'flight-purchase', amount: 100, merchant: 'amadeus', context: { riskLevel: 'high' } }, ['escalate', 'RISK_REVIEW']);
+run('$100 to a merchant off the mandate', { action: 'flight-purchase', amount: 100, merchant: 'sabre', context: { riskLevel: 'low' } }, ['block', 'MERCHANT_NOT_ALLOWED']);
+run('$6000 — gross overspend', { action: 'flight-purchase', amount: 6000, merchant: 'amadeus', context: { riskLevel: 'low' } }, ['quarantine', 'GROSS_OVERSPEND']);
+
+head('The agent cannot argue its way out');
+console.log(dim('  Unsigned context is untrusted input — it never shadows the signed amount.'));
+run('$600 claiming "payAmount: 1"', { action: 'flight-purchase', amount: 600, merchant: 'amadeus', context: { 'mm:payAmount': 1, riskLevel: 'low' } }, ['block', 'SOP_SPEND_CAP']);
+console.log(dim('  A quarantined agent is refused at the edge, before any rule is read.'));
+run('$1 while quarantined', { action: 'flight-purchase', amount: 1, merchant: 'amadeus', context: { riskLevel: 'low' } }, ['quarantine', 'AGENT_QUARANTINED'], { contained: { status: 'quarantined', reason: 'GROSS_OVERSPEND' } });
+
+head('Operating mode narrows the ladder further');
+const mode = (m) => ({ operatingMode: { mode: m } });
+run('read_only — value action refused', { action: 'flight-purchase', amount: 100, merchant: 'amadeus', context: { riskLevel: 'low' } }, ['block', 'MODE_READ_ONLY'], mode('read_only'));
+run('read_only — a $0 read still passes', { action: 'flight-purchase', amount: 0, merchant: 'amadeus', context: { riskLevel: 'low' } }, ['allow', 'AUTHORIZED'], mode('read_only'));
+run('restricted — spend needs a human', { action: 'flight-purchase', amount: 100, merchant: 'amadeus', context: { riskLevel: 'low' } }, ['escalate', 'MODE_RESTRICTED_REVIEW'], mode('restricted'));
+run('restricted — but a block stays a block', { action: 'flight-purchase', amount: 600, merchant: 'amadeus', context: { riskLevel: 'low' } }, ['block', 'SOP_SPEND_CAP'], mode('restricted'));
+
+head('What that means for your tool');
+{
+  let ran = false;
+  const book = guard.guardToolLocal('flight-purchase', async () => { ran = true; return 'booked'; }, (a) => a, bundle);
+  const out = await book({ amount: 300, merchant: 'amadeus', context: { riskLevel: 'low' } });
+  console.log(`  observe   → handler RAN, returned ${JSON.stringify(out)}  ${check(ran === true && out === 'booked')}`);
+}
+{
+  let ran = false;
+  const book = guard.guardToolLocal('flight-purchase', async () => { ran = true; return 'booked'; }, (a) => a, bundle);
+  let name = null;
+  try { await book({ amount: 600, merchant: 'amadeus', context: { riskLevel: 'low' } }); } catch (e) { name = e?.name; }
+  console.log(`  block     → threw ${name}, handler never ran  ${check(name === 'GovernanceBlocked' && ran === false)}`);
+}
+
+if (failed) {
+  console.error(c('31', `\n${failed} case(s) FAILED — that is a bug, please report it.`));
+  console.error(dim('Please report it — https://metamynd.ai\n'));
+  process.exit(1);
+}
+
+console.log(bold('\nPASS') + dim(' — every verdict matched the policy, decided locally in-process.\n'));
+console.log('Wire it into your own agent:');
+console.log(dim("  import { createGuard } from '@metamynd/agentsafe-guard';"));
+console.log(dim('  const safeBooking = guard.guardToolLocal(\'flight-purchase\', bookFlight, mapArgs, bundle);'));
+console.log(`\n${dim('Local evaluation needs nothing from us. The hosted platform adds live policy')}`);
+console.log(`${dim('editing, cumulative spend caps, human escalation, and anchored evidence:')}`);
+console.log(`${dim('https://metamynd.ai')}\n`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metamynd/agentsafe-guard",
-  "version": "0.2.0",
+  "version": "0.3.1",
   "description": "Zero-dependency runtime governance for any Node AI agent — gate tool calls through MetaMynd/AgentSafe (allow / block / escalate) against the agent's mandate, enforced Standards, and SOPs. Ed25519-signed, deterministic, fail-closed.",
   "type": "module",
   "main": "./agentsafe-guard.mjs",
@@ -11,6 +11,8 @@
     "./package.json": "./package.json"
   },
   "files": [
+    "demo.mjs",
+    "cli.mjs",
     "agentsafe-guard.mjs",
     "policy-core.mjs",
     "magp-did.mjs",
@@ -20,7 +22,8 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node local-eval.smoke.mjs"
+    "test": "node demo.mjs && node local-eval.smoke.mjs && node execution-adapter.smoke.mjs",
+    "demo": "node demo.mjs"
   },
   "engines": {
     "node": ">=18"
@@ -44,16 +47,14 @@
   ],
   "author": "MetaMynd",
   "license": "MIT",
-  "homepage": "https://github.com/jasimp18/AgentSafe/tree/main/integrations/agentsafe-guard#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/jasimp18/AgentSafe.git",
-    "directory": "integrations/agentsafe-guard"
-  },
+  "homepage": "https://metamynd.ai",
   "bugs": {
-    "url": "https://github.com/jasimp18/AgentSafe/issues"
+    "url": "https://metamynd.ai/en/support/contact"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "bin": {
+    "agentsafe-guard": "./cli.mjs"
   }
 }

package/policy-core.mjs

@@ -31,6 +31,25 @@ ${c.output ?? ""}`.toLowerCase();
   "tool-not-allowed": (c, cfg) => notInAllowList(c.tool, cfg?.allowed),
   "pii-present": (c) => c.piiPresent === true,
   "rate-limit-exceeded": (c, cfg) => typeof c.callCount === "number" && c.callCount > Number(cfg?.max ?? 0),
+  // --- Evidence-quality atoms (SAFR §24). Unlike the allow-list atoms, these fire on ABSENCE:
+  //     a REQUIRE semantic — "the action must be backed by this evidence; if it isn't, fire"
+  //     (author with escalate/block). Opt-in: they only run when a rule keys them. ---
+  // Fires when any REQUIRED evidence type is not among the attested `evidenceTypes` (missing
+  // evidence — including none supplied at all → all required missing → fires).
+  "evidence-requirement": (c, cfg) => {
+    const required = (cfg?.required ?? []).map((t) => String(t).toLowerCase().trim()).filter(Boolean);
+    if (required.length === 0) return false;
+    const have = new Set((Array.isArray(c.evidenceTypes) ? c.evidenceTypes : []).map((t) => String(t).toLowerCase().trim()));
+    return required.some((r) => !have.has(r));
+  },
+  // Fires when a required minimum confidence (min > 0) is not met — the attested confidence is
+  // below it, or absent (a required confidence that was never supplied fails the bar). A min of
+  // 0 / unset is no requirement and never fires.
+  "evidence-confidence-below": (c, cfg) => {
+    const min = Number(cfg?.min ?? 0);
+    if (!(min > 0)) return false;
+    return typeof c.evidenceConfidence !== "number" || c.evidenceConfidence < min;
+  },
   // Trust guidance (MetaMynd Trust Index / HCS-28). Fires when the counterparty's trust score is
   // below a soft REVIEW line — intended to author an ESCALATE (route to a human), NOT a hard block.
   // The score is server-derived (signed-last) so the agent's itinerary can't fake it; when no score
@@ -145,6 +164,20 @@ var ATOM_SPECS = [
     description: "Routes to human review when the counterparty's MetaMynd Trust Index (HCS-28) score is below a soft review line. Guidance, not a hard block \u2014 author it with an ESCALATE decision. The score is resolved server-side; no counterparty score \u2192 the atom does not fire.",
     config: [{ key: "reviewBelow", type: "number", required: true, description: "Trust score (0\u2013100) below which a human is asked to decide" }],
     requiredContext: ["holTrustScore"]
+  },
+  {
+    predicate: "evidence-requirement",
+    label: "Required evidence missing",
+    description: "Fires when the action is not backed by every REQUIRED evidence type the agent attests to in `evidenceTypes` (missing evidence \u2014 including none supplied). A REQUIRE control (SAFR \xA724): author it with ESCALATE or BLOCK so an under-evidenced action is stopped or reviewed.",
+    config: [{ key: "required", type: "string[]", required: true, description: "Evidence types that must all be present (e.g. kyc, source-doc, signature)" }],
+    requiredContext: ["evidenceTypes"]
+  },
+  {
+    predicate: "evidence-confidence-below",
+    label: "Evidence confidence below minimum",
+    description: "Fires when the attested evidence confidence is below a required minimum \u2014 or absent (SAFR \xA724). A min of 0 / unset is no requirement. Author with ESCALATE to route low-confidence actions to review.",
+    config: [{ key: "min", type: "number", required: true, description: "Minimum evidence confidence (0\u20131) required" }],
+    requiredContext: ["evidenceConfidence"]
   }
 ];
 var CATALOGUED_ATOMS = ATOM_SPECS.filter((s) => !!ATOM_REGISTRY[s.predicate]);
@@ -158,7 +191,7 @@ function requiredContextFor(predicates) {
 }
 
 // src/policy-core/standards-rules.ts
-var PRECEDENCE = { allow: 0, escalate: 1, block: 2 };
+var PRECEDENCE = { allow: 0, observe: 1, escalate: 2, block: 3, suspend: 4, quarantine: 5 };
 function atomFires(atom, ctx) {
   const pred = ATOM_REGISTRY[atom.predicate];
   if (!pred) return false;
@@ -244,8 +277,8 @@ function validateMolecules(molecules) {
     if (!["all", "any", "none"].includes(m.combinator)) {
       issues.push({ moleculeId: m.id, message: `invalid combinator '${m.combinator}' (all|any|none)` });
     }
-    if (!["block", "escalate"].includes(m.decision)) {
-      issues.push({ moleculeId: m.id, message: `invalid decision '${m.decision}' (block|escalate)` });
+    if (!["observe", "block", "escalate", "suspend", "quarantine"].includes(m.decision)) {
+      issues.push({ moleculeId: m.id, message: `invalid decision '${m.decision}' (observe|block|escalate|suspend|quarantine)` });
     }
     if (!m.reasonCode) issues.push({ moleculeId: m.id, message: "molecule is missing a reasonCode" });
     if (!m.atoms || m.atoms.length === 0) {
@@ -359,7 +392,7 @@ function sumEventField(events, type, field) {
 }
 
 // src/policy-core/evaluate.ts
-var PRECEDENCE2 = { allow: 0, escalate: 1, block: 2 };
+var PRECEDENCE2 = { allow: 0, observe: 1, escalate: 2, block: 3, suspend: 4, quarantine: 5 };
 function evaluate(input) {
   let decision = "allow";
   let reasonCode = "AUTHORIZED";
@@ -389,20 +422,66 @@ function buildAuthMessage(f) {
 function applySignedLast(unsigned, signed) {
   return { ...unsigned ?? {}, ...signed };
 }
+
+// src/policy-core/operating-mode.ts
+var MODE_RANK = {
+  read_only: 0,
+  restricted: 1,
+  supervised: 2,
+  autonomous: 3
+};
+var MODES_BY_RANK = ["read_only", "restricted", "supervised", "autonomous"];
+function isOperatingMode(v) {
+  return typeof v === "string" && Object.prototype.hasOwnProperty.call(MODE_RANK, v);
+}
+function asOperatingMode(v) {
+  return isOperatingMode(v) ? v : "autonomous";
+}
+function moreRestrictive(a, b) {
+  return MODE_RANK[a] <= MODE_RANK[b] ? a : b;
+}
+var SUPERVISED_AMOUNT_CAP = 100;
+var RISK_RANK2 = { low: 0, medium: 1, high: 2, critical: 3 };
+function riskAtOrAboveHigh(riskLevel) {
+  const r = typeof riskLevel === "string" ? RISK_RANK2[riskLevel.toLowerCase()] : void 0;
+  return r !== void 0 && r >= RISK_RANK2.high;
+}
+function operatingModeGate(mode, ctx) {
+  const m = asOperatingMode(mode);
+  const valueBearing = (ctx.amount ?? 0) > 0;
+  if (!valueBearing || m === "autonomous") return { decision: "allow", reasonCode: null };
+  switch (m) {
+    case "read_only":
+      return { decision: "block", reasonCode: "MODE_READ_ONLY" };
+    case "restricted":
+      return { decision: "escalate", reasonCode: "MODE_RESTRICTED_REVIEW" };
+    case "supervised":
+      return riskAtOrAboveHigh(ctx.riskLevel) || (ctx.amount ?? 0) >= SUPERVISED_AMOUNT_CAP ? { decision: "escalate", reasonCode: "MODE_SUPERVISED_REVIEW" } : { decision: "allow", reasonCode: null };
+    default:
+      return { decision: "allow", reasonCode: null };
+  }
+}
 export {
   ATOM_REGISTRY,
   ATOM_SPECS,
   CATALOGUED_ATOMS,
+  MODES_BY_RANK,
+  MODE_RANK,
+  SUPERVISED_AMOUNT_CAP,
   applyCapture,
   applyHold,
   applySignedLast,
+  asOperatingMode,
   buildAuthMessage,
   canAuthorize,
   evaluate,
   evaluateBoundStandards,
   evaluateMandate,
   evaluateStandardRules,
+  isOperatingMode,
   moleculeFires,
+  moreRestrictive,
+  operatingModeGate,
   releaseHold,
   remainingBudget,
   requiredContextFor,