agentbundle-cli 0.1.0

package/README.md

@@ -0,0 +1,64 @@
+# agent-bundle
+
+One command to give your AI agent the three things it needs to act online — a **card**
+(Agentcard), an **inbox** (AgentMail), and a **phone number** (AgentPhone). `agent-bundle` walks
+you through installing all three, one at a time, and registers each as an MCP server.
+
+```bash
+npx agentbundle
+```
+
+## What it does
+
+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`).
+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.
+
+All MCP servers are registered at **user scope** (available in every project), via `claude mcp add`.
+
+It's **idempotent** — anything already configured is skipped, so it's safe to re-run.
+
+## Options
+
+| Flag | Effect |
+|---|---|
+| `--only <agentcard\|agentmail\|agentphone>` | Run just one product. |
+| `--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. |
+| `--no-color` | Plain output. |
+| `--help`, `-h` | Help. |
+
+## Skip prompts with env vars
+
+```bash
+export AGENTMAIL_API_KEY=am_...
+export AGENTPHONE_API_KEY=sk_live_...
+npx agentbundle
+```
+
+## Test it safely
+
+This writes the MCP config to a throwaway file and uses stub signups — your real `~/.claude`
+config is never touched and no money is spent:
+
+```bash
+AGENT_BUNDLE_MCP_CONFIG=/tmp/bundle-test.json npx . --sandbox
+cat /tmp/bundle-test.json
+```
+
+## How config is written
+
+By default it uses the `claude` CLI (`claude mcp add --transport http …`). If `claude` isn't on
+your PATH, or you set `AGENT_BUNDLE_MCP_CONFIG`, it writes the MCP entries to that JSON file
+instead. API keys are stored as request headers in the config and never printed to the terminal.
+
+## Requirements
+
+Node 18+ (for built-in `fetch`). Zero runtime dependencies.

package/assets/agentbundle.txt

@@ -0,0 +1,5 @@
+                    _   _                 _ _     
+  __ _ __ _ ___ _ _| |_| |__ _  _ _ _  __| | |___ 
+ / _` / _` / -_) ' \  _| '_ \ || | ' \/ _` | / -_)
+ \__,_\__, \___|_||_\__|_.__/\_,_|_||_\__,_|_\___|
+      |___/                                       

