@thirdfy/agent-cli 0.1.25 → 0.1.28

package/CHANGELOG.md

@@ -4,9 +4,53 @@ All notable changes to `@thirdfy/agent-cli` are documented here. The format is b
 
 ## [Unreleased]
 
+## [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
+
+- `release:npm`: `npm publish` now uses a short-lived `NPM_CONFIG_USERCONFIG` file with `//registry.npmjs.org/:_authToken=…` when a token is present, so npm 10+ authenticates reliably (Bearer env alone was not enough in this repo’s CLI runs).
+- `release:npm -- --publish`: when both `NODE_AUTH_TOKEN` and `NPM_TOKEN` are set but `NODE_AUTH_TOKEN` is much shorter than `NPM_TOKEN` (common placeholder), use `NPM_TOKEN` for the publish subprocess and print a warning.
+
+### 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
+
+**npm:** [`@thirdfy/agent-cli@0.1.27`](https://www.npmjs.com/package/@thirdfy/agent-cli/v/0.1.27)  
+**Git tag:** [`v0.1.27`](https://github.com/thirdfy/agent-cli/releases/tag/v0.1.27)
+
+### Added
+
+- Maintainer [docs/releasing.md](./docs/releasing.md) runbook for npm + GitHub Actions, `.env.example` template, and `npm run release:npm` (`scripts/release-npm.mjs`) with dry-run default and stricter checks for `--publish`.
+
+### Fixed
+
+- **Bugbot (PR #24):** `release:npm` maps `NPM_TOKEN` → `NODE_AUTH_TOKEN` for the publish subprocess; `npm publish` uses `--ignore-scripts` after explicit checks so `prepublishOnly` does not run twice. **Release** GitHub Action uses the same `npm publish --ignore-scripts` after its validation steps.
+
+## [0.1.26] - 2026-05-05
+
+**Git tag:** [`v0.1.26`](https://github.com/thirdfy/agent-cli/releases/tag/v0.1.26) — provider parity merged to `main`; not published to the npm registry (use **0.1.27** for the first npm build that includes PR #23 plus release tooling from PR #24).
+
+### Fixed
+
+- **Provider discovery parity:** Align `actions --provider` filtering with MCP/API provider taxonomy for provider-less spot, Hyperliquid/perps, bridge, DogeOS, prediction, and earn catalog rows.
+- **Metadata-first discovery:** Prefer API-supplied `providerId`, `domain`, and `category` for provider filtering, keeping action-name inference as a legacy fallback only.
+- **Bugbot:** `actions --provider` key fallback now matches provider suffix patterns (e.g. `execute_bridge` for `--provider bridge`).
+- **Bugbot:** After metadata mismatch, hyperliquid/polymarket/bridge/DogeOS branches use action-key matching only (removed redundant `provider ===` checks and dead final equality).
+
 ## [0.1.25] - 2026-05-04
 
-**npm:** `@thirdfy/agent-cli@0.1.25` (publish after merge)
+**npm:** [`@thirdfy/agent-cli@0.1.25`](https://www.npmjs.com/package/@thirdfy/agent-cli/v/0.1.25)  
+**Git tag:** [`v0.1.25`](https://github.com/thirdfy/agent-cli/releases/tag/v0.1.25)
 
 ### Changed
 

package/README.md

@@ -40,7 +40,9 @@ npx @thirdfy/agent-cli --help
 
 ## Release notes
 
-Version history and highlights: [CHANGELOG.md](./CHANGELOG.md). Recent CLI releases document earn/prediction provider discovery, case-insensitive `actions --provider` filtering, self-lane guards for offchain venue orders, and npm-facing README refresh (**v0.1.24**).
+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**.
+
+**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.
 
 ## Quick start
 

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) {
@@ -808,21 +816,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,
     },
   });
 }
@@ -3228,6 +3297,172 @@ function formatActionList(items) {
     .join(', ');
 }
 
+function normalizeProviderId(value) {
+  return String(value || '').trim().toLowerCase();
+}
+
+function rowActionKey(action) {
+  return getActionKey(action)
+    .replace(/-/g, '_')
+    .toLowerCase();
+}
+
+function canonicalActionKey(action) {
+  return getActionKey(action)
+    .replace(/_/g, '-')
+    .toLowerCase();
+}
+
+function inferActionProvider(action) {
+  // API catalog metadata (`providerId`, `domain`, `category`) is the source of truth.
+  // This fallback only keeps older catalog rows / older API deployments discoverable.
+  const key = canonicalActionKey(action);
+  const knownMap = {
+    swap: 'trading',
+    'execute-optimal-swap': 'trading',
+    'get-best-trading-quote': 'trading',
+    'dogeos-barkswap-get-quote': 'dogeos-barkswap',
+    'dogeos-barkswap-execute-swap': 'dogeos-barkswap',
+    'dogeos-get-ecosystem-overview': 'dogeos-ecosystem',
+    'dogeos-get-wallet-actionability': 'dogeos-ecosystem',
+    'dogeos-prepare-trade': 'dogeos-ecosystem',
+    'dogeos-prepare-token-launch': 'dogeos-ecosystem',
+    'dogeos-get-chain-insights': 'dogeos-ecosystem',
+    'dogeos-get-trending-tokens': 'dogeos-ecosystem',
+    'dogeos-get-new-tokens': 'dogeos-ecosystem',
+    'dogeos-get-early-bird-tokens': 'dogeos-ecosystem',
+    'dogeos-get-only-moon-tokens': 'dogeos-ecosystem',
+    'dogeos-get-big-wins-tokens': 'dogeos-ecosystem',
+    'dogeos-get-related-tokens': 'dogeos-ecosystem',
+    'dogeos-laika-read-contract': 'dogeos-laika',
+    'dogeos-laika-execute-raw': 'dogeos-laika',
+    'dogeos-laika-launch-token': 'dogeos-laika',
+    'dogeos-laika-buy-token': 'dogeos-laika',
+    'dogeos-laika-claim': 'dogeos-laika',
+    'dogeos-laika-token-state': 'dogeos-laika',
+    'get-governance-v2-overview': 'governance-v2',
+    'get-governance-v2-timeseries': 'governance-v2',
+    'get-governance-v2-breakdowns': 'governance-v2',
+    'get-hyperliquid-perps-meta': 'hyperliquid',
+    'get-hyperliquid-all-mids': 'hyperliquid',
+    'get-hyperliquid-l2-book': 'hyperliquid',
+    'get-hyperliquid-candles': 'hyperliquid',
+    'get-hyperliquid-user-state': 'hyperliquid',
+    'get-hyperliquid-open-orders': 'hyperliquid',
+    'get-hyperliquid-setup-status': 'hyperliquid',
+    'get-hyperliquid-onboarding-plan': 'hyperliquid',
+    'prepare-hyperliquid-onboarding': 'hyperliquid',
+    'claim-hyperliquid-testnet-faucet': 'hyperliquid',
+    'get-hyperliquid-builder-fee-status': 'hyperliquid',
+    'approve-hyperliquid-agent': 'hyperliquid',
+    'approve-hyperliquid-builder-fee': 'hyperliquid',
+    'register-hyperliquid-referrer': 'hyperliquid',
+    'set-hyperliquid-referrer': 'hyperliquid',
+    'get-hyperliquid-referral-status': 'hyperliquid',
+    'deposit-hyperliquid-staking': 'hyperliquid',
+    'deposit-hyperliquid-bridge': 'hyperliquid',
+    'place-hyperliquid-perps-order': 'hyperliquid',
+    'get-perps-markets': 'hyperliquid',
+    'get-perps-account': 'hyperliquid',
+    'get-perps-position': 'hyperliquid',
+    'place-perps-order': 'hyperliquid',
+    'cancel-perps-order': 'hyperliquid',
+    'get-earn-opportunities': 'earn',
+    'get-earn-provider': 'earn',
+    'get-earn-position': 'earn',
+    'deposit-earn-position': 'earn',
+    'withdraw-earn-position': 'earn',
+    'get-morpho-vaults': 'morpho',
+    'deposit-morpho-vault': 'morpho',
+    'withdraw-morpho-vault': 'morpho',
+    'get-curve-pools': 'curve',
+    'get-curve-pool-details': 'curve',
+    'deposit-curve-pool': 'curve',
+    'withdraw-curve-pool': 'curve',
+    'get-prediction-markets': 'polymarket',
+    'get-prediction-market': 'polymarket',
+    'get-prediction-order-book': 'polymarket',
+    'get-prediction-position': 'polymarket',
+    'place-prediction-order': 'polymarket',
+    'cancel-prediction-order': 'polymarket',
+    'get-polymarket-markets': 'polymarket',
+    'get-polymarket-market': 'polymarket',
+    'get-polymarket-setup-status': 'polymarket',
+    'get-polymarket-order': 'polymarket',
+    'place-polymarket-order': 'polymarket',
+  };
+  if (knownMap[key]) return knownMap[key];
+  if (key.includes('hyperliquid')) return 'hyperliquid';
+  if (key.includes('polymarket') || key.includes('prediction')) return 'polymarket';
+  if (key.includes('morpho')) return 'morpho';
+  if (key.includes('curve')) return 'curve';
+  if (key.includes('earn')) return 'earn';
+  if (key.includes('bridge')) return 'bridge';
+  if (key.includes('dogeos-barkswap')) return 'dogeos-barkswap';
+  if (key.includes('dogeos-laika')) return 'dogeos-laika';
+  if (key.includes('dogeos')) return 'dogeos-ecosystem';
+  return '';
+}
+
+function getActionProviderWithInference(action) {
+  return getActionProvider(action) || inferActionProvider(action);
+}
+
+function isEarnCatalogAction(action) {
+  const actionKey = rowActionKey(action);
+  return (
+    actionKey.includes('_earn_') ||
+    normalizeProviderId(action?.domain) === 'earn' ||
+    normalizeProviderId(action?.category) === 'earn'
+  );
+}
+
+function isSpotTradingCatalogAction(action) {
+  const actionKey = rowActionKey(action);
+  return actionKey === 'swap' || actionKey === 'execute_optimal_swap' || actionKey === 'get_best_trading_quote';
+}
+
+function isProviderActionKey(action, provider) {
+  const actionKey = rowActionKey(action);
+  const normalizedProvider = normalizeProviderId(provider).replace(/-/g, '_');
+  if (!actionKey || !normalizedProvider) return false;
+  return (
+    actionKey === normalizedProvider ||
+    actionKey.startsWith(`${normalizedProvider}_`) ||
+    actionKey.includes(`_${normalizedProvider}_`) ||
+    actionKey.endsWith(`_${normalizedProvider}`)
+  );
+}
+
+function actionMatchesProvider(action, requestedProvider, allActions) {
+  const provider = getActionProviderWithInference(action);
+  const actionKey = rowActionKey(action);
+  if (provider === requestedProvider) return true;
+  if (requestedProvider === 'trading') return isSpotTradingCatalogAction(action);
+  // Here resolved metadata already disagrees with the filter; fall back to action-key shape only.
+  if (requestedProvider === 'hyperliquid') return isProviderActionKey(action, 'hyperliquid');
+  if (requestedProvider === 'polymarket') return isProviderActionKey(action, 'polymarket');
+  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);
+  }
+  if (requestedProvider === 'morpho' || requestedProvider === 'curve') {
+    const hasProtocolSpecificEarnRows = allActions.some((candidate) => getActionProviderWithInference(candidate) === requestedProvider);
+    return isProviderActionKey(action, requestedProvider) || (!hasProtocolSpecificEarnRows && isEarnCatalogAction(action));
+  }
+  if (requestedProvider === 'prediction') {
+    return (
+      provider === 'polymarket' ||
+      provider === 'prediction' ||
+      actionKey.includes('_prediction_') ||
+      normalizeProviderId(action?.domain) === 'prediction' ||
+      normalizeProviderId(action?.category) === 'prediction'
+    );
+  }
+  return isProviderActionKey(action, requestedProvider);
+}
+
 function applyActionFilters(actions, flags) {
   let filtered = actions;
   if (flags.catalog) {
@@ -3235,21 +3470,14 @@ function applyActionFilters(actions, flags) {
     filtered = filtered.filter((a) => String(a.catalog || a.catalogId || 'default').trim().toLowerCase() === expectedCatalog);
   }
   if (flags.provider) {
-    const expectedProvider = String(flags.provider).trim().toLowerCase();
-    filtered = filtered.filter((a) => {
-      const provider = getActionProvider(a);
-      const actionKey = getActionKey(a).replace(/-/g, '_').toLowerCase();
-      if (provider === expectedProvider) return true;
-      if (expectedProvider === 'earn') return provider === 'morpho' || provider === 'curve' || actionKey.includes('_earn_');
-      if (expectedProvider === 'prediction') return provider === 'polymarket' || actionKey.includes('_prediction_');
-      return false;
-    });
+    const expectedProvider = normalizeProviderId(flags.provider);
+    filtered = filtered.filter((a) => actionMatchesProvider(a, expectedProvider, filtered));
   }
   return filtered;
 }
 
 function getActionProvider(action) {
-  return String(action?.provider || action?.providerId || action?.provider_id || action?.catalog || '').trim().toLowerCase();
+  return normalizeProviderId(action?.provider || action?.providerId || action?.provider_id || action?.catalog || '');
 }
 
 async function resolveActionSelection(ctx, flags) {
@@ -3850,7 +4078,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]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thirdfy/agent-cli",
-  "version": "0.1.25",
+  "version": "0.1.28",
   "description": "Thirdfy Agent CLI for onboarding, governance preflight, execute-intent, and status polling.",
   "type": "module",
   "bin": {
@@ -18,6 +18,8 @@
   "scripts": {
     "test": "node --test \"test/**/*.test.cjs\"",
     "lint": "node --check ./bin/thirdfy-agent.mjs",
+    "release:npm": "node ./scripts/release-npm.mjs",
+    "publish:npm:local": "bash ./scripts/local-npm-publish.sh",
     "validate:public-docs": "node ./scripts/validate-public-docs.mjs",
     "validate:cli-contract-schemas": "node ./scripts/validate-cli-contract-schemas.mjs",
     "validate:actions": "node ./scripts/e2e/validate-actions.mjs",