@thirdfy/agent-cli 0.1.27 → 0.1.31

package/CHANGELOG.md

@@ -4,8 +4,32 @@ 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
 
+- `thirdfy-agent analytics portfolio` for API-owned agent portfolio NAV, principal, PnL, ROI, APR, holdings, and confidence reads.
+- `thirdfy-agent analytics leaderboard` for category/network/window-ranked agent performance across `trading`, `yield`, and `prediction`.
 - **`npm run publish:npm:local`** (`scripts/local-npm-publish.sh`): loads gitignored `.env`, exports `NODE_AUTH_TOKEN` from `NPM_TOKEN`, then runs `release:npm` via **node** (`scripts/release-npm.mjs`, `--dry-run` or `--publish`) so the outer `npm run` does not strip registry auth before the release script runs. Documented in `docs/releasing.md` Path B.
 
 ### Fixed
@@ -15,6 +39,8 @@ All notable changes to `@thirdfy/agent-cli` are documented here. The format is b
 
 ### Changed
 
+- Refactored portfolio-related read commands to share query-param and `meta` construction (`applySharedPortfolioListingFiltersToQuery`, `buildAgentKeyPortfolioSummaryQuery`, `metaPortfolioListingFilters`) so telemetry summary and portfolio summary stay aligned.
+- Documented portfolio analytics commands as read-only CLI surfaces over Thirdfy API accounting.
 - **CI:** Release workflow no longer requests `id-token: write` (npm publish uses `secrets.NPM_TOKEN` only).
 
 ## [0.1.27] - 2026-05-05

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, and README refresh through **v0.1.27**.
+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

@@ -279,6 +279,14 @@ async function main() {
     await commandWalletSubmit(context, subFlags, capabilities);
     return;
   }
+  if (commandKey3 === 'analytics portfolio') {
+    await commandAnalyticsPortfolio(context, subFlags, capabilities);
+    return;
+  }
+  if (commandKey3 === 'analytics leaderboard') {
+    await commandAnalyticsLeaderboard(context, subFlags, capabilities);
+    return;
+  }
 
   const rootCommand = parsed.positionals[0];
   switch (rootCommand) {
@@ -675,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() !== '';
@@ -695,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',
       },
     };
   }
@@ -751,7 +794,7 @@ function normalizeSwapAmountContract(params) {
       ...params,
       amountInHuman,
       amountInRaw,
-      amountIn: amountInRaw,
+      amountIn: amountInHuman,
       tokenInDecimals: decimals,
     },
     swapInput: {
@@ -808,21 +851,82 @@ async function commandCatalogsList(ctx, flags, capabilities) {
   });
 }
 
