@thirdfy/agent-cli 0.1.48 → 0.2.1

package/src/commands/bootstrap.mjs

@@ -0,0 +1,762 @@
+import { requireFlag, isNonInteractive } from '../core/args.mjs';
+import { createCliError } from '../core/envelope.mjs';
+import { PROFILE_DEFAULTS } from '../core/constants.mjs';
+import {
+  normalizeRunMode,
+  normalizeProfileName,
+  normalizeCustodyMode,
+  defaultCustodyModeForRunMode,
+  parseBooleanFlag,
+} from '../core/runMode.mjs';
+import {
+  loadProfileConfig,
+  persistProfileConfig,
+  clonePlainConfigTree,
+  setNestedConfigValue,
+  getProfileConfigPath,
+} from '../core/context.mjs';
+import { apiGet, apiPost, requestWithRouteFallback } from '../core/http.mjs';
+import { createRequire } from 'module';
+
+const require = createRequire(import.meta.url);
+const { version: CLI_VERSION } = require('../../package.json');
+
+export function createBootstrapCommands(deps) {
+  const {
+    printEnvelope,
+    extractAgentApiKey,
+    extractAgentKey,
+    buildOnboardingHelp,
+    buildWalletChallengePayload,
+    issueBootstrapToken,
+    verifyOwnerWalletChallenge,
+    resolveEffectiveUserDid,
+    negotiateCapabilities,
+    commandAgentRegister,
+  } = deps;
+
+
+async function commandProfileInit(ctx, flags) {
+  const current = loadProfileConfig();
+  const profile = normalizeProfileName(flags.profile || flags.name || 'personal');
+  const runMode = normalizeRunMode(flags.runMode || PROFILE_DEFAULTS[profile]);
+  const custodyMode = normalizeCustodyMode(flags.custodyMode, runMode);
+  persistProfileConfig({
+    ...current,
+    profile,
+    runMode,
+    custodyMode,
+  });
+  ctx.profile = profile;
+  ctx.runMode = runMode;
+  ctx.custodyMode = custodyMode;
+  printEnvelope({
+    success: true,
+    code: 'PROFILE_INITIALIZED',
+    message: 'Profile initialized',
+    data: {
+      profile,
+      runMode,
+      custodyMode,
+      configPath: getProfileConfigPath(),
+    },
+    meta: { apiBase: ctx.apiBase },
+  });
+}
+
+
+async function commandProfileUse(ctx, flags) {
+  const current = loadProfileConfig();
+  const profile = normalizeProfileName(flags.profile || flags.name || current.profile || 'personal');
+  // `profile use` intentionally re-applies profile defaults unless caller pins a mode.
+  const runMode = normalizeRunMode(flags.runMode || PROFILE_DEFAULTS[profile]);
+  const custodyMode = normalizeCustodyMode(flags.custodyMode || current.custodyMode, runMode);
+  persistProfileConfig({
+    ...current,
+    profile,
+    runMode,
+    custodyMode,
+  });
+  ctx.profile = profile;
+  ctx.runMode = runMode;
+  ctx.custodyMode = custodyMode;
+  printEnvelope({
+    success: true,
+    code: 'PROFILE_UPDATED',
+    message: 'Profile updated',
+    data: {
+      profile,
+      runMode,
+      custodyMode,
+      defaults: PROFILE_DEFAULTS,
+      configPath: getProfileConfigPath(),
+    },
+    meta: { apiBase: ctx.apiBase },
+  });
+}
+
+
+async function commandProfileShow(ctx, _flags) {
+  const config = loadProfileConfig();
+  printEnvelope({
+    success: true,
+    code: 'PROFILE_OK',
+    message: 'Profile configuration loaded',
+    data: {
+      profile: ctx.profile || config.profile || 'personal',
+      runMode: ctx.runMode || config.runMode || 'agent_wallet',
+      custodyMode: ctx.custodyMode || config.custodyMode || defaultCustodyModeForRunMode(ctx.runMode || config.runMode || 'agent_wallet'),
+      profileDefaults: PROFILE_DEFAULTS,
+      configPath: getProfileConfigPath(),
+      config,
+    },
+    meta: { apiBase: ctx.apiBase },
+  });
+}
+
+
+async function commandConfigSet(ctx, flags) {
+  const key = String(flags.key || '').trim();
+  const value = flags.value;
+  if (!key) {
+    throw new Error('Missing --key for config set');
+  }
+  const canonicalKey = key.toLowerCase();
+  const hasValue = !(value === undefined || String(value).trim() === '');
+  if (canonicalKey === 'profile' && hasValue) {
+    normalizeProfileName(value);
+  }
+  if (canonicalKey === 'runmode' && hasValue) {
+    normalizeRunMode(value);
+  }
+  if (canonicalKey === 'custodymode' && hasValue) {
+    const runModeHint = normalizeRunMode(flags.runMode || loadProfileConfig().runMode || 'thirdfy');
+    normalizeCustodyMode(value, runModeHint);
+  }
+
+  const current = loadProfileConfig();
+  const next = setNestedConfigValue(current, key, value);
+  persistProfileConfig(next);
+  printEnvelope({
+    success: true,
+    code: 'CONFIG_UPDATED',
+    message: 'Configuration updated',
+    data: {
+      key,
+      value: value === undefined ? null : String(value),
+      configPath: getProfileConfigPath(),
+    },
+    meta: { apiBase: ctx.apiBase },
+  });
+}
+
+
+async function commandHelpOnboarding(ctx, _flags) {
+  printEnvelope({
+    success: true,
+    code: 'ONBOARDING_HELP_OK',
+    message: 'Thirdfy onboarding help',
+    data: buildOnboardingHelp(ctx),
+    meta: { apiBase: ctx.apiBase },
+  });
+}
+
+
+async function commandWhoami(ctx, _flags) {
+  const config = loadProfileConfig();
+  const auth = config.auth && typeof config.auth === 'object' ? config.auth : {};
+  const agent = config.agent && typeof config.agent === 'object' ? config.agent : {};
+  const wallets = config.wallets && typeof config.wallets === 'object' ? config.wallets : {};
+  const runMode = ctx.runMode || config.runMode || 'agent_wallet';
+  printEnvelope({
+    success: true,
+    code: 'WHOAMI_OK',
+    message: 'Thirdfy CLI identity loaded',
+    data: {
+      profile: ctx.profile || config.profile || 'personal',
+      runMode,
+      custodyMode: ctx.custodyMode || config.custodyMode || defaultCustodyModeForRunMode(runMode),
+      auth: {
+        source: auth.source || null,
+        hasAuthToken: Boolean(auth.authToken),
+        hasOwnerSessionToken: Boolean(auth.ownerSessionToken),
+        ownerSessionToken: maskSecret(auth.ownerSessionToken),
+        ownerSessionExpiresAt: auth.ownerSessionExpiresAt || null,
+      },
+      agent: {
+        hasAgentApiKey: Boolean(agent.apiKey),
+        agentApiKey: maskSecret(agent.apiKey),
+        agentKey: agent.agentKey || null,
+      },
+      wallets: {
+        userDid: wallets.userDid || config.identity?.userDid || null,
+        primaryEvmWallet: wallets.primaryEvmWallet || null,
+        evm: Array.isArray(wallets.evm) ? wallets.evm : [],
+        solana: Array.isArray(wallets.solana) ? wallets.solana : [],
+        executionWallets: wallets.executionWallets || config.executionWallets || {},
+      },
+      configPath: getProfileConfigPath(),
+      nextSteps: buildOnboardingHelp(ctx).paths[0].commands,
+    },
+    meta: { apiBase: ctx.apiBase },
+  });
+}
+
+
+async function commandLogin(ctx, flags) {
+  const current = loadProfileConfig();
+  const authToken = String(flags.authToken || process.env.THIRDFY_AUTH_TOKEN || '').trim();
+  let ownerSessionToken = String(flags.ownerSessionToken || process.env.THIRDFY_OWNER_SESSION_TOKEN || '').trim();
+  const loginRunMode = normalizeRunMode(flags.runMode || current.runMode || process.env.THIRDFY_RUN_MODE || 'agent_wallet');
+  const custodyMode = normalizeCustodyMode(
+    flags.custodyMode || current.custodyMode || process.env.THIRDFY_CUSTODY_MODE,
+    loginRunMode
+  );
+  let loginSource = 'token';
+
+  if (!authToken && !ownerSessionToken) {
+    const challengeId = String(flags.challengeId || '').trim();
+    const signature = String(flags.signature || '').trim();
+    const agentKey = String(flags.agentKey || '').trim();
+    if (challengeId && signature && agentKey) {
+      const verifyResponse = await requestWithRouteFallback(ctx, {
+        method: 'POST',
+        routes: ['/api/v1/agent/onboarding/wallet/verify'],
+        body: {
+          challengeId,
+          signature,
+          agentKey,
+          ...(flags.walletAddress ? { walletAddress: String(flags.walletAddress).trim() } : {}),
+        },
+      });
+      ownerSessionToken = String(
+        verifyResponse?.ownerSessionToken || verifyResponse?.data?.ownerSessionToken || ''
+      ).trim();
+      loginSource = 'wallet-verify';
+    }
+  }
+
+  if (!authToken && !ownerSessionToken) {
+    throw new Error(
+      'Missing login credentials: provide --auth-token, --owner-session-token, or challenge verify inputs (--challenge-id/--signature/--agent-key).'
+    );
+  }
+
+  let bootstrapAgentApiKey = '';
+  let bootstrapPerformed = false;
+  const requestedAgentApiKey = String(flags.agentApiKey || '').trim();
+  const bootstrapAgentKey = String(flags.agentKey || '').trim();
+  if (!requestedAgentApiKey && bootstrapAgentKey) {
+    const bootstrapHeaders = ownerSessionToken
+      ? { 'x-owner-session-token': ownerSessionToken }
+      : authToken
+        ? { Authorization: `Bearer ${authToken}` }
+        : null;
+    if (bootstrapHeaders) {
+      const bootstrapResponse = await requestWithRouteFallback(ctx, {
+        method: 'POST',
+        routes: ['/api/v1/agent/onboarding/me/bootstrap-self'],
+        headers: bootstrapHeaders,
+        body: {
+          agentKey: bootstrapAgentKey,
+          runMode: loginRunMode,
+          custodyMode,
+          ...(flags.walletAddress ? { walletAddress: String(flags.walletAddress).trim() } : {}),
+          rotate: parseBooleanFlag(flags.rotateAgentKey, false),
+        },
+      });
+      bootstrapAgentApiKey = String(
+        bootstrapResponse?.agentApiKey || bootstrapResponse?.data?.agentApiKey || ''
+      ).trim();
+      bootstrapPerformed = true;
+    }
+  }
+
+  const next = {
+    ...current,
+    runMode: loginRunMode,
+    custodyMode,
+    auth: {
+      ...(current.auth && typeof current.auth === 'object' ? current.auth : {}),
+      lastLoginAt: new Date().toISOString(),
+      source: loginSource,
+    },
+  };
+  if (authToken) {
+    next.auth.authToken = authToken;
+    delete next.auth.ownerSessionToken;
+  } else if (ownerSessionToken) {
+    next.auth.ownerSessionToken = ownerSessionToken;
+    delete next.auth.authToken;
+  }
+  if (flags.agentApiKey) {
+    next.agent = {
+      ...(current.agent && typeof current.agent === 'object' ? current.agent : {}),
+      apiKey: requestedAgentApiKey,
+    };
+  } else if (bootstrapAgentApiKey) {
+    next.agent = {
+      ...(current.agent && typeof current.agent === 'object' ? current.agent : {}),
+      apiKey: bootstrapAgentApiKey,
+    };
+  }
+  persistProfileConfig(next);
+  printEnvelope({
+    success: true,
+    code: 'LOGIN_OK',
+    message: 'Login credentials stored',
+    data: {
+      hasAuthToken: Boolean(authToken),
+      hasOwnerSessionToken: Boolean(ownerSessionToken),
+      hasAgentApiKey: Boolean(requestedAgentApiKey || bootstrapAgentApiKey),
+      bootstrapPerformed,
+      runMode: loginRunMode,
+      custodyMode,
+      configPath: getProfileConfigPath(),
+    },
+    meta: { apiBase: ctx.apiBase },
+  });
+}
+
+
+async function commandLoginEmail(ctx, flags) {
+  const current = loadProfileConfig();
+  const email = String(flags.address || flags.email || '').trim().toLowerCase();
+  if (!email) {
+    throw createCliError(
+      'LOGIN_EMAIL_REQUIRED',
+      isNonInteractive(flags)
+        ? 'Missing email address for non-interactive login. Use: thirdfy-agent login email user@example.com [--code <otp> --accept-terms]'
+        : 'Missing email address. Use: thirdfy-agent login email user@example.com'
+    );
+  }
+  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
+    throw createCliError('LOGIN_EMAIL_INVALID', 'Provide a valid email address for Thirdfy email login.');
+  }
+  const code = String(flags.code || flags.otp || '').trim();
+  const keyName = String(flags.keyName || 'Thirdfy CLI').trim();
+  if (!code) {
+    const response = await apiPost(ctx, '/api/v1/agent/onboarding/cli/email/start', {
+      email,
+      keyName,
+      requestedCapabilities: {
+        walletApi: true,
+        agentApi: true,
+        evmWallet: true,
+        solanaWallet: true,
+      },
+    });
+    const data = response?.data || response || {};
+    const next = {
+      ...current,
+      login: {
+        ...(current.login && typeof current.login === 'object' ? current.login : {}),
+        email: {
+          lastEmail: email,
+          lastAttemptId: data.loginAttemptId || null,
+          sentAt: new Date().toISOString(),
+        },
+      },
+    };
+    persistProfileConfig(next);
+    printEnvelope({
+      success: true,
+      code: 'LOGIN_EMAIL_CODE_SENT',
+      message: response?.message || 'Verification code sent',
+      data: {
+        email,
+        loginAttemptId: data.loginAttemptId || null,
+        expiresAt: data.expiresAt || null,
+        nextCommand: data.nextCommand || `thirdfy-agent login email ${email} --code <code> --accept-terms`,
+        configPath: getProfileConfigPath(),
+      },
+      meta: { apiBase: ctx.apiBase },
+    });
+    return;
+  }
+
+  if (!parseBooleanFlag(flags.acceptTerms, false)) {
+    throw createCliError(
+      'LOGIN_EMAIL_TERMS_REQUIRED',
+      'Email login requires --accept-terms to complete first-run onboarding.'
+    );
+  }
+
+  const lastAttempt = current?.login?.email && typeof current.login.email === 'object' ? current.login.email : {};
+  const response = await apiPost(ctx, '/api/v1/agent/onboarding/cli/email/complete', {
+    email,
+    code,
+    loginAttemptId: String(flags.loginAttemptId || lastAttempt.lastAttemptId || '').trim() || undefined,
+    acceptTerms: true,
+    keyName,
+    agentKey: String(flags.agentKey || '').trim() || undefined,
+    runMode: normalizeRunMode(flags.runMode || current.runMode || process.env.THIRDFY_RUN_MODE || 'agent_wallet'),
+    custodyMode: normalizeCustodyMode(
+      flags.custodyMode || current.custodyMode || process.env.THIRDFY_CUSTODY_MODE,
+      normalizeRunMode(flags.runMode || current.runMode || process.env.THIRDFY_RUN_MODE || 'agent_wallet')
+    ),
+    bootstrapAgent: !parseBooleanFlag(flags.noBootstrapAgent, false),
+    rotateAgentKey: parseBooleanFlag(flags.rotateAgentKey, false),
+  });
+  const data = response?.data || response || {};
+  const ownerSessionToken = String(data.ownerSessionToken || '').trim();
+  const bootstrap = data.bootstrap && typeof data.bootstrap === 'object' ? data.bootstrap : {};
+  const agentApiKey = extractAgentApiKey(data);
+  const agentKey = extractAgentKey(data);
+  const wallets = data.wallets && typeof data.wallets === 'object' ? data.wallets : {};
+  const executionWallets = data.executionWallets && typeof data.executionWallets === 'object' ? data.executionWallets : {};
+  const userDid = String(data.owner?.creatorDid || wallets.userDid || '').trim();
+  const primaryEvmWallet = String(wallets.primaryEvmWallet || data.owner?.creatorWallet || '').trim();
+  const persistedWallets = {
+    ...wallets,
+    ...(userDid ? { userDid } : {}),
+    ...(primaryEvmWallet ? { primaryEvmWallet } : {}),
+    ...(Object.keys(executionWallets).length ? { executionWallets } : {}),
+  };
+  const runMode = normalizeRunMode(flags.runMode || current.runMode || process.env.THIRDFY_RUN_MODE || 'agent_wallet');
+  const custodyMode = normalizeCustodyMode(flags.custodyMode || current.custodyMode || process.env.THIRDFY_CUSTODY_MODE, runMode);
+  if (!ownerSessionToken) {
+    throw createCliError('LOGIN_EMAIL_OWNER_SESSION_MISSING', 'Email onboarding completed without an owner session token.');
+  }
+  const next = {
+    ...current,
+    runMode,
+    custodyMode,
+    auth: {
+      ...(current.auth && typeof current.auth === 'object' ? current.auth : {}),
+      lastLoginAt: new Date().toISOString(),
+      source: 'email',
+      ownerSessionToken,
+      ownerSessionExpiresAt: data.ownerSessionExpiresAt || null,
+    },
+    wallets: persistedWallets,
+    login: {
+      ...(current.login && typeof current.login === 'object' ? current.login : {}),
+      email: {
+        lastEmail: email,
+        completedAt: new Date().toISOString(),
+      },
+    },
+  };
+  delete next.auth.authToken;
+  if (agentApiKey || agentKey) {
+    next.agent = {
+      ...(current.agent && typeof current.agent === 'object' ? current.agent : {}),
+      ...(agentApiKey ? { apiKey: agentApiKey } : {}),
+      ...(agentKey ? { agentKey } : {}),
+    };
+  }
+  persistProfileConfig(next);
+  printEnvelope({
+    success: true,
+    code: 'LOGIN_EMAIL_OK',
+    message: response?.message || 'Email login completed',
+    data: {
+      email,
+      hasOwnerSessionToken: Boolean(ownerSessionToken),
+      hasAgentApiKey: Boolean(agentApiKey),
+      agentKey: agentKey || null,
+      evmWallets: Array.isArray(persistedWallets.evm) ? persistedWallets.evm : [],
+      solanaWallets: Array.isArray(persistedWallets.solana) ? persistedWallets.solana : [],
+      primaryEvmWallet: persistedWallets.primaryEvmWallet || null,
+      executionWallets:
+        persistedWallets.executionWallets && typeof persistedWallets.executionWallets === 'object'
+          ? persistedWallets.executionWallets
+          : {},
+      ownerLinkedWallet: data.ownerLinkedWallet || null,
+      configPath: getProfileConfigPath(),
+      nextSteps: response?.nextSteps || [],
+    },
+    meta: { apiBase: ctx.apiBase },
+  });
+}
+
+
+async function commandLogout(ctx, flags) {
+  const current = loadProfileConfig();
+  const localOnly = flags.all ? false : true;
+  const auth = current.auth && typeof current.auth === 'object' ? current.auth : {};
+  const ownerSessionToken = String(auth.ownerSessionToken || '').trim();
+  let revokeAttempted = false;
+  let revokeSuccess = false;
+  let revokeError = null;
+
+  if (!localOnly && ownerSessionToken) {
+    revokeAttempted = true;
+    try {
+      await requestWithRouteFallback(ctx, {
+        method: 'POST',
+        routes: ['/api/v1/agent/onboarding/wallet/logout', '/api/v1/agent/onboarding/wallet/revoke-session'],
+        body: {},
+        headers: {
+          'x-owner-session-token': ownerSessionToken,
+        },
+      });
+      revokeSuccess = true;
+    } catch (error) {
+      revokeError = error?.message || 'OWNER_SESSION_REVOKE_FAILED';
+    }
+  }
+
+  const next = { ...current };
+  delete next.auth;
+  if (flags.clearAgentKey) {
+    delete next.agent;
+  }
+  persistProfileConfig(next);
+  printEnvelope({
+    success: true,
+    code: 'LOGOUT_OK',
+    message: 'Local credentials cleared',
+    data: {
+      localOnly,
+      revokeAttempted,
+      revokeSuccess,
+      revokeError,
+      configPath: getProfileConfigPath(),
+    },
+    meta: { apiBase: ctx.apiBase },
+  });
+}
+
+
+async function commandBootstrapBegin(ctx, flags, capabilities) {
+  const challenge = await apiPost(
+    ctx,
+    '/api/v1/agent/onboarding/wallet/challenge',
+    buildWalletChallengePayload(flags)
+  );
+  printEnvelope({
+    success: true,
+    code: 'BOOTSTRAP_BEGIN_OK',
+    message: 'Bootstrap challenge created',
+    data: {
+      challenge,
+      nextStep:
+        'Run `thirdfy-agent bootstrap complete --agent-key <key> --challenge-id <id> --signature <hex> [--name <agent-name>]`',
+    },
+    meta: {
+      apiBase: ctx.apiBase,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+}
+
+
+async function commandBootstrapComplete(ctx, flags, capabilities) {
+  const agentKey = requireFlag(flags, 'agentKey', 'Missing --agent-key');
+  const lane = normalizeRunMode(flags.lane || flags.runMode || 'self', flags.lane ? '--lane' : '--run-mode');
+  let proofType = String(flags.proofType || '').trim() || 'session_token';
+  if (proofType !== 'session_token' && proofType !== 'wallet_signature') {
+    throw new Error('Invalid --proof-type. Supported values: session_token (preferred) or wallet_signature.');
+  }
+  let ownerSessionToken = String(flags.ownerSessionToken || process.env.THIRDFY_OWNER_SESSION_TOKEN || '').trim();
+  const authToken = String(flags.authToken || process.env.THIRDFY_AUTH_TOKEN || '').trim();
+  let challengeId = String(flags.challengeId || '').trim();
+  let signature = String(flags.signature || '').trim();
+  if (!String(flags.proofType || '').trim() && !ownerSessionToken && !authToken && challengeId && signature) {
+    proofType = 'wallet_signature';
+  }
+  if (proofType === 'wallet_signature' && (!challengeId || !signature)) {
+    throw new Error('wallet_signature proof requires --challenge-id and --signature.');
+  }
+  if (proofType === 'session_token' && !ownerSessionToken && !authToken && challengeId && signature) {
+    const verify = await verifyOwnerWalletChallenge(ctx, {
+      ...flags,
+      agentKey,
+      challengeId,
+      signature,
+    });
+    ownerSessionToken = String(verify?.ownerSessionToken || verify?.data?.ownerSessionToken || '').trim();
+    if (!ownerSessionToken) {
+      throw new Error('Wallet verify did not return owner session token required for bootstrap registration.');
+    }
+  }
+  if (proofType === 'session_token' && (ownerSessionToken || authToken)) {
+    // Avoid replaying a single-use challenge across bootstrap and register calls.
+    challengeId = '';
+    signature = '';
+  }
+  if (proofType === 'session_token' && !ownerSessionToken && !authToken) {
+    throw new Error(
+      'Bootstrap currently supports session_token proof only. Provide --owner-session-token/--auth-token, or --challenge-id + --signature to exchange into a session token.'
+    );
+  }
+
+  const bootstrapPayload = {
+    sub: agentKey,
+    lane,
+    scope: ['onboarding:bootstrap'],
+    proof_type: proofType,
+    ...(ownerSessionToken ? { ownerSessionToken } : {}),
+    ...(authToken ? { authToken } : {}),
+    ...(challengeId ? { challengeId } : {}),
+    ...(signature ? { signature } : {}),
+    agentKey,
+  };
+  const issued = await issueBootstrapToken(ctx, flags, bootstrapPayload);
+  const bootstrapToken = String(issued.data?.token || '').trim();
+
+  const config = loadProfileConfig();
+  const next = {
+    ...config,
+    auth: {
+      ...(config.auth && typeof config.auth === 'object' ? config.auth : {}),
+      bootstrapToken,
+      bootstrapTokenIssuedAt: new Date().toISOString(),
+      bootstrapLane: lane,
+    },
+  };
+  persistProfileConfig(next);
+
+  let registration = null;
+  if (flags.name) {
+    registration = await commandDeveloperBootstrap(
+      ctx,
+      {
+        ...flags,
+        agentKey,
+        name: String(flags.name).trim(),
+        challengeId,
+        signature,
+        ...(ownerSessionToken ? { ownerSessionToken } : {}),
+        __suppressOutput: true,
+      },
+      capabilities
+    );
+  }
+  const registrationAgentApiKey = extractAgentApiKey(registration || {});
+  const registrationAgentKey = extractAgentKey(registration || {}) || agentKey;
+  if (registrationAgentApiKey || registrationAgentKey) {
+    const latest = loadProfileConfig();
+    persistProfileConfig({
+      ...latest,
+      agent: {
+        ...(latest.agent && typeof latest.agent === 'object' ? latest.agent : {}),
+        ...(registrationAgentApiKey ? { apiKey: registrationAgentApiKey } : {}),
+        ...(registrationAgentKey ? { agentKey: registrationAgentKey } : {}),
+      },
+    });
+  }
+
+  printEnvelope({
+    success: true,
+    code: 'BOOTSTRAP_COMPLETE_OK',
+    message: 'Bootstrap token issued',
+    data: {
+      bootstrap: issued.data,
+      registration,
+      persisted: {
+        configPath: getProfileConfigPath(),
+        hasBootstrapToken: Boolean(bootstrapToken),
+      },
+    },
+    meta: {
+      apiBase: ctx.apiBase,
+      mcpBase: issued.mcpBase,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+}
+
+
+async function commandDeveloperBootstrap(ctx, flags, capabilities) {
+  const agentKey = requireFlag(flags, 'agentKey', 'Missing --agent-key');
+  const name = requireFlag(flags, 'name', 'Missing --name');
+  let ownerSessionToken = String(flags.ownerSessionToken || process.env.THIRDFY_OWNER_SESSION_TOKEN || '').trim();
+  let usedWalletFlow = false;
+  const challengeId = String(flags.challengeId || '').trim();
+  const signature = String(flags.signature || '').trim();
+
+  if (!ownerSessionToken && signature) {
+    if (!challengeId) {
+      throw new Error('Missing --challenge-id for wallet bootstrap. Run `agent auth challenge` first.');
+    }
+    const verify = await verifyOwnerWalletChallenge(ctx, {
+      ...flags,
+      challengeId,
+      signature,
+      agentKey,
+    });
+    ownerSessionToken = String(verify?.ownerSessionToken || verify?.data?.ownerSessionToken || '').trim();
+    usedWalletFlow = true;
+  }
+
+  const registerFlags = {
+    ...flags,
+    agentKey,
+    name,
+    ...(ownerSessionToken ? { ownerSessionToken } : {}),
+  };
+  const registerResponse = await commandAgentRegister(
+    ctx,
+    { ...registerFlags, __suppressOutput: true },
+    capabilities
+  );
+  const agentApiKey = extractAgentApiKey(registerResponse || {});
+  const responseAgentKey = extractAgentKey(registerResponse || {}) || agentKey;
+
+  const config = loadProfileConfig();
+  const next = {
+    ...config,
+    auth: {
+      ...(config.auth && typeof config.auth === 'object' ? config.auth : {}),
+      ...(ownerSessionToken ? { ownerSessionToken } : {}),
+      lastLoginAt: new Date().toISOString(),
+      source: usedWalletFlow ? 'wallet-verify-bootstrap' : 'bootstrap',
+    },
+    developer: {
+      ...(config.developer && typeof config.developer === 'object' ? config.developer : {}),
+      agentKey,
+      bootstrapCompletedAt: new Date().toISOString(),
+    },
+  };
+  if (agentApiKey || responseAgentKey) {
+    next.agent = {
+      ...(config.agent && typeof config.agent === 'object' ? config.agent : {}),
+      ...(agentApiKey ? { apiKey: agentApiKey } : {}),
+      ...(responseAgentKey ? { agentKey: responseAgentKey } : {}),
+    };
+  }
+  persistProfileConfig(next);
+  if (!flags.__suppressOutput) {
+    printEnvelope({
+      success: true,
+      code: 'DEVELOPER_BOOTSTRAP_OK',
+      message: 'Developer bootstrap completed',
+      data: {
+        registration: registerResponse,
+        persisted: {
+          ownerSessionTokenSaved: Boolean(ownerSessionToken),
+          source: usedWalletFlow ? 'wallet-verify-bootstrap' : 'bootstrap',
+          configPath: getProfileConfigPath(),
+        },
+      },
+      meta: {
+        apiBase: ctx.apiBase,
+        capabilitiesVersion: capabilities?.contractVersion || null,
+      },
+    });
+  }
+  return {
+    registration: registerResponse,
+    ownerSessionTokenSaved: Boolean(ownerSessionToken),
+    source: usedWalletFlow ? 'wallet-verify-bootstrap' : 'bootstrap',
+  };
+}
+
+  return {
+    commandProfileInit,
+    commandProfileUse,
+    commandProfileShow,
+    commandConfigSet,
+    commandHelpOnboarding,
+    commandWhoami,
+    commandLogin,
+    commandLoginEmail,
+    commandLogout,
+    commandBootstrapBegin,
+    commandBootstrapComplete,
+    commandDeveloperBootstrap,
+  };
+}