@thirdfy/agent-cli 0.1.48 → 0.2.2

package/src/runtime/providerHints.mjs

@@ -0,0 +1,414 @@
+/**
+ * Static and capabilities-backed provider discovery hints for CLI actions filtering.
+ */
+export function createProviderHints({ getNegotiatedCapabilitiesCache }) {
+  function getTradingProviderHint(providerId) {
+    const provider = String(providerId || '').trim().toLowerCase();
+    const manifestHint = getCachedProviderHintFromCapabilities(provider);
+    if (manifestHint) return manifestHint;
+    if (provider === 'trading') {
+      return {
+        provider,
+        category: 'onchain_spot',
+        canonicalWriteAction: 'swap',
+        supportedChains: [1, 10, 130, 137, 8453, 84532, 42161],
+        laneCompatibility:
+          'Kyber quote/build is live on Ethereum, Optimism, Unichain, Polygon, Base, and Arbitrum; sponsored Kyber execution is validated on Base only. Gnosis FX uses the fx provider via CoW.',
+        credentialUx: 'Use normal Thirdfy login/delegation; do not use this provider for Hyperliquid or Polymarket.',
+      };
+    }
+    if (provider === 'hyperliquid') {
+      return {
+        provider,
+        category: 'leveraged_perps',
+        canonicalWriteAction: 'place_hyperliquid_perps_order',
+        readActions: [
+          'get_hyperliquid_perps_meta',
+          'get_hyperliquid_all_mids',
+          'search_hyperliquid_markets',
+          'get_hyperliquid_l2_book',
+          'get_hyperliquid_candles',
+          'get_hyperliquid_user_state',
+          'get_hyperliquid_open_orders',
+          'get_hyperliquid_funding_status',
+          'get_hyperliquid_onboarding_plan',
+          'get_hyperliquid_referral_status',
+          'get_hyperliquid_builder_fee_status',
+        ],
+        orderManagementActions: [
+          'place_hyperliquid_perps_order',
+          'cancel_hyperliquid_perps_order',
+          'get_hyperliquid_open_orders',
+        ],
+        setupActions: [
+          'get_hyperliquid_funding_status',
+          'get_hyperliquid_setup_status',
+          'get_hyperliquid_onboarding_plan',
+          'prepare_hyperliquid_onboarding',
+          'get_bridge_quote',
+          'execute_bridge',
+          'approve_hyperliquid_agent',
+          'get_hyperliquid_builder_fee_status',
+          'approve_hyperliquid_builder_fee',
+          'set_hyperliquid_referrer',
+          'deposit_hyperliquid_bridge',
+          'deposit_hyperliquid_staking',
+          'claim_hyperliquid_testnet_faucet',
+        ],
+        statusActions: [
+          'get_hyperliquid_funding_status',
+          'get_hyperliquid_setup_status',
+          'get_hyperliquid_builder_fee_status',
+          'get_hyperliquid_referral_status',
+        ],
+        credentialType: 'hyperliquid_api_wallet',
+        credentialUx:
+          'Thirdfy manages Hyperliquid API-wallet setup for normal users. Delegated writes require encrypted privateKey-backed hyperliquid_api_wallet credentials; walletAddress-only records are rejected until Privy walletId-backed Hyperliquid signing ships.',
+        recommendedFundingChainId: 42161,
+        supportedFundingSourceChains: [
+          { chainId: 42161, name: 'Arbitrum One', path: 'native USDC -> Bridge2' },
+          { chainId: 8453, name: 'Base', path: 'Li.Fi -> Arbitrum native USDC -> Bridge2' },
+          { chainId: 1, name: 'Ethereum', path: 'Li.Fi -> Arbitrum native USDC -> Bridge2' },
+          { chainId: 137, name: 'Polygon', path: 'Li.Fi -> Arbitrum native USDC -> Bridge2' },
+        ],
+        setupBlockers: [
+          'HYPERLIQUID_SOURCE_FUNDS_REQUIRED',
+          'HYPERLIQUID_ARBITRUM_USDC_REQUIRED',
+          'HYPERLIQUID_BRIDGE2_DEPOSIT_REQUIRED',
+          'HYPERLIQUID_API_WALLET_APPROVAL_REQUIRED',
+          'HYPERLIQUID_BUILDER_APPROVAL_REQUIRED',
+          'HYPERLIQUID_POLICY_REQUIRED',
+          'HYPERLIQUID_CREDITS_REQUIRED',
+          'HYPERLIQUID_API_WALLET_SIGNER_REQUIRED',
+        ],
+        sourceBridgeProvider: 'lifi',
+        funding:
+          'Best path: Base/Ethereum/Polygon USDC -> Li.Fi bridge to native Arbitrum USDC -> Hyperliquid Bridge2. If the user already has native Circle USDC on Arbitrum One (42161), skip Li.Fi and call deposit_hyperliquid_bridge. Minimum 5 USDC; Bridge2 credits the sender/source wallet.',
+        laneCompatibility:
+          'Use self only for setup signatures or Arbitrum funding transactions. Perps orders should use thirdfy, hybrid, or agent_wallet.',
+        setupExample:
+          'actions --provider hyperliquid -> search_hyperliquid_markets (or get_hyperliquid_perps_meta + get_hyperliquid_all_mids) -> get_hyperliquid_funding_status -> get_hyperliquid_onboarding_plan -> prepare_hyperliquid_onboarding -> get_bridge_quote/execute_bridge if source is Base -> deposit_hyperliquid_bridge on 42161 -> approve_hyperliquid_agent -> approve_hyperliquid_builder_fee if required -> get_hyperliquid_setup_status',
+        example:
+          'thirdfy-agent actions --provider hyperliquid && thirdfy-agent preflight --action place_hyperliquid_perps_order --params \'{"coin":"ETH","isBuy":true,"size":0.01,"limitPx":3500,"orderType":"market"}\'',
+      };
+    }
+    if (provider === 'bitfinex') {
+      return {
+        provider,
+        category: 'cex_funding',
+        canonicalReadAction: 'get_bitfinex_funding_ticker',
+        canonicalWriteAction: 'submit_bitfinex_funding_offer',
+        readActions: [
+          'get_bitfinex_funding_ticker',
+          'get_bitfinex_funding_stats_hist',
+          'get_bitfinex_funding_book',
+          'get_bitfinex_funding_info',
+          'get_bitfinex_wallets',
+          'list_bitfinex_funding_offers',
+          'list_bitfinex_funding_credits',
+        ],
+        orderManagementActions: [
+          'submit_bitfinex_funding_offer',
+          'cancel_bitfinex_funding_offer',
+          'submit_bitfinex_order',
+          'update_bitfinex_order',
+          'cancel_bitfinex_order',
+        ],
+        credentialType: 'bitfinex_api_key',
+        credentialRef: 'bitfinex:funding-primary',
+        credentialUx:
+          'Save and verify Bitfinex funding credentials in EarnClaw/Thirdfy first. MCP/CLI order intents reference credentialRef only; raw keys are never sent through agentRun.',
+        laneCompatibility:
+          'Bitfinex CEX writes require thirdfy, hybrid, or agent_wallet so Thirdfy can inject stored credentials and run policy/preflight. Reads and setup discovery can be listed without raw credentials.',
+        example:
+          'thirdfy-agent actions --provider bitfinex && thirdfy-agent run --run-mode thirdfy --action submit_bitfinex_funding_offer --params \'{"symbol":"fUSD","amount":"100","rate":"0.0002","period":2,"credentialRef":"bitfinex:funding-primary"}\'',
+      };
+    }
+    if (provider === 'polymarket') {
+      return {
+        provider,
+        category: 'prediction_market',
+        canonicalWriteAction: 'place_polymarket_order',
+        readActions: [
+          'get_polymarket_tags',
+          'search_polymarket',
+          'get_polymarket_events',
+          'get_polymarket_event',
+          'get_polymarket_markets',
+          'get_polymarket_market',
+          'get_polymarket_order_book',
+          'get_polymarket_prices',
+          'get_polymarket_price_history',
+          'get_polymarket_setup_status',
+          'get_polymarket_onboarding_plan',
+          'get_polymarket_order',
+          'get_polymarket_user_orders',
+        ],
+        discoveryFlow: [
+          'get_polymarket_tags or search_polymarket',
+          'get_polymarket_events active=true closed=false',
+          'get_polymarket_market or get_polymarket_markets',
+          'get_polymarket_order_book',
+          'get_polymarket_prices or get_polymarket_price_history',
+          'get_polymarket_setup_status and get_polymarket_onboarding_plan before place_polymarket_order',
+        ],
+        orderManagementActions: [
+          'place_polymarket_order',
+          'get_polymarket_order',
+          'get_polymarket_user_orders',
+          'cancel_polymarket_order',
+        ],
+        setupActions: [
+          'get_polymarket_setup_status',
+          'get_polymarket_onboarding_plan',
+          'agent_wallet_setup:ensure_agent_wallet_deposit_wallet',
+          'agent_wallet_setup:deploy_deposit_wallet_and_set_approvals',
+          'agent_wallet_setup:create_or_derive_clob_credentials',
+          'browser_setup:add_privy_signer',
+          'browser_setup:create_or_derive_clob_credentials',
+          'browser_setup:deploy_deposit_wallet_and_set_approvals',
+        ],
+        statusActions: ['get_polymarket_setup_status'],
+        credentialType: 'polymarket_clob',
+        credentialUx:
+          'Autonomous agents use an agent-owned Privy wallet and Polymarket deposit wallet first: Thirdfy creates the agent wallet, deploys/approves the deposit wallet, and stores encrypted CLOB credentials once Polymarket key creation is available. User-owned browser setup remains optional for interactive capital.',
+        funding:
+          'Fund the agent-owned Polymarket deposit wallet with Polygon pUSD after deployment and approvals. If users start with Base USDC, route Base USDC -> Polygon pUSD to the deposit wallet recipient before CLOB order placement.',
+        laneCompatibility:
+          'Use agent_wallet as the preferred autonomous-agent path. Use self only for user-owned setup/funding signatures. CLOB orders should use thirdfy, hybrid, or agent_wallet after polymarket_clob credentials are stored.',
+        setupBlockers: [
+          'POLYMARKET_DEPOSIT_WALLET_REQUIRED',
+          'POLYMARKET_CLOB_CREDENTIALS_REQUIRED',
+          'POLYMARKET_DEPOSIT_WALLET_DEPLOY_REQUIRED',
+          'POLYMARKET_DEPOSIT_WALLET_APPROVALS_REQUIRED',
+          'POLYMARKET_DEPOSIT_WALLET_PUSD_REQUIRED',
+          'POLYMARKET_CREDITS_REQUIRED',
+          'POLYMARKET_RELAYER_UNAVAILABLE',
+          'POLYMARKET_CLOB_KEY_CREATION_BLOCKED_UNTIL_POLYMARKET_FIX',
+        ],
+        example:
+          'thirdfy-agent actions --provider polymarket && thirdfy-agent preflight --action place_polymarket_order --params \'{"tokenID":"...","price":0.42,"size":10,"side":"BUY"}\'',
+      };
+    }
+    if (provider === 'prediction') {
+      return {
+        provider,
+        category: 'prediction',
+        canonicalWriteAction: 'place_prediction_order',
+        readActions: [
+          'get_prediction_tags',
+          'search_prediction_markets',
+          'get_prediction_events',
+          'get_prediction_markets',
+          'get_prediction_market',
+          'get_prediction_order_book',
+        ],
+        orderManagementActions: ['place_prediction_order', 'cancel_prediction_order'],
+        compatibilityProvider: 'polymarket',
+      };
+    }
+    if (provider === 'bridge') {
+      return {
+        provider,
+        category: 'bridge',
+        canonicalReadAction: 'get_bridge_quote',
+        canonicalWriteAction: 'execute_bridge',
+        readActions: ['get_bridge_quote', 'get_supported_bridge_chains', 'check_bridge_status'],
+        orderManagementActions: ['execute_bridge'],
+        supportedChains: [1, 8453, 42161, 10, 137, 56, 43114, 250, 100, 1284, 1285, 25, 288, 1088, 42220, 122, 324, 59144, 534352, 5000, 81457, 169],
+        laneCompatibility: 'Li.Fi bridge supports mainnet value movement only; testnets are not auto-mapped to mainnet.',
+      };
+    }
+    if (provider === 'earn') {
+      return {
+        provider,
+        category: 'earn',
+        canonicalReadAction: 'get_earn_opportunities',
+        canonicalWriteAction: 'deposit_earn_position',
+        readActions: [
+          'get_earn_opportunities',
+          'get_earn_provider',
+          'get_earn_position',
+          'get_morpho_vaults',
+          'get_aegis_pools',
+          'get_aegis_pool_state',
+          'get_aegis_vault_state',
+          '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, Curve, Vaults.fyi, or Yield.xyz adapters per provider/opportunity.',
+      };
+    }
+    if (provider === 'capyfi') {
+      return {
+        provider,
+        category: 'earn',
+        canonicalReadAction: 'get_capyfi_markets',
+        canonicalWriteAction: 'deposit_earn_position',
+        readActions: ['get_capyfi_markets', 'get_earn_opportunities', 'get_earn_position'],
+        orderManagementActions: ['deposit_earn_position', 'withdraw_earn_position'],
+        supportedChains: [1, 480],
+        laneCompatibility: 'CapyFi Compound-v2 supply on Ethereum and World Chain; Gnosis pending deployment addresses.',
+        example:
+          'thirdfy-agent run --action deposit_earn_position --params \'{"providerId":"capyfi","opportunityId":"capyfi-1-usdc","amount":"100","chainId":1,"tokenAddress":"0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48"}\'',
+      };
+    }
+    if (provider === 'fx') {
+      return {
+        provider,
+        category: 'fx',
+        canonicalReadAction: 'get_fx_supported_assets',
+        readActions: ['get_fx_supported_assets', 'quote_fx_swap', 'get_monerium_profile_status'],
+        supportedChains: [100],
+        laneCompatibility:
+          'Gnosis FX: quote_fx_swap is read-only; on-chain execution uses the trading/cow path on chain 100. Monerium IBAN flows need credentials.',
+      };
+    }
+    if (provider === 'morpho') {
+      return {
+        provider,
+        category: 'earn',
+        canonicalReadAction: 'get_morpho_vaults',
+        canonicalWriteAction: 'deposit_earn_position',
+        readActions: ['get_morpho_vaults', 'get_earn_provider', 'get_earn_position'],
+        orderManagementActions: ['deposit_earn_position', 'withdraw_earn_position'],
+        supportedChains: [8453, 84532],
+        laneCompatibility: 'Morpho deposits require ERC-20 approvals to the vault/market routes surfaced by the catalog before deposit_earn_position.',
+        example:
+          'thirdfy-agent actions --provider morpho && thirdfy-agent run --action deposit_earn_position --params \'{"providerId":"morpho","vaultAddress":"0x...","tokenAddress":"0x...","amount":"10","chainId":8453}\'',
+      };
+    }
+    if (provider === 'aegis') {
+      return {
+        provider,
+        category: 'earn',
+        canonicalReadAction: 'get_aegis_pools',
+        canonicalWriteAction: 'deposit_aegis_lender',
+        readActions: ['get_earn_opportunities', 'get_aegis_pools', 'get_aegis_pool_state', 'get_aegis_vault_state', 'get_earn_provider'],
+        orderManagementActions: [
+          'deposit_aegis_lender',
+          'redeem_aegis_lender',
+          'open_aegis_vault_and_borrow',
+          'repay_aegis_vault',
+          'stabilize_aegis_vault',
+        ],
+        supportedChains: [8453, 130],
+        laneCompatibility:
+          'Aegis reads are live on Base allowlisted pools and Unichain DFM defaults. Engine writes use AegisRouterV1 with router-only approvals and eth_call simulation; writes stay fail-closed until partner addresses, PoolKeys, Engine ABI/opcodes, and audit sign-off. Use agent_wallet / walletExecute for solo Hermes — not execute-intent.',
+        example:
+          'thirdfy-agent actions --provider aegis --chain-id 8453 --json && thirdfy-agent run --action get_aegis_pool_state --run-mode agent_wallet --params \'{"pool":"tfy-usdc","chainId":8453}\'',
+      };
+    }
+    if (provider === 'curve') {
+      return {
+        provider,
+        category: 'earn',
+        canonicalReadAction: 'get_curve_pools',
+        canonicalWriteAction: 'deposit_earn_position',
+        readActions: ['get_curve_pools', 'get_earn_opportunities', 'get_earn_provider', 'get_earn_position'],
+        orderManagementActions: ['deposit_earn_position', 'withdraw_earn_position'],
+        supportedChains: [8453],
+        laneCompatibility:
+          '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;
+  }
+
+  function getCachedProviderHintFromCapabilities(provider) {
+    const normalizedProvider = String(provider || '').trim().toLowerCase();
+    if (!normalizedProvider) return null;
+    const manifests = Array.isArray(getNegotiatedCapabilitiesCache()?.providers?.manifests)
+      ? getNegotiatedCapabilitiesCache().providers.manifests
+      : [];
+    const match = manifests.find((entry) => String(entry?.providerId || '').trim().toLowerCase() === normalizedProvider);
+    if (!match) return null;
+    const canonicalWriteActions = {
+      trading: 'swap',
+      hyperliquid: 'place_hyperliquid_perps_order',
+      polymarket: 'place_polymarket_order',
+      prediction: 'place_prediction_order',
+      earn: 'deposit_earn_position',
+      morpho: 'deposit_earn_position',
+      aegis: 'deposit_aegis_lender',
+      curve: 'deposit_earn_position',
+      'vaults-fyi': 'deposit_earn_position',
+      'yield-xyz': 'deposit_earn_position',
+    };
+    const canonicalReadActions = {
+      earn: 'get_earn_opportunities',
+      morpho: 'get_morpho_vaults',
+      aegis: 'get_aegis_pools',
+      curve: 'get_curve_pools',
+      'vaults-fyi': 'get_vaults_fyi_vaults',
+      'yield-xyz': 'get_yield_xyz_opportunities',
+      prediction: 'get_prediction_markets',
+    };
+    return {
+      provider: normalizedProvider,
+      category: match.category || match.domain || match.providerKind || null,
+      ...(canonicalReadActions[normalizedProvider] ? { canonicalReadAction: canonicalReadActions[normalizedProvider] } : {}),
+      ...(canonicalWriteActions[normalizedProvider] ? { canonicalWriteAction: canonicalWriteActions[normalizedProvider] } : {}),
+      providerKind: match.providerKind || null,
+      capabilities: Array.isArray(match.capabilities) ? match.capabilities : [],
+      supportedChains: Array.isArray(match.supportedChains) ? match.supportedChains : [],
+      custodyMode: match.custodyMode || null,
+      description: match.description || null,
+      source: 'cli_capabilities_manifest',
+    };
+  }
+
+  function formatProviderAmbiguousActionHint(providerHint) {
+    if (!providerHint) return '';
+    const p = providerHint.provider;
+    const w = providerHint.canonicalWriteAction;
+    if (w) return ` Provider ${p} expects ${w}.`;
+    return ` Provider ${p} did not declare a canonical write action in capabilities; run actions --provider ${p} first.`;
+  }
+
+  function formatProviderUnknownActionHint(providerHint) {
+    if (!providerHint) return '';
+    const p = providerHint.provider;
+    const w = providerHint.canonicalWriteAction;
+    if (w) return ` Provider ${p} expects ${w}; run actions --provider ${p} first.`;
+    return ` Provider ${p} did not declare a canonical write action in capabilities; run actions --provider ${p} first.`;
+  }
+
+  return {
+    getTradingProviderHint,
+    getCachedProviderHintFromCapabilities,
+    formatProviderAmbiguousActionHint,
+    formatProviderUnknownActionHint,
+  };
+}