@thirdfy/agent-cli 0.3.0 → 0.4.0

package/src/runtime/providerHints/prediction.mjs

@@ -0,0 +1,128 @@
+/**
+ * Static provider hints. Prediction markets: Polymarket and the venue-neutral `prediction` provider.
+ * Each entry builds the hint for one provider id; `dispatch.mjs` picks the entry.
+ */
+export const PREDICTION_PROVIDER_HINTS = Object.freeze({
+  polymarket: ({ provider }) => ({
+    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_funding_status',
+      'get_polymarket_setup_status',
+      'get_polymarket_onboarding_plan',
+      'get_polymarket_bridge_supported_assets',
+      'get_polymarket_bridge_status',
+      'get_polymarket_order',
+      'get_polymarket_user_orders',
+      'get_polymarket_user_positions',
+      'get_polymarket_balance_allowance',
+    ],
+    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_funding_status with agentKey (check deposit pUSD + nested setup status)',
+      'when Base USDC is on execution wallet: create_polymarket_bridge_deposit then execute_polymarket_bridge_deposit with confirm=true',
+      'get_polymarket_bridge_status until pUSD lands',
+      'get_polymarket_setup_status with agentKey (check liveOrderReady + apiExecutionGeoblockReady) before place_polymarket_order',
+    ],
+    orderManagementActions: [
+      'place_polymarket_order',
+      'get_polymarket_order',
+      'get_polymarket_user_orders',
+      'get_polymarket_user_positions',
+      'get_polymarket_balance_allowance',
+      'cancel_polymarket_order',
+    ],
+    setupActions: [
+      'get_polymarket_funding_status',
+      'get_polymarket_setup_status',
+      'get_polymarket_onboarding_plan',
+      'create_polymarket_bridge_deposit',
+      'execute_polymarket_bridge_deposit',
+      'prepare_polymarket_onboarding',
+      '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 (derive miss -> create via EU egress)',
+      'browser_setup:add_privy_signer',
+      'browser_setup:create_or_derive_clob_credentials',
+      'browser_setup:deploy_deposit_wallet_and_set_approvals',
+      'agent_wallet_setup:create_or_derive_clob_credentials',
+    ],
+    statusActions: [
+      'get_polymarket_funding_status',
+      'get_polymarket_setup_status',
+      'get_polymarket_recovery_status',
+    ],
+    recoveryActions: [
+      'get_polymarket_recovery_status',
+      'create_polymarket_bridge_withdraw',
+      'execute_polymarket_bridge_withdraw',
+      'get_polymarket_bridge_status',
+      'withdraw_polymarket_collateral',
+    ],
+    decommissionExample: 'get_polymarket_recovery_status -> create_polymarket_bridge_withdraw -> execute_polymarket_bridge_withdraw -> get_polymarket_bridge_status -> withdraw-to-user (legacy: withdraw_polymarket_collateral + Li.Fi)',
+    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 deposit-wallet deployment and approvals. If users start with Base USDC, use Polymarket official Bridge (create_polymarket_bridge_deposit / execute_polymarket_bridge_deposit) from the execution wallet. Li.Fi get_bridge_quote is legacy fallback only.',
+    laneCompatibility: 'Use agent_wallet as the preferred autonomous-agent path: Thirdfy ensures the agent owner signer and deposit wallet, while users fund pUSD into that deposit wallet. Use self/BYOW only for user-owned setup/funding signatures. CLOB order placement is an offchain venue write and should use thirdfy, hybrid, or agent_wallet after polymarket_clob credentials are stored. Production API execution geoblock uses Ireland (Vercel dub1) via internal EU service — check apiExecutionGeoblockReady on setup status, not only runtime/Fly egress.',
+    setupBlockers: [
+      'POLYMARKET_EU_SERVICE_UNAVAILABLE',
+      'POLYMARKET_EU_CONTRACT_MISMATCH',
+      'POLYMARKET_GEOBLOCKED',
+      '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',
+      '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"}\'',
+    readinessFields: [
+      'liveOrderReady',
+      'apiExecutionGeoblockReady',
+      'runtimeGeoblockReady',
+      'setupNextAction',
+      'blockingReasons',
+    ],
+    monetization: 'CLOB V2 builder attribution uses server-side POLYMARKET_BUILDER_CODE. Polymarket relayer gas is separate from Thirdfy credits; credits gate Thirdfy orchestration/order execution, while user/agent deposit-wallet pUSD collateral funds trades.',
+  }),
+  prediction: ({ provider }) => ({
+    provider,
+    category: 'prediction',
+    canonicalWriteAction: 'place_prediction_order',
+    readActions: [
+      'get_prediction_tags',
+      'get_prediction_markets',
+      'get_prediction_events',
+      'get_prediction_event',
+      'get_prediction_market',
+      'get_prediction_order_book',
+      'search_prediction_markets',
+    ],
+    discoveryFlow: [
+      'get_prediction_tags (humans resolve tag_id once)',
+      'get_prediction_markets with numeric tag_id + end_date_min/end_date_max + liquidity_num_min',
+      'get_prediction_order_book when outcomePrices/bestAsk are missing',
+      'place_prediction_order after setup/funding/preflight',
+      'search_prediction_markets only for human text/slug lookup (not agent discovery)',
+    ],
+    orderManagementActions: ['place_prediction_order', 'cancel_prediction_order'],
+    compatibilityProvider: 'polymarket',
+  }),
+});

