@thirdfy/agent-cli 0.1.28 → 0.1.32

package/CHANGELOG.md

@@ -4,6 +4,37 @@ All notable changes to `@thirdfy/agent-cli` are documented here. The format is b
 
 ## [Unreleased]
 
+## [0.1.32] - 2026-05-08
+
+### Added
+
+- **Earn partners (Vaults.fyi and Yield.xyz):** `thirdfy-agent actions --provider vaults-fyi|yield-xyz` returns catalog-aligned hints (`get_vaults_fyi_vaults` / `get_yield_xyz_opportunities`, generic Earn reads, `deposit_earn_position` / `withdraw_earn_position`). Provider inference and `--provider earn` filtering include these providers alongside Morpho and Curve.
+
+### Changed
+
+- Public docs (`docs/command-reference.md`, `docs/action-inventory-and-compatibility.md`, `docs/providers/index.md`) describe partner earn discovery and transaction-prep-first writes.
+- **`--provider earn` hints:** Umbrella `readActions` lists Morpho and Curve discovery actions (`get_morpho_vaults`, `get_curve_pools`) together with partner reads so Earn hints stay symmetric across sub-providers.
+
+## [0.1.31] - 2026-05-07
+
+### Fixed
+
+- **Swap amounts (self / build-tx / execute-intent):** When using `amountInHuman` + `tokenInDecimals`, prepared params now set canonical `amountIn` to the **human decimal** string (matching `amountInRaw` normalization). Previously `amountIn` incorrectly carried base-unit raw integers, which could mis-size swaps outside the managed-wallet execute path.
+
+## [0.1.30] - 2026-05-07
+
+### Fixed
+
+- **Swap amounts:** `amountInRaw` now requires `tokenInDecimals`; without it the CLI errors instead of sending base units as a human `amountIn` (catastrophic mis-size risk).
+- **Managed wallet payload:** Legacy `amountIn` is treated as a **human decimal** string (API contract); base units require `amountInRaw` + `tokenInDecimals`.
+- **Managed wallet payload:** `legacy_human` path strips `tokenInDecimals` from the execute payload for consistency.
+
+## [0.1.29] - 2026-05-07
+
+### Fixed
+
+- **Managed wallet swaps:** Normalize `amountInRaw` / `amountInHuman` into the single human `amountIn` field required by Thirdfy managed-wallet swap execution, preventing ambiguous amount payloads for `agent_wallet` agents.
+
 ## [0.1.28] - 2026-05-05
 
 ### Added

package/README.md

@@ -40,7 +40,7 @@ npx @thirdfy/agent-cli --help
 
 ## Release notes
 
-Version history and highlights: [CHANGELOG.md](./CHANGELOG.md). Recent CLI releases document provider discovery parity, metadata-first `actions --provider` filtering, earn deposit guards, portfolio analytics commands, and README refresh through **v0.1.28**.
+Version history and highlights: [CHANGELOG.md](./CHANGELOG.md). Highlights through **v0.1.31** include provider discovery parity, portfolio analytics, managed-wallet swap normalization, and **self/build-tx** swap human-decimal `amountIn` parity when using `amountInHuman` + `tokenInDecimals`.
 
 **Maintainers — npm:** follow [docs/releasing.md](./docs/releasing.md). From a clone with gitignored `.env`, use `npm run publish:npm:local -- --dry-run` then `npm run publish:npm:local`. Or run `npm run release:npm` after exporting tokens in the shell. Never commit npm tokens — use [.env.example](./.env.example) as a template only.
 
@@ -53,8 +53,8 @@ export THIRDFY_OWNER_SESSION_TOKEN="..."
 
 thirdfy-agent actions --agent-api-key "$AGENT_API_KEY" --json
 thirdfy-agent profile init --profile personal --json
