@thirdfy/agent-cli 0.2.82 → 0.2.84

package/CHANGELOG.md

@@ -4,6 +4,22 @@ All notable changes to `@thirdfy/agent-cli` are documented here. The format is b
 
 ## Unreleased
 
+## [0.2.84] - 2026-10-10
+
+### Added
+
+- **Bermuda private actions and `private: true`.** Provider hints list `bermuda_stealth_exit`, `bermuda_stealth_swap` and `bermuda_sweep_burners`, the trading hint documents `private: true` on `swap`, and the earn hint documents `private: true` on `deposit_earn_position` / `withdraw_earn_position` (Thirdfy API: private swap on a fresh burner where a Bermuda pool exists; refused rather than run publicly elsewhere). `docs/providers/bermuda.md` covers the private writes.
+
+### Fixed
+
+- **Private writes no longer fail the public balance check.** `run` checked the execution wallet's `tokenIn` balance before a write, so `swap` with `private: true` and `bermuda_stealth_swap` stopped with `INSUFFICIENT_FUNDS` although they spend the shielded balance. Funding checks now skip `private: true` and every Bermuda write except `bermuda_deposit`. Pin: `test/funding-token-in.test.cjs`.
+
+## [0.2.83] - 2026-10-08
+
+### Fixed
+
+- **`preflight --run-mode agent_wallet` said `ready` for a venue order the venue could not take.** On production 2026-10-08 (API 3.19.3, CLI 0.2.82) `preflight --action place_hyperliquid_perps_order --run-mode agent_wallet` returned `PREFLIGHT_OK` with `policyEvaluated: false` and `chainId: 8453`, while `venue readiness hyperliquid` returned `HYPERLIQUID_DEPOSIT_REQUIRED`: the preflight sent `/execution-wallet` only `userDid`, `chainId`, `runMode` and `tokenIn`, so the API never saw the action. `preflight` now also sends `action`, `params` and `estimatedAmountUsd`. With Thirdfy API that supports it (capability `commandFeatures.preflightVenueReadiness`), the API checks agent policy, action limits and, for venue orders, venue readiness. A blocked answer (409 `VENUE_NOT_READY`, 403 policy, 429 limits) is `PREFLIGHT_BLOCKED` with `data.status: "blocked"`, `blockedReason`, `blockedStage`, `blockingReasons` and `venueReadiness`, instead of an HTTP error. `data.policyEvaluated` is now always present (false against an older API) and survives a later CLI-local failure (wallet mismatch, funding, native gas), whose `status` stays `failed`; only an API refusal is `blocked`. Venue actions also report `data.executionVenue` (`venue` as the API names it, `brand` for Veranta, `settlement`, `settlementChainId`, `walletLookupChainId`): `chainId` stays the chain the managed wallet was looked up on (Base by default), not where a Hyperliquid, Lighter or Polymarket order runs. `run` and the address-default lookups keep the wallet-only preflight. MCP `walletExecute` has no preflight-only mode and needs no change. Pin: `test/preflight-venue-readiness.test.cjs`.
+
 ## [0.2.82] - 2026-10-01
 
 ### Fixed

package/README.md