package/src/runtime/providerHints/solana.mjs

@@ -0,0 +1,85 @@
+/**
+ * Static provider hints. Solana families (chain 101, agent_wallet only). Same facts as thirdfy-mcp `src/tools/providers/solanaProviderHints.ts`; the catalog stays the source of truth for action names, params and chains.
+ * Each entry builds the hint for one provider id; `dispatch.mjs` picks the entry.
+ */
+export const SOLANA_PROVIDER_HINTS = Object.freeze({
+  jupiter: ({ provider }) => ({
+    provider,
+    category: 'onchain_spot',
+    canonicalReadAction: 'get_jupiter_quote',
+    canonicalWriteAction: 'jupiter_swap',
+    readActions: ['get_jupiter_quote'],
+    orderManagementActions: ['jupiter_swap'],
+    supportedChains: [101],
+    laneCompatibility: 'Jupiter spot swaps. Params: inputMint, outputMint (base58 mints, Jupiter-verified), amount in human units of inputMint. Solana mainnet (chainId 101) only, runMode=agent_wallet on the agent\'s managed Privy Solana wallet. self/BYOW, hybrid and thirdfy lanes are EVM-only. Fund the base58 executionWalletAddress (`thirdfy-agent login email` lists it under executionWallets; `preflight --chain-id 101 --run-mode agent_wallet` returns it) with the token you spend, and give the user that base58 address, not the EVM one. Thirdfy sponsors the network fee (gasSponsored); keep a little SOL only for rent on new token accounts (about 0.002 SOL each) and any SOL the action spends. Jupiter swaps that Jupiter does not sponsor itself still pay their fee in SOL.',
+    example: 'thirdfy-agent run --action jupiter_swap --chain-id 101 --run-mode agent_wallet --params \'{"inputMint":"EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v","outputMint":"So11111111111111111111111111111111111111112","amount":"5"}\' --json',
+  }),
+  solana: ({ provider }) => ({
+    provider,
+    category: 'wallet',
+    canonicalReadAction: 'get_solana_balances',
+    canonicalWriteAction: 'solana_transfer',
+    readActions: ['get_solana_balances'],
+    orderManagementActions: ['solana_transfer'],
+    supportedChains: [101],
+    laneCompatibility: 'SOL and SPL balances and transfers. solana_transfer params: toAddress (base58), amount, optional mint (omit for native SOL). Solana mainnet (chainId 101) only, runMode=agent_wallet on the agent\'s managed Privy Solana wallet. self/BYOW, hybrid and thirdfy lanes are EVM-only. Fund the base58 executionWalletAddress (`thirdfy-agent login email` lists it under executionWallets; `preflight --chain-id 101 --run-mode agent_wallet` returns it) with the token you spend, and give the user that base58 address, not the EVM one. Thirdfy sponsors the network fee (gasSponsored); keep a little SOL only for rent on new token accounts (about 0.002 SOL each) and any SOL the action spends. Jupiter swaps that Jupiter does not sponsor itself still pay their fee in SOL.',
+  }),
+  'jupiter-prediction': ({ provider }) => ({
+    provider,
+    category: 'prediction_markets',
+    canonicalReadAction: 'get_jupiter_prediction_events',
+    canonicalWriteAction: 'place_jupiter_prediction_order',
+    readActions: [
+      'get_jupiter_prediction_events',
+      'get_jupiter_prediction_market',
+      'get_jupiter_prediction_positions',
+    ],
+    orderManagementActions: [
+      'place_jupiter_prediction_order',
+      'close_jupiter_prediction_position',
+      'claim_jupiter_prediction_payout',
+    ],
+    supportedChains: [101],
+    laneCompatibility: 'Jupiter prediction markets. Read the event and market first; the catalog paramsSchema names the order fields. Solana mainnet (chainId 101) only, runMode=agent_wallet on the agent\'s managed Privy Solana wallet. self/BYOW, hybrid and thirdfy lanes are EVM-only. Fund the base58 executionWalletAddress (`thirdfy-agent login email` lists it under executionWallets; `preflight --chain-id 101 --run-mode agent_wallet` returns it) with the token you spend, and give the user that base58 address, not the EVM one. Thirdfy sponsors the network fee (gasSponsored); keep a little SOL only for rent on new token accounts (about 0.002 SOL each) and any SOL the action spends. Jupiter swaps that Jupiter does not sponsor itself still pay their fee in SOL.',
+  }),
+  'jupiter-lend': ({ provider }) => ({
+    provider,
+    category: 'earn',
+    canonicalReadAction: 'get_jupiter_lend_vaults',
+    canonicalWriteAction: 'jupiter_lend_deposit',
+    readActions: ['get_jupiter_lend_vaults', 'get_jupiter_lend_positions'],
+    orderManagementActions: ['jupiter_lend_deposit', 'jupiter_lend_withdraw'],
+    supportedChains: [101],
+    laneCompatibility: 'Jupiter Lend earn vaults. Writes take asset and amount. Solana mainnet (chainId 101) only, runMode=agent_wallet on the agent\'s managed Privy Solana wallet. self/BYOW, hybrid and thirdfy lanes are EVM-only. Fund the base58 executionWalletAddress (`thirdfy-agent login email` lists it under executionWallets; `preflight --chain-id 101 --run-mode agent_wallet` returns it) with the token you spend, and give the user that base58 address, not the EVM one. Thirdfy sponsors the network fee (gasSponsored); keep a little SOL only for rent on new token accounts (about 0.002 SOL each) and any SOL the action spends. Jupiter swaps that Jupiter does not sponsor itself still pay their fee in SOL.',
+  }),
+  'solana-staking': ({ provider }) => ({
+    provider,
+    category: 'staking',
+    canonicalReadAction: 'get_solana_staking_info',
+    canonicalWriteAction: 'solana_stake',
+    readActions: ['get_solana_staking_info', 'get_solana_staking_positions'],
+    orderManagementActions: ['solana_stake', 'solana_unstake', 'solana_withdraw_stake'],
+    supportedChains: [101],
+    laneCompatibility: 'Native SOL staking. solana_unstake deactivates a stake account; solana_withdraw_stake moves SOL back after deactivation completes. Solana mainnet (chainId 101) only, runMode=agent_wallet on the agent\'s managed Privy Solana wallet. self/BYOW, hybrid and thirdfy lanes are EVM-only. Fund the base58 executionWalletAddress (`thirdfy-agent login email` lists it under executionWallets; `preflight --chain-id 101 --run-mode agent_wallet` returns it) with the token you spend, and give the user that base58 address, not the EVM one. Thirdfy sponsors the network fee (gasSponsored); keep a little SOL only for rent on new token accounts (about 0.002 SOL each) and any SOL the action spends. Jupiter swaps that Jupiter does not sponsor itself still pay their fee in SOL.',
+  }),
+  'kamino-vaults': ({ provider }) => ({
+    provider,
+    category: 'earn',
+    canonicalReadAction: 'get_kamino_vaults',
+    canonicalWriteAction: 'kamino_vault_deposit',
+    readActions: ['get_kamino_vaults', 'get_kamino_vault_positions'],
+    orderManagementActions: ['kamino_vault_deposit', 'kamino_vault_withdraw'],
+    supportedChains: [101],
+    laneCompatibility: 'Kamino earn vaults. Writes take vault (base58 address from get_kamino_vaults) and amount. Solana mainnet (chainId 101) only, runMode=agent_wallet on the agent\'s managed Privy Solana wallet. self/BYOW, hybrid and thirdfy lanes are EVM-only. Fund the base58 executionWalletAddress (`thirdfy-agent login email` lists it under executionWallets; `preflight --chain-id 101 --run-mode agent_wallet` returns it) with the token you spend, and give the user that base58 address, not the EVM one. Thirdfy sponsors the network fee (gasSponsored); keep a little SOL only for rent on new token accounts (about 0.002 SOL each) and any SOL the action spends. Jupiter swaps that Jupiter does not sponsor itself still pay their fee in SOL.',
+  }),
+  meteora: ({ provider }) => ({
+    provider,
+    category: 'liquidity_provision',
+    canonicalReadAction: 'get_meteora_pools',
+    canonicalWriteAction: 'open_meteora_position',
+    readActions: ['get_meteora_pools', 'get_meteora_positions'],
+    orderManagementActions: ['open_meteora_position', 'remove_meteora_liquidity', 'claim_meteora_fees'],
+    supportedChains: [101],
+    laneCompatibility: 'Meteora liquidity positions. open_meteora_position takes pool, amountX, amountY; remove_meteora_liquidity and claim_meteora_fees take position (base58). Solana mainnet (chainId 101) only, runMode=agent_wallet on the agent\'s managed Privy Solana wallet. self/BYOW, hybrid and thirdfy lanes are EVM-only. Fund the base58 executionWalletAddress (`thirdfy-agent login email` lists it under executionWallets; `preflight --chain-id 101 --run-mode agent_wallet` returns it) with the token you spend, and give the user that base58 address, not the EVM one. Thirdfy sponsors the network fee (gasSponsored); keep a little SOL only for rent on new token accounts (about 0.002 SOL each) and any SOL the action spends. Jupiter swaps that Jupiter does not sponsor itself still pay their fee in SOL.',
+  }),
+});