package/bin/agent-bundle.js

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+'use strict';
+// agent-bundle — guided onboarding that installs Agentcard, AgentMail, and AgentPhone one by one.
+
+const ui = require('../lib/ui');
+const mcp = require('../lib/mcp');
+const agentcard = require('../lib/steps/agentcard');
+const agentmail = require('../lib/steps/agentmail');
+const agentphone = require('../lib/steps/agentphone');
+
+const STEPS = {
+  agentcard: agentcard.step,
+  agentmail: agentmail.step,
+  agentphone: agentphone.step,
+};
+
+function parseArgs(argv) {
+  const ctx = { dryRun: false, sandbox: false, yes: false, only: null, help: false };
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === '--dry-run') ctx.dryRun = true;
+    else if (a === '--sandbox') ctx.sandbox = true;
+    else if (a === '--yes' || a === '-y') ctx.yes = true;
+    else if (a === '--no-color') {/* handled in ui */}
+    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();
+  }
+  return ctx;
+}
+
+function help() {
+  ui.banner();
+  ui.info('Guided setup for your agent\'s card, inbox, and phone.\n');
+  ui.info(ui.c.bold('Usage:') + '  npx agent-bundle [options]\n');
+  ui.info(ui.c.bold('Options:'));
+  ui.dim('--only <agentcard|agentmail|agentphone>   run just one product');
+  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('Test safely:') + ' AGENT_BUNDLE_MCP_CONFIG=/tmp/x.json npx agent-bundle --sandbox');
+  ui.blank();
+}
+
+function icon(kind) {
+  return kind === 'ok' ? ui.c.green('✓') : kind === 'warn' ? ui.c.yellow('!') : ui.c.red('✗');
+}
+
+async function main() {
+  const ctx = parseArgs(process.argv.slice(2));
+  if (ctx.help) return help();
+
+  ui.banner();
+  if (ctx.dryRun) ui.warn('DRY RUN — nothing will be changed.');
+  if (ctx.sandbox) ui.warn('SANDBOX — stub signups, throwaway config, no real accounts or charges.');
+
+  // Preflight
+  ui.heading(0, 3, 'Preflight');
+  ui.info('Node ' + process.version);
+  ui.info('MCP config target: ' + ui.c.bold(mcp.describeBackend()));
+  ui.dim('Each product loads as MCP tools after you restart your agent session at the end.');
+
+  let order = ['agentcard', 'agentmail', 'agentphone'];
+  if (ctx.only) {
+    if (!STEPS[ctx.only]) {
+      ui.fail(`Unknown --only target: ${ctx.only} (use agentcard | agentmail | agentphone)`);
+      process.exit(2);
+    }
+    order = [ctx.only];
+  }
+
+  if (!ctx.yes && !ctx.dryRun) {
+    ui.blank();
+    const go = await ui.confirm('Ready to set up ' + (ctx.only ? ctx.only : 'all three') + '?', true);
+    if (!go) {
+      ui.info('No problem — run again whenever you\'re ready.');
+      ui.closeUI();
+      return;
+    }
+  }
+
+  // Run steps (failure-isolated: one product failing doesn't stop the others)
+  const results = [];
+  for (const key of order) {
+    try {
+      results.push(await STEPS[key](ctx));
+    } catch (e) {
+      ui.fail(`${key} crashed: ${e.message}`);
+      results.push({ product: key, icon: 'fail', note: e.message });
+    }
+  }
+
+  // Summary
+  ui.blank();
+  ui.info(ui.c.bold('── Summary ──────────────────────────────────────────'));
+  for (const r of results) {
+    process.stdout.write('  ' + icon(r.icon) + ' ' + ui.c.bold(r.product.padEnd(11)) + ' ' + ui.c.dim(r.note) + '\n');
+  }
+  ui.blank();
+
+  const anyConfigured = results.some((r) => r.icon === 'ok');
+  if (anyConfigured && !ctx.dryRun) {
+    ui.info(ui.c.bold('Next:'));
+    ui.step('Restart your agent session so the new MCP tools load.');
+    ui.dim('Then try: list_cards (Agentcard) · list_inboxes (AgentMail) · check usage (AgentPhone).');
+  }
+  if (results.some((r) => r.icon === 'warn')) {
+    ui.warn('Some products need a key — re-run with --only <product> after setting it.');
+  }
+  ui.blank();
+  ui.dim('Security: API keys live in your MCP config, never printed. Don\'t send a key to any other domain.');
+  ui.blank();
+
+  ui.closeUI();
+  process.exit(results.some((r) => r.icon === 'fail') ? 1 : 0);
+}
+
+main().catch((e) => {
+  ui.fail('Unexpected error: ' + e.stack);
+  process.exit(1);
+});

package/lib/agentcard-api.js

