create-metamynd-agent 0.14.4 → 0.14.7

package/README.md

@@ -433,9 +433,12 @@ signed value only and ignores one in the context. Scaffolds pin `@metamynd/agent
 
 The starter rules include a high-risk review. A request that sends **no** `riskLevel` (or an unrecognised one)
 is no longer waved through: it is **escalated** (`CONTEXT_UNVERIFIABLE`) for a human, because an agent that omits
-its risk is indistinguishable from one hiding it. The scaffolded financial examples send `riskLevel` (`'low'`
-unless you say otherwise) — that default is a placeholder, not an assessment — and the neutral template passes
-your own `args` as the context, so include it there. A real integration should send an honest one — or, better, not depend on the agent at all: a mandate
+its risk is indistinguishable from one hiding it. The scaffolded examples pass the tool call's own `riskLevel`
+through **unchanged** — there is no default, so a call that does not say is sent for review rather than treated as
+`'low'` (the demo steps each state their risk explicitly). The neutral template passes your own `args` as the
+context, so include it there. Either way `riskLevel` is **the agent's own claim**: it travels in the request
+context, and even when the agent's key signs that context, the signature proves who said it, not that it is true —
+nothing checks the value unless your owner configures provenance for it. A real integration should send an honest one — or, better, not depend on the agent at all: a mandate
 permission can carry an owner-set `riskTier` that no claim can lower, and a gateway route can derive the risk
 itself with `route.trustedContext` (`@metamynd/agentsafe-http-gateway` 0.10.0). See MAGP §6.3.
 

package/index.mjs

@@ -225,7 +225,8 @@ ${c.b('Options')}
   --force, -f          Scaffold into a non-empty directory, overwriting existing files
   --api <url>          API base (default ${DEFAULT_API})
   --email <email>      Owner login email
-  --password <pw>      Owner password (prefer the interactive prompt or METAMYND_PASSWORD)
+  --password <pw>      Owner password (prefer the interactive prompt or METAMYND_PASSWORD).
+                       One session per account: logging in signs it out of the dashboard.
   --name <name>        Agent name (e.g. "Support Bot")
   --scope <scope>      Mandate action scope (e.g. flight-purchase)
   --per-txn-max <n>    Per-transaction cap (default 500)
@@ -374,6 +375,16 @@ function loadConfigFile(path) {
   return json;
 }
 
+// Written into every financial scaffold's README. The generated code passes the tool call's riskLevel through
+// unchanged (no `?? 'low'`): a missing one must reach the gate as missing, where it escalates by design.
+const RISK_LEVEL_NOTE = `## Risk level: the agent's own claim
+
+\`riskLevel\` is **the agent's own claim**. It travels in the request's context: the agent's key may sign that context,
+which proves who said it, not that it is true, and nothing checks the value unless your owner configures provenance for it (an owner-set \`riskTier\` on the mandate permission, or a
+gateway route's \`trustedContext\`). \`index.mjs\` passes the tool call's own \`riskLevel\` through unchanged —
+there is **no default**. A call that does not state one (or states one the gate does not recognise) is **sent
+for review** (\`CONTEXT_UNVERIFIABLE\`), never treated as \`low\`. The demo steps each state their risk explicitly.`;
+
 // A rule needs `when.predicate` (the atom) and `then` (the decision the gate should return
 // when it fires) — everything else is optional sugar. See backend's atom-catalog.ts for the
 // full predicate list (amount-over, risk-at-or-above, jurisdiction-not-allowed, ...).
@@ -476,10 +487,27 @@ function defaultNeutralDemo() {
   return demo;
 }
 