package/src/runtime/providerHints/trading.mjs

@@ -0,0 +1,78 @@
+/**
+ * Static provider hints. On-chain spot trading, bridging and FX: the `trading` provider, `bridge`, `fx` and BasedBid launches.
+ * Each entry builds the hint for one provider id; `dispatch.mjs` picks the entry.
+ */
+export const TRADING_PROVIDER_HINTS = Object.freeze({
+  trading: ({ provider }) => ({
+    provider,
+    category: 'onchain_spot',
+    canonicalWriteAction: 'swap',
+    supportedChains: [1, 10, 130, 137, 8453, 84532, 42161, 4663],
+    laneCompatibility: 'Kyber quote/build is live on Ethereum, Optimism, Unichain, Polygon, Base, and Arbitrum; sponsored Kyber execution is validated on Base only. Robinhood Chain (4663) uses Li.Fi Intents for spot swaps with user-pays gas. Gnosis FX uses the fx provider via CoW. Pass private: true to swap from the shielded (Bermuda) balance on a fresh burner where a Bermuda pool exists (Base Sepolia 84532 today); it fails instead of falling back to a public swap.',
+    credentialUx: 'Use normal Thirdfy login/delegation; do not use this provider for Hyperliquid, Lighter, or Polymarket.',
+    readActions: ['get_best_trading_quote', 'search_tokens', 'get_token_metadata'],
+    tokenLookup: 'A symbol swap cannot resolve answers TOKEN_NOT_FOUND. Then: 1) search_tokens { query: <symbol>, chainId } (Base 8453, Ethereum 1, Arbitrum 42161, Optimism 10, Polygon 137, Unichain 130, Gnosis 100, World Chain 480, Robinhood 4663, Solana 101, DogeOS testnet 6281971; omit chainId to search all). Candidates and risk come from market-data providers (GeckoTerminal, Jupiter, CoinMarketCap, GMGN; Laika on DogeOS). 2) Show the user every candidate: name, symbol, chain, address, liquidityUsd, risk and warnings. 3) Ask the user which one they mean. 4) Swap with that address on its chain. Never guess or construct an address. A token with risk "high", "medium" or "unknown" may be a scam copy or unchecked: tell the user its warnings and get their confirmation before the swap. To check an address the user gave, use get_token_metadata { tokenIdentifier: "0x..." or Solana mint, chainId }.',
+    example: 'thirdfy-agent run --action swap --params \'{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000"}\'',
+  }),
+  bridge: ({ provider }) => ({
+    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,
+      4663,
+    ],
+    laneCompatibility: 'Li.Fi bridge supports mainnet value movement only; testnets are not auto-mapped to mainnet.',
+  }),
+  fx: ({ provider }) => ({
+    provider,
+    category: 'fx',
+    canonicalReadAction: 'get_fx_supported_assets',
+    readActions: ['get_fx_supported_assets', 'get_monerium_profile_status', 'quote_fx_swap'],
+    supportedChains: [100],
+    laneCompatibility: 'Gnosis FX: quote_fx_swap is read-only; execute swaps via trading/cow on chain 100. Monerium payments require credentials.',
+  }),
+  basedbid: ({ provider }) => ({
+    provider,
+    category: 'spot',
+    canonicalReadAction: 'basedbid_get_tokens',
+    canonicalWriteAction: 'basedbid_create_lbp',
+    readActions: ['basedbid_get_tokens'],
+    orderManagementActions: [
+      'basedbid_create_lbp',
+      'basedbid_create_flash',
+      'basedbid_create_board',
+      'basedbid_buy',
+      'basedbid_sell',
+      'basedbid_claim_fees',
+      'basedbid_update_hook',
+    ],
+    supportedChains: [8453, 1, 4663],
+    laneCompatibility: 'basedbid launchpad. Discovery is read-only. LBP and flash create, buy, and sell are write-enabled on 8453, 1, and 4663. Buy spends native ETH on the target chain. Board, fee claim, and hook writes stay fail-closed. Writes take the preview-then-run path (`thirdfy-agent preview`, then `run`).',
+    example: 'thirdfy-agent run --action basedbid_get_tokens --params \'{"chainId":8453,"limit":10}\' --provider basedbid --json',
+  }),
+});