-thirdfy-agent preflight --agent-api-key "$AGENT_API_KEY" --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000"}' --estimated-amount-usd 25 --json
-thirdfy-agent run --agent-api-key "$AGENT_API_KEY" --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000"}' --estimated-amount-usd 25 --json
+thirdfy-agent preflight --agent-api-key "$AGENT_API_KEY" --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000","tokenInDecimals":6}' --estimated-amount-usd 25 --json
+thirdfy-agent run --agent-api-key "$AGENT_API_KEY" --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000","tokenInDecimals":6}' --estimated-amount-usd 25 --json
 thirdfy-agent intent-status --intent-id "<intentId>" --json
 ```
 
@@ -189,7 +189,7 @@ thirdfy-agent run \
   --run-mode self \
   --broadcast \
   --action swap \
-  --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000","chainId":8453}' \
+  --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000","tokenInDecimals":6,"chainId":8453}' \
   --json
 ```
 
@@ -203,7 +203,7 @@ thirdfy-agent run \
   --run-mode hybrid \
   --hybrid-wallet-mode agent_wallet \
   --action swap \
-  --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000","chainId":8453}' \
+  --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000","tokenInDecimals":6,"chainId":8453}' \
   --estimated-amount-usd 25 \
   --json
 ```
@@ -232,7 +232,7 @@ thirdfy-agent doctor self --json
 For `--action swap`, CLI enforces an explicit amount unit contract:
 
 - Provide exactly one of:
-  - `amountInRaw` (base units integer string), or
+  - `amountInRaw` + `tokenInDecimals` (base units integer string), or
   - `amountInHuman` + `tokenInDecimals` (CLI converts to `amountInRaw`)
 - Legacy `amountIn` is accepted only as raw integer compatibility input.
 - Ambiguous payloads (both/none) fail with `AMOUNT_UNIT_AMBIGUOUS`.
@@ -242,7 +242,7 @@ Examples:
 ```bash
 # Raw/base units
 thirdfy-agent run --agent-api-key "$AGENT_API_KEY" --action swap \
-  --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000","chainId":8453}' --json
+  --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000","tokenInDecimals":6,"chainId":8453}' --json
 
 # Human units + decimals
 thirdfy-agent run --agent-api-key "$AGENT_API_KEY" --action swap \
@@ -335,7 +335,7 @@ thirdfy-agent delegation redeem \
   --run-mode thirdfy \
   --agent-api-key "$AGENT_API_KEY" \
   --action swap \
-  --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000"}' \
+  --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000","tokenInDecimals":6}' \
   --estimated-amount-usd 5 \
   --json
 ```
@@ -369,7 +369,7 @@ thirdfy-agent managed wallet init --auth-token "$THIRDFY_AUTH_TOKEN" --json
 # or: --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN"
 thirdfy-agent managed wallet grant --auth-token "$THIRDFY_AUTH_TOKEN" --agent-key "0xYOUR_AGENT_KEY" --token-address "0x..." --max-usd-per-day 250 --json
 # or: --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN"
-thirdfy-agent agent run --agent-api-key "$AGENT_API_KEY" --signer-method fanout_intent --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000"}' --json
+thirdfy-agent agent run --agent-api-key "$AGENT_API_KEY" --signer-method fanout_intent --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountInRaw":"1000000","tokenInDecimals":6}' --json
 ```
 
 ### Signer command model (managed + BYOW)

package/bin/thirdfy-agent.mjs

@@ -530,10 +530,18 @@ function getTradingProviderHint(providerId) {
       category: 'earn',
       canonicalReadAction: 'get_earn_opportunities',
       canonicalWriteAction: 'deposit_earn_position',
-      readActions: ['get_earn_opportunities', 'get_earn_provider', 'get_earn_position'],
+      readActions: [
+        'get_earn_opportunities',
+        'get_earn_provider',
+        'get_earn_position',
+        'get_morpho_vaults',
+        'get_curve_pools',
+        'get_vaults_fyi_vaults',
+        'get_yield_xyz_opportunities',
+      ],
       orderManagementActions: ['deposit_earn_position', 'withdraw_earn_position'],
       laneCompatibility:
-        'Generic earn writes use deposit_earn_position / withdraw_earn_position on normal Thirdfy policy/delegation rails; routing selects Morpho vault calldata or the validated Curve Base 4pool adapter on Base (8453) per opportunity.',
+        'Generic earn writes use deposit_earn_position / withdraw_earn_position on normal Thirdfy policy/delegation rails; routing selects Morpho, Curve, Vaults.fyi, or Yield.xyz adapters per provider/opportunity.',
     };
   }
   if (provider === 'morpho') {
@@ -563,6 +571,34 @@ function getTradingProviderHint(providerId) {
         'Curve EVM writes are limited to the validated Base mainnet 4pool adapter; other pools remain discovery-only until per-pool calldata is validated.',
     };
   }
