create-metamynd-agent 0.1.0

package/README.md

@@ -0,0 +1,120 @@
+# create-metamynd-agent
+
+Scaffold a **MetaMynd/AgentSafe-governed** AI agent in one command. It logs you in, provisions the
+agent in a **single call** (identity + mandate + starter SOP + all enforced Standards), writes a
+portable `agent.metamynd.json`, and drops a runnable example that gates a tool through the
+[`@metamynd/agentsafe-guard`](https://www.npmjs.com/package/@metamynd/agentsafe-guard).
+
+> **Prerequisite:** an agent is always owned by a **KYB-verified owner** — a person/org with a
+> MetaMynd account. If that's you and you're verified, you're ready. Verify once in the dashboard if
+> not; it's the only gate.
+
+## Try it instantly — sandbox (no account, no KYB)
+
+```bash
+npm create metamynd-agent@latest -- --sandbox   # or: npx create-metamynd-agent --sandbox
+```
+
+Skips login and provisioning entirely — fetches a **shared sandbox agent** config from the public
+`POST /onboarding/sandbox` endpoint and scaffolds a runnable example. Great for a first look; use
+the full flow below when you want your own governed agent with your own limits.
+
+## Use
+
+```bash
+npm create metamynd-agent@latest
+# or
+npx create-metamynd-agent
+```
+
+Answer a few prompts (API, owner email/password, agent name, scope, per-transaction cap) and you get:
+
+```
+my-agent/
+├─ agent.metamynd.json   # portable guard config — HOLDS THE AGENT SECRET KEY (gitignored)
+├─ index.mjs             # runnable example: ALLOW · BLOCK (over cap) · ESCALATE (high risk)
+├─ package.json          # depends on @metamynd/agentsafe-guard
+├─ .gitignore
+└─ README.md
+```
+
+Then:
+
+```bash
+cd my-agent
+npm install
+npm start
+```
+
+## Non-interactive
+
+Every prompt has a flag or environment-variable fallback, so it scripts cleanly in CI:
+
+```bash
+npx create-metamynd-agent \
+  --api http://localhost:9926/api/v1 \
+  --email owner@example.com \
+  --name "Support Bot" \
+  --scope flight-purchase \
+  --per-txn-max 500 \
+  --out ./support-bot \
+  --yes
+# password via env (never on the command line where it lands in shell history):
+METAMYND_PASSWORD='…' npx create-metamynd-agent --yes …
+```
+
+| Flag | Env | Default |
+|---|---|---|
+| `--sandbox` | — | off (skips login/KYB; shared sandbox agent) |
+| `--api <url>` | `METAMYND_API` | `https://metamynd.ai/api/v1` |
+| `--email <email>` | `METAMYND_EMAIL` | — (required) |
+| `--password <pw>` | `METAMYND_PASSWORD` | interactive masked prompt |
+| `--name <name>` | — | `Support Bot` |
+| `--scope <scope>` | — | `flight-purchase` |
+| `--per-txn-max <n>` | — | `500` |
+| `--max-amount <n>` | — | `10000` |
+| `--currency <cur>` | — | `USD` |
+| `--merchants <a,b>` | — | any |
+| `--byok` | — | generate the keypair locally, provision + prove control |
+| `--public-key <hex>` | — | BYOK with a key you already hold (you prove control yourself) |
+| `--out <dir>` | — | `./<agent-slug>` |
+| `--yes`, `-y` | — | non-interactive |
+
+Run `npx create-metamynd-agent --help` for the full list.
+
+## Bring your own key (`--byok`)
+
+```bash
+npx create-metamynd-agent --byok --email you@example.com --name "Support Bot"
+```
+
+Generates an Ed25519 keypair **on your machine**, provisions the agent with only the public key, then
+proves control (signs the one-time challenge → `verify-key`). MetaMynd never sees the private key. The
+generated private key is written into `agent.metamynd.json` (gitignored). Pass `--public-key <hex>`
+instead to register a key you already hold elsewhere — then you complete `verify-key` yourself (the CLI
+prints the challenge + endpoint).
+
+## Delegated issuance (`--request` / `--claim`)
+
+Request an agent for an owner's org when you're **not** the owner — no shared credentials:
+
+```bash
+npx create-metamynd-agent --request --owner owner@example.com --name "Support Bot"   # +--byok optional
+# → saves metamynd-request.json (holds a one-time claim token — do not commit)
+# → the owner approves in their dashboard (AgentSafe → Agent Requests), then:
+npx create-metamynd-agent --claim --watch
+```
+
+`--request` submits the request (as your own authed user) and stores the claim token locally; `--claim`
+polls until the owner approves, then scaffolds the project. With `--byok` the keypair is generated
+locally and control is proven on claim — MetaMynd never sees the private key.
+
+## Security
+
+`agent.metamynd.json` contains the agent's **secret key** (a managed key, or — with `--byok` — the one
+generated locally). The scaffolded project gitignores it. Never commit it or paste it anywhere public.
+
+## Full guide
+
+`docs/integration/INTEGRATE-WITH-METAMYND.md` — the complete integration front-door (payments,
+handshake, edge evaluation, escalation).

