agentbundle-cli 0.1.1 → 0.1.2

package/README.md

@@ -10,13 +10,15 @@ npx agentbundle-cli
 
 ## What it does
 
-A guided, three-step onboarding:
+It asks for **one email up front** and reuses it for all three sign-ups (the Agentcard magic
+link and the AgentMail + AgentPhone verification codes), then runs a guided, three-step onboarding:
 
 1. **Agentcard** — installs the `agent-cards` CLI, signs you up (one magic-link email click),
    registers + authenticates the MCP server via `agent-cards setup-mcp` (hosted HTTP), and offers
    to switch to production (real cards).
-2. **AgentMail** — takes your API key (or points you to the console to make one) and registers the
-   hosted HTTP MCP server (`mcp.agentmail.to`).
+2. **AgentMail** — fully automated: signs you up via the API (no console visit), provisions an
+   inbox, you type in the verification code, and it registers the hosted HTTP MCP server
+   (`mcp.agentmail.to`). Sign-ups are tagged with the `agentbundle` referrer.
 3. **AgentPhone** — fully automated: requests a verification code by email, you type it in, it
    provisions a real US number, and registers the stdio MCP server (`npx -y agentphone-mcp`). No browser.
 
@@ -29,6 +31,7 @@ It's **idempotent** — anything already configured is skipped, so it's safe to
 | Flag | Effect |
 |---|---|
 | `--only <agentcard\|agentmail\|agentphone>` | Run just one product. |
+| `--email <you@example.com>` | Email used for all three sign-ups (skips the up-front prompt). |
 | `--sandbox` | Walk the whole flow with stub signups + a throwaway config — no real accounts, no charges. |
 | `--dry-run` | Print what it would do, change nothing. |
 | `--yes`, `-y` | Accept defaults, skip confirmations. |
@@ -38,7 +41,8 @@ It's **idempotent** — anything already configured is skipped, so it's safe to
 ## Skip prompts with env vars
 
 ```bash
-export AGENTMAIL_API_KEY=am_...
+export AGENT_BUNDLE_EMAIL=you@example.com   # used for all three sign-ups
+export AGENTMAIL_API_KEY=am_...              # already have a key? skip the AgentMail sign-up
 export AGENTPHONE_API_KEY=sk_live_...
 npx agentbundle-cli
 ```

package/bin/agent-bundle.js

@@ -4,10 +4,16 @@
 
 const ui = require('../lib/ui');
 const mcp = require('../lib/mcp');
+const ac = require('../lib/agentcard-api');
 const agentcard = require('../lib/steps/agentcard');
 const agentmail = require('../lib/steps/agentmail');
 const agentphone = require('../lib/steps/agentphone');
 