@@ -0,0 +1,114 @@
+'use strict';
+// Minimal Agentcard auth client used to complete signup from inside agent-bundle, so the whole
+// flow (ask email → magic link → verify) happens here AND the signup is tagged with our source.
+//
+// Mirrors the agent-cards CLI: same API base, same ~/.agent-cards/config.json ({email,jwt,mode},
+// mode 0600), same endpoints (POST /auth/signup, poll GET /auth/me with X-Magic-Token). The one
+// difference: we send `x-platform: agentbundle` so the backend records these signups as coming
+// from the bundle.
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const SOURCE = 'agentbundle'; // the x-platform value the backend tracks signups under
+const API_URL = process.env.AGENT_CARDS_API_URL || 'https://api.agentcard.sh';
+const CONFIG_DIR = path.join(os.homedir(), '.agent-cards');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+
+function readConfig() {
+  try {
+    return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function writeConfig(data) {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  const merged = { ...readConfig(), ...data };
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(merged, null, 2), { mode: 0o600 });
+}
+
+function callerContext() {
+  return process.env.CLAUDECODE || process.env.CLAUDE_CODE ? 'agent:claude-code' : 'unidentified';
+}
+
+function headers(extra) {
+  return {
+    'Content-Type': 'application/json',
+    'x-platform': SOURCE,
+    'x-caller-context': callerContext(),
+    ...(extra || {}),
+  };
+}
+
+async function postJson(pathname, body, extraHeaders) {
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), 30000);
+  try {
+    const res = await fetch(API_URL + pathname, {
+      method: 'POST',
+      headers: headers(extraHeaders),
+      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 };
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+async function getJson(pathname, extraHeaders) {
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), 30000);
+  try {
+    const res = await fetch(API_URL + pathname, { headers: headers(extraHeaders), 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 };
+  } finally {
+    clearTimeout(t);
+  }
+}
+
+// Request a magic link. Returns { sessionId } or throws with a readable message.
+async function requestMagicLink(email) {
+  const r = await postJson('/auth/signup', { email });
+  if (!r.ok || !r.data.sessionId) {
+    throw new Error(r.data.error || r.data.message || `signup failed (HTTP ${r.status})`);
+  }
+  return { sessionId: r.data.sessionId };
+}
+
+// Poll until the user clicks the magic link. Returns { jwt, email, mode }.
+async function waitForVerification(sessionId, { intervalMs = 2500, timeoutMs = 10 * 60 * 1000 } = {}) {
+  const deadline = Date.now() + timeoutMs;
+  // Date.now is fine at runtime; this module is never run inside the workflow sandbox.
+  for (;;) {
+    const r = await getJson('/auth/me', { 'X-Magic-Token': sessionId });
+    if (r.ok && r.data && r.data.status === 'verified' && r.data.jwt) {
+      return { jwt: r.data.jwt, email: r.data.email, mode: r.data.mode };
+    }
+    if (Date.now() > deadline) throw new Error('timed out waiting for the magic link to be clicked');
+    await new Promise((res) => setTimeout(res, intervalMs));
+  }
+}
+
+function isValidEmail(s) {
+  return /^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(s);
+}
+
+module.exports = {
+  SOURCE,
+  API_URL,
+  readConfig,
+  writeConfig,
+  requestMagicLink,
+  waitForVerification,
+  isValidEmail,
+};

package/lib/mcp.js

@@ -0,0 +1,98 @@
+'use strict';
+// Idempotent MCP-server registration.
+//
+// Two backends, auto-selected:
+//   * "claude": uses the `claude` CLI (`claude mcp get` / `claude mcp add`). Default in real use.
+//   * "file":   merges into a JSON config file. Used when AGENT_BUNDLE_MCP_CONFIG is set, or when
+//               `claude` isn't on PATH. Perfect for isolated/sandbox testing — never touches the
+//               user's real ~/.claude config.
+
+const { spawnSync } = require('node:child_process');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+function hasClaude() {
+  const r = spawnSync('claude', ['--version'], { stdio: 'ignore' });
+  return !r.error && r.status === 0;
+}
+
+function pickBackend() {
+  const file = process.env.AGENT_BUNDLE_MCP_CONFIG;
+  if (file) return { backend: 'file', file };
+  if (hasClaude()) return { backend: 'claude', file: null };
+  return { backend: 'file', file: path.join(os.homedir(), '.agent-bundle-mcp.json') };
+}
+
+function readConfig(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return { mcpServers: {} };
+  }
+}
+
+function exists(name) {
+  const { backend, file } = pickBackend();
+  if (backend === 'claude') {
+    const r = spawnSync('claude', ['mcp', 'get', name], { stdio: 'ignore' });
+    return !r.error && r.status === 0;
+  }
+  const cfg = readConfig(file);
+  return !!(cfg.mcpServers && cfg.mcpServers[name]);
+}
+
+// addServer(spec) -> { added, skipped, error? }
+// spec for an HTTP server:  { name, transport: 'http', url, headers }
+// spec for a stdio server:  { name, transport: 'stdio', command, args, env }
+function addServer(spec, { dryRun = false } = {}) {
+  const { name, transport = 'http' } = spec;
+  if (exists(name)) return { added: false, skipped: true };
+
+  const { backend, file } = pickBackend();
+  if (dryRun) return { added: false, skipped: false, dryRun: true, backend, file };
+
+  if (backend === 'claude') {
+    // Default to USER scope so the server is available in every project/session, not just the
+    // directory this ran in (`claude mcp add` defaults to project-local scope). Override with
+    // AGENT_BUNDLE_MCP_SCOPE=local|user|project.
+    const scope = process.env.AGENT_BUNDLE_MCP_SCOPE || 'user';
+    let args;
+    if (transport === 'stdio') {
+      // Name MUST come before --env, or the variadic --env flag swallows it.
+      args = ['mcp', 'add', name, '--scope', scope];
+      for (const [k, v] of Object.entries(spec.env || {})) args.push('--env', `${k}=${v}`);
+      args.push('--', spec.command, ...(spec.args || []));
+    } else {
+      args = ['mcp', 'add', '--scope', scope, '--transport', 'http', name, spec.url];
+      for (const [k, v] of Object.entries(spec.headers || {})) args.push('--header', `${k}: ${v}`);
+    }
+    const r = spawnSync('claude', args, { stdio: 'ignore' });
+    if (r.error) return { added: false, skipped: false, error: r.error.message };
+    if (r.status !== 0) return { added: false, skipped: false, error: `claude mcp add exited ${r.status}` };
+    return { added: true, skipped: false };
+  }
+
+  // file backend
+  fs.mkdirSync(path.dirname(file), { recursive: true });
+  const cfg = readConfig(file);
+  cfg.mcpServers = cfg.mcpServers || {};
+  if (transport === 'stdio') {
+    const entry = { command: spec.command, args: spec.args || [] };
+    if (spec.env && Object.keys(spec.env).length) entry.env = spec.env;
+    cfg.mcpServers[name] = entry;
+  } else {
+    const entry = { type: 'http', url: spec.url };
+    if (spec.headers && Object.keys(spec.headers).length) entry.headers = spec.headers;
+    cfg.mcpServers[name] = entry;
+  }
+  fs.writeFileSync(file, JSON.stringify(cfg, null, 2) + '\n');
+  return { added: true, skipped: false };
+}
+
+function describeBackend() {
+  const { backend, file } = pickBackend();
+  return backend === 'file' ? `file (${file})` : 'claude CLI';
+}
+
+module.exports = { exists, addServer, describeBackend, pickBackend };

