@thirdfy/agent-cli 0.1.21 → 0.1.22

package/CHANGELOG.md

@@ -4,10 +4,20 @@ All notable changes to `@thirdfy/agent-cli` are documented here. The format is b
 
 ## [Unreleased]
 
+## [0.1.22] - 2026-04-28
+
+**npm:** [`@thirdfy/agent-cli@0.1.22`](https://www.npmjs.com/package/@thirdfy/agent-cli/v/0.1.22)  
+**Git tag:** `v0.1.22`
+
+### Added
+
+- **Agent tracking/data commands:** Added `data summary`, `track actions`, `track events`, and `track action` so operators and agents can read Thirdfy-owned analytics and report actions without raw telemetry HTTP calls.
+- **Permissive custom tracking:** `track action` now supports unknown/custom action names with optional `--source`, `--provider`, `--protocol`, `--namespace`, and `--action-type` metadata.
+
 ## [0.1.21] - 2026-04-26
 
-**npm:** [`@thirdfy/agent-cli@0.1.21`](https://www.npmjs.com/package/@thirdfy/agent-cli/v/0.1.21) (after publish)  
-**Git tag:** `v0.1.21`
+**npm:** [`@thirdfy/agent-cli@0.1.21`](https://www.npmjs.com/package/@thirdfy/agent-cli/v/0.1.21)  
+**Git tag:** [`v0.1.21`](https://github.com/thirdfy/agent-cli/releases/tag/v0.1.21)
 
 ### Fixed
 

package/bin/thirdfy-agent.mjs

@@ -176,6 +176,18 @@ async function main() {
     case 'credits balance':
       await commandCreditsBalance(context, subFlags, capabilities);
       return;
+    case 'data summary':
+      await commandDataSummary(context, subFlags, capabilities);
+      return;
+    case 'track actions':
+      await commandTrackList(context, subFlags, capabilities, 'actions');
+      return;
+    case 'track events':
+      await commandTrackList(context, subFlags, capabilities, 'events');
+      return;
+    case 'track action':
+      await commandTrackAction(context, subFlags, capabilities);
+      return;
     case 'delegation create':
       await commandDelegationCreate(context, subFlags, capabilities);
       return;
@@ -539,6 +551,82 @@ async function commandCatalogsList(ctx, flags, capabilities) {
   });
 }
 
+async function commandDataSummary(ctx, flags, capabilities) {
+  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));
+  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: {
+      apiBase: ctx.apiBase,
+      agentKey,
+      chainId: flags.chainId ? Number(flags.chainId) : null,
+    },
+  });
+}
+
+async function commandTrackList(ctx, flags, capabilities, kind) {
+  const agentKey = requireFlag(flags, 'agentKey', 'Missing --agent-key');
+  const query = new URLSearchParams({ agentKey });
+  if (flags.limit) query.set('limit', String(flags.limit));
+  const response = await apiGet(ctx, `/api/v1/agent/telemetry/${kind}?${query.toString()}`);
+  printEnvelope({
+    success: true,
+    code: kind === 'events' ? 'TRACK_EVENTS_OK' : 'TRACK_ACTIONS_OK',
+    message: kind === 'events' ? 'Tracked agent events loaded' : 'Tracked agent actions loaded',
+    data: response,
+    meta: {
+      apiBase: ctx.apiBase,
+      agentKey,
+      kind,
+    },
+  });
+}
+
+async function commandTrackAction(ctx, flags, capabilities) {
+  const agentApiKey = resolveAgentApiKey(flags, 'thirdfy');
+  const action = requireFlag(flags, 'action', 'Missing --action');
+  const payload = {
+    agentApiKey,
+    action,
+    status: String(flags.status || 'observed'),
+  };
+  if (flags.agentKey) payload.agentKey = String(flags.agentKey);
+  if (flags.eventId) payload.eventId = String(flags.eventId);
+  if (flags.idempotencyKey) payload.idempotencyKey = String(flags.idempotencyKey);
+  if (flags.category) payload.category = String(flags.category);
+  if (flags.source) payload.source = String(flags.source);
+  if (flags.provider) payload.provider = String(flags.provider);
+  if (flags.protocol) payload.protocol = String(flags.protocol);
+  if (flags.namespace) payload.namespace = String(flags.namespace);
+  if (flags.actionType) payload.actionType = String(flags.actionType);
+  if (flags.chainId) payload.chainId = Number(flags.chainId);
+  if (flags.amountUsd) payload.amountUsd = Number(flags.amountUsd);
+  if (flags.txHash) payload.txHash = String(flags.txHash);
+  if (flags.userDid) payload.userDid = String(flags.userDid);
+  if (flags.params) payload.params = parseJsonFlag(flags, 'params');
+  if (flags.decision) payload.decision = parseJsonFlag(flags, 'decision');
+  if (flags.proof) payload.proof = parseJsonFlag(flags, 'proof');
+
+  const response = await apiPost(ctx, '/api/v1/agent/telemetry/actions', payload);
+  printEnvelope({
+    success: Boolean(response?.success !== false),
+    code: response?.success === false ? 'TRACK_ACTION_FAILED' : 'TRACK_ACTION_OK',
+    message: response?.success === false ? 'Agent action tracking failed' : 'Agent action tracked',
+    data: response,
+    meta: {
+      apiBase: ctx.apiBase,
+      action,
+      chainId: payload.chainId || null,
+    },
+  });
+}
+
 async function commandActions(ctx, flags, capabilities) {
   const policyAware = Boolean(flags.agentApiKey);
   const actions = applyActionFilters(await getCachedActionsCatalog(ctx, flags), flags);
@@ -3479,6 +3567,10 @@ 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 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]
   thirdfy-agent delegation create [--auth-token <token> | --owner-session-token <token>] --agent-key <key> --owner-address <addr> --token-address <addr> --max-usd-per-day <usd> [--session-account-address <addr>] [--json]
   thirdfy-agent delegation init-custodial [--auth-token <token> | --owner-session-token <token>] [--chain-id <id>] [--json]
   thirdfy-agent delegation custodial-grant [--auth-token <token> | --owner-session-token <token>] --agent-key <key> --token-address <addr> --max-usd-per-day <usd> [--chain-id <id>] [--period-duration <sec>] [--expiry-seconds <sec>] [--json]

package/package.json

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