@thirdfy/agent-cli 0.2.86 → 0.4.0

package/src/runtime/main.mjs

@@ -1,6 +1,9 @@
 import { createRequire } from 'module';
 import { exitAfterOutput, printEnvelope as corePrintEnvelope } from '../core/envelope.mjs';
 import { negotiateCapabilities } from '../core/http.mjs';
+import { describeCliError } from '../core/errorEnvelope.mjs';
+import { applyApiChainRegistry } from '../core/chainRegistry.mjs';
+import { riskRefusalFields } from './risk/riskRefusal.mjs';
 import {
   buildCliProgram,
   collectRootFlags,
@@ -8,11 +11,13 @@ import {
   collectVersionFlagsFromArgv,
   normalizeLegacyShortFlags,
 } from '../cli/program.mjs';
+import { isMissingSubcommand } from '../cli/errors.mjs';
 import { createInitialRuntimeContext, applyFlagsToRuntimeContext } from './context.mjs';
-import { createProviderHints } from './providerHints.mjs';
+import { createProviderHints } from './providerHints/dispatch.mjs';
 import { createRuntimeHandlers } from './handlers.mjs';
 import { isCommanderCliError } from './errors.mjs';
 import { createOnboardingHints } from './onboardingHints.mjs';
+import { walletControlErrorFields } from './execution/walletControl.mjs';
 import { createAgentExtract } from './agentExtract.mjs';
 import { createAuthHelpers } from './authHelpers.mjs';
 import { createExecutionAmounts } from './execution/amounts.mjs';
@@ -49,13 +54,15 @@ export function createThirdfyAgentRuntime() {
     if (ctx.negotiatedCapabilitiesCache) return ctx.negotiatedCapabilitiesCache;
     const capabilities = await negotiateCapabilities(ctx);
     ctx.negotiatedCapabilitiesCache = capabilities;
+    // The API's chain list (chain family, CAIP-2) replaces the built-in defaults.
+    applyApiChainRegistry(capabilities);
     return capabilities;
   }
 
   const providerHints = createProviderHints({
     getNegotiatedCapabilitiesCache: () => context.negotiatedCapabilitiesCache,
   });
-  const { getTradingProviderHint, formatProviderAmbiguousActionHint, formatProviderUnknownActionHint } =
+  const { getTradingProviderHint, getProviderHintForActions, formatProviderAmbiguousActionHint, formatProviderUnknownActionHint } =
     providerHints;
 
   const { extractAgentApiKey, extractAgentKey, maskSecret } = createAgentExtract();
@@ -106,7 +113,7 @@ export function createThirdfyAgentRuntime() {
     buildOwnerAuthHeaders: auth.buildOwnerAuthHeaders,
     probeBitfinexPermissions: bitfinex.probeBitfinexPermissions,
     applyActionFilters: actions.applyActionFilters,
-    getTradingProviderHint,
+    getProviderHintForActions,
     resolveChainSupport: lanes.resolveChainSupport,
     resolveAgentApiKey: payloads.resolveAgentApiKey,
     getPreparedParams: amounts.getPreparedParams,
@@ -124,6 +131,7 @@ export function createThirdfyAgentRuntime() {
     performSelfBroadcast: runners.performSelfBroadcast,
     resolveManagedExecutionPreflight: runners.resolveManagedExecutionPreflight,
     resolveEffectiveUserDid: payloads.resolveEffectiveUserDid,
+    resolveAgentKey: payloads.resolveAgentKey,
     loadEthers: ows.loadEthers,
     resolveOwsBinary: ows.resolveOwsBinary,
     CLI_VERSION,
@@ -170,7 +178,8 @@ export function createThirdfyAgentRuntime() {
           await handleRootOnlyFlows(cliProgram, rootFlowDeps);
           return;
         }
-        if (error.code === 'commander.help' || error.code === 'commander.helpDisplayed') {
+        // Help exits 0; a command group run without its subcommand (`thirdfy-agent doctor`) fails.
+        if ((error.code === 'commander.help' || error.code === 'commander.helpDisplayed') && !isMissingSubcommand(cliProgram, error)) {
           return;
         }
         const exitCode = Number(error.exitCode ?? 1);
@@ -189,7 +198,8 @@ export function createThirdfyAgentRuntime() {
     const onboardingHint = onboarding.buildTopLevelOnboardingHint(payload);
     printEnvelope({
       success: false,
-      code: statusCode ? 'API_REQUEST_FAILED' : clientCode || 'CLI_UNHANDLED_ERROR',
+      // A missing or malformed flag is INVALID_ARGUMENTS at the top too, not an unhandled error.
+      code: statusCode ? 'API_REQUEST_FAILED' : clientCode || (error?.usage === true ? 'INVALID_ARGUMENTS' : 'CLI_UNHANDLED_ERROR'),
       message: error?.message || 'Unhandled CLI error',
       data: {
         statusCode,
@@ -200,6 +210,12 @@ export function createThirdfyAgentRuntime() {
         resolvedAction: payload.resolvedAction || null,
         requestedAction: payload.requestedAction || null,
         onboardingHint,
+        // errorCode, retryable, retryAfterSeconds, nextAction, hint: as thirdfy-mcp's error envelope.
+        ...describeCliError(error),
+        // API 4.0 wallet-control refusals: walletControl, nextAction, userMessage, retryable, hint.
+        ...walletControlErrorFields(payload),
+        // Risk-policy refusals: riskRefusal, blockedReason, blockedStage, retryable and a one-line message.
+        ...riskRefusalFields(payload),
         payload,
       },
       meta: { version: CLI_VERSION, apiBase: context.apiBase },

package/src/runtime/providerHints/apps.mjs

@@ -0,0 +1,36 @@
+/**
+ * Static provider hints. Thirdfy internal apps: Bermuda and Arc.
+ * Each entry builds the hint for one provider id; `dispatch.mjs` picks the entry.
+ */
+export const APPS_PROVIDER_HINTS = Object.freeze({
+  bermuda: ({ provider }) => ({
+    provider,
+    category: 'internal',
+    canonicalReadAction: 'get_bermuda_setup_status',
+    canonicalWriteAction: 'bermuda_deposit',
+    readActions: ['get_bermuda_setup_status', 'get_bermuda_balance'],
+    orderManagementActions: [
+      'bermuda_deposit',
+      'bermuda_transfer',
+      'bermuda_withdraw',
+      'bermuda_stealth_earn',
+      'bermuda_stealth_exit',
+      'bermuda_stealth_swap',
+      'bermuda_sweep_burners',
+    ],
+    supportedChains: [84532],
+    laneCompatibility: 'Base Sepolia shielded accounts (USDC, WETH, MetaMorpho vault shares). Catalog is flag-gated on the API host. Deposit is sent from the execution wallet; every other write is proven and relayed, so the execution wallet never appears: transfer, withdraw, private vault entry/exit (stealth earn/exit), private swap (stealth swap, best of Thirdfy routes and Uniswap v3, fresh burner per trade) and burner sweep. The regular swap takes private: true for the same private swap. Writes are capped at 5 USD; the sweep has no cap. Private writes bill the write_private credit tier; any privacy fee is reported as privacyFee (0 at launch). Responses include privacyNotes.',
+    example: 'thirdfy-agent run --action get_bermuda_setup_status --params \'{"chainId":84532}\' --provider bermuda --json',
+  }),
+  arc: ({ provider }) => ({
+    provider,
+    category: 'internal',
+    canonicalReadAction: 'get_arc_job',
+    canonicalWriteAction: 'create_arc_job',
+    readActions: ['get_arc_job'],
+    orderManagementActions: ['create_arc_job', 'set_arc_job_budget', 'fund_arc_job', 'submit_arc_job', 'complete_arc_job'],
+    supportedChains: [5042002, 5042],
+    laneCompatibility: 'Arc ERC-8183 job escrow. Testnet 5042002 is live. Mainnet 5042 cash is ready. Jobs writes on 5042 need the API jobs contract. Use Privy agent_wallet. USDC pays gas. No Uniswap, Li.Fi, or Yield.xyz on Arc yet.',
+    example: 'thirdfy-agent run --action get_arc_job --params \'{"chainId":5042002,"jobId":1}\' --provider arc --json',
+  }),
+});

package/src/runtime/providerHints/catalogHint.mjs

@@ -0,0 +1,55 @@
+/**
+ * A provider hint built from the provider's catalog rows, for a provider with no static hint and no
+ * capabilities manifest: provider apps (`openclaw`, `thirdfy`, ...), the CEX venues (`binance`,
+ * `okx`, ...) and any provider id the catalog serves. Same rules as thirdfy-mcp `buildProviderHint`
+ * (`src/tools/discovery/getTradingProviderActions.ts`) for a provider without a fallback hint.
+ */
+
+const WRITE_VERB_SEGMENTS = new Set(['swap', 'execute', 'deposit', 'withdraw', 'place', 'cancel', 'approve', 'stake', 'unstake', 'claim']);
+
+const rowAction = (row) =>
+  String(row?.action || row?.actionKey || row?.id || '')
+    .trim()
+    .replace(/-/g, '_')
+    .toLowerCase();
+
+/** The catalog row's own verdict (`behavior.readOnly`), when it has one. */
+const rowReadOnly = (row) => (typeof row?.behavior?.readOnly === 'boolean' ? row.behavior.readOnly : undefined);
+
+/** A write by the row's behavior; by its name only when the row has none. */
+function isWriteRow(row) {
+  const key = rowAction(row);
+  if (!key) return false;
+  const readOnly = rowReadOnly(row);
+  if (readOnly !== undefined) return !readOnly;
+  if (key.startsWith('get_')) return false;
+  if (row?.supportsExecute === true || row?.supportsExecuteIntent === true) return true;
+  return key.split('_').some((segment) => WRITE_VERB_SEGMENTS.has(segment));
+}
+
+const unique = (values) => Array.from(new Set(values.filter(Boolean)));
+
+/** The hint for `provider` from its catalog rows; null when there are none. */
+export function buildCatalogProviderHint(provider, rows) {
+  const actions = Array.isArray(rows) ? rows : [];
+  if (!provider || !actions.length) return null;
+  const readActions = unique(actions.filter((row) => rowReadOnly(row) ?? /^get_/.test(rowAction(row))).map(rowAction));
+  const writeActions = unique(actions.filter(isWriteRow).map(rowAction));
+  const categories = unique(
+    actions.map((row) => String(row?.category || row?.domain || row?.providerDomain || '').trim().toLowerCase()),
+  );
+  const supportedChains = unique(
+    actions.flatMap((row) => {
+      const value = row?.supportedChains || row?.supportedChainIds || row?.chainIds || row?.chains || [];
+      return Array.isArray(value) ? value.map(Number).filter((id) => Number.isInteger(id) && id > 0) : [];
+    }),
+  ).sort((a, b) => a - b);
+  return {
+    provider,
+    ...(categories.length ? { category: categories[0], categories } : {}),
+    ...(readActions.length ? { readActions } : {}),
+    ...(writeActions.length ? { orderManagementActions: writeActions, canonicalWriteAction: writeActions[0] } : {}),
+    ...(supportedChains.length ? { supportedChains } : {}),
+    source: 'actions_catalog_manifest',
+  };
+}

package/src/runtime/providerHints/cex.mjs

@@ -0,0 +1,130 @@
+/**
+ * Static provider hints. Centralized exchanges and their executors: Bitfinex, Hummingbot and Condor.
+ * Each entry builds the hint for one provider id; `dispatch.mjs` picks the entry.
+ */
+export const CEX_PROVIDER_HINTS = Object.freeze({
+  bitfinex: ({ provider }) => ({
+    provider,
+    category: 'cex_funding_and_spot',
+    canonicalReadAction: 'get_bitfinex_funding_ticker',
+    canonicalWriteAction: 'submit_bitfinex_funding_offer',
+    readActions: [
+      'get_bitfinex_funding_stats_hist',
+      'get_bitfinex_funding_ticker',
+      'get_bitfinex_funding_book',
+      'get_bitfinex_wallets',
+      'list_bitfinex_funding_offers',
+      'list_bitfinex_funding_offers_hist',
+      'list_bitfinex_funding_credits',
+      'list_bitfinex_funding_loans',
+      'get_bitfinex_funding_info',
+      'get_bitfinex_ledgers_hist',
+      'get_bitfinex_orders',
+    ],
+    orderManagementActions: [
+      'submit_bitfinex_funding_offer',
+      'cancel_bitfinex_funding_offer',
+      'transfer_bitfinex_between_wallets',
+      'get_bitfinex_orders',
+      'submit_bitfinex_order',
+      'update_bitfinex_order',
+      'cancel_bitfinex_order',
+    ],
+    credentialType: 'api_key',
+    credentialRef: 'bitfinex:funding-primary',
+    credentialUx: 'Bitfinex credentials are owned by Thirdfy API encrypted delegation storage. CLI commands pass credentialRef only; never apiKey/apiSecret.',
+    laneCompatibility: 'Use `thirdfy-agent actions --provider bitfinex` for discovery, then `thirdfy-agent run --run-mode thirdfy` with credentialRef in params. The CLI does not store, log, or sign raw exchange 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"}\'',
+    credentialProfiles: [
+      {
+        id: 'bitfinex_funding_v1',
+        credentialRef: 'bitfinex:funding-primary',
+        required: ['funding.read', 'funding.write', 'wallets.read'],
+      },
+      {
+        id: 'bitfinex_spot_v1',
+        credentialRef: 'bitfinex:spot-primary',
+        required: ['orders.read', 'orders.write', 'wallets.read'],
+      },
+    ],
+    setupBlockers: [
+      'CEX_CREDENTIAL_NOT_FOUND',
+      'BITFINEX_CREDENTIALS_NOT_IN_THIRDFY_DELEGATION_CONTEXT',
+      'BITFINEX_PERMISSION_SCOPE_MISSING',
+      'CEX_POLICY_ACTION_NOT_ALLOWED',
+    ],
+  }),
+  hummingbot: ({ provider }) => ({
+    provider,
+    category: 'cex_executor',
+    canonicalWriteAction: 'hummingbot_executor_create',
+    readActions: [
+      'get_hummingbot_connectors',
+      'get_hummingbot_executor_schema',
+      'get_hummingbot_gateway_networks',
+      'get_hummingbot_gateway_connectors',
+    ],
+    orderManagementActions: ['hummingbot_executor_create', 'hummingbot_executor_stop'],
+    setupActions: [
+      'get_hummingbot_connectors',
+      'get_hummingbot_gateway_networks',
+      'get_hummingbot_gateway_connectors',
+    ],
+    laneCompatibility: 'Prefer Thirdfy /api/v1/agent/hummingbot/* governed routes for writes. Gateway discovery uses catalog reads get_hummingbot_gateway_networks and get_hummingbot_gateway_connectors (runMode=thirdfy).',
+    example: 'thirdfy-agent hummingbot gateway-networks && thirdfy-agent hummingbot executor-stop --executor-id <id>',
+    canonicalReadAction: 'get_hummingbot_connectors',
+    credentialType: 'api_key',
+    credentialProfiles: [
+      {
+        id: 'binance_perpetual_v1',
+        credentialRef: 'binance_perpetual:primary',
+        required: ['trade.read', 'trade.write'],
+      },
+      {
+        id: 'okx_perpetual_v1',
+        credentialRef: 'okx_perpetual:primary',
+        required: ['trade.read', 'trade.write'],
+      },
+    ],
+    credentialUx: 'Hummingbot connector credentials sync from Thirdfy CEX delegation upsert into the org HB API account namespace. The CLI passes orgId and credentialRef only.',
+    setupBlockers: [
+      'HUMMINGBOT_INSTANCE_NOT_CONFIGURED',
+      'HUMMINGBOT_CREDENTIAL_NOT_FOUND',
+      'HUMMINGBOT_GOVERNANCE_DENIED',
+      'HUMMINGBOT_CONNECTOR_REQUIRED',
+    ],
+  }),
+  condor: ({ provider }) => ({
+    provider,
+    category: 'cex_executor',
+    canonicalWriteAction: 'condor_executor_create',
+    readActions: ['get_condor_policy_status'],
+    orderManagementActions: ['condor_executor_create', 'condor_executor_stop'],
+    setupActions: ['get_condor_policy_status'],
+    laneCompatibility: 'Use `thirdfy-agent run --run-mode thirdfy` for get_condor_policy_status, condor_executor_create, and condor_executor_stop. Preflight reservations use governance action condor.executor.create (CLI condor preflight). Do not bypass Pattern A with raw HB writes from Condor runtimes.',
+    example: 'thirdfy-agent condor policy-status && thirdfy-agent condor preflight --estimated-amount-usd 25 --idempotency-key <key>',
+    canonicalReadAction: 'get_condor_policy_status',
+    credentialType: 'api_key',
+    credentialProfiles: [
+      {
+        id: 'okx_perpetual_v1',
+        credentialRef: 'okx_perpetual:primary',
+        required: ['trade.read', 'trade.write'],
+      },
+      {
+        id: 'binance_perpetual_v1',
+        credentialRef: 'binance_perpetual:primary',
+        required: ['trade.read', 'trade.write'],
+      },
+    ],
+    credentialUx: 'Condor Pattern A uses Thirdfy policy and day-cap reservations. The CLI passes orgId/runtimeId only; exchange keys stay in Hummingbot.',
+    setupBlockers: [
+      'PATTERN_A_REQUIRED',
+      'CREDITS_EXHAUSTED',
+      'CONNECTOR_NOT_ALLOWED',
+      'NOTIONAL_CAP',
+      'DAILY_NOTIONAL_CAP',
+      'ACTION_NOT_SUPPORTED',
+    ],
+  }),
+});

package/src/runtime/providerHints/data.mjs

@@ -0,0 +1,144 @@
+/**
+ * Static provider hints. Read-only data and research providers, including the OpenMarket provider apps.
+ * Each entry builds the hint for one provider id; `dispatch.mjs` picks the entry.
+ */
+export const DATA_PROVIDER_HINTS = Object.freeze({
+  fomo: ({ provider }) => ({
+    provider,
+    category: 'smart_money_intel',
+    canonicalReadAction: 'get_fomo_alerts',
+    readActions: [
+      'get_fomo_search',
+      'get_fomo_user',
+      'get_fomo_balances',
+      'get_fomo_leaderboard',
+      'get_fomo_alerts',
+    ],
+    supportedChains: [],
+    laneCompatibility: 'Fomo API (fomoapi.io) uses string chain slugs (robinhood, solana, base, bsc, eth), not numeric chainId. Unofficial integration; not the Fomo consumer app. Read-only handle intel and app alerts via Thirdfy API. Pace calls (~1 req/s).',
+    example: 'thirdfy-agent run --action get_fomo_alerts --params \'{"chain":"robinhood","type":"buy","limit":5}\' --provider fomo --json',
+  }),
+  gmgn: ({ provider }) => ({
+    provider,
+    category: 'smart_money_intel',
+    canonicalReadAction: 'get_gmgn_kol_trades',
+    readActions: [
+      'get_gmgn_token_info',
+      'get_gmgn_token_security',
+      'get_gmgn_token_pool',
+      'get_gmgn_token_holders',
+      'get_gmgn_token_traders',
+      'get_gmgn_token_kline',
+      'get_gmgn_trending',
+      'get_gmgn_trenches',
+      'get_gmgn_hot_searches',
+      'get_gmgn_wallet_activity',
+      'get_gmgn_wallet_stats',
+      'get_gmgn_wallet_token_balance',
+      'get_gmgn_created_tokens',
+      'get_gmgn_kol_trades',
+      'get_gmgn_smartmoney_trades',
+    ],
+    supportedChains: [],
+    laneCompatibility: 'GMGN uses string chain slugs (sol, base, bsc, eth, robinhood), not numeric chainId. Read-only evidence via Thirdfy API. Pace calls (~1 req/s).',
+    example: 'thirdfy-agent run --action get_gmgn_kol_trades --params \'{"chain":"sol","limit":5}\' --provider gmgn --json',
+  }),
+  nansen: ({ provider }) => ({
+    provider,
+    category: 'research_intel',
+    canonicalReadAction: 'get_nansen_perp_screener',
+    readActions: [
+      'get_nansen_perp_screener',
+      'get_nansen_position_intelligence',
+      'get_nansen_address_perp_positions',
+      'get_nansen_address_perp_trades',
+      'get_nansen_address_balances',
+      'get_nansen_address_pnl_summary',
+      'get_nansen_flow_intelligence',
+      'get_nansen_agent_fast',
+      'get_nansen_agent_expert',
+    ],
+    supportedChains: [],
+    laneCompatibility: 'Nansen HL/TGM reads and premium research agent via Thirdfy API. Fast and expert research cost more than screener reads. Pace outbound starts (~1 req/s).',
+    example: 'thirdfy-agent run --action get_nansen_perp_screener --params \'{"date":{"from":"2026-08-27T00:00:00.000Z","to":"2026-08-28T00:00:00.000Z"},"pagination":{"page":1,"per_page":5}}\' --provider nansen --json',
+  }),
+  cmc: ({ provider }) => ({
+    provider,
+    category: 'research_intel',
+    canonicalReadAction: 'get_cmc_quotes',
+    readActions: [
+      'get_cmc_search',
+      'get_cmc_quotes',
+      'get_cmc_info',
+      'get_cmc_global_metrics',
+      'get_cmc_fear_greed',
+      'get_cmc_metrics',
+      'get_cmc_technicals',
+      'get_cmc_marketcap_technicals',
+      'get_cmc_derivatives_metrics',
+      'get_cmc_news',
+      'get_cmc_search_info',
+      'get_cmc_narratives',
+      'get_cmc_upcoming_events',
+      'get_cmc_skill',
+      'get_cmc_daily_market_overview',
+      'get_cmc_btc_etf_demand',
+      'get_cmc_perp_contract_analysis',
+      'get_cmc_market_regime',
+      'get_cmc_derivatives_crowding',
+    ],
+    supportedChains: [],
+    laneCompatibility: 'CoinMarketCap quotes, global metrics, and composed Skill Hub briefs via Thirdfy API. Skill actions may take up to 180s. Composed briefs cost more than cheap reads.',
+    example: 'thirdfy-agent run --action get_cmc_quotes --params \'{"symbol":"BTC","convert":"USD"}\' --provider cmc --json',
+  }),
+  'market-data': ({ provider }) => ({
+    provider,
+    category: 'market_data',
+    canonicalReadAction: 'get_trending_tokens',
+    readActions: [
+      'get_trending_tokens',
+      'get_new_token_launches',
+      'get_token_market_data',
+      'get_chain_market_overview',
+    ],
+    supportedChains: [8453, 84532, 4663],
+    laneCompatibility: 'Read-only market data via API-owned actions. Robinhood Chain uses CoinGecko Onchain network id robinhood.',
+  }),
+  openmarket: ({ provider }) => ({
+    provider,
+    category: 'market_data',
+    canonicalReadAction: 'get_openmarket_candles',
+    readActions: [
+      'get_openmarket_markets',
+      'get_openmarket_candles',
+      'get_openmarket_open_interest',
+      'get_openmarket_funding',
+      'get_openmarket_liquidations',
+      'get_openmarket_order_flow',
+      'get_openmarket_prediction_markets',
+      'get_openmarket_hl_perps_snapshot',
+      'get_openmarket_btc_funding',
+      'get_openmarket_hl_funding',
+      'get_openmarket_hl_open_interest',
+      'get_openmarket_polymarket_top_markets',
+    ],
+    supportedChains: [],
+    laneCompatibility: 'Read-only provider app (no wallet). Series reads take exchange (venue id), symbol (the venue\'s own symbol: BTC on HYPERLIQUID_FUTURES, BTCUSDT on BINANCE_FUTURES), interval and period in seconds (at most 601200). Find symbols with get_openmarket_markets.',
+    example: 'thirdfy-agent run --action get_openmarket_candles --params \'{"exchange":"HYPERLIQUID_FUTURES","symbol":"ETH","interval":"HOUR","period":21600}\' --json',
+  }),
+  'openmarket-metrics': ({ provider }) => ({
+    provider,
+    category: 'market_data',
+    canonicalReadAction: 'get_openmarket_metrics_indicators',
+    readActions: [
+      'get_openmarket_metrics_indicators',
+      'get_openmarket_metrics_volume_profile',
+      'get_openmarket_metrics_screen',
+      'get_openmarket_metrics_market_screen',
+      'get_openmarket_metrics_symbol_resolve',
+    ],
+    supportedChains: [],
+    laneCompatibility: 'Read-only provider app (no wallet). Indicators warm up on about 4x their period over 167h of history: use FIFTEEN_MINUTES or HOUR bars; a value that cannot be computed returns ok false with detail.reason.',
+    example: 'thirdfy-agent run --action get_openmarket_metrics_indicators --params \'{"selector":{"symbol":"BTC","exchange":"HYPERLIQUID_FUTURES","interval":"FIFTEEN_MINUTES"},"queries":[{"metric":"rsi","params":{"period":14}}]}\' --json',
+  }),
+});

package/src/runtime/providerHints/dispatch.mjs

@@ -0,0 +1,177 @@
+import { normalizeVenueProviderId } from '../../core/venueBrand.mjs';
+import { configuredSvmChainIds } from '../../core/chainRegistry.mjs';
+import { PERPS_PROVIDER_HINTS, verantaNamingFields } from './perps.mjs';
+import { PREDICTION_PROVIDER_HINTS } from './prediction.mjs';
+import { TRADING_PROVIDER_HINTS } from './trading.mjs';
+import { EARN_PROVIDER_HINTS } from './earn.mjs';
+import { CEX_PROVIDER_HINTS } from './cex.mjs';
+import { DATA_PROVIDER_HINTS } from './data.mjs';
+import { APPS_PROVIDER_HINTS } from './apps.mjs';
+import { SOLANA_PROVIDER_HINTS } from './solana.mjs';
+import { DOGEOS_PROVIDER_HINTS } from './dogeos.mjs';
+import { walletControlProviderNote } from './walletControl.mjs';
+import { buildCatalogProviderHint } from './catalogHint.mjs';
+
+/** Every static provider hint, by provider id, from the family files in this folder. */
+const STATIC_PROVIDER_HINTS = Object.freeze({
+  ...PERPS_PROVIDER_HINTS,
+  ...PREDICTION_PROVIDER_HINTS,
+  ...TRADING_PROVIDER_HINTS,
+  ...EARN_PROVIDER_HINTS,
+  ...CEX_PROVIDER_HINTS,
+  ...DATA_PROVIDER_HINTS,
+  ...APPS_PROVIDER_HINTS,
+  ...SOLANA_PROVIDER_HINTS,
+  ...DOGEOS_PROVIDER_HINTS,
+});
+
+/** Provider ids with a static hint (read by `scripts/validate-provider-parity.mjs`). */
+export const STATIC_HINT_PROVIDER_IDS = Object.freeze(Object.keys(STATIC_PROVIDER_HINTS));
+
+/**
+ * Providers whose static hint is built on top of the capabilities manifest's hint instead of being
+ * replaced by it. Every other provider answers with the manifest's hint when the API sends one.
+ */
+const MERGES_MANIFEST_HINT = new Set(['hyperliquid']);
+
+/**
+ * `walletControlNote` for the hint's provider when one applies (thirdfy-mcp `walletControlProviderNote`),
+ * and, for a Solana provider on an API that lists no svm chain, an `availability` note so the agent
+ * does not try a chain that is refused (thirdfy-mcp `providerHintFor`).
+ */
+function withWalletControlNote(hint) {
+  const note = walletControlProviderNote(hint.provider, hint);
+  const solanaOff = Object.prototype.hasOwnProperty.call(SOLANA_PROVIDER_HINTS, hint.provider) && configuredSvmChainIds().length === 0;
+  if (!note && !solanaOff) return hint;
+  return {
+    ...hint,
+    ...(note ? { walletControlNote: note } : {}),
+    ...(solanaOff
+      ? { availability: 'Solana execution is not enabled on this Thirdfy API (its capabilities list no svm chain); chain 101 is refused with SOLANA_NOT_ENABLED.' }
+      : {}),
+  };
+}
+
+/**
+ * Static and capabilities-backed provider discovery hints for CLI actions filtering.
+ */
+export function createProviderHints({ getNegotiatedCapabilitiesCache }) {
+  function getTradingProviderHint(providerId) {
+    // `veranta` / `veranta-vault` resolve to the internal `avantis` / `avantis-vault` hints.
+    const provider = normalizeVenueProviderId(providerId || '');
+    const manifestHint = getCachedProviderHintFromCapabilities(provider);
+    const setupHints =
+      manifestHint?.setupHints && typeof manifestHint.setupHints === 'object' ? manifestHint.setupHints : {};
+    const buildHint = Object.prototype.hasOwnProperty.call(STATIC_PROVIDER_HINTS, provider)
+      ? STATIC_PROVIDER_HINTS[provider]
+      : null;
+    if (buildHint && MERGES_MANIFEST_HINT.has(provider)) return withWalletControlNote(buildHint({ provider, manifestHint, setupHints }));
+    if (manifestHint) return withWalletControlNote(manifestHint);
+    return buildHint ? withWalletControlNote(buildHint({ provider, manifestHint, setupHints })) : null;
+  }
+
+  /**
+   * The hint for `actions --provider`: the static or manifest hint, else one built from the
+   * provider's catalog rows (provider apps, CEX venues, any id the catalog serves), as thirdfy-mcp
+   * `getProviderActions` answers it.
+   */
+  function getProviderHintForActions(providerId, rows) {
+    const hint = getTradingProviderHint(providerId);
+    if (hint || !providerId) return hint;
+    const catalogHint = buildCatalogProviderHint(normalizeVenueProviderId(providerId), rows);
+    return catalogHint ? withWalletControlNote(catalogHint) : null;
+  }
+
+  function getCachedProviderHintFromCapabilities(provider) {
+    const normalizedProvider = normalizeVenueProviderId(provider || '');
+    if (!normalizedProvider) return null;
+    const manifests = Array.isArray(getNegotiatedCapabilitiesCache()?.providers?.manifests)
+      ? getNegotiatedCapabilitiesCache().providers.manifests
+      : [];
+    const match = manifests.find((entry) => normalizeVenueProviderId(entry?.providerId || '') === normalizedProvider);
+    if (!match) return null;
+    const canonicalWriteActions = {
+      trading: 'swap',
+      hyperliquid: 'place_hyperliquid_perps_order',
+      lighter: 'place_lighter_perps_order',
+      polymarket: 'place_polymarket_order',
+      prediction: 'place_prediction_order',
+      earn: 'deposit_earn_position',
+      morpho: 'deposit_earn_position',
+      aave: 'deposit_earn_position',
+      aegis: 'deposit_aegis_lender',
+      basedbid: 'basedbid_create_lbp',
+      bermuda: 'bermuda_deposit',
+      arc: 'create_arc_job',
+      curve: 'deposit_earn_position',
+      uniswap: 'mint_uniswap_position',
+      ratehopper: 'setup_ratehopper_cash_lp',
+      'vaults-fyi': 'deposit_earn_position',
+      'yield-xyz': 'deposit_earn_position',
+    };
+    const canonicalReadActions = {
+      earn: 'get_earning_opportunities',
+      morpho: 'get_morpho_vaults',
+      aave: 'get_aave_markets',
+      aegis: 'get_aegis_pools',
+      curve: 'get_curve_pools',
+      uniswap: 'get_uniswap_pools',
+      ratehopper: 'get_ratehopper_agents',
+      'vaults-fyi': 'get-vaults-fyi-vaults',
+      'yield-xyz': 'get_yield_xyz_opportunities',
+      'market-data': 'get_trending_tokens',
+      fomo: 'get_fomo_alerts',
+      gmgn: 'get_gmgn_kol_trades',
+      nansen: 'get_nansen_perp_screener',
+      basedbid: 'basedbid_get_tokens',
+      bermuda: 'get_bermuda_setup_status',
+      arc: 'get_arc_job',
+      cmc: 'get_cmc_quotes',
+      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',
+      ...verantaNamingFields(normalizedProvider),
+      ...(match.setupHints && typeof match.setupHints === 'object' ? { setupHints: match.setupHints } : {}),
+    };
+  }
+
+  // Veranta hints carry `providerAliases`; show the public name in messages (`--provider veranta`).
+  function providerLabelForHint(providerHint) {
+    const alias = Array.isArray(providerHint?.providerAliases) ? providerHint.providerAliases[0] : null;
+    return alias || providerHint.provider;
+  }
+
+  function formatProviderAmbiguousActionHint(providerHint) {
+    if (!providerHint) return '';
+    const p = providerLabelForHint(providerHint);
+    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 = providerLabelForHint(providerHint);
+    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,
+    getProviderHintForActions,
+    getCachedProviderHintFromCapabilities,
+    formatProviderAmbiguousActionHint,
+    formatProviderUnknownActionHint,
+  };
+}