package/src/runtime/providerHints/walletControl.mjs

@@ -0,0 +1,39 @@
+/**
+ * Provider notes for wallets under Thirdfy API 4.0 wallet control (`walletControl.owner` is `user` or
+ * `owner_quorum`), as thirdfy-mcp `src/tools/providers/walletControlHints.ts`. On those wallets the API
+ * pays exits only to owner destinations, and Privy refuses contract calls the signing policy cannot
+ * pin (Kyber, Li.Fi, multicall wrappers, Bermuda, CCTP, Lighter). The API refuses an uncovered call
+ * before signing, so these notes say what to expect, not what is enforced here.
+ */
+
+export const EXIT_DESTINATION_OWNER_ONLY_NOTE =
+  "On a wallet under wallet control (walletControl.owner user or owner_quorum), withdraw-to-user and every other exit with a destination pay only the wallet itself, the owner payout address or the owner's wallet; any other destination is refused with WITHDRAW_DESTINATION_NOT_OWNER before signing.";
+
+const UNCOVERED_ROUTERS_NOTE =
+  'On a wallet under wallet control, Kyber and Li.Fi routes are not covered by the signing policy and are refused before signing.';
+
+const LIGHTER_NOTE =
+  'Lighter onboarding and funding (complete_lighter_onboarding, approve_lighter_integrator and the CCTP deposit intent) need the owner key and are not supported on a wallet under wallet control.';
+
+const MULTICALL_NOTE =
+  'On a wallet under wallet control, multicall position calls (Uniswap v3/v4 LP, Aegis) are not covered by the signing policy and are refused before signing.';
+
+const BERMUDA_NOTE = 'On a wallet under wallet control, Bermuda pool calls are not covered by the signing policy and are refused before signing.';
+
+const PROVIDER_NOTES = Object.freeze({
+  trading: UNCOVERED_ROUTERS_NOTE,
+  bridge: UNCOVERED_ROUTERS_NOTE,
+  lifi: UNCOVERED_ROUTERS_NOTE,
+  lighter: LIGHTER_NOTE,
+  uniswap: MULTICALL_NOTE,
+  aegis: MULTICALL_NOTE,
+  bermuda: BERMUDA_NOTE,
+});
+
+/** The wallet-control note for a provider's hint, or undefined when none applies. */
+export function walletControlProviderNote(provider, hint) {
+  const notes = [];
+  if (Object.prototype.hasOwnProperty.call(PROVIDER_NOTES, provider)) notes.push(PROVIDER_NOTES[provider]);
+  if (/withdraw-to-user|withdraw_to_user/.test(String(hint?.decommissionExample || ''))) notes.push(EXIT_DESTINATION_OWNER_ONLY_NOTE);
+  return notes.length ? notes.join(' ') : undefined;
+}

