@thirdfy/agent-cli 0.1.11 → 0.1.13

package/CHANGELOG.md

@@ -4,6 +4,15 @@ All notable changes to `@thirdfy/agent-cli` are documented here. The format is b
 
 ## [Unreleased]
 
+## [0.1.13] - 2026-04-19
+
+**npm:** [`@thirdfy/agent-cli@0.1.13`](https://www.npmjs.com/package/@thirdfy/agent-cli/v/0.1.13)  
+**Git tag:** `v0.1.13`
+
+### Changed
+
+- **README and onboarding docs refresh:** Updated public README guidance to reflect latest bootstrap/onboarding command surface (`bootstrap begin/complete` plus aliases), session-proof-first issuance behavior, and current release references.
+
 ## [0.1.11] - 2026-04-16
 
 **npm:** [`@thirdfy/agent-cli@0.1.11`](https://www.npmjs.com/package/@thirdfy/agent-cli/v/0.1.11)  

package/README.md

@@ -38,12 +38,12 @@ Run without global install:
 npx @thirdfy/agent-cli --help
 ```
 
-## What's new in 0.1.8
+## What's new in 0.1.12
 
-- Managed custodial lifecycle parity validation is now first-class in CLI E2E/certification.
-- `doctor self` runs as a local diagnostic command without capabilities negotiation.
-- Self-exec effect-check fallback payloads are hardened for deterministic automation parsing.
-- Managed wallet aliases (`managed wallet init/grant`) are wired directly to custodial delegation handlers.
+- Added Model D onboarding commands: `bootstrap begin` and `bootstrap complete`.
+- Added `onboarding begin` and `onboarding complete` aliases for clearer operator flows.
+- Aligned bootstrap completion to session-proof issuance (`session_token`), with wallet challenge/signature supported as an exchange step into session proof.
+- Hardened bootstrap path behavior for safer timeout and one-time challenge handling.
 
 ## Quick start
 
@@ -112,6 +112,21 @@ Use the returned session token:
 thirdfy-agent agent register --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN" --agent-key "0xYOUR_AGENT_KEY" --name "my-agent" --json
 ```
 
+### Bootstrap onboarding (Model D)
+
+```bash
+# Start wallet challenge flow
+thirdfy-agent bootstrap begin --agent-key "0xYOUR_AGENT_KEY" --json
+
+# Complete bootstrap with session proof (recommended)
+thirdfy-agent bootstrap complete --agent-key "0xYOUR_AGENT_KEY" --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN" --lane self --json
+
+# Or use challenge/signature as exchange step to obtain session proof first
+thirdfy-agent bootstrap complete --agent-key "0xYOUR_AGENT_KEY" --challenge-id "<challengeId>" --signature "0x..." --lane self --json
+```
+
+`bootstrap complete` is session-proof-first in the current deployment. Direct `wallet_signature` proof is not accepted as a final issuance proof.
+
 ### Idempotency behavior (`run`)
 
 - `run` auto-generates `idempotencyKey` by default when not provided.
@@ -240,7 +255,7 @@ Provider and venue guides are kept outside `README` so this page stays stable as
 - Discovery: `catalogs list`, `actions`
 - Execution: `preflight`, `run`, `intent-status`, `jeff preflight`, `jeff trade`, `jeff status`
 - Profiles: `profile init`, `profile use`, `profile show`, `whoami`
-- Onboarding: `agent auth challenge`, `agent auth verify`, `agent register`, `agent key rotate`, `agent key revoke`
+- Onboarding: `bootstrap begin`, `bootstrap complete`, `onboarding begin`, `onboarding complete`, `agent auth challenge`, `agent auth verify`, `agent register`, `agent key rotate`, `agent key revoke`, `developer bootstrap`
 - Governance readiness: `delegation create`, `delegation activate`, `delegation status`, `credentials upsert`, `credentials status`
 - Delegation operations: `delegation show`, `delegation inspect`, `delegation revoke`
 - Delegation execution helpers: `delegation balance`, `delegation redeem`
@@ -357,11 +372,11 @@ npm run e2e:managed:delegation:parity
 
 ## Release
 
-Version history and user-facing notes: [CHANGELOG.md](./CHANGELOG.md) (for example [0.1.7](https://github.com/thirdfy/agent-cli/releases/tag/v0.1.7) — login/config UX, custodial delegation helpers, swap and config hardening).
+Version history and user-facing notes: [CHANGELOG.md](./CHANGELOG.md) (for example [0.1.12](https://github.com/thirdfy/agent-cli/releases/tag/v0.1.12) — bootstrap onboarding commands and session-proof alignment).
 
 ```bash
 npm version patch
 npm publish --access public
 ```
 
-After publishing, push the matching tag (for example `v0.1.7`) so the [Release workflow](.github/workflows/release.yml) can create a GitHub release. If the package version is already on npm, the workflow skips republishing and still creates the release when triggered by a tag.
+After publishing, push the matching tag (for example `v0.1.12`) so the [Release workflow](.github/workflows/release.yml) can create a GitHub release. If the package version is already on npm, the workflow skips republishing and still creates the release when triggered by a tag.

package/bin/thirdfy-agent.mjs

@@ -214,6 +214,14 @@ async function main() {
     case 'developer bootstrap':
       await commandDeveloperBootstrap(context, subFlags, capabilities);
       return;
+    case 'bootstrap begin':
+    case 'onboarding begin':
+      await commandBootstrapBegin(context, subFlags, capabilities);
+      return;
+    case 'bootstrap complete':
+    case 'onboarding complete':
+      await commandBootstrapComplete(context, subFlags, capabilities);
+      return;
     default:
       break;
   }
@@ -1091,11 +1099,11 @@ async function commandDeveloperBootstrap(ctx, flags, capabilities) {
     if (!challengeId) {
       throw new Error('Missing --challenge-id for wallet bootstrap. Run `agent auth challenge` first.');
     }
-    const verify = await apiPost(ctx, '/api/v1/agent/onboarding/wallet/verify', {
+    const verify = await verifyOwnerWalletChallenge(ctx, {
+      ...flags,
       challengeId,
       signature,
       agentKey,
-      ...(flags.walletAddress ? { walletAddress: String(flags.walletAddress).trim() } : {}),
     });
     ownerSessionToken = String(verify?.ownerSessionToken || verify?.data?.ownerSessionToken || '').trim();
     usedWalletFlow = true;
@@ -1129,23 +1137,30 @@ async function commandDeveloperBootstrap(ctx, flags, capabilities) {
     },
   };
   persistProfileConfig(next);
-  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(),
+  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,
-    },
-  });
+      meta: {
+        apiBase: ctx.apiBase,
+        capabilitiesVersion: capabilities?.contractVersion || null,
+      },
+    });
+  }
+  return {
+    registration: registerResponse,
+    ownerSessionTokenSaved: Boolean(ownerSessionToken),
+    source: usedWalletFlow ? 'wallet-verify-bootstrap' : 'bootstrap',
+  };
 }
 
 async function commandAgentKeyRotate(ctx, flags, capabilities) {
@@ -1188,14 +1203,21 @@ async function commandAgentKeyRevoke(ctx, flags, capabilities) {
   });
 }
 