package/lib/steps/agentcard.js

@@ -0,0 +1,125 @@
+'use strict';
+// [1/3] Agentcard — virtual cards. agent-bundle drives the full signup (ask email → magic link →
+// verify), tagging the signup source as `agentbundle`, then registers the MCP server with the JWT.
+
+const { spawnSync } = require('node:child_process');
+const ui = require('../ui');
+const mcp = require('../mcp');
+const ac = require('../agentcard-api');
+
+const MCP_NAME = 'agent-cards';
+const MCP_URL = 'https://mcp.agentcard.sh/mcp';
+
+function have(cmd) {
+  const r = spawnSync(cmd, ['--version'], { stdio: 'ignore' });
+  return !r.error && r.status === 0;
+}
+function run(cmd, args) {
+  ui.pause();
+  const r = spawnSync(cmd, args, { stdio: 'inherit' });
+  ui.resume();
+  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 = '';
+  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
+    if (ac.isValidEmail(entered)) email = entered;
+    else ui.warn('That doesn\'t look like an email — try again.');
+  }
+  if (!email) return null;
+
+  let sessionId;
+  try {
+    ui.step(`Sending a magic link to ${email}…`);
+    ({ sessionId } = await ac.requestMagicLink(email));
+  } catch (e) {
+    ui.fail('Could not start signup: ' + e.message);
+    return null;
+  }
+
+  ui.ok(`Magic link sent to ${ui.c.bold(email)}.`);
+  ui.info('Open your inbox and click the link — ' + ui.c.dim('waiting for you…'));
+  try {
+    const { jwt, email: verifiedEmail, mode } = await ac.waitForVerification(sessionId);
+    ac.writeConfig({ email: verifiedEmail || email, jwt, mode });
+    ui.ok(`Signed in as ${ui.c.bold(verifiedEmail || email)}` + (mode ? ` (${mode} mode)` : ''));
+    return jwt;
+  } catch (e) {
+    ui.fail('Signup not completed: ' + e.message);
+    return null;
+  }
+}
+
+async function step(ctx) {
+  ui.heading(1, 3, 'Agentcard — a virtual card for your agent');
+  ui.dim('Prepaid virtual cards with per-task budgets, controlled through MCP tools.');
+
+  if (mcp.exists(MCP_NAME)) {
+    ui.ok('Agentcard MCP server already configured — skipping.');
+    return { product: 'Agentcard', icon: 'ok', note: 'already configured' };
+  }
+
+  // 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.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) {
+    ui.step('[sandbox] simulating email → magic link → verified');
+    jwt = 'sandbox_placeholder_jwt';
+  } else if (ac.readConfig().jwt) {
+    const cfg = ac.readConfig();
+    ui.ok(`Already signed in to Agentcard${cfg.email ? ' as ' + ui.c.bold(cfg.email) : ''} — skipping signup.`);
+    jwt = cfg.jwt;
+  } else if (!process.stdin.isTTY) {
+    ui.warn('Not signed in to Agentcard, and no interactive terminal to complete signup.');
+    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();
+    if (!jwt) {
+      ui.warn('Skipped Agentcard signup — re-run with --only agentcard when ready.');
+      return { product: 'Agentcard', icon: 'warn', note: 'signup not completed' };
+    }
+  }
+
+  // 2. Register the MCP server with the JWT (matches the authenticated hosted-HTTP setup).
+  ui.step('Registering the Agentcard MCP server…');
+  const res = mcp.addServer(
+    { name: MCP_NAME, transport: 'http', url: MCP_URL, headers: { Authorization: `Bearer ${jwt}` } },
+    { dryRun: ctx.dryRun }
+  );
+  if (res.error) {
+    ui.fail('Failed to register MCP server: ' + res.error);
+    return { product: 'Agentcard', icon: 'fail', note: res.error };
+  }
+  ui.ok('Agentcard MCP server registered.');
+
+  // 3. Production (go live) — needs payment method + identity; opt-in. Uses the CLI when present.
+  let note = 'configured (TEST mode)';
+  if (ctx.sandbox) {
+    ui.dim('TEST mode by default. Going live (real cards) is offered here in a real run.');
+  } else {
+    const live = ctx.yes ? false : await ui.confirm('Switch to PRODUCTION now (issue real cards)? Needs a payment method + a quick identity check.', false);
+    if (live) {
+      if (have('agent-cards') && run('agent-cards', ['mode', 'prod'])) {
+        ui.info('To fund real cards, run ' + ui.c.bold('agent-cards payment-method') + ' (one-time Stripe page) and finish the identity prompts.');
+        note = 'configured (PROD mode — finish payment method to issue real cards)';
+      } else {
+        ui.info('Install the CLI (' + ui.c.bold('npm i -g agent-cards') + ') then run ' + ui.c.bold('agent-cards mode prod') + ' to go live.');
+        note = 'configured (TEST mode — install CLI to go live)';
+      }
+    } else {
+      ui.info('Staying in ' + ui.c.bold('TEST') + ' mode (sandbox cards). Go live anytime with ' + ui.c.bold('agent-cards mode prod') + '.');
+    }
+  }
+
+  return { product: 'Agentcard', icon: 'ok', note };
+}
+
+module.exports = { step, MCP_NAME };