+const MODULES = {
+  agentcard,
+  agentmail,
+  agentphone,
+};
 const STEPS = {
   agentcard: agentcard.step,
   agentmail: agentmail.step,
@@ -15,7 +21,7 @@ const STEPS = {
 };
 
 function parseArgs(argv) {
-  const ctx = { dryRun: false, sandbox: false, yes: false, only: null, help: false };
+  const ctx = { dryRun: false, sandbox: false, yes: false, only: null, help: false, email: (process.env.AGENT_BUNDLE_EMAIL || '').trim() };
   for (let i = 0; i < argv.length; i++) {
     const a = argv[i];
     if (a === '--dry-run') ctx.dryRun = true;
@@ -25,6 +31,8 @@ function parseArgs(argv) {
     else if (a === '--help' || a === '-h') ctx.help = true;
     else if (a === '--only') ctx.only = (argv[++i] || '').toLowerCase();
     else if (a.startsWith('--only=')) ctx.only = a.slice(7).toLowerCase();
+    else if (a === '--email') ctx.email = (argv[++i] || '').trim();
+    else if (a.startsWith('--email=')) ctx.email = a.slice(8).trim();
   }
   return ctx;
 }
@@ -35,13 +43,14 @@ function help() {
   ui.info(ui.c.bold('Usage:') + '  npx agentbundle-cli [options]\n');
   ui.info(ui.c.bold('Options:'));
   ui.dim('--only <agentcard|agentmail|agentphone>   run just one product');
+  ui.dim('--email <you@example.com>   email used for all three sign-ups (skips the prompt)');
   ui.dim('--sandbox    walk the whole flow with stub signups + a throwaway config (no money, no real accounts)');
   ui.dim('--dry-run    print what it would do, change nothing');
   ui.dim('--yes, -y    accept defaults, skip confirmations');
   ui.dim('--no-color   disable colored output');
   ui.dim('--help, -h   show this help');
   ui.blank();
-  ui.info(ui.c.bold('Pre-set keys to skip prompts:') + ' AGENTMAIL_API_KEY, AGENTPHONE_API_KEY');
+  ui.info(ui.c.bold('Pre-set to skip prompts:') + ' AGENT_BUNDLE_EMAIL, AGENTMAIL_API_KEY, AGENTPHONE_API_KEY');
   ui.info(ui.c.bold('Test safely:') + ' AGENT_BUNDLE_MCP_CONFIG=/tmp/x.json npx agentbundle-cli --sandbox');
   ui.blank();
 }
@@ -50,6 +59,24 @@ function icon(kind) {
   return kind === 'ok' ? ui.c.green('✓') : kind === 'warn' ? ui.c.yellow('!') : ui.c.red('✗');
 }
 
+// One email drives all three sign-ups (Agentcard magic link, AgentMail + AgentPhone OTP). Collect
+// it once up front so each product reuses it instead of asking three times. Stores it on ctx.email.
+async function collectEmail(ctx) {
+  if (ctx.email && ac.isValidEmail(ctx.email)) return ctx.email; // from --email / AGENT_BUNDLE_EMAIL
+  if (ctx.sandbox) { ctx.email = 'agent@sandbox.local'; return ctx.email; }
+  // An invalid --email / AGENT_BUNDLE_EMAIL with no TTY to fix it must be cleared, otherwise the
+  // steps would post the bad value to the signup APIs and fail. Treat it as "no email set".
+  if (ctx.dryRun || !process.stdin.isTTY) { ctx.email = ''; return ''; }
+  for (let tries = 0; tries < 3; tries++) {
+    const entered = await ui.ask("What email should your agent's card, inbox, and phone use?");
+    if (!entered) break;
+    if (ac.isValidEmail(entered)) { ctx.email = entered; return entered; }
+    ui.warn("That doesn't look like an email — try again.");
+  }
+  ctx.email = '';
+  return '';
+}
+
 async function main() {
   const ctx = parseArgs(process.argv.slice(2));
   if (ctx.help) return help();
@@ -73,6 +100,23 @@ async function main() {
     order = [ctx.only];
   }
 
+  // Step one: collect the single email FIRST — before the confirm or any product — so every
+  // sign-up reuses it (Agentcard magic link, AgentMail + AgentPhone codes) and no step ever asks
+  // for it again. A pre-set --email / AGENT_BUNDLE_EMAIL skips the prompt entirely.
+  // Only prompt when a selected product actually needs signup; if everything is already
+  // configured the prompt is skipped and the run stays a clean no-op.
+  if (!ctx.dryRun) {
+    const needEmail = order.some((key) => MODULES[key].needsSetup(ctx));
+    if (needEmail) {
+      ui.blank();
+      ui.info(ui.c.bold(ui.c.blue('Step one — your email')));
+      ui.dim('Asked once here, then reused for the sign-ups below — you won\'t be asked again.');
+      await collectEmail(ctx);
+      if (ctx.email) ui.ok('Using ' + ui.c.bold(ctx.email) + ' for the products that need it.');
+      else ui.warn('No email set up front — each product will ask only if it needs one.');
+    }
+  }
+
   if (!ctx.yes && !ctx.dryRun) {
     ui.blank();
     const go = await ui.confirm('Ready to set up ' + (ctx.only ? ctx.only : 'all three') + '?', true);

package/lib/steps/agentcard.js

@@ -21,9 +21,10 @@ function run(cmd, args) {
   return !r.error && r.status === 0;
 }
 
-// Ask for the email, send the magic link, and wait for the click. Returns the JWT, or null.
-async function completeSignup() {
-  let email = '';
+// Send the magic link and wait for the click. Reuses the shared email collected up front
+// (ctx.email); only asks if one wasn't provided. Returns the JWT, or null.
+async function completeSignup(ctx) {
+  let email = ctx && ctx.email && ac.isValidEmail(ctx.email) ? ctx.email : '';
   for (let tries = 0; tries < 3 && !email; tries++) {
     const entered = await ui.ask('What email should your Agentcard account use?');
     if (!entered) return null; // blank = skip
@@ -66,7 +67,7 @@ async function step(ctx) {
   // 1. Get an authenticated session (JWT).
   let jwt;
   if (ctx.dryRun) {
-    ui.step('would ask for your email, POST /auth/signup (x-platform: agentbundle), and wait for the magic link');
+    ui.step('would use the shared email, POST /auth/signup (x-platform: agentbundle), and wait for the magic link');
     ui.dim(`would: claude mcp add --transport http ${MCP_NAME} ${MCP_URL} --header "Authorization: Bearer <jwt>"`);
     return { product: 'Agentcard', icon: 'ok', note: 'configured (dry-run)' };
   } else if (ctx.sandbox) {
@@ -81,7 +82,7 @@ async function step(ctx) {
     ui.info('Re-run this in a terminal so it can collect your email and the magic link.');
     return { product: 'Agentcard', icon: 'warn', note: 'needs interactive signup' };
   } else {
-    jwt = await completeSignup();
+    jwt = await completeSignup(ctx);
     if (!jwt) {
       ui.warn('Skipped Agentcard signup — re-run with --only agentcard when ready.');
       return { product: 'Agentcard', icon: 'warn', note: 'signup not completed' };
@@ -122,4 +123,10 @@ async function step(ctx) {
   return { product: 'Agentcard', icon: 'ok', note };
 }
 
-module.exports = { step, MCP_NAME };
+// Whether a real run would need the shared email for this product (i.e. it isn't already set up).
+// Lets the launcher skip the up-front email prompt when nothing needs signup.
+function needsSetup() {
+  return !mcp.exists(MCP_NAME) && !ac.readConfig().jwt;
+}
+
+module.exports = { step, MCP_NAME, needsSetup };

package/lib/steps/agentmail.js

@@ -1,12 +1,66 @@
 'use strict';
-// [2/3] AgentMail — an email inbox. API-key driven (one console visit only if no key yet).
+// [2/3] AgentMail — an email inbox. Fully API-driven: sign-up -> OTP -> verify (no console visit).
+// Signs up via https://docs.agentmail.to/api-reference/agent/sign-up, tagging referrer=agentbundle,
+// reusing the email collected up front. The sign-up response carries the api_key directly; the OTP
+// verify step lifts the unverified-org send allowlist.
 
 const ui = require('../ui');
 const mcp = require('../mcp');
+const ac = require('../agentcard-api'); // shared email validation (isValidEmail)
 
 const MCP_NAME = 'agentmail';
 const MCP_URL = 'https://mcp.agentmail.to/mcp';
+const API = 'https://api.agentmail.to';
 const CONSOLE = 'https://console.agentmail.to';
+const REFERRER = 'agentbundle';     // the channel we report this sign-up came from
+const SOURCE = 'agentbundle-cli';   // platform identifier
+
+async function apiPost(path, body, token) {
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), 30000);
+  try {
+    const res = await fetch(API + path, {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        ...(token ? { Authorization: `Bearer ${token}` } : {}),
+      },
+      body: JSON.stringify(body),
+      signal: ctrl.signal,
+    });
+    const text = await res.text();
+    let data;
+    try { data = JSON.parse(text); } catch { data = { raw: text }; }
+    return { ok: res.ok, status: res.status, data };
+  } catch (e) {
+    return { ok: false, status: 0, data: { error: e.message } };
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+// Derive an inbox username from the email local-part, plus a short suffix so the globally-unique
+// inbox address (username@agentmail.to) is unlikely to collide with an existing one.
+function usernameFor(email) {
+  const local = String(email).split('@')[0].toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+  const base = local || 'agent';
+  const suffix = Math.random().toString(36).slice(2, 6);
+  return `${base}-${suffix}`;
+}
+
+function register(key, ctx, extraNote) {
+  ui.step('Registering the AgentMail MCP server…');
+  const res = mcp.addServer(
+    { name: MCP_NAME, transport: 'http', url: MCP_URL, headers: { 'x-api-key': key } },
+    { dryRun: ctx.dryRun }
+  );
+  if (res.error) {
+    ui.fail('Failed to register MCP server: ' + res.error);
+    return { product: 'AgentMail', icon: 'fail', note: res.error };
+  }
+  ui.ok('AgentMail MCP server registered.');
+  return { product: 'AgentMail', icon: 'ok', note: extraNote || 'configured' };
+}
 
 async function step(ctx) {
   ui.heading(2, 3, 'AgentMail — an email inbox for your agent');
@@ -17,38 +71,94 @@ async function step(ctx) {
     return { product: 'AgentMail', icon: 'ok', note: 'already configured' };
   }
 
-  // Get the API key: env first, else prompt (the one possible browser touch).
-  let key = process.env.AGENTMAIL_API_KEY || '';
-  if (key) {
-    ui.ok(`Using AGENTMAIL_API_KEY from your environment (${ui.mask(key)}).`);
-  } else if (ctx.sandbox) {
-    key = 'am_sandbox_placeholder_key';
-    ui.step('[sandbox] using a placeholder AgentMail key.');
-  } else if (ctx.dryRun) {
-    ui.step('would prompt for an AgentMail API key (am_…)');
+  // A pre-set key short-circuits the whole sign-up. Trim it — a copied key often carries a
+  // trailing newline/space that would register a broken credential.
+  const envKey = (process.env.AGENTMAIL_API_KEY || '').trim();
+  if (envKey) {
+    ui.ok(`Using AGENTMAIL_API_KEY from your environment (${ui.mask(envKey)}).`);
+    return register(envKey, ctx);
+  }
+
+  if (ctx.dryRun) {
+    ui.step('would: POST /v0/agent/sign-up (referrer: agentbundle) → ask for OTP → POST /v0/agent/verify → get am_ key + inbox');
     ui.dim(`would: claude mcp add --transport http ${MCP_NAME} ${MCP_URL} --header "x-api-key: …"`);
     return { product: 'AgentMail', icon: 'ok', note: 'configured (dry-run)' };
-  } else {
-    ui.info('AgentMail needs an API key (starts with ' + ui.c.bold('am_') + ').');
-    ui.info('Get one (free tier) at ' + ui.c.cyan(CONSOLE) + ' → Settings → API Keys.');
-    key = await ui.ask('Paste your AgentMail API key (or leave blank to skip for now):');
-    if (!key) {
-      ui.warn('No key provided — skipping AgentMail. Re-run later with the key set.');
-      return { product: 'AgentMail', icon: 'warn', note: 'needs key (set AGENTMAIL_API_KEY)' };
-    }
   }
 
-  ui.step('Registering the AgentMail MCP server…');
-  const res = mcp.addServer(
-    { name: MCP_NAME, url: MCP_URL, headers: { 'x-api-key': key } },
-    { dryRun: ctx.dryRun }
-  );
-  if (res.error) {
-    ui.fail('Failed to register MCP server: ' + res.error);
-    return { product: 'AgentMail', icon: 'fail', note: res.error };
+  if (ctx.sandbox) {
+    ui.step('[sandbox] simulating sign-up → OTP → verify…');
+    ui.ok('[sandbox] provisioned inbox my-agent@agentmail.to');
+    return register('am_sandbox_placeholder_key', ctx, 'configured (sandbox inbox)');
   }
-  ui.ok('AgentMail MCP server registered.');
-  return { product: 'AgentMail', icon: 'ok', note: 'configured' };
+
+  // Real flow — reuse the email collected up front; only ask (with validation) if one wasn't provided.
+  let email = ctx.email && ac.isValidEmail(ctx.email) ? ctx.email : '';
+  for (let tries = 0; !email && tries < 3; tries++) {
+    const entered = await ui.ask('What email should AgentMail send your verification code to?');
+    if (!entered) break;
+    if (ac.isValidEmail(entered)) email = entered;
+    else ui.warn("That doesn't look like an email — try again.");
+  }
+  if (!email) {
+    ui.warn('No email — skipping AgentMail. Re-run later.');
+    return { product: 'AgentMail', icon: 'warn', note: 'skipped (no email)' };
+  }
+
+  // Sign-up is idempotent on human_email (re-signup just rotates the key + returns it), so an
+  // existing account isn't a 409 — it returns 200. A 409 is a username collision (the random
+  // suffix clashed with another inbox), so retry with a fresh username before giving up.
+  ui.step('Creating your AgentMail inbox…');
+  let signup;
+  for (let attempt = 0; attempt < 3; attempt++) {
+    signup = await apiPost('/v0/agent/sign-up', {
+      human_email: email,
+      username: usernameFor(email),
+      source: SOURCE,
+      referrer: REFERRER,
+    });
+    if (signup.status !== 409) break;
+  }
+
+  if (signup.status === 409) {
+    ui.warn('Could not auto-pick an available inbox name after a few tries.');
+    ui.info('Grab a key from ' + ui.c.cyan(CONSOLE) + ' → Settings → API Keys.');
+    const key = (await ui.ask('Paste your AgentMail API key (am_…), or blank to skip:')).trim();
+    if (!key) return { product: 'AgentMail', icon: 'warn', note: 'needs key (set AGENTMAIL_API_KEY)' };
+    return register(key, ctx);
+  }
+  if (!signup.ok || !signup.data.api_key) {
+    ui.fail('Sign-up failed: ' + (signup.data.error || signup.data.message || `HTTP ${signup.status}`));
+    return { product: 'AgentMail', icon: 'fail', note: 'sign-up failed' };
+  }
+
+  const key = signup.data.api_key;
+  const inbox = signup.data.inbox_id;
+  if (inbox) ui.ok('Inbox created: ' + ui.c.bold(inbox));
+
+  // Verify the OTP to lift the unverified-org send allowlist. The key already works for receiving
+  // without it, so a missing/wrong code degrades gracefully rather than failing the whole step.
+  ui.ok(`Verification code sent to ${email}. Check your inbox.`);
+  const otp = await ui.ask('Enter the 6-digit code (or blank to verify later):');
+  if (otp) {
+    ui.step('Verifying…');
+    const verify = await apiPost('/v0/agent/verify', { otp_code: otp }, key);
+    if (verify.ok && verify.data.verified) {
+      ui.ok('AgentMail account verified — sending unlocked.');
+    } else {
+      ui.warn('Could not verify the code now (' + (verify.data.error || verify.data.message || `HTTP ${verify.status}`) + ').');
+      ui.dim('Your inbox still works for receiving; verify later to lift send limits.');
+    }
+  } else {
+    ui.dim('Skipped verification — inbox works for receiving; verify later to send freely.');
+  }
+
+  ui.dim('API key stored in the MCP config (masked: ' + ui.mask(key) + '). Never share it.');
+  return register(key, ctx, inbox ? `inbox ${inbox}` : 'configured');
+}
+
+// Whether a real run would need the shared email for this product (i.e. it isn't already set up).
+function needsSetup() {
+  return !mcp.exists(MCP_NAME) && !(process.env.AGENTMAIL_API_KEY || '').trim();
 }
 
-module.exports = { step, MCP_NAME };
+module.exports = { step, MCP_NAME, needsSetup };

package/lib/steps/agentphone.js

@@ -3,10 +3,12 @@
 
 const ui = require('../ui');
 const mcp = require('../mcp');
+const ac = require('../agentcard-api'); // shared email validation (isValidEmail)
 
 const MCP_NAME = 'agentphone';
 const API = 'https://api.agentphone.ai';
 const SETTINGS = 'https://agentphone.ai/settings';
+const SOURCE = 'agentbundle';   // sent on verify so AgentPhone attributes the signup to the bundle
 
 async function apiPost(path, body) {
   const ctrl = new AbortController();
@@ -53,14 +55,16 @@ async function step(ctx) {
     return { product: 'AgentPhone', icon: 'ok', note: 'already configured' };
   }
 
-  // Existing key in env?
-  if (process.env.AGENTPHONE_API_KEY) {
-    ui.ok(`Using AGENTPHONE_API_KEY from your environment (${ui.mask(process.env.AGENTPHONE_API_KEY)}).`);
-    return register(process.env.AGENTPHONE_API_KEY, ctx);
+  // Existing key in env? Trim it — a copied key often carries a trailing newline/space that
+  // would register a broken credential.
+  const envKey = (process.env.AGENTPHONE_API_KEY || '').trim();
+  if (envKey) {
+    ui.ok(`Using AGENTPHONE_API_KEY from your environment (${ui.mask(envKey)}).`);
+    return register(envKey, ctx);
   }
 
   if (ctx.dryRun) {
-    ui.step('would: POST /v0/agent/sign-up → ask for OTP → POST /v0/agent/verify → get sk_live_ key + number');
+    ui.step('would: POST /v0/agent/sign-up → ask for OTP → POST /v0/agent/verify (source: agentbundle) → get sk_live_ key + number');
     ui.dim(`would: claude mcp add ${MCP_NAME} --env AGENTPHONE_API_KEY=… -- npx -y agentphone-mcp`);
     return { product: 'AgentPhone', icon: 'ok', note: 'configured (dry-run)' };
   }
@@ -71,8 +75,14 @@ async function step(ctx) {
     return register('sk_live_sandbox_placeholder_key', ctx, 'configured (sandbox number)');
   }
 
-  // Real flow.
-  const email = await ui.ask('What email should AgentPhone send your verification code to?');
+  // Real flow — reuse the email collected up front; only ask (with validation) if one wasn't provided.
+  let email = ctx.email && ac.isValidEmail(ctx.email) ? ctx.email : '';
+  for (let tries = 0; !email && tries < 3; tries++) {
+    const entered = await ui.ask('What email should AgentPhone send your verification code to?');
+    if (!entered) break;
+    if (ac.isValidEmail(entered)) email = entered;
+    else ui.warn("That doesn't look like an email — try again.");
+  }
   if (!email) {
     ui.warn('No email — skipping AgentPhone. Re-run later.');
     return { product: 'AgentPhone', icon: 'warn', note: 'skipped (no email)' };
@@ -84,7 +94,7 @@ async function step(ctx) {
   if (signup.status === 409) {
     ui.warn('You already have an AgentPhone account for that email.');
     ui.info('Grab a key from ' + ui.c.cyan(SETTINGS) + ' → API Keys.');
-    const key = await ui.ask('Paste your AgentPhone API key (sk_live_…), or blank to skip:');
+    const key = (await ui.ask('Paste your AgentPhone API key (sk_live_…), or blank to skip:')).trim();
     if (!key) return { product: 'AgentPhone', icon: 'warn', note: 'needs key (set AGENTPHONE_API_KEY)' };
     return register(key, ctx);
   }
@@ -101,7 +111,7 @@ async function step(ctx) {
   }
 
   ui.step('Verifying and provisioning your number…');
-  const verify = await apiPost('/v0/agent/verify', { verification_id: signup.data.verification_id, otp_code: otp });
+  const verify = await apiPost('/v0/agent/verify', { verification_id: signup.data.verification_id, otp_code: otp, source: SOURCE });
   if (!verify.ok || !verify.data.api_key) {
     ui.fail('Verification failed: ' + (verify.data.error || verify.data.message || `HTTP ${verify.status}`));
     return { product: 'AgentPhone', icon: 'fail', note: 'verification failed' };
@@ -112,4 +122,9 @@ async function step(ctx) {
   return register(verify.data.api_key, ctx, `live number ${verify.data.phone_number}`);
 }
 
-module.exports = { step, MCP_NAME };
+// Whether a real run would need the shared email for this product (i.e. it isn't already set up).
+function needsSetup() {
+  return !mcp.exists(MCP_NAME) && !(process.env.AGENTPHONE_API_KEY || '').trim();
+}
+
+module.exports = { step, MCP_NAME, needsSetup };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentbundle-cli",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "One command to give your AI agent a card, an inbox, and a phone — installs Agentcard, AgentMail, and AgentPhone via a guided onboarding flow.",
   "bin": {
     "agentbundle-cli": "bin/agent-bundle.js",