@thirdfy/agent-cli 0.1.27 → 0.1.28

package/CHANGELOG.md

@@ -4,8 +4,12 @@ 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
@@ -15,6 +19,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). 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.
 

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,
     },
   });
 }
@@ -4009,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.27",
+  "version": "0.1.28",
   "description": "Thirdfy Agent CLI for onboarding, governance preflight, execute-intent, and status polling.",
   "type": "module",
   "bin": {