@thirdfy/agent-cli 0.1.22 → 0.1.23

package/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to `@thirdfy/agent-cli` are documented here. The format is b
 
 ## [Unreleased]
 
+## [0.1.23] - 2026-05-02
+
+**npm:** [`@thirdfy/agent-cli@0.1.23`](https://www.npmjs.com/package/@thirdfy/agent-cli/v/0.1.23)  
+**Git tag:** `v0.1.23`
+
+### Added
+
+- Provider discovery hints for `earn`, `morpho`, `curve`, and generic `prediction` so agents can filter action catalogs by domain without hard-coded protocol-specific flows.
+- Curve/Base 4pool write hints surfaced through the actions provider filter for earn flows.
+
+### Fixed
+
+- **Provider filter:** Case-insensitive matching for earn-related action keys when filtering catalogs by provider.
+- **Self custody:** `preflight` and self-exec paths reject offchain venue order actions before `build-tx`, aligned with venue execution guardrails.
+
 ## [0.1.22] - 2026-04-28
 
 **npm:** [`@thirdfy/agent-cli@0.1.22`](https://www.npmjs.com/package/@thirdfy/agent-cli/v/0.1.22)  

package/bin/thirdfy-agent.mjs

@@ -374,6 +374,212 @@ function shouldApplySwapAmountContract(actionName) {
   return action === 'swap' || /(^|:|-)swap$/.test(action);
 }
 
+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',
+      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',
+        'get_hyperliquid_l2_book',
+        'get_hyperliquid_candles',
+        'get_hyperliquid_user_state',
+        'get_hyperliquid_open_orders',
+        'get_hyperliquid_onboarding_plan',
+        'get_hyperliquid_referral_status',
+        'get_hyperliquid_builder_fee_status',
+      ],
+      orderManagementActions: [
+        'place_hyperliquid_perps_order',
+        'get_hyperliquid_open_orders',
+      ],
+      setupActions: [
+        '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_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 -> 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 === 'polymarket') {
+    return {
+      provider,
+      category: 'prediction_market',
+      canonicalWriteAction: 'place_polymarket_order',
+      readActions: [
+        'get_polymarket_markets',
+        'get_polymarket_market',
+        'get_polymarket_order_book',
+        'get_polymarket_prices',
+        'get_polymarket_price_history',
+        'get_polymarket_setup_status',
+        'get_polymarket_order',
+        'get_polymarket_user_orders',
+      ],
+      orderManagementActions: [
+        'place_polymarket_order',
+        'get_polymarket_order',
+        'get_polymarket_user_orders',
+        'cancel_polymarket_order',
+      ],
+      setupActions: [
+        'get_polymarket_setup_status',
+        'agent_wallet_setup:ensure_agent_wallet_safe',
+        'agent_wallet_setup:deploy_safe_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_safe_and_set_approvals',
+      ],
+      statusActions: ['get_polymarket_setup_status'],
+      credentialType: 'polymarket_clob',
+      credentialUx:
+        'Autonomous agents use an agent-owned Privy wallet/Safe first: Thirdfy creates the agent wallet, deploys/approves the Safe, 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 Safe with Polygon USDC/pUSD collateral after Safe deployment and approvals.',
+      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_AGENT_WALLET_SAFE_REQUIRED',
+        'POLYMARKET_CLOB_CREDENTIALS_REQUIRED',
+        'POLYMARKET_SAFE_DEPLOYMENT_REQUIRED',
+        'POLYMARKET_SAFE_APPROVALS_REQUIRED',
+        'POLYMARKET_USDC_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_markets', 'get_prediction_market', 'get_prediction_order_book'],
+      orderManagementActions: ['place_prediction_order', 'cancel_prediction_order'],
+      compatibilityProvider: 'polymarket',
+    };
+  }
+  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'],
+      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.',
+    };
+  }
+  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 === '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.',
+    };
+  }
+  return null;
+}
+
+function getCachedProviderHintFromCapabilities(_provider) {
+  return null;
+}
+
+const OFFCHAIN_VENUE_ORDER_ACTIONS = new Set([
+  'place_hyperliquid_perps_order',
+  'place-hyperliquid-perps-order',
+  'place_polymarket_order',
+  'place-polymarket-order',
+]);
+
+function enforceOffchainVenueLaneCompatibility(action, runMode) {
+  const normalizedAction = String(action || '').trim().toLowerCase();
+  if (runMode !== 'self' || !OFFCHAIN_VENUE_ORDER_ACTIONS.has(normalizedAction)) return;
+  throw createCliError(
+    'OFFCHAIN_VENUE_ORDER_SELF_UNSUPPORTED',
+    'Polymarket CLOB and Hyperliquid perps orders are offchain signed API actions, not EVM build-tx actions. Use self for setup/funding signatures, then run venue orders with --run-mode thirdfy, --run-mode hybrid, or --run-mode agent_wallet.',
+    {
+      recommendedRunModes: ['thirdfy', 'hybrid', 'agent_wallet'],
+      setupOnlyRunMode: 'self',
+    }
+  );
+}
+
 function createCliError(code, message, payload = {}) {
   const error = new Error(message);
   error.payload = {
@@ -630,6 +836,7 @@ async function commandTrackAction(ctx, flags, capabilities) {
 async function commandActions(ctx, flags, capabilities) {
   const policyAware = Boolean(flags.agentApiKey);
   const actions = applyActionFilters(await getCachedActionsCatalog(ctx, flags), flags);
+  const providerHint = getTradingProviderHint(flags.provider);
   const effectiveRunMode = getEffectiveRunMode(ctx, flags);
   const chainIdFilter = Number(flags.chainId || 0) || undefined;
   const chainSupport = resolveChainSupport(capabilities, chainIdFilter, effectiveRunMode);
@@ -637,7 +844,7 @@ async function commandActions(ctx, flags, capabilities) {
     success: true,
     code: 'OK',
     message: 'Actions loaded',
-    data: { actions },
+    data: { actions, ...(providerHint ? { providerHint } : {}) },
     meta: {
       apiBase: ctx.apiBase,
       policyAware,
@@ -653,6 +860,7 @@ async function commandPreflight(ctx, flags, capabilities) {
   const resolved = await resolveActionSelection(ctx, flags);
   prepareActionParamsForFlags(flags, resolved.resolvedAction);
   const runMode = getEffectiveRunMode(ctx, flags);
+  enforceOffchainVenueLaneCompatibility(resolved.resolvedAction, runMode);
   const hybridWalletMode = runMode === 'hybrid' ? normalizeHybridWalletMode(flags.hybridWalletMode) : null;
   enforceChainCompatibility(capabilities, flags, runMode);
   const backendResult = await runPreflightByMode(runMode, ctx, flags, resolved, { hybridWalletMode });
@@ -687,6 +895,7 @@ async function commandRun(ctx, flags, capabilities) {
   const resolved = await resolveActionSelection(ctx, flags);
   prepareActionParamsForFlags(flags, resolved.resolvedAction);
   const runMode = getEffectiveRunMode(ctx, flags);
+  enforceOffchainVenueLaneCompatibility(resolved.resolvedAction, runMode);
   const hybridWalletMode = runMode === 'hybrid' ? normalizeHybridWalletMode(flags.hybridWalletMode) : null;
   enforceChainCompatibility(capabilities, flags, runMode);
   const skipPreflight = Boolean(flags.skipPreflight);
@@ -812,6 +1021,7 @@ async function commandWalletSign(ctx, flags, capabilities) {
   const normalizedFlags = { ...flags, runMode: 'self' };
   const resolved = await resolveActionSelection(ctx, normalizedFlags);
   prepareActionParamsForFlags(normalizedFlags, resolved.resolvedAction);
+  enforceOffchainVenueLaneCompatibility(resolved.resolvedAction, 'self');
   enforceChainCompatibility(capabilities, normalizedFlags, 'self');
   const selfResult = await executeSelfRun(ctx, normalizedFlags, resolved, {
     skipPreflight: Boolean(normalizedFlags.skipPreflight),
@@ -1682,6 +1892,7 @@ async function commandPrompt(ctx, flags, capabilities, promptTokens) {
 async function commandSelfExec(ctx, flags, capabilities) {
   const resolved = await resolveActionSelection(ctx, flags);
   prepareActionParamsForFlags(flags, resolved.resolvedAction);
+  enforceOffchainVenueLaneCompatibility(resolved.resolvedAction, 'self');
   enforceChainCompatibility(capabilities, flags, 'self');
   const selfResult = await executeSelfRun(ctx, flags, resolved, {
     skipPreflight: Boolean(flags.skipPreflight),
@@ -2969,11 +3180,22 @@ function applyActionFilters(actions, flags) {
   }
   if (flags.provider) {
     const expectedProvider = String(flags.provider).trim().toLowerCase();
-    filtered = filtered.filter((a) => String(a.provider || '').trim().toLowerCase() === expectedProvider);
+    filtered = filtered.filter((a) => {
+      const provider = getActionProvider(a);
+      const actionKey = getActionKey(a).replace(/-/g, '_').toLowerCase();
+      if (provider === expectedProvider) return true;
+      if (expectedProvider === 'earn') return provider === 'morpho' || provider === 'curve' || actionKey.includes('_earn_');
+      if (expectedProvider === 'prediction') return provider === 'polymarket' || actionKey.includes('_prediction_');
+      return false;
+    });
   }
   return filtered;
 }
 
+function getActionProvider(action) {
+  return String(action?.provider || action?.providerId || action?.provider_id || action?.catalog || '').trim().toLowerCase();
+}
+
 async function resolveActionSelection(ctx, flags) {
   const requestedAction = requireFlag(flags, 'action', 'Missing --action');
   const requestedLower = requestedAction.toLowerCase();
@@ -3009,10 +3231,11 @@ async function resolveActionSelection(ctx, flags) {
     return { requestedAction, resolvedAction: exactAlias[0].key, resolvedActionMeta: exactAlias[0].action || null };
   }
   if (exactAlias.length > 1) {
+    const providerHint = flags.provider ? getTradingProviderHint(flags.provider) : null;
     throw new Error(
       `Ambiguous --action "${requestedAction}". Alias matches multiple actions: ${formatActionList(
         exactAlias.map((v) => v.key)
-      )}.`
+      )}.${providerHint ? ` Provider ${providerHint.provider} expects ${providerHint.canonicalWriteAction}.` : ''}`
     );
   }
 
@@ -3025,14 +3248,18 @@ async function resolveActionSelection(ctx, flags) {
     return { requestedAction, resolvedAction: fuzzy[0].key, resolvedActionMeta: fuzzy[0].action || null };
   }
   if (fuzzy.length > 1) {
+    const providerHint = flags.provider ? getTradingProviderHint(flags.provider) : null;
     throw new Error(
       `Ambiguous --action "${requestedAction}". Did you mean one of: ${formatActionList(
         fuzzy.slice(0, 10).map((v) => v.key)
-      )}?`
+      )}?${providerHint ? ` Provider ${providerHint.provider} expects ${providerHint.canonicalWriteAction}.` : ''}`
     );
   }
+  const providerHint = flags.provider ? getTradingProviderHint(flags.provider) : null;
   throw new Error(
-    `Unknown --action "${requestedAction}". No compatible action found in current catalog/provider scope.`
+    `Unknown --action "${requestedAction}". No compatible action found in current catalog/provider scope.${
+      providerHint ? ` Provider ${providerHint.provider} expects ${providerHint.canonicalWriteAction}; run actions --provider ${providerHint.provider} first.` : ''
+    }`
   );
 }
 

package/package.json

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