@thirdfy/agent-cli 0.1.28 → 0.1.31

package/CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to `@thirdfy/agent-cli` are documented here. The format is b
 
 ## [Unreleased]
 
+## [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

@@ -683,6 +683,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 +714,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 +794,7 @@ function normalizeSwapAmountContract(params) {
       ...params,
       amountInHuman,
       amountInRaw,
-      amountIn: amountInRaw,
+      amountIn: amountInHuman,
       tokenInDecimals: decimals,
     },
     swapInput: {
@@ -3089,6 +3124,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 = {
@@ -4133,7 +4188,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.31",
   "description": "Thirdfy Agent CLI for onboarding, governance preflight, execute-intent, and status polling.",
   "type": "module",
   "bin": {