@metamynd/agentsafe-guard 0.12.1 → 0.12.4

package/agentsafe-guard.mjs

@@ -10,6 +10,7 @@
 // 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 { resolve as resolvePath } from 'node:path';
 import { evaluate, buildAuthMessage, applySignedLast, operatingModeGate } from './policy-core.mjs';
 import { envelopeHashFor } from './governance-envelope.mjs';
 import { verifyDidSignature } from './magp-did.mjs';
@@ -84,6 +85,38 @@ export function executionAdapterFromEnv(env = (typeof process !== 'undefined' ?
  *   agentDid the agent's did:hedera
  *   agentKey the agent's Ed25519 private key (Hedera DER hex, held only by the agent)
  */
+/**
+ * Read + parse an agent config file, failing with the NEXT STEP rather than a bare `ENOENT`.
+ * `agent.metamynd.json` holds the agent's identity (and, for a managed key, its secret), so it is
+ * deliberately gitignored — which means a fresh clone of any agent project can never contain it.
+ * A raw "no such file or directory" left a first-time user with no way forward (beta regression
+ * 2026-09-20, BR-004); the message below names the three ways to get the file.
+ */
+function readConfigFile(path, who) {
+  let text;
+  try {
+    text = readFileSync(path, 'utf8');
+  } catch (e) {
+    if (e && e.code === 'ENOENT') {
+      throw new Error([
+        `${who}: no agent config at "${resolvePath(path)}".`,
+        `  agent.metamynd.json holds the agent's identity and key, so it is gitignored - a fresh clone never has it.`,
+        `  To get one:`,
+        `    1. New agent:      npx create-metamynd-agent      (creates the agent and writes this file)`,
+        `    2. Existing agent: dashboard -> Agents -> your agent -> download its configuration, save it as ${path}`,
+        `    3. Kept elsewhere: pass its real path, e.g. createGuardFromConfig('/path/to/agent.metamynd.json')`,
+        `  Then re-run. Step-by-step: https://metamynd.ai/developers/quickstart`,
+      ].join('\n'));
+    }
+    throw new Error(`${who}: cannot read agent config "${path}": ${e && e.message}`);
+  }
+  try {
+    return JSON.parse(text);
+  } catch (e) {
+    throw new Error(`${who}: "${path}" is not valid JSON (${e.message}). Re-download the configuration rather than editing it by hand.`);
+  }
+}
+
 /**
  * Async loader — build a guard from the portable config the one-call `POST /onboarding/agent`
  * endpoint returns: a URL, a file path, or the config object itself. Overrides win over the config.
@@ -100,7 +133,7 @@ export function executionAdapterFromEnv(env = (typeof process !== 'undefined' ?
 export async function createGuardFromConfig(source, overrides = {}) {
   let cfg = source;
   if (typeof source === 'string') {
-    cfg = /^https?:\/\//.test(source) ? await (await fetch(source)).json() : JSON.parse(readFileSync(source, 'utf8'));
+    cfg = /^https?:\/\//.test(source) ? await (await fetch(source)).json() : readConfigFile(source, 'createGuardFromConfig');
   }
   if (cfg && cfg.data && !cfg.agentDid) cfg = cfg.data; // unwrap a { success, data } API response
   const { passphrase, ...rest } = overrides;
@@ -119,8 +152,7 @@ export function createGuard(opts = {}) {
   // addition to explicit { api, agentDid, agentKey }. Explicit fields win over the config.
   let cfg = opts.config ?? null;
   if (!cfg && opts.configPath) {
-    try { cfg = JSON.parse(readFileSync(opts.configPath, 'utf8')); }
-    catch (e) { throw new Error(`createGuard: cannot read configPath "${opts.configPath}": ${e.message}`); }
+    cfg = readConfigFile(opts.configPath, 'createGuard');
   }
   if (cfg && cfg.data && !cfg.agentDid) cfg = cfg.data; // unwrap a { success, data } API response
   const api = opts.api ?? cfg?.apiBase ?? cfg?.api;

package/cli.mjs

@@ -19,7 +19,19 @@ if (cmd === 'demo') {
   // or when a control named by --require is not configured at all.
   const { verify } = await import('./verify.mjs');
   try {
+    // --context <file>: the request context of a request that satisfies every rule (see verify.mjs).
+    let context;
+    // flag() is null when absent and '' when given with no value (`--context` last, or an unset shell
+    // variable) — the latter must be an error, not a silent bare run.
+    if (flag('context') !== null) {
+      const path = flag('context');
+      if (!path) throw new Error('--context needs a file path');
+      try { context = JSON.parse((await import('node:fs')).readFileSync(path, 'utf8')); }
+      catch (e) { throw new Error(`cannot read --context ${path}: ${e.message}`); }
+      if (context === null || typeof context !== 'object' || Array.isArray(context)) throw new Error(`--context ${path} must contain a JSON object`);
+    }
     const result = await verify({
+      context,
       configPath: flag('config') ?? './agent.metamynd.json',
       require: (flag('require') ?? '').split(',').map((s) => s.trim()).filter(Boolean),
       json: process.argv.includes('--json'),
@@ -50,6 +62,9 @@ if (cmd === 'demo') {
       --config <path>     agent config (default ./agent.metamynd.json)
       --require <a,b>     fail when a control is NOT configured, e.g.
                           --require merchants,perTxn
+      --context <path>    JSON file: the request context of a request that
+                          satisfies every rule (rule inputs like consent or
+                          evidenceTypes), for policies that require inputs
       --json              machine-readable output
 
     A control the mandate does not set is reported, never passed: an empty

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@metamynd/agentsafe-guard",
-  "version": "0.12.1",
+  "version": "0.12.4",
   "description": "Zero-dependency runtime governance for any Node AI agent \u2014 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",
@@ -26,7 +26,7 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node demo.mjs && node local-eval.smoke.mjs && node execution-adapter.smoke.mjs && node verify.smoke.mjs && node context-signature.smoke.mjs && node local-decision-report.smoke.mjs && node resource-constraint.smoke.mjs && node passphrase-key.smoke.mjs",
+    "test": "node demo.mjs && node local-eval.smoke.mjs && node execution-adapter.smoke.mjs && node verify.smoke.mjs && node context-signature.smoke.mjs && node local-decision-report.smoke.mjs && node resource-constraint.smoke.mjs && node passphrase-key.smoke.mjs && node missing-config.smoke.mjs",
     "demo": "node demo.mjs"
   },
   "engines": {

package/verify.mjs

@@ -41,7 +41,7 @@ const CONTROLS = {
     detail: 'the ceiling on any single action',
     configured: (c) => {
       const k = c.find((x) => x.leftOperand === 'mm:payAmount' && x.operator === 'lteq');
-      return k ? { configured: true, summary: `${k.rightOperand}${k.unit ? ' ' + k.unit : ''}`, limit: Number(k.rightOperand) } : { configured: false };
+      return k ? { configured: true, summary: `${k.rightOperand}${k.unit ? ' ' + k.unit : ''}`, limit: Number(k.rightOperand), unit: k.unit } : { configured: false };
     },
   },
   cumulative: {
@@ -49,7 +49,7 @@ const CONTROLS = {
     detail: 'the ceiling on total spend across actions',
     configured: (c) => {
       const k = c.find((x) => x.leftOperand === 'mm:cumulativeSpend' && x.operator === 'lteq');
-      return k ? { configured: true, summary: `${k.rightOperand}${k.unit ? ' ' + k.unit : ''}`, limit: Number(k.rightOperand) } : { configured: false };
+      return k ? { configured: true, summary: `${k.rightOperand}${k.unit ? ' ' + k.unit : ''}`, limit: Number(k.rightOperand), unit: k.unit } : { configured: false };
     },
   },
   merchants: {
@@ -92,7 +92,15 @@ function packsFor(bundle, action) {
 
 const permits = (v) => v.decision === 'allow' || v.decision === 'observe';
 
-export async function verify({ configPath = './agent.metamynd.json', require: required = [], json = false, log = console.log, env = process.env } = {}) {
+/**
+ * `context` is the request context of a request that satisfies every rule in the agent's policy
+ * (rule inputs such as `consent`, `evidenceTypes`, `jurisdiction`). The baseline and cap checks send
+ * it, because a policy that REQUIRES an input blocks a request without it — which would make the
+ * baseline report a healthy agent as broken, and let a cap "hold" for the wrong reason. Omit it for
+ * a policy with no input-dependent rules (the old behaviour, unchanged). The scope check never
+ * uses it: an ungranted action must be refused whatever the context says.
+ */
+export async function verify({ configPath = './agent.metamynd.json', require: required = [], json = false, log = console.log, env = process.env, context: baseContext = {} } = {}) {
   // AGENT_KEY / AGENT_DID / METAMYND_API from the environment win over the config file.
   // CI is the whole point of this command, and a CI story that requires committing the
   // agent's signing key to the repository is not one — so a key-less config plus a secret
@@ -116,6 +124,12 @@ export async function verify({ configPath = './agent.metamynd.json', require: re
   const found = {};
   for (const [key, spec] of Object.entries(CONTROLS)) found[key] = spec.configured(constraints);
 
+  // The probes must be denominated in the currency the mandate's caps are. `evaluateLocally` assumes USD when a
+  // request names none, and a cap in any other currency refuses a currency-less or mismatched request (fail-closed),
+  // so a GBP agent would fail its own baseline check and read as broken. Only a cap that names a unit sets one.
+  const unitOf = (control) => (control.unit ? { currency: control.unit } : {});
+  const baselineCurrency = unitOf(found.perTxn.configured ? found.perTxn : found.cumulative);
+
   const checks = [];
   const add = (control, status, assertion, verdict, note) =>
     checks.push({ control, status, assertion, decision: verdict?.decision ?? null, reasonCode: verdict?.reasonCode ?? null, note });
@@ -125,7 +139,7 @@ export async function verify({ configPath = './agent.metamynd.json', require: re
   {
     const amount = found.perTxn.configured ? Math.max(1, Math.floor(found.perTxn.limit / 2)) : 1;
     const merchant = found.merchants.list?.length ? found.merchants.list[0] : 'any-merchant';
-    const v = evaluate({ action, amount, merchant, context: { riskLevel: 'low' } });
+    const v = evaluate({ action, amount, ...baselineCurrency, merchant, context: { riskLevel: 'low', ...baseContext } });
     add('baseline', permits(v) ? PASS : FAIL, 'permits ordinary in-scope work', v,
       permits(v) ? null : 'the agent cannot perform the action it was issued for');
   }
@@ -141,7 +155,7 @@ export async function verify({ configPath = './agent.metamynd.json', require: re
   // 3–5. Only assert a limit the mandate actually sets. Asserting an absent control is how
   //      you end up believing in one.
   if (found.perTxn.configured) {
-    const v = evaluate({ action, amount: found.perTxn.limit + 1, merchant: found.merchants.list?.length ? found.merchants.list[0] : 'any-merchant', context: {} });
+    const v = evaluate({ action, amount: found.perTxn.limit + 1, ...unitOf(found.perTxn), merchant: found.merchants.list?.length ? found.merchants.list[0] : 'any-merchant', context: { ...baseContext } });
     add('perTxn', permits(v) ? FAIL : PASS, `refuses ${found.perTxn.limit + 1} against a cap of ${found.perTxn.limit}`, v,
       permits(v) ? 'the per-transaction cap did not hold' : null);
   } else {
@@ -150,8 +164,8 @@ export async function verify({ configPath = './agent.metamynd.json', require: re
 
   if (found.cumulative.configured) {
     const v = evaluate({
-      action, amount: 1, merchant: found.merchants.list?.length ? found.merchants.list[0] : 'any-merchant',
-      cumulativeSpend: found.cumulative.limit + 1, context: {},
+      action, amount: 1, ...unitOf(found.cumulative), merchant: found.merchants.list?.length ? found.merchants.list[0] : 'any-merchant',
+      cumulativeSpend: found.cumulative.limit + 1, context: { ...baseContext },
     });
     add('cumulative', permits(v) ? FAIL : PASS, `refuses spending past a total of ${found.cumulative.limit}`, v,
       permits(v) ? 'the cumulative cap did not hold' : null);
@@ -166,7 +180,7 @@ export async function verify({ configPath = './agent.metamynd.json', require: re
     // Deliberately UNDER any cap: a refusal at an amount that also trips a spend limit
     // proves nothing about merchants, which is exactly how this went unnoticed before.
     const amt = found.perTxn.configured ? Math.max(1, Math.floor(found.perTxn.limit / 2)) : 1;
-    const v = evaluate({ action, amount: amt, merchant: '__unapproved_supplier__', context: {} });
+    const v = evaluate({ action, amount: amt, ...baselineCurrency, merchant: '__unapproved_supplier__', context: { ...baseContext } });
     add('merchants', permits(v) ? FAIL : PASS, 'refuses an unlisted merchant, under the cap', v,
       permits(v) ? 'the merchant allow-list did not hold' : null);
   } else {