package/lib/steps/agentmail.js

@@ -0,0 +1,54 @@
+'use strict';
+// [2/3] AgentMail — an email inbox. API-key driven (one console visit only if no key yet).
+
+const ui = require('../ui');
+const mcp = require('../mcp');
+
+const MCP_NAME = 'agentmail';
+const MCP_URL = 'https://mcp.agentmail.to/mcp';
+const CONSOLE = 'https://console.agentmail.to';
+
+async function step(ctx) {
+  ui.heading(2, 3, 'AgentMail — an email inbox for your agent');
+  ui.dim('Real inboxes the agent owns — for sign-ups, verification emails, and outreach.');
+
+  if (mcp.exists(MCP_NAME)) {
+    ui.ok('AgentMail MCP server already configured — skipping.');
+    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_…)');
+    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 };
+  }
+  ui.ok('AgentMail MCP server registered.');
+  return { product: 'AgentMail', icon: 'ok', note: 'configured' };
+}
+
+module.exports = { step, MCP_NAME };

package/lib/steps/agentphone.js

@@ -0,0 +1,115 @@
+'use strict';
+// [3/3] AgentPhone — a real phone number. Fully API-driven: sign-up -> OTP -> verify. No browser.
+
+const ui = require('../ui');
+const mcp = require('../mcp');
+
+const MCP_NAME = 'agentphone';
+const API = 'https://api.agentphone.ai';
+const SETTINGS = 'https://agentphone.ai/settings';
+
+async function apiPost(path, body) {
+  const ctrl = new AbortController();
+  const t = setTimeout(() => ctrl.abort(), 30000);
+  try {
+    const res = await fetch(API + path, {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      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);
+  }
+}
+
+function register(key, ctx, extraNote) {
+  ui.step('Registering the AgentPhone MCP server…');
+  // AgentPhone ships a stdio MCP server (npm: agentphone-mcp); the key is passed via env.
+  const res = mcp.addServer(
+    { name: MCP_NAME, transport: 'stdio', command: 'npx', args: ['-y', 'agentphone-mcp'], env: { AGENTPHONE_API_KEY: key } },
+    { dryRun: ctx.dryRun }
+  );
+  if (res.error) {
+    ui.fail('Failed to register MCP server: ' + res.error);
+    return { product: 'AgentPhone', icon: 'fail', note: res.error };
+  }
+  ui.ok('AgentPhone MCP server registered.');
+  return { product: 'AgentPhone', icon: 'ok', note: extraNote || 'configured' };
+}
+
+async function step(ctx) {
+  ui.heading(3, 3, 'AgentPhone — a real phone number for your agent');
+  ui.dim('A live US number for SMS + voice. This step is fully automated — no browser needed.');
+
+  if (mcp.exists(MCP_NAME)) {
+    ui.ok('AgentPhone MCP server already configured — skipping.');
+    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);
+  }
+
+  if (ctx.dryRun) {
+    ui.step('would: POST /v0/agent/sign-up → ask for OTP → POST /v0/agent/verify → 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)' };
+  }
+
+  if (ctx.sandbox) {
+    ui.step('[sandbox] simulating sign-up → OTP → verify…');
+    ui.ok('[sandbox] provisioned number +1 (555) 010-0042');
+    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?');
+  if (!email) {
+    ui.warn('No email — skipping AgentPhone. Re-run later.');
+    return { product: 'AgentPhone', icon: 'warn', note: 'skipped (no email)' };
+  }
+
+  ui.step('Requesting a verification code…');
+  const signup = await apiPost('/v0/agent/sign-up', { human_email: email, agent_name: 'my-agent' });
+
+  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:');
+    if (!key) return { product: 'AgentPhone', icon: 'warn', note: 'needs key (set AGENTPHONE_API_KEY)' };
+    return register(key, ctx);
+  }
+  if (!signup.ok || !signup.data.verification_id) {
+    ui.fail('Sign-up failed: ' + (signup.data.error || signup.data.message || `HTTP ${signup.status}`));
+    return { product: 'AgentPhone', icon: 'fail', note: 'sign-up failed' };
+  }
+
+  ui.ok(`Code sent to ${email}. Check your inbox.`);
+  const otp = await ui.ask('Enter the 6-digit code:');
+  if (!otp) {
+    ui.warn('No code entered — skipping AgentPhone.');
+    return { product: 'AgentPhone', icon: 'warn', note: 'skipped (no code)' };
+  }
+
+  ui.step('Verifying and provisioning your number…');
+  const verify = await apiPost('/v0/agent/verify', { verification_id: signup.data.verification_id, otp_code: otp });
+  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' };
+  }
+
+  ui.ok('Verified! Your agent now has a number: ' + ui.c.bold(verify.data.phone_number));
+  ui.dim('API key stored in the MCP config (masked: ' + ui.mask(verify.data.api_key) + '). Never share it.');
+  return register(verify.data.api_key, ctx, `live number ${verify.data.phone_number}`);
+}
+
+module.exports = { step, MCP_NAME };