package/src/runtime/risk/notional.mjs

@@ -0,0 +1,59 @@
+import { createCliError } from '../../core/envelope.mjs';
+import { isReadOnlyResolvedAction } from '../../core/readOnlyActions.mjs';
+import { resolveExecuteEstimatedAmountUsd } from '../execution/payloads.mjs';
+
+/**
+ * The USD notional of a write (`--estimated-amount-usd`), as thirdfy-mcp `walletExecute` checks it.
+ * Spend limits are checked against it; a write sent without it is checked against $0.
+ */
+
+export const NOTIONAL_WARNING =
+  'estimatedAmountUsd was not sent for this write. Send the USD notional it moves; a later release will refuse writes without it.';
+
+/**
+ * True when a write needs its USD notional: the catalog row's `behavior.requiresEstimatedAmountUsd`
+ * when the API publishes it, else true (a cancel or approval row says false).
+ */
+export function writeNeedsNotional(behavior) {
+  return typeof behavior?.requiresEstimatedAmountUsd === 'boolean' ? behavior.requiresEstimatedAmountUsd : true;
+}
+
+/** `THIRDFY_NOTIONAL_ESTIMATE_MODE`: `refuse`, or `warn` for anything else (unset included). */
+export function notionalEstimateMode(env = process.env) {
+  return String(env.THIRDFY_NOTIONAL_ESTIMATE_MODE || '').trim().toLowerCase() === 'refuse' ? 'refuse' : 'warn';
+}
+
+/**
+ * For a write about to be sent with no USD notional: refuses it with ESTIMATED_AMOUNT_USD_REQUIRED
+ * in `refuse` mode (nothing is sent), and otherwise returns the warning to put in `meta.warnings`.
+ * Returns null when the write has its notional or does not need one.
+ */
+export function checkWriteNotional({ action, estimatedAmountUsd, behavior, env = process.env }) {
+  if (estimatedAmountUsd != null || !writeNeedsNotional(behavior)) return null;
+  if (notionalEstimateMode(env) === 'refuse') {
+    throw createCliError(
+      'ESTIMATED_AMOUNT_USD_REQUIRED',
+      `${action} is a write: send --estimated-amount-usd, the USD notional it moves (THIRDFY_NOTIONAL_ESTIMATE_MODE=refuse).`,
+      { action },
+    );
+  }
+  return NOTIONAL_WARNING;
+}
+
+/** Run modes whose write carries `estimatedAmountUsd` to the API (`/execute`, `/execute-intent`). */
+const NOTIONAL_RUN_MODES = new Set(['agent_wallet', 'thirdfy']);
+
+/**
+ * The notional check for `run`, `wallet execute` and `agent run`: `meta.warnings` for a write sent
+ * without --estimated-amount-usd (empty when none applies), or a throw in `refuse` mode.
+ */
+export function runNotionalWarnings(resolved, flags, runMode, env = process.env) {
+  if (!NOTIONAL_RUN_MODES.has(runMode) || isReadOnlyResolvedAction(resolved)) return [];
+  const warning = checkWriteNotional({
+    action: resolved.resolvedAction,
+    estimatedAmountUsd: resolveExecuteEstimatedAmountUsd(resolved.resolvedAction, flags),
+    behavior: resolved.resolvedActionMeta?.behavior,
+    env,
+  });
+  return warning ? [warning] : [];
+}

