@thirdfy/agent-cli 0.1.31 → 0.1.33

package/CHANGELOG.md

@@ -4,6 +4,27 @@ All notable changes to `@thirdfy/agent-cli` are documented here. The format is b
 
 ## [Unreleased]
 
+## [0.1.33] - 2026-05-12
+
+### Added
+
+- **Bitfinex CEX delegation:** Permission profiles for funding vs spot, `--permission-profile` on credential upsert, onboarding hints when credentials are missing from Thirdfy delegation context, and `get-bitfinex-ledgers-hist` read-check documentation.
+
+### Changed
+
+- **DogeOS provider discovery:** Tests and docs aligned with catalog-driven provider hints.
+
+## [0.1.32] - 2026-05-08
+
+### Added
+
+- **Earn partners (Vaults.fyi and Yield.xyz):** `thirdfy-agent actions --provider vaults-fyi|yield-xyz` returns catalog-aligned hints (`get_vaults_fyi_vaults` / `get_yield_xyz_opportunities`, generic Earn reads, `deposit_earn_position` / `withdraw_earn_position`). Provider inference and `--provider earn` filtering include these providers alongside Morpho and Curve.
+
+### Changed
+
+- Public docs (`docs/command-reference.md`, `docs/action-inventory-and-compatibility.md`, `docs/providers/index.md`) describe partner earn discovery and transaction-prep-first writes.
+- **`--provider earn` hints:** Umbrella `readActions` lists Morpho and Curve discovery actions (`get_morpho_vaults`, `get_curve_pools`) together with partner reads so Earn hints stay symmetric across sub-providers.
+
 ## [0.1.31] - 2026-05-07
 
 ### Fixed

package/bin/thirdfy-agent.mjs

@@ -19,9 +19,23 @@ 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 BITFINEX_PERMISSION_PROFILES = {
+  funding: {
+    id: 'funding',
+    credentialRef: 'bitfinex:funding-primary',
+    required: {
+      funding: { read: 1, write: 1 },
+      wallets: { read: 1, write: 0 },
+    },
+  },
+  spot: {
+    id: 'spot',
+    credentialRef: 'bitfinex:spot-primary',
+    required: {
+      orders: { read: 1, write: 1 },
+      wallets: { read: 1, write: 0 },
+    },
+  },
 };
 const RUN_MODES = ['thirdfy', 'self', 'hybrid', 'agent_wallet'];
 const HYBRID_WALLET_MODES = ['self', 'agent_wallet'];