-async function commandAgentAuthChallenge(ctx, flags, capabilities) {
+function buildWalletChallengePayload(flags) {
   const payload = {
     agentKey: requireFlag(flags, 'agentKey', 'Missing --agent-key'),
     chainId: Number(flags.chainId || 8453),
   };
   if (flags.walletAddress) payload.walletAddress = String(flags.walletAddress).trim();
+  return payload;
+}
 
-  const response = await apiPost(ctx, '/api/v1/agent/onboarding/wallet/challenge', payload);
+async function commandAgentAuthChallenge(ctx, flags, capabilities) {
+  const response = await apiPost(
+    ctx,
+    '/api/v1/agent/onboarding/wallet/challenge',
+    buildWalletChallengePayload(flags)
+  );
   printEnvelope({
     success: true,
     code: 'OWNER_CHALLENGE_CREATED',
@@ -1209,21 +1231,186 @@ async function commandAgentAuthChallenge(ctx, flags, capabilities) {
 }
 
 async function commandAgentAuthVerify(ctx, flags, capabilities) {
+  const response = await verifyOwnerWalletChallenge(ctx, flags);
+  printEnvelope({
+    success: true,
+    code: 'OWNER_VERIFIED',
+    message: 'Wallet challenge verified',
+    data: response,
+    meta: {
+      apiBase: ctx.apiBase,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+}
+
+async function verifyOwnerWalletChallenge(ctx, flags) {
   const payload = {
     challengeId: requireFlag(flags, 'challengeId', 'Missing --challenge-id'),
     signature: requireFlag(flags, 'signature', 'Missing --signature'),
     agentKey: requireFlag(flags, 'agentKey', 'Missing --agent-key'),
   };
   if (flags.walletAddress) payload.walletAddress = String(flags.walletAddress).trim();
+  return apiPost(ctx, '/api/v1/agent/onboarding/wallet/verify', payload);
+}
+
+function resolveMcpBase(flags) {
+  return String(flags.mcpBase || process.env.THIRDFY_MCP_BASE_URL || 'https://mcp.thirdfy.com').trim().replace(/\/+$/, '');
+}
+
+async function issueBootstrapToken(ctx, flags, payload) {
+  const mcpBase = resolveMcpBase(flags);
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), Number(ctx.timeoutMs || DEFAULT_TIMEOUT_MS));
+  let response;
+  let text = '';
+  try {
+    response = await fetch(`${mcpBase}/auth/bootstrap/issue`, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        'x-cli-version': CLI_VERSION,
+      },
+      body: JSON.stringify(payload),
+      signal: controller.signal,
+    });
+    text = await response.text();
+  } catch (error) {
+    if (error?.name === 'AbortError') {
+      throw createCliError('TIMEOUT', `Request timed out after ${ctx.timeoutMs}ms`, {
+        routes: ['/auth/bootstrap/issue'],
+      });
+    }
+    throw error;
+  } finally {
+    clearTimeout(timeout);
+  }
+  const data = text ? safeJsonParse(text) : {};
+  if (!response.ok) {
+    const message = data?.error || data?.message || 'Bootstrap token issuance failed';
+    throw createCliError('BOOTSTRAP_TOKEN_ISSUE_FAILED', message, data);
+  }
+  return {
+    mcpBase,
+    data,
+  };
+}
 
-  const response = await apiPost(ctx, '/api/v1/agent/onboarding/wallet/verify', payload);
+async function commandBootstrapBegin(ctx, flags, capabilities) {
+  const challenge = await apiPost(
+    ctx,
+    '/api/v1/agent/onboarding/wallet/challenge',
+    buildWalletChallengePayload(flags)
+  );
   printEnvelope({
     success: true,
-    code: 'OWNER_VERIFIED',
-    message: 'Wallet challenge verified',
-    data: response,
+    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');
+  const 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 (challenge exchange only).');
+  }
+  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 (proofType === 'wallet_signature' && (!challengeId || !signature)) {
+    throw new Error('wallet_signature bootstrap is not supported directly. Provide --owner-session-token or --auth-token.');
+  }
+  if (!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 (ownerSessionToken || authToken) {
+    // Avoid replaying a single-use challenge across bootstrap and register calls.
+    challengeId = '';
+    signature = '';
+  }
+  if (!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: 'session_token',
+    ...(ownerSessionToken ? { ownerSessionToken } : {}),
+    ...(authToken ? { authToken } : {}),
+    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
+    );
+  }
+
+  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,
     },
   });
@@ -1700,11 +1887,11 @@ function normalizeProfileName(value) {
   throw new Error(`Unsupported profile "${value}". Supported: ${Object.keys(PROFILE_DEFAULTS).join(', ')}`);
 }
 
-function normalizeRunMode(value) {
+function normalizeRunMode(value, flagName = '--run-mode') {
   const normalized = String(value || '').trim().toLowerCase();
   if (!normalized) return 'thirdfy';
   if (RUN_MODES.includes(normalized)) return normalized;
-  throw new Error(`Unsupported --run-mode "${value}". Supported: ${RUN_MODES.join(', ')}`);
+  throw new Error(`Unsupported ${flagName} "${value}". Supported: ${RUN_MODES.join(', ')}`);
 }
 
 function defaultCustodyModeForRunMode(runMode) {
@@ -2803,6 +2990,10 @@ Core commands:
   thirdfy-agent credentials status --auth-token <token> [--venue <id>] [--json]
   thirdfy-agent agent auth challenge --agent-key <key> [--wallet-address <addr>] [--chain-id <id>] [--json]
   thirdfy-agent agent auth verify --challenge-id <id> --signature <hex> --agent-key <key> [--wallet-address <addr>] [--json]
+  thirdfy-agent bootstrap begin --agent-key <key> [--wallet-address <addr>] [--chain-id <id>] [--json]
+  thirdfy-agent bootstrap complete --agent-key <key> [--proof-type session_token] [--lane self|hybrid|thirdfy] [--owner-session-token <token> | --auth-token <token> | --challenge-id <id> --signature <hex>] [--name <agent-name>] [--mcp-base <url>] [--json]
+  thirdfy-agent onboarding begin ...      # alias of bootstrap begin
+  thirdfy-agent onboarding complete ...   # alias of bootstrap complete
   thirdfy-agent developer bootstrap --agent-key <key> --name <name> [--owner-session-token <token> | --challenge-id <id> --signature <hex>] [--json]
   thirdfy-agent agent register --agent-key <key> --name <name> [--auth-token <token> | --owner-session-token <token>] [--json]
   thirdfy-agent agent key rotate [--agent-key <key>] [--auth-token <token> | --owner-session-token <token>] [--json]
@@ -2820,6 +3011,7 @@ Core commands:
 
 Global flags:
   --api-base <url>   default: https://api.thirdfy.com
+  --mcp-base <url>   default: https://mcp.thirdfy.com (bootstrap token issuance)
   --run-mode <mode>  thirdfy | self | hybrid
   --custody-mode <mode>  managed | external
   --profile <name>   personal | builder | network

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thirdfy/agent-cli",
-  "version": "0.1.11",
+  "version": "0.1.13",
   "description": "Thirdfy Agent CLI for onboarding, governance preflight, execute-intent, and status polling.",
   "type": "module",
   "bin": {