@thirdfy/agent-cli 0.3.0 → 0.4.1

package/src/cli/options/bootstrap.mjs

@@ -1,7 +1,17 @@
-/** Commander 13+ rejects multi-character short flags; keep the historical `-ni` spelling working. */
+/**
+ * Commander 13+ rejects multi-character short flags; keep the historical `-ni` spelling working, and
+ * `--ni`, the spelling the README and onboarding help use.
+ */
+const NOT_INTERACTIVE_ALIASES = new Set(['-ni', '--ni']);
+
 export function normalizeLegacyShortFlags(argv) {
   const end = argv.indexOf('--');
-  return argv.map((arg, index) => (arg === '-ni' && (end === -1 || index < end) ? '--not-interactive' : arg));
+  return argv.map((arg, index) => (NOT_INTERACTIVE_ALIASES.has(arg) && (end === -1 || index < end) ? '--not-interactive' : arg));
+}
+
+/** `help onboarding --path`: one path, as thirdfy-mcp `describeOnboardingPath`. */
+export function attachOnboardingHelpOptions(cmd) {
+  return cmd.option('--path <id>', 'one path: email_otp | wallet_sign | existing_credentials | mcp_bootstrap | all');
 }
 
 export function attachBootstrapOptions(cmd) {
@@ -16,9 +26,11 @@ export function attachBootstrapOptions(cmd) {
     .option('--otp <otp>', 'email OTP alias')
     .option('--accept-terms', 'accept terms for email login')
     .option('--key-name <name>', 'Privy key name')
-    .option('--not-interactive', 'fail fast when required login input is missing (alias: -ni)')
+    .option('--not-interactive', 'fail fast when required login input is missing (aliases: --ni, -ni)')
     .option('--no-bootstrap-agent', 'skip agent bootstrap on email login')
     .option('--rotate-agent-key', 'rotate agent key')
+    .option('--owner-payout-address <addr>', 'owner payout address for exits from a wallet under wallet control (API 4.0+)')
+    .option('--allowed-actions <list>', "comma-separated catalog action names for the agent's action template (API 4.0+)")
     .option('--login-attempt-id <id>', 'email login attempt id')
     .option('--all', 'logout all sessions')
     .option('--clear-agent-key', 'clear stored agent key on logout');

package/src/cli/options/chains.mjs

@@ -1,3 +1,8 @@
 export function attachChainOptions(cmd) {
   return cmd.option('--chain-id <id>', 'chain id');
 }
+
+/** Options for `chains` (thirdfy-mcp getChainCapabilities / getNonEvmCapabilities). */
+export function attachChainListOptions(cmd) {
+  return cmd.option('--non-evm', 'only the non-EVM (Solana) execution contract');
+}

package/src/cli/options/credits.mjs

@@ -13,3 +13,12 @@ export function attachCreditsOptions(cmd) {
     )
     .option('--surface <surface>', 'billing surface (console, automation, cli, agent_api)', 'cli');
 }
+
+/** `credits buy` only: no catalog or pricing flags, and no --action / --params to override. */
+export function attachCreditsBuyOptions(cmd) {
+  return cmd
+    .option('--usd <dollars>', 'whole US dollars of credits to buy with USDC from the agent wallet')
+    .option('--tx-hash <hash>', 'resume a purchase whose USDC payment was already sent (after WRITE_OUTCOME_UNKNOWN)')
+    .option('--chain-id <id>', 'chain the USDC is paid on (default 8453 Base; 84532 Base Sepolia on test APIs)')
+    .option('--idempotency-key <key>', 'idempotency key for this purchase');
+}

package/src/cli/options/data.mjs

@@ -1,4 +1,4 @@
-/** Options of the data commands: `signals`, and the data-category filter of `actions`. */
+/** Options of the discovery and data commands: `actions` filters and `signals`. */
 
 export function attachSignalsOptions(cmd) {
   return cmd
@@ -12,3 +12,15 @@ export function attachDataCategoryOptions(cmd) {
     'only data reads of this category (market_data, signal, research, wallet); comma-separated for several',
   );
 }
+
+/** `actions` filters. It lists actions only, so it takes none of the `run` / `preflight` options. */
+export function attachActionListOptions(cmd) {
+  return cmd
+    .option('--provider <id>', 'only this provider (hyperliquid, polymarket, earn, ...)')
+    .option('--chain-id <id>', 'only actions on this chain')
+    .option('--catalog <id>', 'only this actions catalog')
+    .option('--search <text>', 'only actions whose name, description or aliases contain this text (one page)')
+    .option('--limit <n>', 'page size (concise: 50 by default, at most 100; detailed: 10, at most 25)')
+    .option('--offset <n>', 'skip this many matching actions (default 0)')
+    .option('--view <view>', 'concise (default with paging) or detailed (full entries with paramsSchema)');
+}

package/src/cli/options/index.mjs

@@ -4,20 +4,21 @@ import { attachExecutionOptions } from './execution.mjs';
 import { attachDelegationOptions } from './delegation.mjs';
 import { attachTrackingOptions } from './tracking.mjs';
 import { attachWalletOptions } from './wallet.mjs';
-import { attachBootstrapOptions } from './bootstrap.mjs';
+import { attachBootstrapOptions, attachOnboardingHelpOptions } from './bootstrap.mjs';
 import { attachCredentialsOptions } from './credentials.mjs';
 import { attachAnalyticsOptions } from './analytics.mjs';
 import { attachPolymarketOptions } from './polymarket.mjs';
 import { attachHummingbotOptions } from './hummingbot.mjs';
 import { attachCondorOptions } from './condor.mjs';
 import { attachAgentRegisterOptions } from './agent.mjs';
-import { attachChainOptions } from './chains.mjs';
-import { attachCreditsOptions } from './credits.mjs';
+import { attachChainListOptions, attachChainOptions } from './chains.mjs';
+import { attachCreditsBuyOptions, attachCreditsOptions } from './credits.mjs';
 import { attachChatOptions } from './chat.mjs';
 import { attachVenueOptions } from './venue.mjs';
 import { attachBrainOptions } from './brain.mjs';
 import { attachCertificationOptions } from './certification.mjs';
-import { attachDataCategoryOptions, attachSignalsOptions } from './data.mjs';
+import { attachActionListOptions, attachDataCategoryOptions, attachSignalsOptions } from './data.mjs';
+import { attachWalletControlOptions } from './walletControl.mjs';
 
 const BUNDLES = {
   auth: attachAuthOptions,
@@ -26,6 +27,7 @@ const BUNDLES = {
   tracking: attachTrackingOptions,
   wallet: attachWalletOptions,
   bootstrap: attachBootstrapOptions,
+  onboardingHelp: attachOnboardingHelpOptions,
   credentials: attachCredentialsOptions,
   analytics: attachAnalyticsOptions,
   polymarket: attachPolymarketOptions,
@@ -33,13 +35,17 @@ const BUNDLES = {
   condor: attachCondorOptions,
   agent: attachAgentRegisterOptions,
   chains: attachChainOptions,
+  chainList: attachChainListOptions,
   credits: attachCreditsOptions,
+  creditsBuy: attachCreditsBuyOptions,
   chat: attachChatOptions,
   venue: attachVenueOptions,
   brain: attachBrainOptions,
   certification: attachCertificationOptions,
   signals: attachSignalsOptions,
   dataCategory: attachDataCategoryOptions,
+  actionList: attachActionListOptions,
+  walletControl: attachWalletControlOptions,
 };
 
 /** @param {import('commander').Command} cmd */

package/src/cli/options/walletControl.mjs

@@ -0,0 +1,8 @@
+/** Options of `wallet-control request|submit` (owner actions on a user-owned agent wallet). */
+export function attachWalletControlOptions(cmd) {
+  return cmd
+    .option('--action <action>', 'owner action: update_policy, stop_agent, resume_agent, change_payout, export')
+    .option('--payout-address <addr>', 'new owner payout address (change_payout)')
+    .option('--recipient-public-key <key>', 'HPKE recipient public key (export)')
+    .option('--signature-input <json>', 'the signatureInput of the request the owner signed (submit)');
+}

package/src/commands/bootstrap.mjs

@@ -1,4 +1,4 @@
-import { requireFlag, isNonInteractive } from '../core/args.mjs';
+import { requireFlag, isNonInteractive, usageError } from '../core/args.mjs';
 import { createCliError } from '../core/envelope.mjs';
 import { PROFILE_DEFAULTS } from '../core/constants.mjs';
 import {
@@ -16,6 +16,7 @@ import {
   getProfileConfigPath,
 } from '../core/context.mjs';
 import { apiGet, apiPost, requestWithRouteFallback } from '../core/http.mjs';
+import { isEvmAddress, isSolanaAddress } from '../core/chainRegistry.mjs';
 import { createRequire } from 'module';
 
 const require = createRequire(import.meta.url);
@@ -153,12 +154,24 @@ async function commandConfigSet(ctx, flags) {
 }
 
 
+const ONBOARDING_PATHS = ['email_otp', 'wallet_sign', 'existing_credentials', 'mcp_bootstrap'];
+
+/** `help onboarding [--path <id>]`: every path, or one with `selectedPath` (thirdfy-mcp `describeOnboardingPath`). */
 async function commandHelpOnboarding(ctx, flags) {
+  const help = buildOnboardingHelp(ctx, flags);
+  const selectedPath = String(flags.path || 'all').trim().toLowerCase();
+  if (selectedPath !== 'all' && !ONBOARDING_PATHS.includes(selectedPath)) {
+    throw usageError(`--path must be one of ${ONBOARDING_PATHS.join(', ')} or all`, 'path');
+  }
+  const data =
+    selectedPath === 'all'
+      ? { selectedPath, ...help }
+      : { selectedPath, ...help.paths.find((entry) => entry.id === selectedPath), nonInteractive: help.nonInteractive, gas: help.gas, apiBase: help.apiBase };
   printEnvelope({
     success: true,
     code: 'ONBOARDING_HELP_OK',
-    message: 'Thirdfy onboarding help',
-    data: buildOnboardingHelp(ctx, flags),
+    message: selectedPath === 'all' ? 'Thirdfy onboarding help' : `Thirdfy onboarding help: ${selectedPath}`,
+    data,
     meta: { apiBase: ctx.apiBase },
   });
 }
@@ -289,6 +302,16 @@ async function commandLogin(ctx, flags) {
 
   let bootstrapAgentApiKey = '';
   let bootstrapPerformed = false;
+  // API 4.0: where exits from a wallet under wallet control may pay, and the agent's action
+  // template. The API validates both and answers ownerPayout / actionTemplate (thirdfy-mcp
+  // bootstrapSelfIdentity parity).
+  const ownerPayoutAddress = String(flags.ownerPayoutAddress || '').trim();
+  const allowedActions = String(flags.allowedActions || '')
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+  let ownerPayout;
+  let actionTemplate;
   const requestedAgentApiKey = String(flags.agentApiKey || '').trim();
   const bootstrapAgentKey = String(flags.agentKey || '').trim();
   if (!requestedAgentApiKey && bootstrapAgentKey) {
@@ -308,11 +331,15 @@ async function commandLogin(ctx, flags) {
           custodyMode,
           ...(flags.walletAddress ? { walletAddress: String(flags.walletAddress).trim() } : {}),
           rotate: parseBooleanFlag(flags.rotateAgentKey, false),
+          ...(ownerPayoutAddress ? { ownerPayoutAddress } : {}),
+          ...(allowedActions.length ? { allowedActions } : {}),
         },
       });
       bootstrapAgentApiKey = String(
         bootstrapResponse?.agentApiKey || bootstrapResponse?.data?.agentApiKey || ''
       ).trim();
+      ownerPayout = bootstrapResponse?.ownerPayout || bootstrapResponse?.data?.ownerPayout;
+      actionTemplate = bootstrapResponse?.actionTemplate || bootstrapResponse?.data?.actionTemplate;
       bootstrapPerformed = true;
     }
   }
@@ -355,6 +382,8 @@ async function commandLogin(ctx, flags) {
       hasOwnerSessionToken: Boolean(ownerSessionToken),
       hasAgentApiKey: Boolean(requestedAgentApiKey || bootstrapAgentApiKey),
       bootstrapPerformed,
+      ...(ownerPayout ? { ownerPayout } : {}),
+      ...(actionTemplate ? { actionTemplate } : {}),
       runMode: loginRunMode,
       custodyMode,
       configPath: getProfileConfigPath(),
@@ -499,12 +528,15 @@ async function commandLoginEmail(ctx, flags) {
   // Persist first so operators keep session tokens even when wallet provisioning failed.
   persistProfileConfig(next);
 
+  // An EVM (0x) or Solana (base58) execution wallet counts; an agent may have only a Solana one.
   const executionWalletAddresses = Object.values(executionWallets)
     .map((row) => (row && typeof row === 'object' ? String(row.walletAddress || '').trim() : ''))
-    .filter((addr) => /^0x[a-fA-F0-9]{40}$/.test(addr));
+    .filter((addr) => isEvmAddress(addr) || isSolanaAddress(addr));
   const hasExecutionWallet = executionWalletAddresses.length > 0;
   if (runMode === 'agent_wallet' && (executionWalletsError || !hasExecutionWallet)) {
-    const fundHint = executionWalletAddresses[0] || 'the managed execution wallet address for each chain';
+    const fundHint = executionWalletAddresses.length
+      ? executionWalletAddresses.join(', ')
+      : 'the managed execution wallet address for each chain';
     throw createCliError(
       'LOGIN_EMAIL_INCOMPLETE',
       executionWalletsError
@@ -538,6 +570,13 @@ async function commandLoginEmail(ctx, flags) {
         ? {
             fundingReminder:
               'Fund executionWallets addresses for agent_wallet. Do not fund the owner embedded wallet for Path A trading.',
+            ...(executionWalletAddresses.some((addr) => isSolanaAddress(addr))
+              ? {
+                  solanaFundingReminder: `Fund the Solana execution wallet ${executionWalletAddresses
+                    .filter((addr) => isSolanaAddress(addr))
+                    .join(', ')} (base58; give the user this address, not the EVM one) with the SPL tokens (such as USDC) the agent trades. Thirdfy sponsors Solana network fees; keep a little SOL only for rent on new token accounts (about 0.002 SOL each).`,
+                }
+              : {}),
           }
         : {}),
     },

package/src/commands/chat.mjs

@@ -16,6 +16,9 @@ const NETWORK_CHAIN_IDS = {
   'arc-testnet': 5042002,
   'arc-mainnet': 5042,
   'arc': 5042,
+  // Solana (svm). Without these, --network sol-mainnet fell through to the Base default.
+  'sol-mainnet': 101,
+  'sol-devnet': 103,
 };
 
 const DEFAULT_CHAT_CHAIN_ID = 8453;

package/src/commands/credits.mjs

@@ -1,9 +1,12 @@
-import { requireFlag } from '../core/args.mjs';
+import { requireFlag, usageError } from '../core/args.mjs';
 import { apiGet, apiPost } from '../core/http.mjs';
+import { loadProfileConfig, resolveCreditsLedger } from '../core/context.mjs';
+import { createCliError } from '../core/envelope.mjs';
 import { toAvantisSpelling } from '../core/venueBrand.mjs';
 import {
   formatCreditsEstimateSummary,
   formatCreditsModelsSummary,
+  stripUsdFields,
 } from '../lib/creditsUsdSummary.mjs';
 
 function resolveToolCallsEstimate(flags) {
@@ -32,7 +35,38 @@ function resolveToolCallsEstimate(flags) {
   };
 }
 
-export function createCreditsCommands({ printEnvelope, getAuthToken }) {
+/** Thirdfy credits are bought on Base with USDC from the agent's wallet (thirdfy-api-v2 `buy-agent-credits`). */
+const CREDITS_PURCHASE_CHAIN_ID = 8453;
+
+export function createCreditsCommands({ printEnvelope, getAuthToken, buildOwnerAuthHeaders, commandWalletExecute }) {
+  /**
+   * `credits buy --usd <n>`: buy the agent's Thirdfy credits with USDC from its execution wallet on
+   * Base (gas sponsored), as thirdfy-mcp's `walletExecute buy-agent-credits` does. A shortcut for
+   * `wallet execute --action buy-agent-credits --params '{"usdAmount":n}' --chain-id 8453`; the API
+   * sets the allowed range (whole dollars, $2 to $1,000 today). A purchase whose claim did not
+   * finish answers WRITE_OUTCOME_UNKNOWN: check `credits balance`, do not buy again; `--tx-hash`
+   * resumes that purchase without paying twice. `--chain-id` defaults to Base (84532 on test APIs).
+   */
+  async function commandCreditsBuy(ctx, flags, capabilities) {
+    const raw = String(requireFlag(flags, 'usd', 'Missing --usd (whole US dollars, for example --usd 10)')).trim();
+    if (!/^\d+$/.test(raw) || Number(raw) <= 0) throw usageError('--usd must be a whole number of US dollars, for example 10', 'usd');
+    const usdAmount = Number(raw);
+    const txHash = String(flags.txHash || '').trim();
+    await commandWalletExecute(
+      ctx,
+      {
+        ...flags,
+        action: 'buy-agent-credits',
+        // txHash resumes a purchase whose payment was already sent (the catalog row takes it).
+        params: JSON.stringify({ usdAmount, ...(txHash ? { txHash } : {}) }),
+        chainId: String(flags.chainId || CREDITS_PURCHASE_CHAIN_ID),
+        estimatedAmountUsd: String(usdAmount),
+        runMode: 'agent_wallet',
+      },
+      capabilities,
+    );
+  }
+
   async function commandCreditsTransactions(ctx, flags) {
     const authToken = getAuthToken(flags, 'Missing --auth-token (or THIRDFY_AUTH_TOKEN) for credits transactions');
     const page = Number(flags.page || 1);
@@ -111,29 +145,88 @@ export function createCreditsCommands({ printEnvelope, getAuthToken }) {
     });
   }
 
+  /**
+   * `pricing quote --action <id>`: the credits one catalog action costs, and `wouldBePaidBy`
+   * (agent_credits | free_request | owner_credits | none) when the API can read the balances
+   * (thirdfy-api-v2#887). The ledger follows `resolveCreditsLedger`. Agent: `POST /agent/credits/quote`
+   * with the agent's key. Owner (session token or auth token): `/credits/pricing/quote`, for one of the
+   * owner's agents with --agent-key. An API without the agent route (404, before #887) is quoted
+   * through the owner route when owner auth is set and the key's agent is known: --agent-key, or the
+   * configured agent when the key also comes from env or config. Credits only.
+   */
   async function commandPricingQuote(ctx, flags) {
-    const authToken = getAuthToken(flags, 'Missing --auth-token (or THIRDFY_AUTH_TOKEN) for pricing quote');
     const action = requireFlag(flags, 'action', 'Missing --action for pricing quote');
-    const response = await apiPost(
-      ctx,
-      '/api/v1/credits/pricing/quote',
-      {
-        // Veranta names price as their Avantis spelling, which every API deployment knows.
-        actionKey: toAvantisSpelling(action),
-        chainId: Number(flags.chainId || 8453),
-      },
-      { Authorization: `Bearer ${authToken}` },
-    );
+    // Veranta names price as their Avantis spelling, which every API deployment knows.
+    const body = { actionKey: toAvantisSpelling(action), chainId: Number(flags.chainId || 8453) };
+    const { ledger: requestedLedger, agentApiKey, agentApiKeyExplicit } = resolveCreditsLedger(flags);
+    const flagAgentKey = String(flags.agentKey || '').trim();
+    const ownerHeaders = () =>
+      buildOwnerAuthHeaders(flags, 'Missing --owner-session-token or --auth-token (or THIRDFY_OWNER_SESSION_TOKEN / THIRDFY_AUTH_TOKEN), or an agent key, for pricing quote');
+    const ownerQuote = (agentKey) =>
+      apiPost(ctx, '/api/v1/credits/pricing/quote', { ...body, ...(agentKey ? { agentKey } : {}) }, ownerHeaders());
+    let ledger = requestedLedger;
+    let quotedAgentKey = flagAgentKey || null;
+    const warnings = [];
+    let response;
+    if (ledger === 'agent') {
+      try {
+        response = await apiPost(ctx, '/api/v1/agent/credits/quote', body, { 'x-agent-api-key': agentApiKey });
+        quotedAgentKey = response?.agentKey || null;
+        if (flagAgentKey && quotedAgentKey && flagAgentKey.toLowerCase() !== String(quotedAgentKey).toLowerCase()) {
+          warnings.push(`--agent-key ${flagAgentKey} is not the agent of this API key; the quote is for ${quotedAgentKey}.`);
+        }
+      } catch (error) {
+        if (Number(error?.statusCode) !== 404) throw error;
+        // Owner auth is needed for the older owner route, and the agent must be the key's own.
+        let hasOwner = true;
+        try {
+          ownerHeaders();
+        } catch {
+          hasOwner = false;
+        }
+        if (!hasOwner) {
+          throw createCliError(
+            'OWNER_AUTH_REQUIRED',
+            'This Thirdfy API has no agent quote route yet: pass --owner-session-token or --auth-token for an owner quote.',
+            { blockedStage: 'auth' },
+          );
+        }
+        const pairedAgentKey = flagAgentKey || (agentApiKeyExplicit ? '' : String(process.env.THIRDFY_AGENT_KEY || loadProfileConfig()?.agent?.agentKey || '').trim());
+        if (!pairedAgentKey) {
+          throw createCliError(
+            'AGENT_IDENTITY_UNAVAILABLE',
+            'This Thirdfy API has no agent quote route yet; to quote through the owner route, pass --agent-key (the agent of this API key).',
+            { blockedStage: 'auth' },
+          );
+        }
+        ledger = 'owner';
+        quotedAgentKey = pairedAgentKey;
+        response = await ownerQuote(pairedAgentKey);
+      }
+    } else {
+      response = await ownerQuote(flagAgentKey);
+    }
     printEnvelope({
       success: true,
       code: 'OK',
-      message: 'Action pricing quote generated',
-      data: response,
-      meta: { apiBase: ctx.apiBase, action },
+      // wouldBePaidBy (agent_credits | free_request | owner_credits | none), when the API sends it.
+      message: response?.wouldBePaidBy ? `Action pricing quote generated; would be paid by ${response.wouldBePaidBy}` : 'Action pricing quote generated',
+      // An action's cost is in credits only, never dollars (thirdfy-mcp quoteActionPricing).
+      data: stripUsdFields(response),
+      meta: {
+        apiBase: ctx.apiBase,
+        action,
+        ledger,
+        ...(quotedAgentKey ? { agentKey: quotedAgentKey } : {}),
+        ...(warnings.length ? { warnings } : {}),
+      },
     });
   }
 
+
+
   return {
+    commandCreditsBuy,
     commandCreditsTransactions,
     commandCreditsUsage,
     commandModelsList,

package/src/commands/delegation.mjs

@@ -426,9 +426,11 @@ async function commandDelegationRedeem(ctx, flags, capabilities) {
   if (!['thirdfy', 'hybrid', 'agent_wallet'].includes(selectedRunMode)) {
     throw createCliError('DELEGATION_REDEEM_MODE_INVALID', 'delegation redeem supports only --run-mode thirdfy|hybrid|agent_wallet');
   }
+  // Pass the run mode on only when it was given: a profile / config default must still be able to
+  // switch to agent_wallet on a Solana action (commandRun resolves the effective mode itself).
   const delegatedFlags = {
     ...flags,
-    runMode: selectedRunMode,
+    ...(flags.runMode ? { runMode: selectedRunMode } : {}),
   };
   if (!delegatedFlags.estimatedAmountUsd) {
     delegatedFlags.estimatedAmountUsd = '5';

package/src/commands/discovery.mjs

@@ -1,10 +1,58 @@
 import { requireFlag, parseJsonFlag } from '../core/args.mjs';
 import { apiGet, apiPost } from '../core/http.mjs';
-import { extractActions, getCachedActionsCatalog } from '../core/context.mjs';
+import { extractActions, getCachedActionsCatalogSnapshot, resolveCreditsLedger } from '../core/context.mjs';
 import { getEffectiveRunMode } from '../core/runMode.mjs';
-import { formatCreditsBalanceSummary } from '../lib/creditsUsdSummary.mjs';
+import { creditsFreeQuotaNote, formatCreditsBalanceSummary, stripUsdFields } from '../lib/creditsUsdSummary.mjs';
 import { filterActionsByChain } from '../runtime/actions/chainFilter.mjs';
-export function createDiscoveryCommands({ printEnvelope, applyActionFilters, getTradingProviderHint, resolveChainSupport, getAuthToken, resolveAgentApiKey }) {
+import { pageActionList, readActionListPaging } from '../runtime/actions/actionList.mjs';
+import {
+  caip2ForChainId,
+  chainRegistrySource,
+  configuredEvmChainIds,
+  configuredSvmChainIds,
+  getApiChainRegistry,
+  isSvmChainId,
+} from '../core/chainRegistry.mjs';
+import { SOLANA_PROVIDER_HINTS } from '../runtime/providerHints/solana.mjs';
+
+/** Execution lanes when the API's capabilities name none (thirdfy-mcp SUPPORTED_EXECUTION_LANES). */
+const DEFAULT_EXECUTION_LANES = Object.freeze(['thirdfy', 'hybrid', 'self', 'agent_wallet', 'validation_only']);
+
+/** Chain ids the catalog rows name (`supportedChains` and the like), EVM only. Same as thirdfy-mcp `inferCatalogEvmChainIds`. */
+function catalogEvmChainIds(rows) {
+  const found = new Set();
+  const collect = (value) => {
+    if (typeof value === 'number' && Number.isInteger(value) && value > 0) found.add(value);
+    else if (typeof value === 'string' && /^\d+$/.test(value)) found.add(Number(value));
+    else if (Array.isArray(value)) value.forEach(collect);
+  };
+  for (const row of Array.isArray(rows) ? rows : []) {
+    for (const key of ['chainId', 'chainIds', 'supportedChainIds', 'supportedChains', 'chains', 'networks']) collect(row?.[key]);
+  }
+  return [...found].filter((chainId) => !isSvmChainId(chainId)).sort((a, b) => a - b);
+}
+
+/** The Solana execution contract, as thirdfy-mcp `solanaExecutionContract` with CLI commands. */
+function solanaExecutionContract() {
+  const chainIds = configuredSvmChainIds();
+  return {
+    enabled: chainIds.length > 0,
+    chainFamily: 'svm',
+    chainIds,
+    caip2: Object.fromEntries(chainIds.map((id) => [id, caip2ForChainId(id)]).filter(([, caip2]) => caip2)),
+    requiredRunMode: 'agent_wallet',
+    supportedExecutionLanes: ['agent_wallet'],
+    wallet: "The agent's managed Privy Solana wallet. executionWalletAddress is base58 and case-sensitive.",
+    commands: ['preview', 'run', 'wallet execute', 'agent run'],
+    evmOnlyCommands: ['self-exec', 'wallet sign', 'wallet submit'],
+    providers: Object.keys(SOLANA_PROVIDER_HINTS),
+    flow: '`thirdfy-agent login email` (executionWallets) or `preflight --chain-id 101 --run-mode agent_wallet` gives the base58 executionWalletAddress -> give the user that address (not the EVM one) and fund it with the token to spend -> `run --chain-id 101 --run-mode agent_wallet` with base58 params (for example jupiter_swap {inputMint, outputMint, amount}).',
+    gas: 'Thirdfy sponsors Solana network fees (the execution-wallet reply says gasSponsored): never ask the user to buy SOL for gas. The wallet pays only rent for new token accounts (about 0.002 SOL each) and SOL the action spends; a write short of it is refused with INSUFFICIENT_NATIVE_GAS.',
+    notes:
+      'Solana execution runs only with --run-mode agent_wallet on chain 101 (103 devnet where a provider supports it). self, hybrid and thirdfy stay EVM-only. Check `actions --chain-id 101` (supportedChains) for each action\'s chains.',
+  };
+}
+export function createDiscoveryCommands({ printEnvelope, applyActionFilters, getProviderHintForActions, resolveChainSupport, getAuthToken, buildOwnerAuthHeaders, resolveAgentApiKey }) {
 async function commandCatalogsList(ctx, flags, capabilities) {
   const response = await apiGet(ctx, '/api/v1/agent/actions/catalog');
   const actions = extractActions(response);
@@ -32,20 +80,32 @@ async function commandCatalogsList(ctx, flags, capabilities) {
 }
 
 async function commandActions(ctx, flags, capabilities) {
-  const policyAware = Boolean(flags.agentApiKey);
+  // The agent's own list whenever execution would run with a key (flag, env or config), so `actions`
+  // lists what `run` / `preflight` accept, as thirdfy-mcp `getAgentActions` does.
+  const paging = readActionListPaging(flags);
+  const snapshot = await getCachedActionsCatalogSnapshot(ctx, flags);
   const chainIdFilter = Number(flags.chainId || 0) || undefined;
-  const actions = filterActionsByChain(applyActionFilters(await getCachedActionsCatalog(ctx, flags), flags), chainIdFilter);
-  const providerHint = getTradingProviderHint(flags.provider);
+  const actions = filterActionsByChain(applyActionFilters(snapshot.actions, flags), chainIdFilter);
+  const providerHint = getProviderHintForActions(flags.provider, actions);
+  // --search / --limit / --offset / --view: one page, as thirdfy-mcp getAgentActions answers.
+  const page = paging ? pageActionList(actions, paging) : null;
   const effectiveRunMode = getEffectiveRunMode(ctx, flags);
   const chainSupport = resolveChainSupport(capabilities, chainIdFilter, effectiveRunMode);
   printEnvelope({
     success: true,
     code: 'OK',
     message: 'Actions loaded',
-    data: { actions, ...(providerHint ? { providerHint } : {}) },
+    data: {
+      ...(page
+        ? { actions: page.actions, pagination: page.pagination, view: page.view, ...(page.hint ? { hint: page.hint } : {}) }
+        : { actions }),
+      ...(providerHint ? { providerHint } : {}),
+    },
     meta: {
       apiBase: ctx.apiBase,
-      policyAware,
+      // A key was sent; policyScoped: the API answered with the agent policy's allowlist.
+      policyAware: snapshot.keyed,
+      policyScoped: snapshot.policyScoped,
       runMode: effectiveRunMode,
       profile: ctx.profile || null,
       chainCompatibility: chainSupport,
@@ -54,19 +114,101 @@ async function commandActions(ctx, flags, capabilities) {
   });
 }
 
-async function commandCreditsBalance(ctx, flags, capabilities) {
-  const authToken = getAuthToken(flags, 'Missing --auth-token (or THIRDFY_AUTH_TOKEN) for credits balance');
-  const response = await apiGet(ctx, '/api/v1/credits/balance', {
-    Authorization: `Bearer ${authToken}`,
+/**
+ * `chains`: which chains Thirdfy acts on, from the API's capabilities and catalog (thirdfy-mcp
+ * `getChainCapabilities`). `--non-evm`: the Solana execution contract (`getNonEvmCapabilities`).
+ */
+async function commandChains(ctx, flags, capabilities) {
+  const svmChainIds = configuredSvmChainIds();
+  const nonEvmChains = svmChainIds.length > 0 ? ['solana'] : [];
+  const meta = { apiBase: ctx.apiBase, capabilitiesVersion: capabilities?.contractVersion || null };
+  if (flags.nonEvm) {
+    const executionEnabled = svmChainIds.length > 0;
+    printEnvelope({
+      success: true,
+      code: 'OK',
+      message: executionEnabled ? 'Solana execution is enabled' : 'Solana execution is not enabled on this API',
+      data: {
+        supportedChains: nonEvmChains,
+        executionEnabled,
+        contractVersion: 'v2',
+        chainRegistrySource: chainRegistrySource(),
+        solana: solanaExecutionContract(),
+        notes: executionEnabled
+          ? 'Solana execution is enabled through `run` / `wallet execute` / `agent run` with --run-mode agent_wallet on chain 101 (the agent\'s managed Privy Solana wallet). self-exec, wallet sign and wallet submit stay EVM-only.'
+          : 'Solana execution is not enabled on this Thirdfy API: its capabilities list no svm chain. Chains 101/103 are refused with SOLANA_NOT_ENABLED.',
+      },
+      meta,
+    });
+    return;
+  }
+  const configured = configuredEvmChainIds();
+  let catalogChainIds = [];
+  let catalogSource = 'live';
+  let catalogError;
+  try {
+    catalogChainIds = catalogEvmChainIds((await getCachedActionsCatalogSnapshot(ctx, flags)).actions);
+  } catch (error) {
+    catalogSource = 'unavailable';
+    catalogError = error?.message || String(error);
+  }
+  const apiChains = getApiChainRegistry()?.chains;
+  printEnvelope({
+    success: true,
+    code: 'OK',
+    message: 'Chain capabilities loaded',
+    data: {
+      supportedEvmChainIds: [...new Set([...configured, ...catalogChainIds])].sort((a, b) => a - b),
+      configuredEvmChainIds: configured,
+      catalogEvmChainIds: catalogChainIds,
+      catalogSource,
+      ...(catalogError ? { catalogError } : {}),
+      supportedNonEvmChains: nonEvmChains,
+      supportedSvmChainIds: svmChainIds,
+      chainRegistrySource: chainRegistrySource(),
+      caip2: Object.fromEntries(
+        [...configured, ...svmChainIds].map((id) => [id, caip2ForChainId(id)]).filter(([, caip2]) => caip2),
+      ),
+      supportedExecutionLanes: Array.isArray(capabilities?.runModes) && capabilities.runModes.length
+        ? capabilities.runModes
+        : [...DEFAULT_EXECUTION_LANES],
+      defaultChainId: 8453,
+      defaultExecutionLane: getEffectiveRunMode(ctx, flags),
+      nonEvmExecutionContract: solanaExecutionContract(),
+      // Each chain the API lists, with its execution lanes (CLI only; the MCP has no per-chain lanes).
+      ...(apiChains ? { chains: apiChains } : {}),
+    },
+    meta,
   });
+}
+
+/**
+ * `credits balance`. Owner auth reads the owner's balance (`/credits/balance`). An explicit
+ * --agent-api-key, or no owner auth but an agent key in env or config, reads the agent's own ledger
+ * (`/agent/credits/balance`: its credits, free requests today and the owner-credits fallback), as
+ * thirdfy-mcp getCreditsBalance. Credits only, never dollars.
+ */
+async function commandCreditsBalance(ctx, flags, capabilities) {
+  const { ledger, agentApiKey } = resolveCreditsLedger(flags);
+  const agentLedger = ledger === 'agent';
+  const response = agentLedger
+    ? await apiGet(ctx, '/api/v1/agent/credits/balance', { 'x-agent-api-key': agentApiKey })
+    : await apiGet(
+        ctx,
+        '/api/v1/credits/balance',
+        buildOwnerAuthHeaders(flags, 'Missing --owner-session-token or --auth-token (or THIRDFY_OWNER_SESSION_TOKEN / THIRDFY_AUTH_TOKEN), or an agent key for the agent\'s own credits, for credits balance'),
+      );
   const summary = formatCreditsBalanceSummary(response);
+  const note = creditsFreeQuotaNote(response);
   printEnvelope({
     success: true,
     code: 'OK',
     message: flags.json ? 'Credits balance loaded' : `Credits balance loaded: ${summary}`,
-    data: response,
+    // Credits only: no USD price per credit (thirdfy-mcp getCreditsBalance).
+    data: { ...stripUsdFields(response), ...(note ? { note } : {}) },
     meta: {
       apiBase: ctx.apiBase,
+      ledger: agentLedger ? 'agent' : 'owner',
       capabilitiesVersion: capabilities?.contractVersion || null,
       ...(flags.json ? {} : { summary }),
     },
@@ -76,6 +218,7 @@ async function commandCreditsBalance(ctx, flags, capabilities) {
   return {
     commandCatalogsList,
     commandActions,
+    commandChains,
     commandCreditsBalance,
   };
 }