@@ -40,10 +40,10 @@ Run without global install:
 npx @thirdfy/agent-cli --help
 ```
 
-## What's new in v0.2.82
+## What's new in v0.2.84
 
-- **`agent_wallet` preflight shows native gas** on chains where the wallet pays gas (DogeOS 6281971): `gasSponsored`, `gasReady`, `nativeGasBalance`, from Thirdfy API 3.18.2. A write from a wallet with 0 native coin stops before `/execute` with `INSUFFICIENT_NATIVE_GAS` and the faucet link.
-- **DogeOS Laika buys pass preflight.** A buy spends native DOGE (`dogeAmountWei`); the CLI no longer checks the balance of the token being bought. Launch and claim are treated the same way, and a sell still checks the token it sells.
+- **Private actions (Bermuda, Base Sepolia).** Hints cover `bermuda_stealth_exit`, `bermuda_stealth_swap` and `bermuda_sweep_burners`, plus `private: true` on `swap`, `deposit_earn_position` and `withdraw_earn_position` (Thirdfy API: the action runs from the shielded balance on a fresh burner where a Bermuda pool exists, or is refused; it never falls back to a public action). See [docs/providers/bermuda.md](./docs/providers/bermuda.md).
+- **`run` no longer blocks private writes on the public balance check.** `private: true` and Bermuda writes (except `bermuda_deposit`) spend the shielded balance, so the execution wallet's `tokenIn` balance is not checked.
 - See [CHANGELOG.md](./CHANGELOG.md) and GitHub Releases for older versions.
 
 ## Quick start

package/package.json

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

package/src/core/fundingTokenIn.mjs

@@ -24,11 +24,21 @@ const POSITION_EXIT_ACTIONS = new Set([
   'dogeos_laika_claim',
 ]);
 
+/**
+ * Shielded spends pay from the Bermuda pool, not the execution wallet: `private: true` on any action,
+ * and every Bermuda write except the public deposit into the pool.
+ */
+function spendsShieldedFunds(params, actionId) {
+  if (params.private === true) return true;
+  return actionId.startsWith('bermuda_') && actionId !== 'bermuda_deposit';
+}
+
 export function resolveTokenInForFunding(params, action) {
   if (!params || typeof params !== 'object') return '';
+  const actionId = normalizeActionKey(action);
+  if (spendsShieldedFunds(params, actionId)) return '';
   const explicit = String(params.tokenIn || '').trim();
   if (explicit) return explicit;
-  const actionId = normalizeActionKey(action);
   if (NATIVE_ETH_SPEND_ACTIONS.has(actionId)) return '';
   if (POSITION_EXIT_ACTIONS.has(actionId)) return '';
   if (params.amountEth != null && String(params.amountEth).trim() !== '') return '';

package/src/runtime/execution/actionPreflight.mjs

@@ -0,0 +1,93 @@
+import { toLegacyVenueActionKey } from '../../core/venueBrand.mjs';
+import { resolveExecuteEstimatedAmountUsd } from './payloads.mjs';
+
+/**
+ * Action-aware `agent_wallet` preflight (Thirdfy API: `GET /agent/execution-wallet?action=…`).
+ *
+ * Up to 0.2.82 the CLI sent only `userDid`, `chainId`, `runMode` and `tokenIn`, so the API never
+ * saw the action: `preflight --action place_hyperliquid_perps_order --run-mode agent_wallet` said
+ * `ready` with `policyEvaluated: false` while `venue readiness hyperliquid` said
+ * `HYPERLIQUID_DEPOSIT_REQUIRED` (production, 2026-10-08). Sending the action lets the API run
+ * agent policy, action limits and, for venue orders, venue readiness. An API without the feature
+ * ignores the extra query fields and answers `policyEvaluated` absent (reported as false).
+ */
+
+/** Venue an action trades on, and where it settles. Null for actions outside the four venues. */
+const VENUE_SETTLEMENT = Object.freeze({
+  hyperliquid: { venue: 'hyperliquid', settlement: 'hyperliquid_l1', settlementChainId: null },
+  lighter: { venue: 'lighter', settlement: 'lighter_l2', settlementChainId: null },
+  polymarket: { venue: 'polymarket', settlement: 'polygon', settlementChainId: 137 },
+  // `venue` matches the API's stored id; `brand` is the public name.
+  avantis: { venue: 'avantis', brand: 'veranta', settlement: 'base', settlementChainId: 8453 },
+});
+
+export function resolveActionVenue(action) {
+  const key = toLegacyVenueActionKey(action).replace(/-/g, '_');
+  for (const token of Object.keys(VENUE_SETTLEMENT)) {
+    if (new RegExp(`(^|_)${token}(_|$)`).test(key)) return VENUE_SETTLEMENT[token];
+  }
+  return null;
+}
+
+/**
+ * The venue an action executes on, next to the chain the managed wallet was looked up on. The
+ * managed wallet is one EVM address on every chain, so a Hyperliquid order still resolves it on the
+ * default chain; this says the order itself does not run there.
+ */
+export function describeExecutionVenue(action, walletLookupChainId) {
+  const venue = resolveActionVenue(action);
+  if (!venue) return null;
+  return { ...venue, walletLookupChainId: Number(walletLookupChainId) || null };
+}
+
+/** Adds `action`, `params` and `estimatedAmountUsd` to an `/execution-wallet` query. */
+export function appendActionPreflightQuery(query, { action, params, flags }) {
+  const actionId = String(action || '').trim();
+  if (!actionId) return query;
+  query.set('action', actionId);
+  if (params && typeof params === 'object' && !Array.isArray(params) && Object.keys(params).length) {
+    query.set('params', JSON.stringify(params));
+  }
+  const estimatedAmountUsd = resolveExecuteEstimatedAmountUsd(actionId, flags);
+  if (estimatedAmountUsd != null) query.set('estimatedAmountUsd', String(estimatedAmountUsd));
+  return query;
+}
+
+/** Venue fields an action preflight carries onto the CLI envelope. */
+export const ACTION_PREFLIGHT_VENUE_FIELDS = Object.freeze(['venue', 'venueReadiness', 'blockingReasons']);
+
+/** Stages at which the API refused the action itself (as opposed to a CLI-local check). */
+const API_BLOCK_STAGES = new Set(['catalog', 'policy', 'venue_readiness']);
+
+/** True when the API blocked the action (policy, catalog, venue readiness). */
+export function isApiActionBlock(preflight) {
+  return preflight?.success === false && API_BLOCK_STAGES.has(String(preflight?.blockedStage || ''));
+}
+
+/** Policy and venue fields of an action-aware `/execution-wallet` answer (allowed or blocked). */
+export function pickActionPreflightFields(response) {
+  const out = { policyEvaluated: response?.policyEvaluated === true };
+  for (const key of [...ACTION_PREFLIGHT_VENUE_FIELDS, 'actionPreflight']) {
+    if (response?.[key] != null) out[key] = response[key];
+  }
+  return out;
+}
+
+/**
+ * A blocked action preflight arrives as a non-2xx answer (409 `VENUE_NOT_READY`, 403 policy, 429
+ * limits) with `preflightBlocked: true`. Turn it into a blocked preflight result; null otherwise.
+ */
+export function blockedActionPreflightFromError(error) {
+  const payload = error?.payload;
+  if (!payload || typeof payload !== 'object' || payload.preflightBlocked !== true) return null;
+  return {
+    success: false,
+    blockedReason: String(payload.blockedReason || 'PREFLIGHT_BLOCKED'),
+    blockedStage: String(payload.blockedStage || 'policy'),
+    error: String(payload.error || payload.message || error?.message || 'Preflight blocked'),
+    statusCode: Number(error?.statusCode) || null,
+    signerMethod: payload.signerMethod || 'managed_wallet_server',
+    ...pickActionPreflightFields(payload),
+    ...(payload.data ? { data: payload.data } : {}),
+  };
+}

package/src/runtime/execution/runners.mjs

@@ -1,5 +1,13 @@
 import { randomUUID } from 'crypto';
 import { pickNativeGasFields } from './nativeGas.mjs';
+import {
+  ACTION_PREFLIGHT_VENUE_FIELDS,
+  appendActionPreflightQuery,
+  blockedActionPreflightFromError,
+  describeExecutionVenue,
+  isApiActionBlock,
+  pickActionPreflightFields,
+} from './actionPreflight.mjs';
 import { requireFlag } from '../../core/args.mjs';
 import { createCliError } from '../../core/envelope.mjs';
 import {
@@ -204,6 +212,8 @@ async function runPreflightByMode(runMode, ctx, flags, resolved, options = {}) {
       // Reads carry no transaction; keep funding optional so preflight matches run.
       requireFundingCheck: !isReadOnlyAction(resolved),
       preflightSeed: options.managedPreflight,
+      // Ask the API to check policy and venue readiness for this action, not just the wallet.
+      evaluateAction: true,
     });
     const normalized = normalizeIntentResponse({
       success: preflight.success,
@@ -222,8 +232,21 @@ async function runPreflightByMode(runMode, ctx, flags, resolved, options = {}) {
     normalized.signerMethod = preflight.signerMethod || 'managed_wallet_server';
     normalized.executionWalletPreflight = preflight;
     normalized.fundingTokenBalance = preflight.fundingTokenBalance || null;
+    normalized.policyEvaluated = preflight.policyEvaluated === true;
+    for (const key of [...ACTION_PREFLIGHT_VENUE_FIELDS, 'executionVenue']) {
+      if (preflight[key] != null) normalized[key] = preflight[key];
+    }
+    // Only an API refusal of the action is `blocked`; CLI-local checks keep `failed`.
+    const apiBlocked = isApiActionBlock(preflight);
+    if (apiBlocked) normalized.status = 'blocked';
     return {
-      message: preflight.success ? 'Managed wallet preflight completed' : 'Managed wallet preflight failed',
+      message: preflight.success
+        ? 'Managed wallet preflight completed'
+        : preflight.blockedStage === 'venue_readiness'
+          ? 'Managed wallet preflight blocked: venue not ready'
+          : apiBlocked
+            ? 'Managed wallet preflight blocked by policy'
+            : 'Managed wallet preflight failed',
       route: 'execution_wallet_preflight',
       normalized,
     };
@@ -768,22 +791,42 @@ async function resolveManagedExecutionPreflight(ctx, flags, resolved, options =
     runMode,
   });
   if (tokenIn) query.set('tokenIn', tokenIn);
+  const evaluateAction = options.evaluateAction === true;
+  if (evaluateAction) appendActionPreflightQuery(query, { action, params, flags });
+  const executionVenue = describeExecutionVenue(action, chainId);
   const preflightSeed = options.preflightSeed && typeof options.preflightSeed === 'object'
     ? options.preflightSeed
     : null;
   if (preflightSeed && preflightSeed.success === false) {
     return preflightSeed;
   }
-  const response = preflightSeed
-    ? {
+  // A seed (address default lookup) carries no policy answer; an action preflight asks the API again.
+  const useSeed = Boolean(preflightSeed) && !evaluateAction;
+  let response;
+  if (useSeed) {
+    response = {
       executionWalletAddress: preflightSeed.executionWalletAddress || null,
       signerMethod: preflightSeed.signerMethod || null,
       fundingTokenBalance: preflightSeed.fundingTokenBalance || null,
       ...pickNativeGasFields(preflightSeed),
+    };
+  } else {
+    try {
+      response = await apiGet(ctx, `/api/v1/agent/execution-wallet?${query.toString()}`, {
+        'x-agent-api-key': agentApiKey,
+      });
+    } catch (error) {
+      const blocked = evaluateAction ? blockedActionPreflightFromError(error) : null;
+      if (!blocked) throw error;
+      return {
+        ...blocked,
+        userDid,
+        chainId,
+        ...(executionVenue ? { executionVenue } : {}),
+      };
     }
-    : await apiGet(ctx, `/api/v1/agent/execution-wallet?${query.toString()}`, {
-      'x-agent-api-key': agentApiKey,
-    });
+  }
+  const actionFields = evaluateAction ? pickActionPreflightFields(response) : {};
   const executionWalletAddress = String(response?.executionWalletAddress || '').trim().toLowerCase();
   const signerMethod = String(response?.signerMethod || 'managed_wallet_server').trim();
   const rawBalance = String(response?.fundingTokenBalance?.raw || '').trim();
@@ -803,6 +846,8 @@ async function resolveManagedExecutionPreflight(ctx, flags, resolved, options =
           executionWalletAddress,
           signerMethod,
           fundingTokenBalance: response?.fundingTokenBalance || null,
+          ...actionFields,
+          ...(executionVenue ? { executionVenue } : {}),
         };
       }
     }
@@ -819,6 +864,8 @@ async function resolveManagedExecutionPreflight(ctx, flags, resolved, options =
       executionWalletAddress,
       signerMethod,
       fundingTokenBalance: response?.fundingTokenBalance || null,
+      ...actionFields,
+      ...(executionVenue ? { executionVenue } : {}),
     };
   }
 
@@ -831,6 +878,8 @@ async function resolveManagedExecutionPreflight(ctx, flags, resolved, options =
       executionWalletAddress,
       signerMethod,
       fundingTokenBalance: response?.fundingTokenBalance || null,
+      ...actionFields,
+      ...(executionVenue ? { executionVenue } : {}),
     };
   }
 
@@ -847,6 +896,8 @@ async function resolveManagedExecutionPreflight(ctx, flags, resolved, options =
       executionWalletAddress,
       signerMethod,
       fundingTokenBalance: response?.fundingTokenBalance || null,
+      ...actionFields,
+      ...(executionVenue ? { executionVenue } : {}),
       ...nativeGas,
     };
   }
@@ -860,6 +911,8 @@ async function resolveManagedExecutionPreflight(ctx, flags, resolved, options =
     chainId,
     tokenIn: tokenIn || null,
     ...nativeGas,
+    ...actionFields,
+    ...(executionVenue ? { executionVenue } : {}),
   };
 }
 

package/src/runtime/providerHints.mjs

@@ -127,7 +127,7 @@ export function createProviderHints({ getNegotiatedCapabilitiesCache }) {
         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.',
+          '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.',
       };
     }
@@ -512,7 +512,7 @@ export function createProviderHints({ getNegotiatedCapabilitiesCache }) {
         ],
         orderManagementActions: ['deposit_earn_position', 'withdraw_earn_position', 'claim_earn_rewards'],
         laneCompatibility:
-          'Generic earn writes use deposit_earn_position / withdraw_earn_position on normal Thirdfy policy/delegation rails; Yield.xyz incentive claims use claim_earn_rewards (no amount; optional passthrough from get_earn_position.claimableRewards). Routing selects Morpho, Aave, Curve, Vaults.fyi, or Yield.xyz adapters per provider/opportunity.',
+          'Generic earn writes use deposit_earn_position / withdraw_earn_position on normal Thirdfy policy/delegation rails; Yield.xyz incentive claims use claim_earn_rewards (no amount; optional passthrough from get_earn_position.claimableRewards). Routing selects Morpho, Aave, Curve, Vaults.fyi, or Yield.xyz adapters per provider/opportunity. With private: true (deposit_earn_position / withdraw_earn_position) the position is entered or exited from the shielded (Bermuda) USDC balance on allowlisted vaults where a Bermuda pool exists (Base Sepolia MetaMorpho today); a private withdraw without amount exits everything; otherwise it is refused, never run publicly.',
       };
     }
     if (provider === 'capyfi') {
@@ -817,10 +817,13 @@ export function createProviderHints({ getNegotiatedCapabilitiesCache }) {
           'bermuda_transfer',
           'bermuda_withdraw',
           'bermuda_stealth_earn',
+          'bermuda_stealth_exit',
+          'bermuda_stealth_swap',
+          'bermuda_sweep_burners',
         ],
         supportedChains: [84532],
         laneCompatibility:
-          'Base Sepolia shielded USDC lab rail. Catalog is flag-gated on the API host. Deposit is Privy-direct from the execution wallet. Transfer, withdraw, and stealth earn use the Bermuda relayer. Max write size is capped at 5 USD in catalog policy.',
+          '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 tier and private swaps carry a privacy fee. Responses include privacyNotes.',
         example:
           'thirdfy-agent run --action get_bermuda_setup_status --params \'{"chainId":84532}\' --provider bermuda --json',
       };