+  if (provider === 'vaults-fyi') {
+    return {
+      provider,
+      category: 'earn',
+      canonicalReadAction: 'get_vaults_fyi_vaults',
+      canonicalWriteAction: 'deposit_earn_position',
+      readActions: ['get_vaults_fyi_vaults', 'get_earn_opportunities', 'get_earn_provider', 'get_earn_position'],
+      orderManagementActions: ['deposit_earn_position', 'withdraw_earn_position'],
+      laneCompatibility:
+        'Vaults.fyi writes are transaction-prep first. Thirdfy validates partner payloads, chain/user context, and allowed targets before returning or submitting prepared calls.',
+      example:
+        'thirdfy-agent actions --provider vaults-fyi && thirdfy-agent preflight --action deposit_earn_position --params \'{"providerId":"vaults-fyi","opportunityId":"...","vaultAddress":"0x...","tokenAddress":"0x...","amount":"10","chainId":8453}\'',
+    };
+  }
+  if (provider === 'yield-xyz') {
+    return {
+      provider,
+      category: 'earn',
+      canonicalReadAction: 'get_yield_xyz_opportunities',
+      canonicalWriteAction: 'deposit_earn_position',
+      readActions: ['get_yield_xyz_opportunities', 'get_earn_opportunities', 'get_earn_provider', 'get_earn_position'],
+      orderManagementActions: ['deposit_earn_position', 'withdraw_earn_position'],
+      laneCompatibility:
+        'Yield.xyz writes are transaction-prep first. Thirdfy calls Yield.xyz directly and validates returned unsigned transactions with @yieldxyz/shield before signing or returning prepared calls.',
+      example:
+        'thirdfy-agent actions --provider yield-xyz && thirdfy-agent preflight --action deposit_earn_position --params \'{"providerId":"yield-xyz","opportunityId":"ethereum-eth-lido-staking","tokenAddress":"0x...","amount":"0.01","chainId":1}\'',
+    };
+  }
   return null;
 }
 