package/src/runtime/risk/orderPreview.mjs

@@ -0,0 +1,154 @@
+import { randomUUID } from 'crypto';
+import { createCliError } from '../../core/envelope.mjs';
+import { chainGasNote } from '../../core/chainRegistry.mjs';
+import { findRiskRefusal, riskRefusalMessage } from './riskRefusal.mjs';
+import { writeNeedsNotional } from './notional.mjs';
+
+/**
+ * `preview`: what Thirdfy would decide about a write before it is sent, from the action-aware
+ * execution-wallet preflight (`GET /agent/execution-wallet?action=&params=`), which runs the same
+ * policy, venue-readiness and risk-policy checks as `/agent/execute`. Same verdict as thirdfy-mcp
+ * `previewOrder` (`src/tools/risk/previewOrder.ts`). Nothing is signed, billed or reserved.
+ */
+
+export const NO_RISK_POLICY_NOTE = 'No risk policy set; only spend limits apply.';
+export const NO_ORDER_PREVIEW_NOTE =
+  'No orderPreview for this write: it carries no USD amount (a cancel, approval or setting), so only the action and policy checks apply.';
+/** The API's spend preview (previewKind "spend"): its rows are the enforced spend limits. */
+export const SPEND_PREVIEW_NOTE =
+  'No risk policy set (leverage and loss-at-stop limits); the spend limits shown are enforced. Liquidation price and loss at the stop are not computed for this order.';
+
+const isRecord = (value) => Boolean(value && typeof value === 'object' && !Array.isArray(value));
+
+/**
+ * The preflight answer as a short verdict. `preflight` is the CLI's managed-wallet preflight result
+ * for an action (allowed, or blocked by the API); a blocked order is a verdict, not a failure.
+ */
+export function shapeOrderPreview({ action, chainId, preflight }) {
+  const data = isRecord(preflight) ? preflight : {};
+  const actionPreflight = isRecord(data.actionPreflight) ? data.actionPreflight : {};
+  // A chain whose wallet pays gas (DogeOS): the preflight answers success at 0 balance (gasReady
+  // false, nativeGasWarning), but the send refuses it. Solana has a note too (sponsored fees), and a
+  // Solana wallet at 0 SOL is normal there, so it is never blocked on gas here.
+  const gas = chainGasNote(chainId, { gasSponsored: data.gasSponsored });
+  const gasWarning = isRecord(data.nativeGasWarning) ? data.nativeGasWarning : undefined;
+  const noGas = gas?.sponsored === false && (data.gasReady === false || gasWarning?.code === 'INSUFFICIENT_NATIVE_GAS');
+  const preflightBlocked = data.success === false;
+  const blocked = preflightBlocked || noGas;
+  const orderPreview = isRecord(data.orderPreview)
+    ? data.orderPreview
+    : isRecord(actionPreflight.orderPreview)
+      ? actionPreflight.orderPreview
+      : undefined;
+  const riskRefusal = findRiskRefusal(data);
+  const amountUsd = typeof actionPreflight.amountUsd === 'number' ? actionPreflight.amountUsd : undefined;
+  // Venue warnings that do not block (Hyperliquid: a stop past the estimated liquidation price).
+  const warnings = Array.isArray(actionPreflight.warnings)
+    ? actionPreflight.warnings.filter((warning) => isRecord(warning) && typeof warning.message === 'string')
+    : [];
+  const reason =
+    typeof data.error === 'string' && data.error && data.error !== data.blockedReason ? data.error : undefined;
+  const note = !orderPreview
+    ? NO_ORDER_PREVIEW_NOTE
+    : orderPreview.previewKind === 'spend'
+      ? SPEND_PREVIEW_NOTE
+      : orderPreview.riskPolicyEnforced === false
+        ? `${NO_RISK_POLICY_NOTE} The policy rows are informational.`
+        : undefined;
+  const gasMessage = noGas ? (typeof gasWarning?.message === 'string' && gasWarning.message) || gas?.note : undefined;
+  const noteWithGas = gas && !noGas ? [note, gas.note].filter(Boolean).join(' ') : note;
+  const venueSetup = isRecord(data.venueSetup) ? data.venueSetup : actionPreflight.venueSetup;
+  return {
+    action,
+    chainId,
+    success: !blocked,
+    wouldSign: typeof orderPreview?.wouldSign === 'boolean' ? orderPreview.wouldSign && !blocked : !blocked,
+    ...(preflightBlocked
+      ? {
+          blockedReason: data.blockedReason || 'PREFLIGHT_BLOCKED',
+          blockedStage: data.blockedStage || 'preflight',
+          ...(reason ? { reason } : {}),
+        }
+      : noGas
+        ? { blockedReason: 'INSUFFICIENT_NATIVE_GAS', blockedStage: 'gas', nextAction: 'fund_native_gas' }
+        : {}),
+    ...(riskRefusal
+      ? { riskRefusal, message: riskRefusalMessage(riskRefusal) }
+      : gasMessage
+        ? { message: gasMessage }
+        : {}),
+    ...(gas ? { gas } : {}),
+    ...(amountUsd != null ? { amountUsd } : {}),
+    ...(orderPreview ? { orderPreview } : {}),
+    ...(warnings.length ? { warnings: warnings.map((warning) => ({ code: warning.code, message: warning.message })) } : {}),
+    ...(noteWithGas ? { note: noteWithGas } : {}),
+    // The venue lacks setup only: Thirdfy runs it by itself with the first order (no funds move).
+    ...(isRecord(venueSetup) && venueSetup.runsWithOrder === true ? { venueSetup } : {}),
+  };
+}
+
+/**
+ * A write that moves value which Thirdfy could not size: no --estimated-amount-usd, and neither the
+ * preflight (`amountUsd`) nor the preview (`notionalUsd`) derived one from the params. The limits
+ * were checked against $0, so "would sign" would be a verdict on nothing. Throws
+ * ESTIMATED_AMOUNT_USD_REQUIRED (a request to fix, not a verdict).
+ */
+export function assertPreviewSized({ shaped, estimatedAmountUsd, behavior }) {
+  const sizedUsd = Math.max(
+    typeof shaped.amountUsd === 'number' ? shaped.amountUsd : 0,
+    isRecord(shaped.orderPreview) && typeof shaped.orderPreview.notionalUsd === 'number' ? shaped.orderPreview.notionalUsd : 0,
+  );
+  if (shaped.success !== true || estimatedAmountUsd != null || sizedUsd > 0 || !writeNeedsNotional(behavior)) return;
+  throw createCliError(
+    'ESTIMATED_AMOUNT_USD_REQUIRED',
+    `${shaped.action} moves value: run preview again with --estimated-amount-usd, the USD value of the order (for a swap, the USD value of what is sold), so the limits are checked against it.`,
+    { action: shaped.action },
+  );
+}
+
+const SCHEMA_CONFIRMATION_KEYS = ['confirmWrites', 'confirm'];
+
+/** True when the action's catalog `paramsSchema` lists `confirmWrites` or `confirm`. */
+export function schemaTakesConfirmation(schema) {
+  const properties = isRecord(schema?.properties) ? schema.properties : null;
+  return Boolean(properties && SCHEMA_CONFIRMATION_KEYS.some((key) => Object.prototype.hasOwnProperty.call(properties, key)));
+}
+
+/**
+ * The order a would-sign preview describes: the `run` arguments, with one idempotency key for this
+ * preview so the same order is never placed twice, and `command`, the argv to place it. Without the
+ * caller's estimate, the size the API resolved (`amountUsd`, or the preview's `notionalUsd`) stands in,
+ * so the run is not refused for it. Undefined when Thirdfy would not sign it.
+ */
+export function buildPreviewOrder({ shaped, params, estimatedAmountUsd, paramsSchema }) {
+  if (shaped.wouldSign !== true) return undefined;
+  // The API's amountUsd, or the venue preview's notionalUsd when only the preview sized the order
+  // (the same size assertPreviewSized accepts; thirdfy-mcp #249).
+  const sizedUsd = Math.max(
+    typeof shaped.amountUsd === 'number' ? shaped.amountUsd : 0,
+    isRecord(shaped.orderPreview) && typeof shaped.orderPreview.notionalUsd === 'number' ? shaped.orderPreview.notionalUsd : 0,
+  );
+  const usd = typeof estimatedAmountUsd === 'number' ? estimatedAmountUsd : sizedUsd > 0 ? sizedUsd : undefined;
+  const confirmWrites = schemaTakesConfirmation(paramsSchema);
+  const executionIdempotencyKey = `preview-${randomUUID()}`;
+  const command = [
+    'thirdfy-agent', 'run', '--run-mode', 'agent_wallet',
+    '--action', shaped.action,
+    '--params', JSON.stringify(params || {}),
+    '--chain-id', String(shaped.chainId),
+    ...(usd !== undefined ? ['--estimated-amount-usd', String(usd)] : []),
+    '--idempotency-key', executionIdempotencyKey,
+    ...(confirmWrites ? ['--confirm-writes'] : []),
+    '--json',
+  ];
+  return {
+    action: shaped.action,
+    params: params || {},
+    chainId: shaped.chainId,
+    runMode: 'agent_wallet',
+    ...(usd !== undefined ? { estimatedAmountUsd: usd } : {}),
+    ...(confirmWrites ? { confirmWrites: true } : {}),
+    executionIdempotencyKey,
+    command,
+  };
+}