@@ -79,15 +93,21 @@ main().catch((error) => {
 
 function buildTopLevelOnboardingHint(payload) {
   const reason = String(payload?.blockedReason || payload?.error || '').trim();
+  const permissionProfile = inferBitfinexPermissionProfileFromAction(
+    payload?.resolvedAction || payload?.action || payload?.requestedAction
+  );
   if (!reason) return null;
   if (
-    ['CEX_CREDENTIAL_NOT_FOUND', 'BITFINEX_CREDENTIALS_NOT_IN_CONTEXT', 'BITFINEX_ENV_CREDENTIALS_NOT_CONFIGURED'].includes(
-      reason
-    )
+    [
+      'CEX_CREDENTIAL_NOT_FOUND',
+      'BITFINEX_CREDENTIALS_NOT_IN_CONTEXT',
+      'BITFINEX_CREDENTIALS_NOT_IN_THIRDFY_DELEGATION_CONTEXT',
+      'BITFINEX_ENV_CREDENTIALS_NOT_CONFIGURED',
+    ].includes(reason)
   ) {
     return {
       type: 'bitfinex_credentials',
-      command: buildBitfinexOnboardingCommand(),
+      command: buildBitfinexOnboardingCommand(permissionProfile),
     };
   }
   return null;
@@ -530,10 +550,18 @@ function getTradingProviderHint(providerId) {
       category: 'earn',
       canonicalReadAction: 'get_earn_opportunities',
       canonicalWriteAction: 'deposit_earn_position',
-      readActions: ['get_earn_opportunities', 'get_earn_provider', 'get_earn_position'],
+      readActions: [
+        'get_earn_opportunities',
+        'get_earn_provider',
+        'get_earn_position',
+        'get_morpho_vaults',
+        'get_curve_pools',
+        'get_vaults_fyi_vaults',
+        'get_yield_xyz_opportunities',
+      ],
       orderManagementActions: ['deposit_earn_position', 'withdraw_earn_position'],
       laneCompatibility:
-        'Generic earn writes use deposit_earn_position / withdraw_earn_position on normal Thirdfy policy/delegation rails; routing selects Morpho vault calldata or the validated Curve Base 4pool adapter on Base (8453) per opportunity.',
+        'Generic earn writes use deposit_earn_position / withdraw_earn_position on normal Thirdfy policy/delegation rails; routing selects Morpho, Curve, Vaults.fyi, or Yield.xyz adapters per provider/opportunity.',
     };
   }
   if (provider === 'morpho') {
@@ -563,6 +591,34 @@ function getTradingProviderHint(providerId) {
         'Curve EVM writes are limited to the validated Base mainnet 4pool adapter; other pools remain discovery-only until per-pool calldata is validated.',
     };
   }
+  if (provider === 'vaults-fyi') {
+    return {
+      provider,
+      category: 'earn',
+      canonicalReadAction: 'get_vaults_fyi_vaults',
+      canonicalWriteAction: 'deposit_earn_position',
+      readActions: ['get_vaults_fyi_vaults', 'get_earn_opportunities', 'get_earn_provider', 'get_earn_position'],
+      orderManagementActions: ['deposit_earn_position', 'withdraw_earn_position'],
+      laneCompatibility:
+        'Vaults.fyi writes are transaction-prep first. Thirdfy validates partner payloads, chain/user context, and allowed targets before returning or submitting prepared calls.',
+      example:
+        'thirdfy-agent actions --provider vaults-fyi && thirdfy-agent preflight --action deposit_earn_position --params \'{"providerId":"vaults-fyi","opportunityId":"...","vaultAddress":"0x...","tokenAddress":"0x...","amount":"10","chainId":8453}\'',
+    };
+  }
+  if (provider === 'yield-xyz') {
+    return {
+      provider,
+      category: 'earn',
+      canonicalReadAction: 'get_yield_xyz_opportunities',
+      canonicalWriteAction: 'deposit_earn_position',
+      readActions: ['get_yield_xyz_opportunities', 'get_earn_opportunities', 'get_earn_provider', 'get_earn_position'],
+      orderManagementActions: ['deposit_earn_position', 'withdraw_earn_position'],
+      laneCompatibility:
+        'Yield.xyz writes are transaction-prep first. Thirdfy calls Yield.xyz directly and validates returned unsigned transactions with @yieldxyz/shield before signing or returning prepared calls.',
+      example:
+        'thirdfy-agent actions --provider yield-xyz && thirdfy-agent preflight --action deposit_earn_position --params \'{"providerId":"yield-xyz","opportunityId":"ethereum-eth-lido-staking","tokenAddress":"0x...","amount":"0.01","chainId":1}\'',
+    };
+  }
   return null;
 }
 
@@ -582,11 +638,15 @@ function getCachedProviderHintFromCapabilities(provider) {
     earn: 'deposit_earn_position',
     morpho: 'deposit_earn_position',
     curve: 'deposit_earn_position',
+    'vaults-fyi': 'deposit_earn_position',
+    'yield-xyz': 'deposit_earn_position',
   };
   const canonicalReadActions = {
     earn: 'get_earn_opportunities',
     morpho: 'get_morpho_vaults',
     curve: 'get_curve_pools',
+    'vaults-fyi': 'get_vaults_fyi_vaults',
+    'yield-xyz': 'get_yield_xyz_opportunities',
     prediction: 'get_prediction_markets',
   };
   return {
@@ -1565,12 +1625,17 @@ 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 permissionProfile = String(flags.permissionProfile || 'funding').trim().toLowerCase();
+  const bitfinexProfile =
+    String(venue).trim().toLowerCase() === 'bitfinex'
+      ? BITFINEX_PERMISSION_PROFILES[permissionProfile] || BITFINEX_PERMISSION_PROFILES.funding
+      : null;
   const payload = {
     venue,
     apiKey: requireFlag(flags, 'apiKey', 'Missing --api-key'),
     apiSecret: requireFlag(flags, 'apiSecret', 'Missing --api-secret'),
     credentialType: String(flags.credentialType || 'api_key'),
-    credentialRef: String(flags.credentialRef || ''),
+    credentialRef: String(flags.credentialRef || bitfinexProfile?.credentialRef || ''),
   };
   if (flags.passphrase) payload.passphrase = String(flags.passphrase);
   if (flags.metadata) payload.metadata = parseJsonFlag(flags, 'metadata');
@@ -1586,6 +1651,7 @@ async function commandCredentialsUpsert(ctx, flags, capabilities) {
     permissionProbe = await probeBitfinexPermissions({
       apiKey: payload.apiKey,
       apiSecret: payload.apiSecret,
+      permissionProfile: bitfinexProfile?.id || 'funding',
       timeoutMs: ctx.timeoutMs,
       baseUrl: String(flags.bitfinexBaseUrl || process.env.BITFINEX_BASE_URL || DEFAULT_BITFINEX_BASE_URL),
     });
@@ -2681,11 +2747,14 @@ function shouldUseBuildTxExecution(runMode, resolved) {
   return true;
 }
 
-function buildBitfinexOnboardingCommand() {
+function buildBitfinexOnboardingCommand(permissionProfile = 'funding') {
+  const profile = BITFINEX_PERMISSION_PROFILES[permissionProfile] || BITFINEX_PERMISSION_PROFILES.funding;
   return [
     'thirdfy-agent credentials upsert',
     '--auth-token "$THIRDFY_AUTH_TOKEN"',
     '--venue bitfinex',
+    `--permission-profile ${profile.id}`,
+    `--credential-ref ${profile.credentialRef}`,
     '--api-key "<BITFINEX_API_KEY>"',
     '--api-secret "<BITFINEX_API_SECRET>"',
     '--verify-permissions',
@@ -2693,6 +2762,15 @@ function buildBitfinexOnboardingCommand() {
   ].join(' ');
 }
 
+function inferBitfinexPermissionProfileFromAction(actionName) {
+  const action = String(actionName || '')
+    .trim()
+    .toLowerCase()
+    .replace(/[_\s]+/g, '-');
+  if (!action.includes('bitfinex')) return 'funding';
+  return action.includes('bitfinex-order') ? 'spot' : 'funding';
+}
+
 function applyExecutionFallbackHints(normalized, { flags, runMode, resolvedAction }) {
   if (!normalized || typeof normalized !== 'object') return normalized;
   const next = { ...normalized };
@@ -2705,9 +2783,11 @@ function applyExecutionFallbackHints(normalized, { flags, runMode, resolvedActio
   }
   const resolvedActionLower = String(resolvedAction || '').trim().toLowerCase();
   const looksBitfinexAction = resolvedActionLower.includes('bitfinex');
+  const permissionProfile = inferBitfinexPermissionProfileFromAction(resolvedActionLower);
   const cexCredentialMissingSignals = new Set([
     'CEX_CREDENTIAL_NOT_FOUND',
     'BITFINEX_CREDENTIALS_NOT_IN_CONTEXT',
+    'BITFINEX_CREDENTIALS_NOT_IN_THIRDFY_DELEGATION_CONTEXT',
     'BITFINEX_ENV_CREDENTIALS_NOT_CONFIGURED',
   ]);
   const hasMissingCredentialSignal = Array.from(reasons).some((code) => cexCredentialMissingSignals.has(code));
@@ -2716,7 +2796,7 @@ function applyExecutionFallbackHints(normalized, { flags, runMode, resolvedActio
       type: 'bitfinex_credentials',
       message:
         'Bitfinex credentials are missing for this delegated account. Onboard credentials first, then retry the same command.',
-      command: buildBitfinexOnboardingCommand(),
+      command: buildBitfinexOnboardingCommand(permissionProfile),
     };
   }
   if (
@@ -3434,6 +3514,9 @@ function inferActionProvider(action) {
     'get-curve-pool-details': 'curve',
     'deposit-curve-pool': 'curve',
     'withdraw-curve-pool': 'curve',
+    'get-vaults-fyi-vaults': 'vaults-fyi',
+    'get-vaults-fyi-opportunities': 'vaults-fyi',
+    'get-yield-xyz-opportunities': 'yield-xyz',
     'get-prediction-markets': 'polymarket',
     'get-prediction-market': 'polymarket',
     'get-prediction-order-book': 'polymarket',
@@ -3449,9 +3532,11 @@ function inferActionProvider(action) {
   if (knownMap[key]) return knownMap[key];
   if (key.includes('hyperliquid')) return 'hyperliquid';
   if (key.includes('polymarket') || key.includes('prediction')) return 'polymarket';
+  if (key.includes('vaults-fyi')) return 'vaults-fyi';
+  if (key.includes('yield-xyz')) return 'yield-xyz';
   if (key.includes('morpho')) return 'morpho';
   if (key.includes('curve')) return 'curve';
-  if (key.includes('earn')) return 'earn';
+  if (key.includes('earn') || key.includes('yield') || key.includes('vault')) return 'earn';
   if (key.includes('bridge')) return 'bridge';
   if (key.includes('dogeos-barkswap')) return 'dogeos-barkswap';
   if (key.includes('dogeos-laika')) return 'dogeos-laika';
@@ -3500,9 +3585,9 @@ function actionMatchesProvider(action, requestedProvider, allActions) {
   if (requestedProvider === 'bridge') return isProviderActionKey(action, 'bridge');
   if (requestedProvider.startsWith('dogeos')) return isProviderActionKey(action, requestedProvider);
   if (requestedProvider === 'earn') {
-    return provider === 'earn' || provider === 'morpho' || provider === 'curve' || isEarnCatalogAction(action);
+    return provider === 'earn' || provider === 'morpho' || provider === 'curve' || provider === 'vaults-fyi' || provider === 'yield-xyz' || isEarnCatalogAction(action);
   }
-  if (requestedProvider === 'morpho' || requestedProvider === 'curve') {
+  if (requestedProvider === 'morpho' || requestedProvider === 'curve' || requestedProvider === 'vaults-fyi' || requestedProvider === 'yield-xyz') {
     const hasProtocolSpecificEarnRows = allActions.some((candidate) => getActionProviderWithInference(candidate) === requestedProvider);
     return isProviderActionKey(action, requestedProvider) || (!hasProtocolSpecificEarnRows && isEarnCatalogAction(action));
   }
@@ -4015,9 +4100,10 @@ function parseBitfinexPermissionRows(rawData) {
   return parsed;
 }
 
-function getMissingBitfinexScopes(scopePermissions) {
+function getMissingBitfinexScopes(scopePermissions, permissionProfile = 'funding') {
+  const profile = BITFINEX_PERMISSION_PROFILES[permissionProfile] || BITFINEX_PERMISSION_PROFILES.funding;
   const missing = [];
-  for (const [scope, required] of Object.entries(BITFINEX_REQUIRED_SCOPE_PERMISSIONS)) {
+  for (const [scope, required] of Object.entries(profile.required)) {
     const actual = scopePermissions[scope] || { read: 0, write: 0 };
     if (actual.read < required.read || actual.write < required.write) {
       missing.push({
@@ -4030,7 +4116,7 @@ function getMissingBitfinexScopes(scopePermissions) {
   return missing;
 }
 
-async function probeBitfinexPermissions({ apiKey, apiSecret, timeoutMs, baseUrl }) {
+async function probeBitfinexPermissions({ apiKey, apiSecret, permissionProfile = 'funding', timeoutMs, baseUrl }) {
   const normalizedBaseUrl = String(baseUrl || DEFAULT_BITFINEX_BASE_URL).trim().replace(/\/+$/, '');
   const apiPath = '/v2/auth/r/permissions';
   const nonce = Date.now().toString();
@@ -4081,18 +4167,19 @@ async function probeBitfinexPermissions({ apiKey, apiSecret, timeoutMs, baseUrl
       );
     }
     const scopePermissions = parseBitfinexPermissionRows(parsed);
-    const missingScopes = getMissingBitfinexScopes(scopePermissions);
+    const missingScopes = getMissingBitfinexScopes(scopePermissions, permissionProfile);
     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 }
+          .join(', ')}). Enable the ${permissionProfile} profile scopes and retry onboarding.`,
+        { missingScopes, scopePermissions, permissionProfile }
       );
     }
     return {
       venue: 'bitfinex',
+      permissionProfile,
       checked: true,
       scopes: scopePermissions,
       missingScopes: [],
@@ -4156,7 +4243,7 @@ Core commands:
   thirdfy-agent wallet sign --agent-api-key <key> --action <id> --params <json> [--chain-id <id>] [--json]
   thirdfy-agent wallet submit --signed-tx-hex <hex> [--chain-id <id>] [--rpc-url <url>] [--json]
   thirdfy-agent agent run --agent-api-key <key> --action <id> --params <json> [--signer-method managed_wallet_server|byow|fanout_intent] [--strategy-intent single_wallet|fanout] [--run-mode <mode>] [--user-did <did>] [--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 upsert --auth-token <token> --venue <id> --api-key <key> --api-secret <secret> [--permission-profile funding|spot] [--credential-ref <ref>] [--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]

package/package.json

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