@@ -582,11 +618,15 @@ function getCachedProviderHintFromCapabilities(provider) {
     earn: 'deposit_earn_position',
     morpho: 'deposit_earn_position',
     curve: 'deposit_earn_position',
+    'vaults-fyi': 'deposit_earn_position',
+    'yield-xyz': 'deposit_earn_position',
   };
   const canonicalReadActions = {
     earn: 'get_earn_opportunities',
     morpho: 'get_morpho_vaults',
     curve: 'get_curve_pools',
+    'vaults-fyi': 'get_vaults_fyi_vaults',
+    'yield-xyz': 'get_yield_xyz_opportunities',
     prediction: 'get_prediction_markets',
   };
   return {
@@ -683,6 +723,17 @@ function decimalToRawUnits(amountHuman, decimals) {
   return (wholePart + fracPart).toString();
 }
 
+function rawUnitsToDecimalString(amountRaw, decimals) {
+  const raw = normalizeIntegerRawAmount(amountRaw);
+  const base = 10n ** BigInt(decimals);
+  const n = BigInt(raw);
+  const whole = n / base;
+  const frac = n % base;
+  if (decimals === 0 || frac === 0n) return whole.toString();
+  const fracText = frac.toString().padStart(decimals, '0').replace(/0+$/, '');
+  return `${whole.toString()}.${fracText}`;
+}
+
 function normalizeSwapAmountContract(params) {
   const hasRaw = params.amountInRaw !== undefined && params.amountInRaw !== null && String(params.amountInRaw).trim() !== '';
   const hasHuman = params.amountInHuman !== undefined && params.amountInHuman !== null && String(params.amountInHuman).trim() !== '';
@@ -703,34 +754,58 @@ function normalizeSwapAmountContract(params) {
 
   if (hasRaw) {
     const amountInRaw = normalizeIntegerRawAmount(params.amountInRaw);
+    const hasDecimals =
+      params.tokenInDecimals !== undefined &&
+      params.tokenInDecimals !== null &&
+      String(params.tokenInDecimals).trim() !== '';
+    if (!hasDecimals) {
+      throw createCliError(
+        'AMOUNT_UNIT_DECIMALS_REQUIRED',
+        'amountInRaw requires tokenInDecimals (integer 0-36).'
+      );
+    }
+    const decimals = Number(params.tokenInDecimals);
+    if (!Number.isInteger(decimals) || decimals < 0 || decimals > 36) {
+      throw createCliError(
+        'AMOUNT_UNIT_DECIMALS_REQUIRED',
+        'amountInRaw requires tokenInDecimals (integer 0-36).'
+      );
+    }
+    const amountInHuman = rawUnitsToDecimalString(amountInRaw, decimals);
     return {
       params: {
         ...params,
         amountInRaw,
-        amountIn: amountInRaw,
+        amountIn: amountInHuman,
+        tokenInDecimals: decimals,
       },
       swapInput: {
         amountInRaw,
-        amountInHuman: null,
-        tokenInDecimals: null,
+        amountInHuman,
+        tokenInDecimals: decimals,
         unitSource: 'raw',
       },
     };
   }
 
   if (hasLegacy) {
-    const amountInRaw = normalizeIntegerRawAmount(params.amountIn, 'AMOUNT_UNIT_INVALID');
+    const amountInHuman = String(params.amountIn).trim();
+    if (!/^\d+(\.\d+)?$/.test(amountInHuman)) {
+      throw createCliError(
+        'AMOUNT_UNIT_INVALID',
+        'Legacy swap amountIn must be a decimal token-unit string (example: "1.25"). For base units use amountInRaw with tokenInDecimals.'
+      );
+    }
     return {
       params: {
         ...params,
-        amountInRaw,
-        amountIn: amountInRaw,
+        amountIn: amountInHuman,
       },
       swapInput: {
-        amountInRaw,
-        amountInHuman: null,
+        amountInRaw: null,
+        amountInHuman,
         tokenInDecimals: null,
-        unitSource: 'legacy_raw',
+        unitSource: 'legacy_human',
       },
     };
   }
@@ -759,7 +834,7 @@ function normalizeSwapAmountContract(params) {
       ...params,
       amountInHuman,
       amountInRaw,
-      amountIn: amountInRaw,
+      amountIn: amountInHuman,
       tokenInDecimals: decimals,
     },
     swapInput: {
@@ -3089,6 +3164,26 @@ function buildManagedExecutePayload(flags, options) {
   const params = getPreparedParams(flags);
   const managedParams = { ...params };
   if (flags.__swapInput?.unitSource === 'human' && flags.__swapInput.amountInHuman) {
+    delete managedParams.amountInRaw;
+    delete managedParams.amountInHuman;
+    delete managedParams.tokenInDecimals;
+    managedParams.amountIn = flags.__swapInput.amountInHuman;
+  } else if (flags.__swapInput?.unitSource === 'raw' && flags.__swapInput.amountInRaw) {
+    const decimals = flags.__swapInput.tokenInDecimals;
+    delete managedParams.amountInHuman;
+    delete managedParams.amountInRaw;
+    delete managedParams.tokenInDecimals;
+    if (!Number.isInteger(decimals) || decimals < 0 || decimals > 36) {
+      throw createCliError(
+        'AMOUNT_UNIT_DECIMALS_REQUIRED',
+        'amountInRaw requires tokenInDecimals (integer 0-36).'
+      );
+    }
+    managedParams.amountIn = rawUnitsToDecimalString(flags.__swapInput.amountInRaw, decimals);
+  } else if (flags.__swapInput?.unitSource === 'legacy_human' && flags.__swapInput.amountInHuman) {
+    delete managedParams.amountInRaw;
+    delete managedParams.amountInHuman;
+    delete managedParams.tokenInDecimals;
     managedParams.amountIn = flags.__swapInput.amountInHuman;
   }
   const payload = {
@@ -3379,6 +3474,9 @@ function inferActionProvider(action) {
     'get-curve-pool-details': 'curve',
     'deposit-curve-pool': 'curve',
     'withdraw-curve-pool': 'curve',
+    'get-vaults-fyi-vaults': 'vaults-fyi',
+    'get-vaults-fyi-opportunities': 'vaults-fyi',
+    'get-yield-xyz-opportunities': 'yield-xyz',
     'get-prediction-markets': 'polymarket',
     'get-prediction-market': 'polymarket',
     'get-prediction-order-book': 'polymarket',
@@ -3394,9 +3492,11 @@ function inferActionProvider(action) {
   if (knownMap[key]) return knownMap[key];
   if (key.includes('hyperliquid')) return 'hyperliquid';
   if (key.includes('polymarket') || key.includes('prediction')) return 'polymarket';
+  if (key.includes('vaults-fyi')) return 'vaults-fyi';
+  if (key.includes('yield-xyz')) return 'yield-xyz';
   if (key.includes('morpho')) return 'morpho';
   if (key.includes('curve')) return 'curve';
-  if (key.includes('earn')) return 'earn';
+  if (key.includes('earn') || key.includes('yield') || key.includes('vault')) return 'earn';
   if (key.includes('bridge')) return 'bridge';
   if (key.includes('dogeos-barkswap')) return 'dogeos-barkswap';
   if (key.includes('dogeos-laika')) return 'dogeos-laika';
@@ -3445,9 +3545,9 @@ function actionMatchesProvider(action, requestedProvider, allActions) {
   if (requestedProvider === 'bridge') return isProviderActionKey(action, 'bridge');
   if (requestedProvider.startsWith('dogeos')) return isProviderActionKey(action, requestedProvider);
   if (requestedProvider === 'earn') {
-    return provider === 'earn' || provider === 'morpho' || provider === 'curve' || isEarnCatalogAction(action);
+    return provider === 'earn' || provider === 'morpho' || provider === 'curve' || provider === 'vaults-fyi' || provider === 'yield-xyz' || isEarnCatalogAction(action);
   }
-  if (requestedProvider === 'morpho' || requestedProvider === 'curve') {
+  if (requestedProvider === 'morpho' || requestedProvider === 'curve' || requestedProvider === 'vaults-fyi' || requestedProvider === 'yield-xyz') {
     const hasProtocolSpecificEarnRows = allActions.some((candidate) => getActionProviderWithInference(candidate) === requestedProvider);
     return isProviderActionKey(action, requestedProvider) || (!hasProtocolSpecificEarnRows && isEarnCatalogAction(action));
   }
@@ -4133,7 +4233,7 @@ Global flags:
   --profile <name>   personal | builder | network
   --env <file>       load env vars from file
   --timeout <ms>     request timeout
-  --params <json>    for swap: exactly one of {amountInRaw} or {amountInHuman + tokenInDecimals}
+  --params <json>    for swap: amountInRaw + tokenInDecimals, or amountInHuman + tokenInDecimals, or legacy human amountIn (decimal string)
   --broadcast        with run --run-mode self, sign and broadcast using OWS
   --user-did <did>   required for managed wallet server execution paths
   --allow-wallet-mismatch  bypass strict funded-wallet vs execution-wallet guard

package/package.json

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