@thirdfy/agent-cli 0.1.10 → 0.1.11

package/CHANGELOG.md

@@ -4,6 +4,17 @@ All notable changes to `@thirdfy/agent-cli` are documented here. The format is b
 
 ## [Unreleased]
 
+## [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)  
+**Git tag:** `v0.1.11`
+
+### Added
+
+- **Self identity bootstrap during login:** `thirdfy-agent login` can now auto-bootstrap scoped self identity when `--agent-key` is provided, and persist the returned `agentApiKey` without manual env injection.
+- **Custody mode profile contract:** Added persisted `custodyMode` (`managed` or `external`) across `profile init`, `profile use`, and `whoami`/config UX.
+- **Self custody validation E2E:** Added `e2e:self:managed-custody-validation` and wired it into production certification flow.
+
 ## [0.1.9] - 2026-04-08
 
 **npm:** [`@thirdfy/agent-cli@0.1.9`](https://www.npmjs.com/package/@thirdfy/agent-cli/v/0.1.9)  

package/README.md

@@ -81,9 +81,13 @@ Execution-only workflows can run with only `AGENT_API_KEY` after onboarding is c
 # Store auth defaults once
 thirdfy-agent login --auth-token "$THIRDFY_AUTH_TOKEN" --agent-api-key "$AGENT_API_KEY" --json
 
+# Bootstrap scoped self identity + custody mode in one step
+thirdfy-agent login --auth-token "$THIRDFY_AUTH_TOKEN" --agent-key "0xYOUR_AGENT_KEY" --run-mode self --custody-mode external --wallet-address "0xYOUR_AGENT_KEY" --json
+
 # Inspect config
 thirdfy-agent whoami --json
 thirdfy-agent config set --key runMode --value self --json
+thirdfy-agent config set --key custodyMode --value external --json
 
 # Local-only logout (default)
 thirdfy-agent logout --json
@@ -136,6 +140,9 @@ Auth expectations by mode:
 - `self`: requires execution identity (`agentApiKey`) today; keyless self lane is blocked with deterministic `SELF_OPEN_DISABLED`.
 - `hybrid`: requires execution identity and governed mirror semantics.
 - `thirdfy`: requires execution identity and delegated governance path.
+- custody mode defaults are profile-aware:
+  - `managed` default for `thirdfy`
+  - `external` default for `self` and `hybrid`
 
 Selection precedence:
 
@@ -344,6 +351,7 @@ thirdfy-agent managed run --agent-api-key "$AGENT_API_KEY" --run-mode thirdfy --
 npm run validate:cli-contract-schemas
 npm test
 npm run smoke:cli
+npm run e2e:self:managed-custody-validation
 npm run e2e:managed:delegation:parity
 ```
 

package/bin/thirdfy-agent.mjs

@@ -24,6 +24,7 @@ const BITFINEX_REQUIRED_SCOPE_PERMISSIONS = {
   wallets: { read: 1, write: 1 },
 };
 const RUN_MODES = ['thirdfy', 'self', 'hybrid'];
+const CUSTODY_MODES = ['managed', 'external'];
 const EFFECT_CHECK_MODES = ['strict', 'relaxed', 'off'];
 const PROFILE_DEFAULTS = {
   personal: 'self',
@@ -94,6 +95,7 @@ async function main() {
   const profileState = resolveProfileState(globalFlags);
   context.profile = profileState.profile;
   context.runMode = profileState.runMode;
+  context.custodyMode = profileState.custodyMode;
   context.profileConfigPath = profileState.configPath;
 
   if (globalFlags.version) {
@@ -1401,13 +1403,16 @@ 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',
@@ -1415,6 +1420,7 @@ async function commandProfileInit(ctx, flags) {
     data: {
       profile,
       runMode,
+      custodyMode,
       configPath: getProfileConfigPath(),
     },
     meta: { apiBase: ctx.apiBase },
@@ -1426,13 +1432,16 @@ async function commandProfileUse(ctx, flags) {
   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',
@@ -1440,6 +1449,7 @@ async function commandProfileUse(ctx, flags) {
     data: {
       profile,
       runMode,
+      custodyMode,
       defaults: PROFILE_DEFAULTS,
       configPath: getProfileConfigPath(),
     },
@@ -1456,6 +1466,7 @@ async function commandProfileShow(ctx, _flags) {
     data: {
       profile: ctx.profile || config.profile || 'personal',
       runMode: ctx.runMode || config.runMode || 'thirdfy',
+      custodyMode: ctx.custodyMode || config.custodyMode || defaultCustodyModeForRunMode(ctx.runMode || config.runMode || 'thirdfy'),
       profileDefaults: PROFILE_DEFAULTS,
       configPath: getProfileConfigPath(),
       config,
@@ -1478,6 +1489,10 @@ async function commandConfigSet(ctx, flags) {
   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);
@@ -1499,6 +1514,11 @@ 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 || 'thirdfy');
+  const custodyMode = normalizeCustodyMode(
+    flags.custodyMode || current.custodyMode || process.env.THIRDFY_CUSTODY_MODE,
+    loginRunMode
+  );
   let loginSource = 'token';
 
   if (!authToken && !ownerSessionToken) {
@@ -1529,8 +1549,40 @@ async function commandLogin(ctx, flags) {
     );
   }
 
+  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(),
@@ -1547,7 +1599,12 @@ async function commandLogin(ctx, flags) {
   if (flags.agentApiKey) {
     next.agent = {
       ...(current.agent && typeof current.agent === 'object' ? current.agent : {}),
-      apiKey: String(flags.agentApiKey).trim(),
+      apiKey: requestedAgentApiKey,
+    };
+  } else if (bootstrapAgentApiKey) {
+    next.agent = {
+      ...(current.agent && typeof current.agent === 'object' ? current.agent : {}),
+      apiKey: bootstrapAgentApiKey,
     };
   }
   persistProfileConfig(next);
@@ -1558,7 +1615,10 @@ async function commandLogin(ctx, flags) {
     data: {
       hasAuthToken: Boolean(authToken),
       hasOwnerSessionToken: Boolean(ownerSessionToken),
-      hasAgentApiKey: Boolean(flags.agentApiKey),
+      hasAgentApiKey: Boolean(requestedAgentApiKey || bootstrapAgentApiKey),
+      bootstrapPerformed,
+      runMode: loginRunMode,
+      custodyMode,
       configPath: getProfileConfigPath(),
     },
     meta: { apiBase: ctx.apiBase },
@@ -1622,9 +1682,14 @@ function resolveProfileState(flags) {
       PROFILE_DEFAULTS[profile] ||
       'thirdfy'
   );
+  const custodyMode = normalizeCustodyMode(
+    flags.custodyMode || process.env.THIRDFY_CUSTODY_MODE || persisted.custodyMode,
+    runMode
+  );
   return {
     profile,
     runMode,
+    custodyMode,
     configPath: getProfileConfigPath(),
   };
 }
@@ -1642,6 +1707,18 @@ function normalizeRunMode(value) {
   throw new Error(`Unsupported --run-mode "${value}". Supported: ${RUN_MODES.join(', ')}`);
 }
 
+function defaultCustodyModeForRunMode(runMode) {
+  return runMode === 'thirdfy' ? 'managed' : 'external';
+}
+
+function normalizeCustodyMode(value, runModeHint = 'thirdfy') {
+  const fallback = defaultCustodyModeForRunMode(runModeHint);
+  const normalized = String(value || '').trim().toLowerCase();
+  if (!normalized) return fallback;
+  if (CUSTODY_MODES.includes(normalized)) return normalized;
+  throw new Error(`Unsupported custody mode "${value}". Supported: ${CUSTODY_MODES.join(', ')}`);
+}
+
 function normalizeManagedRunMode(value) {
   const mode = normalizeRunMode(value || 'thirdfy');
   if (mode === 'self') {
@@ -2700,11 +2777,11 @@ function printHelp() {
 thirdfy-agent ${CLI_VERSION}
 
 Core commands:
-  thirdfy-agent profile init [--profile personal|builder|network] [--run-mode thirdfy|self|hybrid] [--json]
-  thirdfy-agent profile use --profile <name> [--run-mode thirdfy|self|hybrid] [--json]
+  thirdfy-agent profile init [--profile personal|builder|network] [--run-mode thirdfy|self|hybrid] [--custody-mode managed|external] [--json]
+  thirdfy-agent profile use --profile <name> [--run-mode thirdfy|self|hybrid] [--custody-mode managed|external] [--json]
   thirdfy-agent profile show [--json]
   thirdfy-agent config set --key <path> --value <value> [--json]
-  thirdfy-agent login [--auth-token <token> | --owner-session-token <token>] [--agent-api-key <key>] [--json]
+  thirdfy-agent login [--auth-token <token> | --owner-session-token <token>] [--agent-api-key <key>] [--agent-key <key>] [--run-mode <mode>] [--custody-mode managed|external] [--wallet-address <addr>] [--json]
   thirdfy-agent logout [--all] [--clear-agent-key] [--json]
   thirdfy-agent whoami [--json]
   thirdfy-agent catalogs list [--json]
@@ -2744,6 +2821,7 @@ Core commands:
 Global flags:
   --api-base <url>   default: https://api.thirdfy.com
   --run-mode <mode>  thirdfy | self | hybrid
+  --custody-mode <mode>  managed | external
   --profile <name>   personal | builder | network
   --env <file>       load env vars from file
   --timeout <ms>     request timeout

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thirdfy/agent-cli",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "Thirdfy Agent CLI for onboarding, governance preflight, execute-intent, and status polling.",
   "type": "module",
   "bin": {
@@ -27,6 +27,7 @@
     "e2e:delegation:lifecycle": "node ./scripts/e2e/delegation-lifecycle.mjs",
     "e2e:delegation:commands": "node ./scripts/e2e/delegation-command-parity.mjs",
     "e2e:self:delegation:parity": "node ./scripts/e2e/self-delegation-parity.mjs",
+    "e2e:self:managed-custody-validation": "node ./scripts/e2e/self-managed-custody-validation.mjs",
     "e2e:managed:delegation:parity": "node ./scripts/e2e/managed-custodial-lifecycle.mjs",
     "e2e:delegation:prod:certify": "node ./scripts/e2e/prod-delegation-certify.mjs",
     "e2e:report:last": "node ./scripts/e2e/report-last.mjs",
@@ -53,6 +54,7 @@
   },
   "homepage": "https://github.com/thirdfy/agent-cli#readme",
   "dependencies": {
+    "@open-wallet-standard/core": "^1.3.0",
     "ethers": "^6.16.0"
   }
 }