+/**
+ * Where an agent's rules are edited in the dashboard. SOPs belong to the legal entity, so the page is
+ * VeriFAI → Legal Entities (/dashboard/organization), SOPs tab; the AgentSafe sidebar group links the same
+ * tab as "SOPs". This said "Legal Entity → SOPs", a path no menu had (2026-10-02 eval, L-1).
+ */
+const SOPS_PATH = 'Dashboard → VeriFAI → Legal Entities → SOPs tab (also linked as AgentSafe → SOPs)';
+/** The same path for the generated demo's console output, which stays ASCII. */
+const SOPS_PATH_ASCII = 'Dashboard -> VeriFAI -> Legal Entities -> SOPs';
+/**
+ * A --sandbox scaffold runs as the SHARED sandbox agent, which no user has dashboard access to, so "change
+ * the rules in the dashboard" sent them somewhere they could not go (L-7). Say how to get an agent whose
+ * rules they CAN change instead.
+ */
+const SANDBOX_RULES_FIXED = "This is the shared sandbox agent: its rules are fixed and nobody can edit them. To change the rules, provision your own agent — re-run without --sandbox (it signs you up and creates an agent whose SOPs you own, edited at " + SOPS_PATH + "), or use --harness for a free local agent whose rules you edit by hand.";
+
 /** A --config file's rules cannot reach an agent the caller does not provision themselves: say so instead of implying they apply. */