-async function commandDataSummary(ctx, flags, capabilities) {
+/** Query params shared by telemetry summary and portfolio summary (`agentKey` + scope filters). */
+function applySharedPortfolioListingFiltersToQuery(query, flags) {
+  if (flags.chainId) query.set('chainId', String(flags.chainId));
+  if (flags.network) query.set('networkId', String(flags.network));
+  if (flags.networkId) query.set('networkId', String(flags.networkId));
+  if (flags.chainType) query.set('chainType', String(flags.chainType));
+  if (flags.category) query.set('category', String(flags.category));
+}
+
+function buildAgentKeyPortfolioSummaryQuery(flags, { includeLimit = false } = {}) {
   const agentKey = requireFlag(flags, 'agentKey', 'Missing --agent-key');
   const query = new URLSearchParams({ agentKey });
-  if (flags.chainId) query.set('chainId', String(flags.chainId));
-  if (flags.limit) query.set('limit', String(flags.limit));
+  applySharedPortfolioListingFiltersToQuery(query, flags);
+  if (includeLimit && flags.limit) query.set('limit', String(flags.limit));
+  return { agentKey, query };
+}
+
+/** `meta` fields that echo portfolio scope filters (keep in sync with query construction). */
+function metaPortfolioListingFilters(ctx, flags, capabilities, agentKey) {
+  return {
+    apiBase: ctx.apiBase,
+    agentKey,
+    chainId: flags.chainId ? Number(flags.chainId) : null,
+    networkId: flags.networkId || flags.network || null,
+    chainType: flags.chainType || null,
+    category: flags.category || null,
+    capabilitiesVersion: capabilities?.contractVersion || null,
+  };
+}
+
+async function commandDataSummary(ctx, flags, capabilities) {
+  const { agentKey, query } = buildAgentKeyPortfolioSummaryQuery(flags, { includeLimit: true });
   const response = await apiGet(ctx, `/api/v1/agent/telemetry/summary?${query.toString()}`);
   printEnvelope({
     success: true,
     code: 'DATA_SUMMARY_OK',
     message: 'Agent data summary loaded',
     data: response,
+    meta: metaPortfolioListingFilters(ctx, flags, capabilities, agentKey),
+  });
+}
+
+async function commandAnalyticsPortfolio(ctx, flags, capabilities) {
+  const { agentKey, query } = buildAgentKeyPortfolioSummaryQuery(flags);
+  const response = await apiGet(ctx, `/api/v1/agent/portfolio/summary?${query.toString()}`);
+  printEnvelope({
+    success: true,
+    code: 'ANALYTICS_PORTFOLIO_OK',
+    message: 'Agent portfolio summary loaded',
+    data: response,
+    meta: metaPortfolioListingFilters(ctx, flags, capabilities, agentKey),
+  });
+}
+
+async function commandAnalyticsLeaderboard(ctx, flags, capabilities) {
+  const query = new URLSearchParams();
+  const window = flags.window || '7d';
+  const metric = flags.metric || 'roiPct';
+  applySharedPortfolioListingFiltersToQuery(query, flags);
+  query.set('window', String(window));
+  query.set('metric', String(metric));
+  if (flags.limit) query.set('limit', String(flags.limit));
+  const response = await apiGet(ctx, `/api/v1/agent/portfolio/leaderboard?${query.toString()}`);
+  printEnvelope({
+    success: true,
+    code: 'ANALYTICS_LEADERBOARD_OK',
+    message: 'Agent portfolio leaderboard loaded',
+    data: response,
     meta: {
       apiBase: ctx.apiBase,
-      agentKey,
-      chainId: flags.chainId ? Number(flags.chainId) : null,
+      networkId: flags.networkId || flags.network || null,
+      chainType: flags.chainType || null,
+      category: flags.category || null,
+      window,
+      metric,
+      capabilitiesVersion: capabilities?.contractVersion || null,
     },
   });
 }
@@ -3020,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 = {
@@ -4009,7 +4133,9 @@ Core commands:
   thirdfy-agent whoami [--json]
   thirdfy-agent catalogs list [--json]
   thirdfy-agent actions [--catalog <id>] [--provider <id>] [--agent-api-key <key>] [--chain-id <id>] [--run-mode <mode>] [--json]
-  thirdfy-agent data summary --agent-key <key> [--chain-id <id>] [--limit <n>] [--json]
+  thirdfy-agent data summary --agent-key <key> [--chain-id <id>] [--network <id>] [--category trading|yield|prediction] [--limit <n>] [--json]
+  thirdfy-agent analytics portfolio --agent-key <key> [--network base-mainnet] [--category trading|yield|prediction] [--json]
+  thirdfy-agent analytics leaderboard [--category trading|yield|prediction] [--network base-mainnet] [--window 24h|7d|30d|all] [--metric roiPct|pnlUsd|aprPct|currentValueUsd] [--json]
   thirdfy-agent track actions --agent-key <key> [--limit <n>] [--json]
   thirdfy-agent track events --agent-key <key> [--limit <n>] [--json]
   thirdfy-agent track action --agent-api-key <key> --action <name> [--category <name>] [--source agent|external_mcp|operator|thirdfy|custom] [--provider <id>] [--protocol <id>] [--namespace <name>] [--action-type supported|custom] [--status observed|planned|skipped|submitted|confirmed|failed|blocked] [--chain-id <id>] [--params <json>] [--json]
@@ -4062,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.27",
+  "version": "0.1.31",
   "description": "Thirdfy Agent CLI for onboarding, governance preflight, execute-intent, and status polling.",
   "type": "module",
   "bin": {