package/index.mjs

@@ -0,0 +1,542 @@
+#!/usr/bin/env node
+// create-metamynd-agent — scaffold a MetaMynd/AgentSafe-governed agent in one command.
+//
+// Logs a KYB-verified owner in, provisions the agent in ONE call
+// (POST /onboarding/agent → identity + mandate + starter SOP + enforced Standards),
+// writes the portable `agent.metamynd.json`, and drops a runnable example that gates a
+// tool through the guard (allow / block / escalate).
+//
+// ZERO dependencies: Node ≥ 18 built-ins only (fetch, readline).
+//
+//   npm create metamynd-agent@latest
+//   npx create-metamynd-agent
+//   npx create-metamynd-agent --api http://localhost:9926/api/v1 --email you@x.com \
+//       --name "Support Bot" --scope flight-purchase --per-txn-max 500 --out ./support-bot --yes
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import readline from 'node:readline';
+import crypto from 'node:crypto';
+
+const GUARD_PKG = '@metamynd/agentsafe-guard';
+const GUARD_VERSION = '^0.1.0';
+const DEFAULT_API = 'https://metamynd.ai/api/v1';
+
+// ---------- tiny ANSI ----------
+const c = {
+  b: (s) => `\x1b[1m${s}\x1b[0m`,
+  dim: (s) => `\x1b[2m${s}\x1b[0m`,
+  green: (s) => `\x1b[32m${s}\x1b[0m`,
+  red: (s) => `\x1b[31m${s}\x1b[0m`,
+  yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+  cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+};
+
+// ---------- args ----------
+function parseArgs(argv) {
+  const out = { _: [] };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '-h' || a === '--help') { out.help = true; continue; }
+    if (a === '-v' || a === '--version') { out.version = true; continue; }
+    if (a === '-y' || a === '--yes' || a === '--non-interactive') { out.yes = true; continue; }
+    if (a.startsWith('--')) {
+      const eq = a.indexOf('=');
+      if (eq !== -1) { out[a.slice(2, eq)] = a.slice(eq + 1); continue; }
+      const key = a.slice(2);
+      const next = argv[i + 1];
+      if (next === undefined || next.startsWith('-')) { out[key] = true; }
+      else { out[key] = next; i++; }
+    } else { out._.push(a); }
+  }
+  return out;
+}
+
+const HELP = `${c.b('create-metamynd-agent')} — scaffold a governed AI agent
+
+${c.b('Usage')}
+  npm create metamynd-agent@latest
+  npx create-metamynd-agent [options]
+
+${c.b('Options')}
+  --sandbox            No login, no KYB: scaffold against the shared sandbox agent (fastest start)
+  --request            Delegated: request an agent for an owner's org (--owner <email>, +--byok)
+  --claim [--watch]    Delegated: claim the config once the owner approves (reads metamynd-request.json)
+  --owner <email>      Target owner's email (with --request)
+  --api <url>          API base (default ${DEFAULT_API})
+  --email <email>      Owner login email
+  --password <pw>      Owner password (prefer the interactive prompt or METAMYND_PASSWORD)
+  --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)
+  --max-amount <n>     Total mandate budget (default 10000)
+  --currency <cur>     Currency (default USD)
+  --merchants <a,b>    Allowed merchants, comma-separated (optional)
+  --byok               Bring-your-own-key: generate the keypair locally, provision + prove control
+                       (MetaMynd never sees the private key). Overridden by --public-key.
+  --public-key <hex>   BYOK with a key you already hold (SPKI/raw hex); you prove control yourself
+  --out <dir>          Output project directory (default ./<agent-slug>)
+  --yes, -y            Non-interactive: use flags/env/defaults, never prompt
+  -h, --help           Show this help
+  -v, --version        Show version
+
+${c.b('Environment')}
+  METAMYND_API, METAMYND_EMAIL, METAMYND_PASSWORD  — fallbacks for the flags above
+
+${c.b('What it does')}
+  1. Logs in as a KYB-verified owner       → owner access token
+  2. POST /onboarding/agent (one call)      → identity + mandate + SOP + Standards
+  3. Writes agent.metamynd.json + a runnable example that gates a tool through the guard.
+`;
+
+// ---------- prompts ----------
+function makeRl() {
+  return readline.createInterface({ input: process.stdin, output: process.stdout });
+}
+function ask(rl, query, def) {
+  const suffix = def !== undefined && def !== '' ? c.dim(` (${def})`) : '';
+  return new Promise((res) => rl.question(`${query}${suffix}: `, (a) => res(a.trim() || (def ?? ''))));
+}
+// Hidden input (password) — raw mode, masks with '*', handles backspace/paste/Ctrl-C.
+function askHidden(query) {
+  return new Promise((resolve) => {
+    const stdin = process.stdin;
+    process.stdout.write(`${query}: `);
+    const wasRaw = stdin.isRaw;
+    if (stdin.setRawMode) stdin.setRawMode(true);
+    stdin.resume();
+    stdin.setEncoding('utf8');
+    let input = '';
+    const done = () => {
+      if (stdin.setRawMode) stdin.setRawMode(Boolean(wasRaw));
+      stdin.pause();
+      stdin.removeListener('data', onData);
+      process.stdout.write('\n');
+      resolve(input);
+    };
+    const onData = (chunk) => {
+      for (const ch of chunk) {
+        const code = ch.charCodeAt(0);
+        if (code === 13 || code === 10 || code === 4) { done(); return; } // Enter / Ctrl-D
+        if (code === 3) { process.stdout.write('\n'); process.exit(130); } // Ctrl-C
+        if (code === 127 || code === 8) { if (input.length) { input = input.slice(0, -1); process.stdout.write('\b \b'); } continue; } // backspace
+        if (code < 32) continue; // ignore other control chars
+        input += ch;
+        process.stdout.write('*');
+      }
+    };
+    stdin.on('data', onData);
+  });
+}
+
+function fail(msg) {
+  console.error(`\n${c.red('✖')} ${msg}\n`);
+  process.exit(1);
+}
+
+function slugify(name) {
+  return String(name).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 60) || 'metamynd-agent';
+}
+
+// ---------- BYOK (bring-your-own-key) ----------
+// Generate an Ed25519 keypair CLIENT-SIDE — the private key never leaves this machine, so MetaMynd
+// never sees it. The public key is sent as SPKI DER hex (algorithm-tagged Ed25519, unambiguous to
+// the Hedera SDK); the private key is PKCS8 DER hex, the exact format the guard's createGuard loads.
+function generateAgentKeypair() {
+  const { publicKey, privateKey } = crypto.generateKeyPairSync('ed25519');
+  return {
+    publicKeyHex: publicKey.export({ format: 'der', type: 'spki' }).toString('hex'),
+    privateKeyHex: privateKey.export({ format: 'der', type: 'pkcs8' }).toString('hex'),
+  };
+}
+
+// Sign a BYOK challenge exactly as the gate verifies it: Ed25519 over the UTF-8 bytes of the raw
+// challenge nonce, hex-encoded. Mirrors agentsafe-guard's sign().
+function signChallengeHex(privateKeyHex, challenge) {
+  const key = crypto.createPrivateKey({ key: Buffer.from(privateKeyHex, 'hex'), format: 'der', type: 'pkcs8' });
+  return crypto.sign(null, Buffer.from(challenge, 'utf8'), key).toString('hex');
+}
+
+// ---------- API ----------
+async function apiPost(base, path, body, token) {
+  let res;
+  try {
+    res = await fetch(`${base}${path}`, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json', ...(token ? { Authorization: `Bearer ${token}` } : {}) },
+      body: JSON.stringify(body),
+    });
+  } catch (e) {
+    fail(`Cannot reach ${base}${path} — is the API up? (${e.message})`);
+  }
+  const text = await res.text();
+  let json = null;
+  try { json = text ? JSON.parse(text) : null; } catch { /* non-JSON */ }
+  if (!res.ok) {
+    const detail = json?.message ? (typeof json.message === 'string' ? json.message : JSON.stringify(json.message)) : text.slice(0, 300);
+    fail(`${path} → HTTP ${res.status}${detail ? `: ${detail}` : ''}`);
+  }
+  return json;
+}
+
+// ---------- scaffolding ----------
+function exampleIndex(scope, perTxnMax) {
+  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.
+// Every governed tool call is checked (allow / block / escalate) before it runs.
+import { createGuardFromConfig } from '${GUARD_PKG}';
+
+const guard = await createGuardFromConfig('./agent.metamynd.json'); // no env vars
+
+// --- Your real tool. Replace the body with your actual implementation. ---
+async function bookFlight(args) {
+  return { pnr: 'PNR-DEMO', ...args };
+}
+
+// --- The GATED version. Register THIS with your agent instead of the raw handler. ---
+const gatedBookFlight = guard.guardTool(
+  '${scope}',                                   // = your mandate scope
+  bookFlight,
+  (a) => ({                                     // map tool args → gate inputs
+    amount: a.amount,
+    currency: 'USD',
+    merchant: a.merchant,
+    context: { tool: 'book-flight', riskLevel: a.riskLevel ?? 'low' },
+  }),
+);
+
+async function ask(label, args) {
+  try {
+    const r = await gatedBookFlight(args);
+    console.log('  \\x1b[32m✅ ALLOW\\x1b[0m    ' + label.padEnd(26) + ' → booked ' + r.pnr);
+  } catch (e) {
+    const g = e.governance ?? {};
+    const tag = g.decision === 'escalate' ? '\\x1b[33m⚠ ESCALATE\\x1b[0m' : '\\x1b[31m⛔ BLOCK\\x1b[0m';
+    console.log('  ' + tag + ' ' + label.padEnd(26) + ' → ' + (g.reasonCode ?? e.message));
+  }
+}
+
+console.log('\\n  ${scope} — every action passes through the MetaMynd gate\\n  ' + '─'.repeat(58));
+await ask('$${under} low risk',  { amount: ${under}, merchant: 'skyward-air', riskLevel: 'low' });
+await ask('$${over} over cap',  { amount: ${over}, merchant: 'skyward-air', riskLevel: 'low' });
+await ask('$${under} high risk', { amount: ${under}, merchant: 'skyward-air', riskLevel: 'high' });
+console.log('\\n  Change the rules any time in the dashboard (Legal Entity → SOPs) — no redeploy.\\n');
+`;
+}
+
+function examplePackageJson(slug) {
+  return JSON.stringify(
+    {
+      name: slug,
+      version: '0.1.0',
+      private: true,
+      type: 'module',
+      scripts: { start: 'node index.mjs' },
+      dependencies: { [GUARD_PKG]: GUARD_VERSION },
+    },
+    null,
+    2,
+  ) + '\n';
+}
+
+function exampleReadme(slug, scope) {
+  return `# ${slug}
+
+A MetaMynd/AgentSafe-governed agent, scaffolded with \`create-metamynd-agent\`.
+
+## Run
+
+\`\`\`bash
+npm install
+npm start
+\`\`\`
+
+You should see an ALLOW, a BLOCK (over the per-transaction cap), and an ESCALATE (high risk).
+
+## Files
+
+- \`agent.metamynd.json\` — your portable guard config (identity, mandate scope \`${scope}\`, issuer keys).
+  **Contains the agent's secret key — never commit it.** It is already in \`.gitignore\`.
+- \`index.mjs\` — wraps a tool with \`guard.guardTool(...)\`; the tool only runs when the gate allows.
+
+## 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)\`.
+
+Full integration guide: \`docs/integration/INTEGRATE-WITH-METAMYND.md\`.
+`;
+}
+
+function gitignore() {
+  return `node_modules/\nagent.metamynd.json\n.env\n`;
+}
+
+function writeFileSafe(dir, name, content) {
+  const p = join(dir, name);
+  if (existsSync(p)) { console.log(`  ${c.yellow('skip')}  ${name} ${c.dim('(exists)')}`); return; }
+  writeFileSync(p, content);
+  console.log(`  ${c.green('create')} ${name}`);
+}
+
+/** Write the scaffolded project + print next steps. Shared by the provision and sandbox paths. */
+function scaffoldProject({ outDir, config, slug, scope, perTxnMax, sandbox }) {
+  console.log(`\n  ${c.b('Scaffolding')} ${c.dim(outDir)}`);
+  if (!existsSync(outDir)) mkdirSync(outDir, { recursive: true });
+  writeFileSafe(outDir, 'agent.metamynd.json', JSON.stringify(config, null, 2) + '\n');
+  writeFileSafe(outDir, 'index.mjs', exampleIndex(scope, perTxnMax));
+  writeFileSafe(outDir, 'package.json', examplePackageJson(slug));
+  writeFileSafe(outDir, '.gitignore', gitignore());
+  writeFileSafe(outDir, 'README.md', exampleReadme(slug, scope));
+
+  const rel = outDir.replace(resolve('.'), '.').replace(/\\/g, '/');
+  console.log(`\n${c.green(c.b('  ✓ Done.'))} Your governed agent is ready.\n`);
+  if (sandbox) {
+    console.log(`  ${c.dim('Shared sandbox agent — for trying MetaMynd only. Provision your own (drop --sandbox) for anything real.')}\n`);
+  } else if (config.agentKey) {
+    console.log(`  ${c.yellow('⚠ agent.metamynd.json holds the agent secret key')} — it is gitignored; never commit it.\n`);
+  }
+  console.log(`  Next:`);
+  console.log(c.cyan(`    cd ${rel}`));
+  console.log(c.cyan(`    npm install`));
+  console.log(c.cyan(`    npm start`) + c.dim('   → ALLOW · BLOCK (over cap) · ESCALATE (high risk)\n'));
+  console.log(c.dim(`  Change the rules any time in the dashboard (Legal Entity → SOPs) — no redeploy.\n`));
+}
+
+/** --sandbox: no login, no KYB — fetch the shared sandbox agent config and scaffold. */
+async function runSandbox(args) {
+  const apiRaw = (typeof args.api === 'string' ? args.api : undefined) ?? process.env.METAMYND_API ?? DEFAULT_API;
+  const base = String(apiRaw).replace(/\/+$/, '');
+  console.log(c.dim(`  → requesting a sandbox agent from ${base} …`));
+  const provisioned = await apiPost(base, '/onboarding/sandbox', {}, null);
+  const config = provisioned?.data;
+  if (!config?.agentDid) fail('Sandbox did not return a config with an agentDid.');
+  console.log(`  ${c.green('✓')} sandbox agent ${c.b(config.agentDid)} ${c.dim('(shared test identity)')}`);
+  const scope = config.mandate?.scope || 'flight-purchase';
+  const perTxnMax = Number(config.perTxnMax) || 500;
+  const outDir = resolve(String(args.out || './metamynd-sandbox'));
+  scaffoldProject({ outDir, config, slug: 'metamynd-sandbox', scope, perTxnMax, sandbox: true });
+}
+
+// ---------- delegated issuance (#6) ----------
+async function apiGet(base, path, { claimToken } = {}) {
+  let res;
+  try {
+    res = await fetch(`${base}${path}`, { headers: { ...(claimToken ? { 'x-claim-token': claimToken } : {}) } });
+  } catch (e) {
+    fail(`Cannot reach ${base}${path} — is the API up? (${e.message})`);
+  }
+  const text = await res.text();
+  let json = null;
+  try { json = text ? JSON.parse(text) : null; } catch { /* non-JSON */ }
+  if (!res.ok) fail(`${path} → HTTP ${res.status}${json?.message ? `: ${json.message}` : ''}`);
+  return json;
+}
+
+// Minimal auth for the request flow (flags/env, interactive fallback) — mirrors main()'s login.
+async function authFlow(args) {
+  const apiRaw = (typeof args.api === 'string' ? args.api : undefined) ?? process.env.METAMYND_API ?? DEFAULT_API;
+  const base = String(apiRaw).replace(/\/+$/, '');
+  const interactive = !args.yes && process.stdin.isTTY;
+  const rl = interactive ? makeRl() : null;
+  let email = (typeof args.email === 'string' ? args.email : undefined) ?? process.env.METAMYND_EMAIL;
+  if (!email && interactive) email = await ask(rl, 'Your email', '');
+  if (!email) { rl?.close(); fail('An email is required (--email or METAMYND_EMAIL).'); }
+  let password = typeof args.password === 'string' ? args.password : process.env.METAMYND_PASSWORD;
+  if (password === undefined) {
+    if (!interactive) { rl?.close(); fail('A password is required (--password or METAMYND_PASSWORD).'); }
+    rl?.pause();
+    password = await askHidden('Password');
+    rl?.resume();
+  }
+  rl?.close();
+  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.');
+  return { base, token, email };
+}
+
+const REQUEST_STATE_FILE = 'metamynd-request.json';
+
+// --request: a developer requests an agent for an owner's org (the owner approves in the dashboard).
+// Writes metamynd-request.json (requestId + one-time claim token, and the local private key for --byok)
+// so `--claim` can finish once the owner approves.
+async function runRequest(args) {
+  const owner = (typeof args.owner === 'string' ? args.owner : undefined) ?? process.env.METAMYND_OWNER;
+  if (!owner) fail('--owner <ownerEmail> is required for a delegated request.');
+  const { base, token } = await authFlow(args);
+
+  const name = (typeof args.name === 'string' ? args.name : undefined) ?? 'Delegated Agent';
+  const scope = (typeof args.scope === 'string' ? args.scope : undefined) ?? 'flight-purchase';
+  const perTxnMax = Number(args['per-txn-max']) || 500;
+  let publicKey, generated;
+  if (args.byok) {
+    generated = generateAgentKeypair();
+    publicKey = generated.publicKeyHex;
+    console.log(`  ${c.green('✓')} generated an Ed25519 keypair locally ${c.dim('(private key stays on this machine)')}`);
+  }
+
+  console.log(c.dim(`  → requesting "${name}" for ${owner} …`));
+  const res = await apiPost(base, '/onboarding/requests', { ownerEmail: owner, name, scope, perTxnMax, ...(publicKey ? { publicKey } : {}) }, token);
+  const d = res.data;
+  const state = { api: base, requestId: d.requestId, claimToken: d.claimToken, byok: !!generated, privateKey: generated?.privateKeyHex ?? null, name, scope, perTxnMax };
+  const file = resolve(String(args.out || '.'), REQUEST_STATE_FILE);
+  writeFileSync(file, JSON.stringify(state, null, 2) + '\n');
+
+  console.log(`  ${c.green('✓')} request ${c.b(d.requestId)} submitted — awaiting ${owner}'s approval`);
+  console.log(`  ${c.yellow('⚠ saved the one-time claim token to')} ${file.replace(resolve('.'), '.').replace(/\\/g, '/')} ${c.dim('(secret — do not commit)')}\n`);
+  console.log(`  The owner approves in the dashboard (AgentSafe → Agent Requests). Then run:`);
+  console.log(c.cyan(`    npx create-metamynd-agent --claim --watch\n`));
+}
+
+// --claim: poll for the owner's approval, then scaffold. Reads metamynd-request.json (or flags).
+async function runClaim(args) {
+  const file = resolve(String(args['request-file'] || `./${REQUEST_STATE_FILE}`));
+  const state = existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : {};
+  const base = String((typeof args.api === 'string' ? args.api : undefined) ?? state.api ?? DEFAULT_API).replace(/\/+$/, '');
+  const requestId = (typeof args['request-id'] === 'string' ? args['request-id'] : undefined) ?? state.requestId;
+  const claimToken = (typeof args.token === 'string' ? args.token : undefined) ?? state.claimToken;
+  if (!requestId || !claimToken) fail(`Need a requestId + claim token (--request-id/--token, or a ${REQUEST_STATE_FILE}).`);
+
+  const watch = !!args.watch;
+  let claimed;
+  for (;;) {
+    const res = await apiGet(base, `/onboarding/requests/${encodeURIComponent(requestId)}/claim`, { claimToken });
+    const d = res.data;
+    if (d.status === 'approved') { claimed = d; break; }
+    if (d.status === 'denied' || d.status === 'expired') fail(`Request was ${d.status}.`);
+    if (!watch) {
+      console.log(`  ${c.dim(`request is still ${d.status} — the owner hasn't approved yet. Re-run, or add --watch to poll.`)}`);
+      return;
+    }
+    process.stdout.write(c.dim(`  · ${d.status}, waiting for approval …\r`));
+    await new Promise((r) => setTimeout(r, 5000));
+  }
+
+  const config = claimed.config;
+  if (!config?.agentDid) fail('Approved, but no config was returned.');
+  console.log(`\n  ${c.green('✓')} approved — claimed config for ${c.b(config.agentDid)}`);
+
+  // BYOK: inject the local private key and prove control via the claim token.
+  if (state.byok && state.privateKey && config.challenge) {
+    config.agentKey = state.privateKey;
+    const signature = signChallengeHex(state.privateKey, config.challenge);
+    await apiPost(base, `/onboarding/requests/${encodeURIComponent(requestId)}/verify-key`, { signature, claimToken }, null);
+    config.keyVerified = true;
+    delete config.challenge;
+    console.log(`  ${c.green('✓')} key verified — MetaMynd never saw your private key`);
+  }
+
+  const slug = slugify(state.name || 'metamynd-agent');
+  const outDir = resolve(String(args.out || `./${slug}`));
+  scaffoldProject({ outDir, config, slug, scope: state.scope || config.mandate?.scope || 'flight-purchase', perTxnMax: Number(state.perTxnMax) || 500, sandbox: false });
+}
+
+// ---------- main ----------
+async function main() {
+  const args = parseArgs(process.argv.slice(2));
+  if (args.help) { console.log(HELP); return; }
+  if (args.version) {
+    try { console.log(JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8')).version); }
+    catch { console.log('unknown'); }
+    return;
+  }
+
+  console.log(`\n${c.b(c.cyan('  create-metamynd-agent'))}  ${c.dim('— provision a governed agent in ~2 minutes')}\n`);
+
+  // --sandbox: skip login + provisioning entirely.
+  if (args.sandbox) { await runSandbox(args); return; }
+  // Delegated issuance (#6): request an agent for an owner's org / claim it once approved.
+  if (args.request) { await runRequest(args); return; }
+  if (args.claim) { await runClaim(args); return; }
+
+  const interactive = !args.yes && process.stdin.isTTY;
+  const rl = interactive ? makeRl() : null;
+  const pick = async (flag, envVar, prompt, def) => {
+    const fromFlag = typeof args[flag] === 'string' ? args[flag] : undefined;
+    const fromEnv = envVar ? process.env[envVar] : undefined;
+    if (fromFlag !== undefined) return fromFlag;
+    if (fromEnv !== undefined && fromEnv !== '') return fromEnv;
+    if (!interactive) return def;
+    return ask(rl, prompt, def);
+  };
+
+  // 1. Connection + login
+  const apiRaw = await pick('api', 'METAMYND_API', 'API base URL', DEFAULT_API);
+  const base = String(apiRaw).replace(/\/+$/, '');
+  const email = await pick('email', 'METAMYND_EMAIL', 'Owner email', '');
+  if (!email) { rl?.close(); fail('An owner email is required (--email or METAMYND_EMAIL).'); }
+  let password = typeof args.password === 'string' ? args.password : process.env.METAMYND_PASSWORD;
+  if (password === undefined) {
+    if (!interactive) { rl?.close(); fail('A password is required in --yes mode (--password or METAMYND_PASSWORD).'); }
+    // Pause the readline interface so it doesn't consume the raw keystrokes.
+    rl?.pause();
+    password = await askHidden('Owner password');
+    rl?.resume();
+  }
+
+  console.log(c.dim(`\n  → logging in to ${base} …`));
+  const login = await apiPost(base, '/auth/login', { username: email, password }, null);
+  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}`);
+
+  // 2. Agent details
+  const name = await pick('name', null, 'Agent name', 'Support Bot');
+  const scope = await pick('scope', null, 'Mandate scope (governed action)', 'flight-purchase');
+  const perTxnMax = Number(await pick('per-txn-max', null, 'Per-transaction cap', '500')) || 500;
+  const maxAmount = Number(await pick('max-amount', null, 'Total mandate budget', '10000')) || 10000;
+  const currency = (await pick('currency', null, 'Currency', 'USD')) || 'USD';
+  const merchantsRaw = await pick('merchants', null, 'Allowed merchants (comma-sep, blank = any)', '');
+  const merchants = String(merchantsRaw).split(',').map((s) => s.trim()).filter(Boolean);
+
+  // BYOK: --byok generates a keypair on THIS machine (MetaMynd never sees the private key). An
+  // explicit --public-key means the caller holds the key elsewhere and will prove it themselves.
+  let publicKey = typeof args['public-key'] === 'string' ? args['public-key'] : undefined;
+  let generatedKey = null;
+  if (args.byok && !publicKey) {
+    generatedKey = generateAgentKeypair();
+    publicKey = generatedKey.publicKeyHex;
+    console.log(`  ${c.green('✓')} generated an Ed25519 keypair locally ${c.dim('(private key stays on this machine)')}`);
+  }
+
+  const slug = slugify(name);
+  const outDir = resolve(String(args.out || (interactive ? await ask(rl, 'Output directory', `./${slug}`) : `./${slug}`)));
+
+  rl?.close();
+
+  // 3. Provision (one call)
+  console.log(c.dim(`\n  → provisioning "${name}" (identity + mandate + SOP + Standards) …`));
+  const body = { name, scope, currency, maxAmount, perTxnMax, merchants, ...(publicKey ? { publicKey } : {}) };
+  const provisioned = await apiPost(base, '/onboarding/agent', body, token);
+  const config = provisioned?.data;
+  if (!config?.agentDid) fail('Provisioning did not return a config with an agentDid.');
+  console.log(`  ${c.green('✓')} agent DID ${c.b(config.agentDid)}`);
+  if (config.standards?.length) console.log(`  ${c.green('✓')} enforced Standards: ${config.standards.join(', ')}`);
+
+  // 3b. BYOK: prove control of the key (verify-key), else the gate blocks with AGENT_KEY_UNVERIFIED.
+  if (generatedKey) {
+    // We hold the private key — inject it into the config so the scaffolded guard can sign, and
+    // prove possession by signing the issued challenge.
+    config.agentKey = generatedKey.privateKeyHex;
+    if (config.challenge) {
+      console.log(c.dim('  → proving key control (verify-key) …'));
+      const signature = signChallengeHex(generatedKey.privateKeyHex, config.challenge);
+      await apiPost(base, `/agent-identity/${encodeURIComponent(config.identityId)}/verify-key`, { signature }, token);
+      config.keyVerified = true;
+      delete config.challenge; // one-time; consumed
+      console.log(`  ${c.green('✓')} key verified — MetaMynd never saw your private key`);
+    }
+  } else if (publicKey) {
+    // External BYOK key the CLI can't sign — tell the operator how to finish proving control.
+    console.log(`  ${c.yellow('⚠ bring-your-own-key:')} no managed key minted. Prove control before the gate accepts the agent:`);
+    console.log(c.dim(`      sign this challenge with your private key (Ed25519 over its UTF-8 bytes, hex):`));
+    console.log(c.dim(`      challenge: ${config.challenge ?? '(none returned)'}`));
+    console.log(c.dim(`      POST ${base}/agent-identity/${config.identityId}/verify-key  { "signature": "<hex>" }  (owner token)`));
+  }
+
+  // 4. Scaffold + next steps
+  scaffoldProject({ outDir, config, slug, scope, perTxnMax, sandbox: false });
+}
+
+main().catch((e) => fail(e?.stack || e?.message || String(e)));

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "create-metamynd-agent",
+  "version": "0.1.0",
+  "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, and drops a runnable example.",
+  "type": "module",
+  "bin": {
+    "create-metamynd-agent": "index.mjs"
+  },
+  "files": [
+    "index.mjs",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "create",
+    "scaffold",
+    "cli",
+    "ai",
+    "agent",
+    "governance",
+    "metamynd",
+    "agentsafe",
+    "mandate",
+    "policy"
+  ],
+  "author": "MetaMynd",
+  "license": "MIT",
+  "homepage": "https://github.com/jasimp18/AgentSafe/tree/main/integrations/create-metamynd-agent#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/jasimp18/AgentSafe.git",
+    "directory": "integrations/create-metamynd-agent"
+  },
+  "bugs": {
+    "url": "https://github.com/jasimp18/AgentSafe/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}