-function warnRulesNotApplied(fileConfig, where) {
+function warnRulesNotApplied(fileConfig, where, { shared = false } = {}) {
   if (policyMolecules(fileConfig).length === 0) return;
-  console.log(`  ${c.yellow('!')} the rules in ${c.b('the config file')} are not applied to ${where} — its rules are the platform's defaults. Set your own in the dashboard (Legal Entity → SOPs), or provision your own agent (drop this flag) to author them here.`);
+  console.log(shared
+    ? `  ${c.yellow('!')} the rules in ${c.b('the config file')} are not applied to ${where} — its rules are the platform's defaults, and nobody can change them. Provision your own agent (drop this flag) to author them here.`
+    : `  ${c.yellow('!')} the rules in ${c.b('the config file')} are not applied to ${where} — its rules are the platform's defaults. Its owner sets them in the dashboard (${SOPS_PATH}), or provision your own agent (drop this flag) to author them here.`);
 }
 
 /**
@@ -1032,7 +1060,7 @@ function keepConfigAndFail(outDir, config, why) {
  * it — the same shape of gap --harness's README documents. See exampleIndex() below, which is
  * what the real (non-sandbox) flow scaffolds by default instead.
  */
-function exampleIndexNoGateway(scope, perTxnMax, currency, merchant) {
+function exampleIndexNoGateway(scope, perTxnMax, currency, merchant, sandbox = false) {
   const under = Math.max(1, Math.round(perTxnMax * 0.5));
   const over = Math.round(perTxnMax + 100);
   return `// index.mjs — your agent, governed by MetaMynd/AgentSafe.
@@ -1061,7 +1089,10 @@ const gatedBookFlight = guard.guardTool(
     amount: a.amount,
     currency: '${currency}',
     merchant: a.merchant,
-    context: { tool: 'book-flight', riskLevel: a.riskLevel ?? 'low' },
+    // riskLevel is the agent's OWN claim: signing it proves who said it, not that it is true, and nothing checks it unless
+    // the owner configures provenance. Passed through as-is: when the agent does not say, it stays absent and the gate sends
+    // the action for review — never 'low'.
+    context: { tool: 'book-flight', riskLevel: a.riskLevel },
   }),
 );
 
@@ -1176,8 +1207,12 @@ console.log(bold('  Without MetaMynd, you can be bypassed.') + ' bookFlight() ru
 console.log(dim('  call it directly instead of gatedBookFlight and nothing above stops you.'));
 console.log(dim('  Re-scaffold without --sandbox/--no-gateway for the default shape, which does.'));
 console.log('');
-console.log('  Change the cap in the dashboard (Legal Entity -> SOPs) and run again.');
-console.log(dim('  The outcome changes. This file does not. That is the point.'));
+${sandbox ? `console.log('  This is the SHARED sandbox agent: its rules are fixed and nobody can edit them.');
+console.log(dim('  To change the cap, provision your own agent: re-run create-metamynd-agent'));
+console.log(dim('  without --sandbox (it signs you up), then change the cap in your dashboard'));
+console.log(dim('  (${SOPS_PATH_ASCII}) and run again.'));
+console.log(dim('  The outcome changes. Your code does not. That is the point.'));` : `console.log('  Change the cap in the dashboard (${SOPS_PATH_ASCII}) and run again.');
+console.log(dim('  The outcome changes. This file does not. That is the point.'));`}
 console.log('');
 `;
 }
@@ -1222,7 +1257,8 @@ async function bookFlightViaGateway(args, decision) {
     amount: args.amount,
     currency: args.currency ?? '${currency}',
     merchant: args.merchant,
-    context: { tool: 'book-flight', riskLevel: args.riskLevel ?? 'low' },
+    // Passed through as-is (never defaulted): a missing riskLevel must reach the gateway as missing.
+    context: { tool: 'book-flight', riskLevel: args.riskLevel },
     payload,
   });
   signed.authorizationId = decision?.authorizationId;
@@ -1250,7 +1286,10 @@ const gatedBookFlight = guard.guardTool(
     amount: a.amount,
     currency: a.currency ?? '${currency}',
     merchant: a.merchant,
-    context: { tool: 'book-flight', riskLevel: a.riskLevel ?? 'low' },
+    // riskLevel is the agent's OWN claim: signing it proves who said it, not that it is true, and nothing checks it unless
+    // the owner configures provenance. Passed through as-is: when the agent does not say, it stays absent and the gate sends
+    // the action for review — never 'low'.
+    context: { tool: 'book-flight', riskLevel: a.riskLevel },
     // The authorization is bound to the SAME body bookFlightViaGateway() sends, so the gate records what this agent
     // signed and the gateway can prove it is running exactly that. Keep the two in step if you add a field.
     payload: { amount: a.amount, merchant: a.merchant, currency: a.currency ?? '${currency}' },
@@ -1373,7 +1412,7 @@ console.log('');
 console.log(bold('  With MetaMynd, you can\\'t be bypassed.') + ' ./gateway is why - it independently');
 console.log(dim('  re-verified step 1 before running it, and holds the tool this file never can.'));
 console.log('');
-console.log('  Change the cap in the dashboard (Legal Entity -> SOPs) and run again.');
+console.log('  Change the cap in the dashboard (${SOPS_PATH_ASCII}) and run again.');
 console.log(dim('  The outcome changes. This file does not. That is the point.'));
 console.log('');
 `;
@@ -1406,7 +1445,7 @@ If a committed \`package-lock.json\` pins an older \`${GUARD_PKG}\` than this pr
  * with `gatewayPort` the tool lives in a separate process (./gateway, the real enforcement
  * boundary); without it (--no-gateway) the tool is a local function in this process.
  */
-function exampleIndexNeutral({ scope, gatewayPort, demo, merchant }) {
+function exampleIndexNeutral({ scope, gatewayPort, demo, merchant, sandbox = false }) {
   const withGateway = gatewayPort != null;
   const steps = [
     ...demo.cases,
@@ -1553,8 +1592,12 @@ console.log(bold('  Without MetaMynd, you can be bypassed.') + ' performAction()
 console.log(dim('  call it directly instead of gatedAction and nothing above stops you.'));
 console.log(dim('  Re-scaffold without --no-gateway for the default shape, which closes that.'));`}
 console.log('');
-console.log('  Change your rules in the dashboard (Legal Entity -> SOPs) and run again.');
-console.log(dim('  The outcome changes. This file does not. That is the point.'));
+${sandbox ? `console.log('  This is the SHARED sandbox agent: its rules are fixed and nobody can edit them.');
+console.log(dim('  To change them, provision your own agent: re-run create-metamynd-agent'));
+console.log(dim('  without --sandbox (it signs you up), then change its rules in your dashboard'));
+console.log(dim('  (${SOPS_PATH_ASCII}) and run again.'));
+console.log(dim('  The outcome changes. Your code does not. That is the point.'));` : `console.log('  Change your rules in the dashboard (${SOPS_PATH_ASCII}) and run again.');
+console.log(dim('  The outcome changes. This file does not. That is the point.'));`}
 console.log('');
 `;
 }
@@ -1733,7 +1776,15 @@ Replace \`performAction()\` in \`server.mjs\` with your implementation and put a
 }
 
 /** The README for a non-financial hosted scaffold. `withGateway` selects the two-process shape. */
-function exampleReadmeNeutral(slug, scope, withGateway, gatewayPort, daemonKey, demo) {
+/** The generated README's "Change the rules" body: the dashboard path, or — for the shared sandbox agent — how to get an agent whose rules you can change. */
+function changeRulesSection(sandbox) {
+  return sandbox
+    ? `${SANDBOX_RULES_FIXED} An \`escalate\` verdict is held for an owner to approve; poll \`guard.escalationStatus(id)\`.`
+    : `Edit the agent's SOPs in the dashboard (${SOPS_PATH}). The agent's behaviour changes live —
+no redeploy. An \`escalate\` verdict is held for an owner to approve; poll \`guard.escalationStatus(id)\`.`;
+}
+
+function exampleReadmeNeutral(slug, scope, withGateway, gatewayPort, daemonKey, demo, sandbox = false) {
   const configLine = daemonKey
     ? `- \`agent.metamynd.json\` — your portable guard config (identity, mandate scope \`${scope}\`, issuer keys).
   **Holds no secret key.** Signing goes through your already-running agentsafe-signer daemon instead.`
@@ -1812,8 +1863,7 @@ ${clonedFreshSection(daemonKey)}
 
 ## Change the rules
 
-Edit the agent's SOPs in the dashboard (Legal Entity → SOPs). The agent's behaviour changes live —
-no redeploy. An \`escalate\` verdict is held for an owner to approve; poll \`guard.escalationStatus(id)\`.
+${changeRulesSection(sandbox)}
 
 ## What this is not
 
@@ -1850,7 +1900,7 @@ function examplePackageJson(slug, neutral = false) {
   ) + '\n';
 }
 
-function exampleReadme(slug, scope, withGateway, gatewayPort, daemonKey = false) {
+function exampleReadme(slug, scope, withGateway, gatewayPort, daemonKey = false, sandbox = false) {
   const configFileLine = daemonKey
     ? `- \`agent.metamynd.json\` — your portable guard config (identity, mandate scope \`${scope}\`, issuer keys).
   **Holds no secret key.** Signing goes through your already-running agentsafe-signer daemon
@@ -1877,6 +1927,8 @@ You should see an ALLOW (fulfilled by \`./gateway\`), a BLOCK (over the per-tran
 an ESCALATE (high risk). The BLOCK and ESCALATE never reach the gateway at all — this file's own
 \`guard.guardTool()\` refuses them first. Only the ALLOW crosses into the other process.
 
+${RISK_LEVEL_NOTE}
+
 ## Files
 
 ${configFileLine}
@@ -1898,6 +1950,8 @@ npm start
 
 You should see an ALLOW, a BLOCK (over the per-transaction cap), and an ESCALATE (high risk).
 
+${RISK_LEVEL_NOTE}
+
 ## Files
 
 ${configFileLine}
@@ -1940,8 +1994,7 @@ ${clonedFreshSection(daemonKey)}
 
 ## Change the rules
 
-Edit the agent's SOPs in the dashboard (Legal Entity → SOPs). The agent's behaviour changes live —
-no redeploy. An \`escalate\` verdict is held for an owner to approve; poll \`guard.escalationStatus(id)\`.
+${changeRulesSection(sandbox)}
 
 Full integration guide: \`docs/integration/INTEGRATE-WITH-METAMYND.md\`.
 `;
@@ -2282,10 +2335,10 @@ function scaffoldProject({ outDir, config, slug, scope, perTxnMax, currency = 'U
     outDir,
     'index.mjs',
     neutral
-      ? exampleIndexNeutral({ scope, gatewayPort: withGateway ? gatewayPort : null, demo, merchant })
+      ? exampleIndexNeutral({ scope, gatewayPort: withGateway ? gatewayPort : null, demo, merchant, sandbox: !!sandbox })
       : withGateway
         ? exampleIndex(scope, perTxnMax, gatewayPort, currency, paymentMerchant)
-        : exampleIndexNoGateway(scope, perTxnMax, currency, paymentMerchant),
+        : exampleIndexNoGateway(scope, perTxnMax, currency, paymentMerchant, !!sandbox),
     force,
   );
   writeFileSafe(outDir, 'package.json', examplePackageJson(slug, neutral), force);
@@ -2294,8 +2347,8 @@ function scaffoldProject({ outDir, config, slug, scope, perTxnMax, currency = 'U
     outDir,
     'README.md',
     neutral
-      ? exampleReadmeNeutral(slug, scope, withGateway, gatewayPort, config.keyProvider === 'daemon', demo)
-      : exampleReadme(slug, scope, withGateway, gatewayPort, config.keyProvider === 'daemon'),
+      ? exampleReadmeNeutral(slug, scope, withGateway, gatewayPort, config.keyProvider === 'daemon', demo, !!sandbox)
+      : exampleReadme(slug, scope, withGateway, gatewayPort, config.keyProvider === 'daemon', !!sandbox),
     force,
   );
   // `npm test` (agentsafe-guard verify --context) needs the request inputs of a compliant request:
@@ -2366,7 +2419,9 @@ function scaffoldProject({ outDir, config, slug, scope, perTxnMax, currency = 'U
     console.log(c.dim('                 · BLOCK (the agent asking to raise its OWN limit)\n'));
   }
   console.log(c.cyan(`    npm test`) + c.dim('    → assert it CANNOT exceed its mandate. Put this in CI.\n'));
-  console.log(c.dim(`  Change the rules any time in the dashboard (Legal Entity → SOPs) — no redeploy.\n`));
+  console.log(c.dim(sandbox
+    ? `  ${SANDBOX_RULES_FIXED}\n`
+    : `  Change the rules any time in the dashboard (${SOPS_PATH}) — no redeploy.\n`));
 }
 
 /** --sandbox: no login, no KYB — fetch the shared sandbox agent config and scaffold. */
@@ -2381,7 +2436,7 @@ async function runSandbox(args) {
   const fileConfig = typeof args.config === 'string' ? loadConfigFile(args.config) : null;
   if (fileConfig) console.log(`  ${c.green('✓')} loaded policy config ${c.dim(args.config)}`);
   const { financial } = announceFinancial(args, fileConfig);
-  warnRulesNotApplied(fileConfig, 'the shared sandbox agent');
+  warnRulesNotApplied(fileConfig, 'the shared sandbox agent', { shared: true });
   if (!financial && typeof fileConfig?.scope === 'string' && fileConfig.scope !== 'perform-action') {
     console.log(`  ${c.yellow('!')} the scope "${fileConfig.scope}" in the config file is not used: the shared sandbox agent's scope is "perform-action".`);
   }
@@ -3095,7 +3150,8 @@ async function callGateway(path, action, args) {
   // The COMPLETE body the tool receives, signed as a payload (MAGP 8.3.9): the eight signed fields cover amount and merchant
   // only, and this gateway refuses to run the tool on a body that is not exactly the one signed here.
   const payload = { amount: args.amount, merchant: args.merchant, currency: args.currency ?? '${currency}' };
-  const signed = await guard.buildSignedRequest({ action, amount: args.amount, currency: args.currency ?? '${currency}', merchant: args.merchant, context: { tool: '${scope}', riskLevel: args.riskLevel ?? 'low' }, payload });
+  // riskLevel is passed through as-is (never defaulted): a missing one must reach the gateway as missing.
+  const signed = await guard.buildSignedRequest({ action, amount: args.amount, currency: args.currency ?? '${currency}', merchant: args.merchant, context: { tool: '${scope}', riskLevel: args.riskLevel }, payload });
   const res = await fetch(GATEWAY + path, { method: 'POST', headers: { 'content-type': 'application/json', 'x-magp-request': JSON.stringify(signed) }, body: JSON.stringify(payload) });
   const body = await res.json().catch(() => null);
   if (!res.ok) {
@@ -3120,7 +3176,10 @@ const gatedBookFlight = guard.guardToolLocal(
     amount: a.amount,
     currency: a.currency ?? '${currency}',
     merchant: a.merchant,
-    context: { tool: 'book-flight', riskLevel: a.riskLevel ?? 'low' },
+    // riskLevel is the agent's OWN claim: signing it proves who said it, not that it is true, and nothing checks it unless
+    // the owner configures provenance. Passed through as-is: when the agent does not say, it stays absent and the gate sends
+    // the action for review — never 'low'.
+    context: { tool: 'book-flight', riskLevel: a.riskLevel },
   }),
   getBundle,
 );
@@ -3474,7 +3533,9 @@ action outside the mandate entirely. Every step says what it expects and flags a
     : `None of your rules could be staged in the demo (see below), so it shows only a BLOCK for an
 action outside the mandate. Your rules are still enforced; see \`metamynd-rules.json\`.`)
   : `You should see an ALLOW, a BLOCK (over the per-transaction cap), an ESCALATE (high risk —
-open the dashboard to approve it), and a BLOCK (an action outside the mandate entirely).`}
+open the dashboard to approve it), and a BLOCK (an action outside the mandate entirely).
+
+${RISK_LEVEL_NOTE}`}
 
 ## Files
 
@@ -3704,9 +3765,15 @@ async function authFlow(args) {
   const login = await apiPost(base, '/auth/login', { username: email, password }, null);
   const token = login?.data?.accessToken;
   if (!token) fail('Login succeeded but no access token was returned.');
+  console.log(c.dim(`  ${SESSION_REPLACED_NOTE}`));
   return { base, token, email };
 }
 
+// One session per account: a CLI login replaces the account's dashboard session (the dashboard then answers
+// SESSION_REPLACED and explains). Said up front so it is not a surprise (item 14 of the 2026-10-02 open items).
+const SESSION_REPLACED_NOTE =
+  'Note: an account has one session at a time, so this login signs that account out of the MetaMynd dashboard in your browser. Sign in there again afterwards.';
+
 const REQUEST_STATE_FILE = 'metamynd-request.json';
 
 // --request: a developer requests an agent for an owner's org (the owner approves in the dashboard).
@@ -3911,6 +3978,7 @@ async function main() {
   const token = login?.data?.accessToken;
   if (!token) { rl?.close(); fail('Login succeeded but no access token was returned.'); }
   console.log(`  ${c.green('✓')} authenticated as ${email}`);
+  console.log(c.dim(`    ${SESSION_REPLACED_NOTE}`));
 
   // 2. Agent details — a --config file's fields are the default at every prompt/flag below.
   const name = await pick('name', null, 'Agent name', fileConfig?.name ?? 'Support Bot');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-metamynd-agent",
-  "version": "0.14.4",
+  "version": "0.14.7",
   "description": "Scaffold a MetaMynd/AgentSafe-governed AI agent in one command — logs in, provisions the agent (identity + mandate + SOP + Standards) in a single call, writes agent.metamynd.json plus a runnable agent + separate tool-gateway process that closes direct-call, confused-deputy, replay, and cumulative-spend bypasses. --harness scaffolds a free, local, zero-network governance harness instead.",
   "type": "module",
   "bin": {