package/lib/ui.js

@@ -0,0 +1,107 @@
+'use strict';
+// Zero-dependency terminal UI helpers: colors, headings, prompts, masking.
+
+const readline = require('node:readline/promises');
+const fs = require('node:fs');
+const path = require('node:path');
+const { stdin, stdout } = require('node:process');
+
+const useColor = stdout.isTTY && !process.env.NO_COLOR && !process.argv.includes('--no-color');
+const wrap = (code) => (s) => (useColor ? `\x1b[${code}m${s}\x1b[0m` : String(s));
+
+const c = {
+  bold: wrap('1'),
+  dim: wrap('2'),
+  red: wrap('31'),
+  green: wrap('32'),
+  yellow: wrap('33'),
+  blue: wrap('34'),
+  cyan: wrap('36'),
+  gray: wrap('90'),
+};
+
+// Header matches the Agentcard support agent: figlet "Small" font, rendered in green.
+function banner() {
+  let art;
+  try {
+    art = fs.readFileSync(path.join(__dirname, '..', 'assets', 'agentbundle.txt'), 'utf8').replace(/\s+$/, '');
+  } catch {
+    art = 'agentbundle';
+  }
+  stdout.write('\n');
+  for (const lineText of art.split('\n')) stdout.write(c.green(lineText) + '\n');
+  stdout.write(
+    '  ' + c.bold('Agentcard') + c.dim(' · ') + c.bold('AgentMail') + c.dim(' · ') + c.bold('AgentPhone') + '\n'
+  );
+}
+
+function heading(n, total, title) {
+  stdout.write('\n' + c.bold(c.blue(`[${n}/${total}] ${title}`)) + '\n');
+}
+
+const info = (m) => stdout.write('  ' + m + '\n');
+const step = (m) => stdout.write('  ' + c.cyan('→') + ' ' + m + '\n');
+const ok = (m) => stdout.write('  ' + c.green('✓') + ' ' + m + '\n');
+const warn = (m) => stdout.write('  ' + c.yellow('!') + ' ' + m + '\n');
+const fail = (m) => stdout.write('  ' + c.red('✗') + ' ' + m + '\n');
+const dim = (m) => stdout.write('  ' + c.dim(m) + '\n');
+const blank = () => stdout.write('\n');
+
+// One shared readline interface with a line QUEUE. Reading all stdin lines into a queue means
+// no line is ever dropped — including pre-buffered/piped input, where readline would otherwise
+// emit a 'line' event before the next prompt is registered. Works the same for a live terminal.
+// We don't pass `output`, so the terminal's own echo handles typed input and readline never
+// fights an interactive child process for the TTY. Paused around child spawns (pause/resume).
+let _rl;
+const _queue = [];
+let _waiter = null;
+let _closed = false;
+
+function initRl() {
+  if (_rl) return;
+  _rl = readline.createInterface({ input: stdin });
+  _rl.on('line', (line) => {
+    if (_waiter) { const w = _waiter; _waiter = null; w(line); }
+    else _queue.push(line);
+  });
+  _rl.on('close', () => { _closed = true; if (_waiter) { const w = _waiter; _waiter = null; w(null); } });
+}
+function nextLine() {
+  initRl();
+  if (_queue.length) return Promise.resolve(_queue.shift());
+  if (_closed) return Promise.resolve(null);
+  return new Promise((res) => { _waiter = res; });
+}
+function pause() { if (_rl) _rl.pause(); }
+function resume() { if (_rl) _rl.resume(); }
+function closeUI() { if (_rl) { _rl.close(); _rl = null; } }
+
+async function ask(question, fallback = '') {
+  stdout.write('  ' + c.cyan('?') + ' ' + question + ' ');
+  const line = await nextLine();
+  const a = (line == null ? '' : line).trim();
+  if (line == null) stdout.write('\n');
+  return a || fallback;
+}
+
+async function confirm(question, defaultYes = true) {
+  const hint = defaultYes ? '(Y/n)' : '(y/N)';
+  const a = (await ask(`${question} ${c.dim(hint)}`)).toLowerCase();
+  if (!a) return defaultYes;
+  return a === 'y' || a === 'yes';
+}
+
+async function pressEnter(message = 'Press Enter to continue…') {
+  await ask(c.dim(message));
+}
+
+// Mask a secret for display: show prefix + last 4, hide the middle.
+function mask(secret) {
+  if (!secret) return '(none)';
+  const s = String(secret);
+  if (s.length <= 10) return s.slice(0, 2) + '…';
+  const head = s.includes('_') ? s.slice(0, s.indexOf('_') + 1) : s.slice(0, 3);
+  return head + '…' + s.slice(-4);
+}
+
+module.exports = { c, banner, heading, info, step, ok, warn, fail, dim, blank, ask, confirm, pressEnter, mask, pause, resume, closeUI };

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "agentbundle-cli",
+  "version": "0.1.0",
+  "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",
+    "agentbundle": "bin/agent-bundle.js",
+    "agent-bundle": "bin/agent-bundle.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin",
+    "lib",
+    "assets",
+    "README.md"
+  ],
+  "keywords": [
+    "ai-agent",
+    "agentcard",
+    "agentmail",
+    "agentphone",
+    "mcp",
+    "onboarding",
+    "cli"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tiny-agent-company/tiny-agent-company.git",
+    "directory": "apps/agent-bundle-cli"
+  },
+  "license": "MIT"
+}