package/src/runtime/risk/riskRefusal.mjs

@@ -0,0 +1,74 @@
+/**
+ * Thirdfy agent risk policy refusals (thirdfy-api-v2 `policy/risk/`), as thirdfy-mcp
+ * `src/wallet/riskRefusal.ts` shows them to agents.
+ *
+ * With a risk policy set, the API checks an order before signing and refuses one that breaks a
+ * limit with `blockedReason`, `blockedStage: 'risk_policy'` and `riskRefusal { code, field, limit,
+ * value }`. On `/agent/execute` those sit under the error body's `data`; on the `/execution-wallet`
+ * preflight at the top level or under `data`. Agents read the top level, so the CLI lifts them there
+ * with a one-line message.
+ */
+
+const isRecord = (value) => Boolean(value && typeof value === 'object' && !Array.isArray(value));
+
+/** The payload and the bodies nested under its `data` (up to three deep), outermost first. */
+function nestedBodies(payload) {
+  const bodies = [payload];
+  let current = payload.data;
+  for (let depth = 0; depth < 3 && isRecord(current); depth += 1) {
+    bodies.push(current);
+    current = current.data;
+  }
+  return bodies;
+}
+
+/** The first `riskRefusal` with a string `code`, at the top level or under `data`. */
+export function findRiskRefusal(payload) {
+  if (!isRecord(payload)) return undefined;
+  for (const body of nestedBodies(payload)) {
+    const candidate = body.riskRefusal;
+    if (isRecord(candidate) && typeof candidate.code === 'string' && candidate.code) return candidate;
+  }
+  return undefined;
+}
+
+function findString(payload, field) {
+  for (const body of nestedBodies(payload)) {
+    const value = body[field];
+    if (typeof value === 'string' && value) return value;
+  }
+  return undefined;
+}
+
+const formatValue = (value) =>
+  value === undefined || value === null ? 'unknown' : typeof value === 'object' ? JSON.stringify(value) : String(value);
+
+/** One line for a person or a model: `refused by risk policy: maxLeverage 5, order 10`. */
+export function riskRefusalMessage(refusal) {
+  if (refusal.code === 'POLICY_STATE_UNREAD') {
+    const reason = typeof refusal.reason === 'string' && refusal.reason ? ` (${refusal.reason})` : '';
+    return `refused by risk policy: a value it needs could not be read${reason}; nothing was signed, retry shortly`;
+  }
+  const field = refusal.field || refusal.code;
+  return `refused by risk policy: ${field} ${formatValue(refusal.limit)}, order ${formatValue(refusal.value)}`;
+}
+
+/**
+ * The top-level fields for a payload that carries a `riskRefusal` anywhere under it: `riskRefusal`,
+ * `blockedReason` and `errorCode` (the refusal, not the HTTP status's generic code), `blockedStage`
+ * (the nested ones when present), `retryable` (true only for POLICY_STATE_UNREAD) and `message`.
+ * Undefined when there is none.
+ */
+export function riskRefusalFields(payload) {
+  const refusal = findRiskRefusal(payload);
+  if (!refusal) return undefined;
+  const blockedReason = findString(payload, 'blockedReason') || refusal.code;
+  return {
+    riskRefusal: refusal,
+    blockedReason,
+    errorCode: blockedReason,
+    blockedStage: findString(payload, 'blockedStage') || 'risk_policy',
+    retryable: refusal.code === 'POLICY_STATE_UNREAD',
+    message: riskRefusalMessage(refusal),
+  };
+}

package/src/runtime/validation/actionParamsGate.mjs

@@ -105,6 +105,8 @@ export function enforceCatalogActionParams(resolved, flags, getPreparedParams) {
     if (result.sanitizedParams && flags) {
       flags.__preparedParams = result.sanitizedParams;
     }
+    // Payload builders copy --confirm-writes only into the confirmation keys this schema lists.
+    if (flags) flags.__actionParamsSchema = resolveActionParamsSchema(resolved);
     return;
   }
   throw createCliError('PARAMS_SCHEMA_INVALID', result.error || 'Action params failed catalog schema validation', {