@thirdfy/agent-cli 0.1.9 → 0.1.11

package/CHANGELOG.md

@@ -4,6 +4,22 @@ 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)  
+**Git tag:** [`v0.1.9`](https://github.com/thirdfy/agent-cli/releases/tag/v0.1.9)
+
 ### Fixed
 
 - **Self preflight routing for swap-like actions:** `preflight --run-mode self` now selects the validation route by action capability. When an action advertises `supportsExecuteIntent=false` and `supportsBuildTx=true`, preflight uses `build-tx` directly instead of forcing execute-intent validation.

package/README.md

@@ -16,8 +16,13 @@ If you want the full developer docs, start here:
 - [API Reference home](https://docs.thirdfy.com/api)
 - [LLM docs map (llms.txt)](https://docs.thirdfy.com/llms.txt)
 - [LLM full API snapshot (llms-full.txt)](https://docs.thirdfy.com/llms-full.txt)
+- [Provider docs index (repo)](./docs/providers/index.md)
+- [Action inventory and compatibility](./docs/action-inventory-and-compatibility.md)
+- [Command reference](./docs/command-reference.md)
 - [DogeOS quickstart (repo)](./docs/dogeos-quickstart.md)
+- [Bitfinex CEX workflow (repo)](./docs/bitfinex-cex-workflow.md)
 - [Action onboarding standard](./docs/action-onboarding-standard.md)
+- [Provider docs governance model](./docs/provider-docs-governance.md)
 - [Skill integration RFC](./docs/skill-integration-rfc.md)
 
 ## Install
@@ -76,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
@@ -131,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:
 
@@ -215,6 +227,14 @@ Jeff-friendly aliases map directly to core commands:
 - `thirdfy-agent jeff status --intent-id ...` -> alias of `intent-status`
 - `thirdfy-agent prompt "<text>"` -> captures prompt intent and suggests deterministic execution commands
 
+## Provider-specific workflows
+
+Provider and venue guides are kept outside `README` so this page stays stable as integrations grow.
+
+- Provider index: [`docs/providers/index.md`](./docs/providers/index.md)
+- Bitfinex runbook: [`docs/providers/bitfinex.md`](./docs/providers/bitfinex.md)
+- DogeOS runbook: [`docs/providers/dogeos.md`](./docs/providers/dogeos.md)
+
 ## Command groups
 
 - Discovery: `catalogs list`, `actions`
@@ -226,6 +246,12 @@ Jeff-friendly aliases map directly to core commands:
 - Delegation execution helpers: `delegation balance`, `delegation redeem`
 - Account: `credits balance`
 
+## Where to find what is supported
+
+- Full command groups and usage map: [`docs/command-reference.md`](./docs/command-reference.md)
+- Live action inventory in your environment: [`docs/action-inventory-and-compatibility.md`](./docs/action-inventory-and-compatibility.md)
+- Provider runbooks and provider status: [`docs/providers/index.md`](./docs/providers/index.md)
+
 ## Delegation lifecycle (canonical)
 
 Use `create` + `activate` as the default delegated execution lifecycle:
@@ -325,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

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { randomUUID } from 'crypto';
+import { createHmac, randomUUID } from 'crypto';
 import { spawnSync } from 'child_process';
 import fs from 'fs';
 import os from 'os';
@@ -18,7 +18,13 @@ const {
 const DEFAULT_API_BASE = 'https://api.thirdfy.com';
 const DEFAULT_TIMEOUT_MS = 30000;
 const DEFAULT_CATALOG_CACHE_TTL_MS = 60_000;
+const DEFAULT_BITFINEX_BASE_URL = 'https://api.bitfinex.com';
+const BITFINEX_REQUIRED_SCOPE_PERMISSIONS = {
+  funding: { read: 1, write: 1 },
+  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',
@@ -52,6 +58,7 @@ main().catch((error) => {
   const payload = error?.payload && typeof error.payload === 'object' ? error.payload : {};
   const blockedReason = String(payload.blockedReason || payload.error || '').trim() || undefined;
   const blockedStage = String(payload.blockedStage || '').trim() || undefined;
+  const onboardingHint = buildTopLevelOnboardingHint(payload);
   printEnvelope({
     success: false,
     code: statusCode ? 'API_REQUEST_FAILED' : 'CLI_UNHANDLED_ERROR',
@@ -60,6 +67,7 @@ main().catch((error) => {
       statusCode,
       blockedReason,
       blockedStage,
+      onboardingHint,
       payload,
     },
     meta: { version: CLI_VERSION, apiBase: context.apiBase },
@@ -67,10 +75,27 @@ main().catch((error) => {
   process.exit(1);
 });
 
+function buildTopLevelOnboardingHint(payload) {
+  const reason = String(payload?.blockedReason || payload?.error || '').trim();
+  if (!reason) return null;
+  if (
+    ['CEX_CREDENTIAL_NOT_FOUND', 'BITFINEX_CREDENTIALS_NOT_IN_CONTEXT', 'BITFINEX_ENV_CREDENTIALS_NOT_CONFIGURED'].includes(
+      reason
+    )
+  ) {
+    return {
+      type: 'bitfinex_credentials',
+      command: buildBitfinexOnboardingCommand(),
+    };
+  }
+  return null;
+}
+
 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) {
@@ -518,10 +543,15 @@ async function commandPreflight(ctx, flags, capabilities) {
   const runMode = getEffectiveRunMode(ctx, flags);
   enforceChainCompatibility(capabilities, flags, runMode);
   const backendResult = await runPreflightByMode(runMode, ctx, flags, resolved);
-  const normalized = backendResult.normalized;
+  const normalized = applyExecutionFallbackHints(backendResult.normalized, {
+    flags,
+    runMode,
+    resolvedAction: resolved.resolvedAction,
+  });
+  const preflightBlocked = !normalized.success && Boolean(normalized.preflightBlocked);
   printEnvelope({
     success: normalized.success,
-    code: normalized.success ? 'PREFLIGHT_OK' : 'PREFLIGHT_FAILED',
+    code: normalized.success ? 'PREFLIGHT_OK' : preflightBlocked ? 'PREFLIGHT_BLOCKED' : 'PREFLIGHT_FAILED',
     message: backendResult.message,
     data: normalized,
     meta: {
@@ -548,7 +578,11 @@ async function commandRun(ctx, flags, capabilities) {
   const backendResult = await runExecutionByMode(runMode, ctx, flags, resolved, {
     skipPreflight,
   });
-  const normalized = backendResult.normalized;
+  const normalized = applyExecutionFallbackHints(backendResult.normalized, {
+    flags,
+    runMode,
+    resolvedAction: resolved.resolvedAction,
+  });
   if (runMode === 'self' && parseBooleanFlag(flags.broadcast, false) && normalized?.success) {
     const executed = await performSelfBroadcast(ctx, flags, resolved.resolvedAction, normalized);
     printEnvelope({
@@ -925,8 +959,9 @@ async function commandDelegationRedeem(ctx, flags, capabilities) {
 
 async function commandCredentialsUpsert(ctx, flags, capabilities) {
   const authToken = getAuthToken(flags, 'Missing --auth-token (or THIRDFY_AUTH_TOKEN) for credentials upsert');
+  const venue = requireFlag(flags, 'venue', 'Missing --venue');
   const payload = {
-    venue: requireFlag(flags, 'venue', 'Missing --venue'),
+    venue,
     apiKey: requireFlag(flags, 'apiKey', 'Missing --api-key'),
     apiSecret: requireFlag(flags, 'apiSecret', 'Missing --api-secret'),
     credentialType: String(flags.credentialType || 'api_key'),
@@ -937,6 +972,19 @@ async function commandCredentialsUpsert(ctx, flags, capabilities) {
   if (flags.policy) payload.policy = parseJsonFlag(flags, 'policy');
   if (flags.agentKey) payload.agentKey = String(flags.agentKey).trim();
   if (flags.chainId) payload.chainId = Number(flags.chainId);
+  const probeEnabled =
+    String(venue).trim().toLowerCase() === 'bitfinex' &&
+    !parseBooleanFlag(flags.skipPermissionsProbe, false) &&
+    parseBooleanFlag(flags.verifyPermissions, true);
+  let permissionProbe = null;
+  if (probeEnabled) {
+    permissionProbe = await probeBitfinexPermissions({
+      apiKey: payload.apiKey,
+      apiSecret: payload.apiSecret,
+      timeoutMs: ctx.timeoutMs,
+      baseUrl: String(flags.bitfinexBaseUrl || process.env.BITFINEX_BASE_URL || DEFAULT_BITFINEX_BASE_URL),
+    });
+  }
 
   const response = await requestWithRouteFallback(ctx, {
     method: 'POST',
@@ -953,6 +1001,7 @@ async function commandCredentialsUpsert(ctx, flags, capabilities) {
     data: response,
     meta: {
       apiBase: ctx.apiBase,
+      permissionProbe,
       capabilitiesVersion: capabilities?.contractVersion || null,
     },
   });
@@ -1354,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',
@@ -1368,6 +1420,7 @@ async function commandProfileInit(ctx, flags) {
     data: {
       profile,
       runMode,
+      custodyMode,
       configPath: getProfileConfigPath(),
     },
     meta: { apiBase: ctx.apiBase },
@@ -1379,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',
@@ -1393,6 +1449,7 @@ async function commandProfileUse(ctx, flags) {
     data: {
       profile,
       runMode,
+      custodyMode,
       defaults: PROFILE_DEFAULTS,
       configPath: getProfileConfigPath(),
     },
@@ -1409,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,
@@ -1431,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);
@@ -1452,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) {
@@ -1482,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(),
@@ -1500,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);
@@ -1511,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 },
@@ -1575,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(),
   };
 }
@@ -1595,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') {
@@ -1711,6 +1835,66 @@ function enforceChainCompatibility(capabilities, flags, runMode) {
   }
 }
 
+function shouldUseBuildTxExecution(runMode, resolved) {
+  if (runMode !== 'self' && runMode !== 'hybrid') return false;
+  const meta = resolved?.resolvedActionMeta || null;
+  if (!meta || typeof meta !== 'object') return true;
+  if (meta.supportsBuildTx === false) return false;
+  return true;
+}
+
+function buildBitfinexOnboardingCommand() {
+  return [
+    'thirdfy-agent credentials upsert',
+    '--auth-token "$THIRDFY_AUTH_TOKEN"',
+    '--venue bitfinex',
+    '--api-key "<BITFINEX_API_KEY>"',
+    '--api-secret "<BITFINEX_API_SECRET>"',
+    '--verify-permissions',
+    '--json',
+  ].join(' ');
+}
+
+function applyExecutionFallbackHints(normalized, { flags, runMode, resolvedAction }) {
+  if (!normalized || typeof normalized !== 'object') return normalized;
+  const next = { ...normalized };
+  const reasons = new Set();
+  const topBlockedReason = String(next.blockedReason || '').trim();
+  if (topBlockedReason) reasons.add(topBlockedReason);
+  const blockedByReason = next.blockedByReason && typeof next.blockedByReason === 'object' ? next.blockedByReason : {};
+  for (const key of Object.keys(blockedByReason)) {
+    if (String(key || '').trim()) reasons.add(String(key).trim());
+  }
+  const resolvedActionLower = String(resolvedAction || '').trim().toLowerCase();
+  const looksBitfinexAction = resolvedActionLower.includes('bitfinex');
+  const cexCredentialMissingSignals = new Set([
+    'CEX_CREDENTIAL_NOT_FOUND',
+    'BITFINEX_CREDENTIALS_NOT_IN_CONTEXT',
+    'BITFINEX_ENV_CREDENTIALS_NOT_CONFIGURED',
+  ]);
+  const hasMissingCredentialSignal = Array.from(reasons).some((code) => cexCredentialMissingSignals.has(code));
+  if (looksBitfinexAction && hasMissingCredentialSignal) {
+    next.onboardingHint = {
+      type: 'bitfinex_credentials',
+      message:
+        'Bitfinex credentials are missing for this delegated account. Onboard credentials first, then retry the same command.',
+      command: buildBitfinexOnboardingCommand(),
+    };
+  }
+  if (
+    looksBitfinexAction &&
+    runMode !== 'thirdfy' &&
+    (topBlockedReason === 'SELF_MODE_REQUIRES_BUILD_TX' || topBlockedReason === 'HYBRID_MODE_REQUIRES_BUILD_TX')
+  ) {
+    next.onboardingHint = {
+      ...(next.onboardingHint || {}),
+      runMode: 'thirdfy',
+      runModeMessage: 'Bitfinex actions require delegated execute-intent rail. Re-run with --run-mode thirdfy.',
+    };
+  }
+  return next;
+}
+
 function shouldUseBuildTxPreflight(runMode, resolved) {
   if (runMode !== 'self') return false;
   const meta = resolved?.resolvedActionMeta || null;
@@ -1725,7 +1909,7 @@ async function runPreflightByMode(runMode, ctx, flags, resolved) {
     const normalized = await executeSelfRun(
       ctx,
       flags,
-      { resolvedAction },
+      resolved,
       { skipPreflight: route === 'build_tx' }
     );
     const blockedByGovernance = !normalized.success && Boolean(normalized.preflightBlocked);
@@ -1843,6 +2027,7 @@ async function executeThirdfyRun(ctx, flags, resolved, options) {
 
 async function executeSelfRun(ctx, flags, resolved, options) {
   const skipPreflight = Boolean(options?.skipPreflight);
+  const blockedReasonCode = String(options?.blockedReasonCode || 'SELF_MODE_REQUIRES_BUILD_TX');
   if (!skipPreflight) {
     const preflightPayload = buildIntentPayload(flags, {
       validationOnly: true,
@@ -1861,6 +2046,17 @@ async function executeSelfRun(ctx, flags, resolved, options) {
       return preflightNormalized;
     }
   }
+  if (!shouldUseBuildTxExecution(options?.runMode || 'self', resolved)) {
+    const normalized = normalizeIntentResponse({
+      success: false,
+      status: 'failed',
+      blockedReason: blockedReasonCode,
+      blockedStage: 'routing',
+      error: 'Selected action does not support build-tx self lane. Use --run-mode thirdfy for delegated CEX execution.',
+    });
+    normalized.preflightBlocked = true;
+    return normalized;
+  }
   const buildTxPayload = buildBuildTxPayload(flags, resolved.resolvedAction);
   const buildTx = await apiPost(ctx, '/api/v1/agent/build-tx', buildTxPayload);
   return normalizeIntentResponse({
@@ -1873,7 +2069,11 @@ async function executeSelfRun(ctx, flags, resolved, options) {
 }
 
 async function executeHybridRun(ctx, flags, resolved, options) {
-  const selfResult = await executeSelfRun(ctx, flags, resolved, options);
+  const selfResult = await executeSelfRun(ctx, flags, resolved, {
+    ...(options || {}),
+    runMode: 'hybrid',
+    blockedReasonCode: 'HYBRID_MODE_REQUIRES_BUILD_TX',
+  });
   if (!selfResult.success) return selfResult;
 
   const mirrorPayload = buildIntentPayload(flags, {
@@ -2454,6 +2654,114 @@ function safeJsonParse(text) {
   }
 }
 
+function parseBitfinexPermissionRows(rawData) {
+  const rows = Array.isArray(rawData) ? rawData : [];
+  const parsed = {};
+  for (const row of rows) {
+    if (!Array.isArray(row) || row.length < 3) continue;
+    const scope = String(row[0] || '').trim().toLowerCase();
+    if (!scope) continue;
+    const read = Number(row[1]) === 1 ? 1 : 0;
+    const write = Number(row[2]) === 1 ? 1 : 0;
+    parsed[scope] = { read, write };
+  }
+  return parsed;
+}
+
+function getMissingBitfinexScopes(scopePermissions) {
+  const missing = [];
+  for (const [scope, required] of Object.entries(BITFINEX_REQUIRED_SCOPE_PERMISSIONS)) {
+    const actual = scopePermissions[scope] || { read: 0, write: 0 };
+    if (actual.read < required.read || actual.write < required.write) {
+      missing.push({
+        scope,
+        required,
+        actual,
+      });
+    }
+  }
+  return missing;
+}
+
+async function probeBitfinexPermissions({ apiKey, apiSecret, timeoutMs, baseUrl }) {
+  const normalizedBaseUrl = String(baseUrl || DEFAULT_BITFINEX_BASE_URL).trim().replace(/\/+$/, '');
+  const apiPath = '/v2/auth/r/permissions';
+  const nonce = Date.now().toString();
+  const payload = '{}';
+  const signature = createHmac('sha384', String(apiSecret || ''))
+    .update(`/api${apiPath}${nonce}${payload}`)
+    .digest('hex');
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), Number(timeoutMs || DEFAULT_TIMEOUT_MS));
+  try {
+    const response = await fetch(`${normalizedBaseUrl}${apiPath}`, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        'bfx-apikey': String(apiKey || ''),
+        'bfx-nonce': nonce,
+        'bfx-signature': signature,
+      },
+      body: payload,
+      signal: controller.signal,
+    });
+    const text = await response.text();
+    const parsed = text ? safeJsonParse(text) : {};
+    const bitfinexApiError =
+      Array.isArray(parsed) && String(parsed[0] || '').trim().toLowerCase() === 'error'
+        ? {
+            code: Number(parsed[1]) || null,
+            message: String(parsed[2] || 'Unknown Bitfinex API error'),
+          }
+        : parsed && typeof parsed === 'object' && String(parsed.event || '').trim().toLowerCase() === 'error'
+          ? {
+              code: Number(parsed.code) || null,
+              message: String(parsed.msg || parsed.message || 'Unknown Bitfinex API error'),
+            }
+          : null;
+    if (!response.ok) {
+      throw createCliError(
+        'BITFINEX_PERMISSIONS_PROBE_FAILED',
+        `Bitfinex permissions probe failed with HTTP ${response.status}. Verify API key/secret and key validity before onboarding.`,
+        { statusCode: response.status }
+      );
+    }
+    if (bitfinexApiError) {
+      throw createCliError(
+        'BITFINEX_PERMISSIONS_PROBE_FAILED',
+        `Bitfinex permissions probe failed: ${bitfinexApiError.message}. Verify API key/secret and key validity before onboarding.`,
+        { statusCode: response.status, bitfinexApiError }
+      );
+    }
+    const scopePermissions = parseBitfinexPermissionRows(parsed);
+    const missingScopes = getMissingBitfinexScopes(scopePermissions);
+    if (missingScopes.length > 0) {
+      throw createCliError(
+        'BITFINEX_PERMISSION_SCOPE_MISSING',
+        `Bitfinex key is missing required scopes (${missingScopes
+          .map((entry) => entry.scope)
+          .join(', ')}). Enable funding+wallets read/write and retry onboarding.`,
+        { missingScopes, scopePermissions }
+      );
+    }
+    return {
+      venue: 'bitfinex',
+      checked: true,
+      scopes: scopePermissions,
+      missingScopes: [],
+    };
+  } catch (error) {
+    if (error?.payload) throw error;
+    throw createCliError(
+      'BITFINEX_PERMISSIONS_PROBE_FAILED',
+      `Could not verify Bitfinex key permissions. ${String(error?.message || 'Unknown probe error')}`,
+      {}
+    );
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 function printEnvelope(payload) {
   if (jsonMode) {
     process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
@@ -2469,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]
@@ -2491,7 +2799,7 @@ Core commands:
   thirdfy-agent managed wallet init [--auth-token <token> | --owner-session-token <token>] [--chain-id <id>] [--json]
   thirdfy-agent managed wallet grant [--auth-token <token> | --owner-session-token <token>] --agent-key <key> --token-address <addr> --max-usd-per-day <usd> [--chain-id <id>] [--period-duration <sec>] [--expiry-seconds <sec>] [--json]
   thirdfy-agent managed run --agent-api-key <key> --action <id> --params <json> [--run-mode thirdfy|hybrid] [--idempotency-key <key>] [--json]
-  thirdfy-agent credentials upsert --auth-token <token> --venue <id> --api-key <key> --api-secret <secret> [--json]
+  thirdfy-agent credentials upsert --auth-token <token> --venue <id> --api-key <key> --api-secret <secret> [--verify-permissions] [--skip-permissions-probe] [--bitfinex-base-url <url>] [--json]
   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]
@@ -2513,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.9",
+  "version": "0.1.11",
   "description": "Thirdfy Agent CLI for onboarding, governance preflight, execute-intent, and status polling.",
   "type": "module",
   "bin": {
@@ -18,6 +18,7 @@
   "scripts": {
     "test": "node --test \"test/**/*.test.cjs\"",
     "lint": "node --check ./bin/thirdfy-agent.mjs",
+    "validate:public-docs": "node ./scripts/validate-public-docs.mjs",
     "validate:cli-contract-schemas": "node ./scripts/validate-cli-contract-schemas.mjs",
     "validate:actions": "node ./scripts/e2e/validate-actions.mjs",
     "e2e:base:simulate": "node ./scripts/e2e/base-simulate.mjs",
@@ -26,11 +27,12 @@
     "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",
     "smoke:cli": "node ./bin/thirdfy-agent.mjs --help && node ./bin/thirdfy-agent.mjs --version --json",
-    "prepublishOnly": "npm run validate:cli-contract-schemas && npm run test && npm run smoke:cli"
+    "prepublishOnly": "npm run validate:public-docs && npm run validate:cli-contract-schemas && npm run test && npm run smoke:cli"
   },
   "keywords": [
     "thirdfy",
@@ -52,6 +54,7 @@
   },
   "homepage": "https://github.com/thirdfy/agent-cli#readme",
   "dependencies": {
+    "@open-wallet-standard/core": "^1.3.0",
     "ethers": "^6.16.0"
   }
 }

package/src/utils/cli/intentNormalization.cjs

@@ -33,6 +33,7 @@ function normalizeIntentResponse(response) {
   const topLevelGovernanceSignal = String(response?.governanceSignal || '').trim() || null;
   const topLevelDelegationSignal = String(response?.delegationSignal || '').trim() || null;
   const policyEvaluated = response?.policyEvaluated === true;
+  const preflightBlocked = response?.preflightBlocked === true;
   return {
     success,
     status: response?.status || (success ? 'queued' : 'failed'),
@@ -48,6 +49,7 @@ function normalizeIntentResponse(response) {
     governanceSignal: topLevelGovernanceSignal,
     delegationSignal: topLevelDelegationSignal,
     policyEvaluated,
+    preflightBlocked,
     error: response?.error || null,
     mode: response?.mode || null,
     unsignedTx: response?.unsignedTx || null,