@thirdfy/agent-cli 0.2.15 → 0.2.16

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to `@thirdfy/agent-cli` are documented here. The format is b
 
 ## [Unreleased]
 
+## [0.2.16] - 2026-06-30
+
+### Added
+
+- `credits` command group: `balance`, `transactions` (with `includeMetadata`), `usage`, `models list`, `models estimate`, and `pricing quote`. Passes `toolCallsList` into pricing estimate for action-tier line items. Pairs with Thirdfy API **v3.8.2+** and `thirdfy-mcp` **v0.0.65+**.
+
 ## [0.2.15] - 2026-06-26
 
 ### Added

package/README.md

@@ -40,9 +40,9 @@ Run without global install:
 npx @thirdfy/agent-cli --help
 ```
 
-## What's new in v0.2.15
+## What's new in v0.2.16
 
-- `hummingbot` command group for governed Condor CEX executor ops: `status`, `connectors`, `executor-schema`, `executor-create`. Provider runbook at [`docs/providers/hummingbot.md`](./docs/providers/hummingbot.md). Pairs with Thirdfy API **v3.6.0+** and `thirdfy-mcp` **v0.0.64+**.
+- `credits` commands for balance, transactions (optional billing metadata), usage summary, model pricing, turn estimate, and action quote. Pairs with Thirdfy API **v3.8.2+** and `thirdfy-mcp` **v0.0.65+**.
 
 Older versions: see [CHANGELOG.md](./CHANGELOG.md) and [GitHub Releases](https://github.com/thirdfy/agent-cli/releases).
 

package/package.json

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

package/src/cli/help.mjs

@@ -68,6 +68,11 @@ Core commands:
   thirdfy-agent prompt "<natural language prompt>" [--json]
   thirdfy-agent intent-status --intent-id <id> [--json]
   thirdfy-agent credits balance --auth-token <token> [--json]
+  thirdfy-agent credits transactions --auth-token <token> [--page <n>] [--limit <n>] [--include-metadata] [--json]
+  thirdfy-agent credits usage --auth-token <token> [--range 7d|30d|90d] [--json]
+  thirdfy-agent models list --auth-token <token> [--json]
+  thirdfy-agent models estimate --auth-token <token> --model <key> [--input-tokens <n>] [--output-tokens <n>] [--json]
+  thirdfy-agent pricing quote --auth-token <token> --action <action-key> [--chain-id <id>] [--json]
 
 Global flags:
   --api-base <url>   default: https://api.thirdfy.com

package/src/cli/manifest.mjs

@@ -161,6 +161,41 @@ export const CLI_MANIFEST = [
     options: ['auth'],
     description: 'Credits balance',
   },
+  {
+    path: ['credits', 'transactions'],
+    handler: 'commandCreditsTransactions',
+    tier: 'online',
+    options: ['auth', 'credits'],
+    description: 'Paginated credit transactions with optional billing metadata',
+  },
+  {
+    path: ['credits', 'usage'],
+    handler: 'commandCreditsUsage',
+    tier: 'online',
+    options: ['auth', 'credits'],
+    description: 'Credits usage summary by model, provider, and action',
+  },
+  {
+    path: ['models', 'list'],
+    handler: 'commandModelsList',
+    tier: 'online',
+    options: ['auth'],
+    description: 'List model pricing from chat_model_catalog',
+  },
+  {
+    path: ['models', 'estimate'],
+    handler: 'commandModelsEstimate',
+    tier: 'online',
+    options: ['auth', 'credits', 'execution'],
+    description: 'Estimate model and action credits before execution',
+  },
+  {
+    path: ['pricing', 'quote'],
+    handler: 'commandPricingQuote',
+    tier: 'online',
+    options: ['auth', 'execution'],
+    description: 'Quote action-tier credits for a catalog action',
+  },
   {
     path: ['data', 'summary'],
     handler: 'commandDataSummary',

package/src/cli/options/credits.mjs

@@ -0,0 +1,15 @@
+export function attachCreditsOptions(cmd) {
+  return cmd
+    .option('--page <n>', 'page number for transactions', '1')
+    .option('--limit <n>', 'page size for transactions', '20')
+    .option('--include-metadata', 'include unified billing metadata on transactions')
+    .option('--range <range>', 'usage summary range (7d, 30d, 90d)', '7d')
+    .option('--model <key>', 'chat model key for pricing estimate')
+    .option('--input-tokens <n>', 'estimated input tokens for pricing estimate', '0')
+    .option('--output-tokens <n>', 'estimated output tokens for pricing estimate', '0')
+    .option(
+      '--tool-calls <value>',
+      'tool call count or comma-separated AgentKit tool names for pricing estimate',
+    )
+    .option('--surface <surface>', 'billing surface (console, automation, cli, agent_api)', 'cli');
+}

package/src/cli/options/index.mjs

@@ -11,6 +11,7 @@ import { attachPolymarketOptions } from './polymarket.mjs';
 import { attachHummingbotOptions } from './hummingbot.mjs';
 import { attachAgentRegisterOptions } from './agent.mjs';
 import { attachChainOptions } from './chains.mjs';
+import { attachCreditsOptions } from './credits.mjs';
 
 const BUNDLES = {
   auth: attachAuthOptions,
@@ -25,6 +26,7 @@ const BUNDLES = {
   hummingbot: attachHummingbotOptions,
   agent: attachAgentRegisterOptions,
   chains: attachChainOptions,
+  credits: attachCreditsOptions,
 };
 
 /** @param {import('commander').Command} cmd */

package/src/commands/credits.mjs

@@ -0,0 +1,134 @@
+import { requireFlag } from '../core/args.mjs';
+import { apiGet, apiPost } from '../core/http.mjs';
+
+function resolveToolCallsEstimate(flags) {
+  const raw = flags.toolCalls ?? flags.toolCallsList;
+  if (raw == null || raw === '') {
+    return { toolCalls: 0, toolCallsList: undefined };
+  }
+
+  const value = String(raw).trim();
+  if (!value) {
+    return { toolCalls: 0, toolCallsList: undefined };
+  }
+
+  if (/^\d+$/.test(value)) {
+    return { toolCalls: Number(value), toolCallsList: undefined };
+  }
+
+  const toolCallsList = value
+    .split(',')
+    .map((entry) => entry.trim())
+    .filter(Boolean);
+
+  return {
+    toolCalls: toolCallsList.length,
+    toolCallsList,
+  };
+}
+
+export function createCreditsCommands({ printEnvelope, getAuthToken }) {
+  async function commandCreditsTransactions(ctx, flags) {
+    const authToken = getAuthToken(flags, 'Missing --auth-token (or THIRDFY_AUTH_TOKEN) for credits transactions');
+    const page = Number(flags.page || 1);
+    const limit = Number(flags.limit || 20);
+    const includeMetadata = flags.includeMetadata === true || flags.includeMetadata === 'true';
+    const response = await apiGet(
+      ctx,
+      `/api/v1/credits/transactions?page=${page}&limit=${limit}&includeMetadata=${includeMetadata}`,
+      { Authorization: `Bearer ${authToken}` },
+    );
+    printEnvelope({
+      success: true,
+      code: 'OK',
+      message: 'Credit transactions loaded',
+      data: response,
+      meta: { apiBase: ctx.apiBase, page, limit, includeMetadata },
+    });
+  }
+
+  async function commandCreditsUsage(ctx, flags) {
+    const authToken = getAuthToken(flags, 'Missing --auth-token (or THIRDFY_AUTH_TOKEN) for credits usage');
+    const range = String(flags.range || '7d');
+    const response = await apiGet(ctx, `/api/v1/credits/usage/summary?range=${encodeURIComponent(range)}`, {
+      Authorization: `Bearer ${authToken}`,
+    });
+    printEnvelope({
+      success: true,
+      code: 'OK',
+      message: 'Credits usage summary loaded',
+      data: response,
+      meta: { apiBase: ctx.apiBase, range },
+    });
+  }
+
+  async function commandModelsList(ctx, flags) {
+    const authToken = getAuthToken(flags, 'Missing --auth-token (or THIRDFY_AUTH_TOKEN) for models list');
+    const response = await apiGet(ctx, '/api/v1/credits/pricing/models', {
+      Authorization: `Bearer ${authToken}`,
+    });
+    printEnvelope({
+      success: true,
+      code: 'OK',
+      message: 'Model pricing loaded',
+      data: response,
+      meta: { apiBase: ctx.apiBase },
+    });
+  }
+
+  async function commandModelsEstimate(ctx, flags) {
+    const authToken = getAuthToken(flags, 'Missing --auth-token (or THIRDFY_AUTH_TOKEN) for models estimate');
+    const modelKey = requireFlag(flags, 'model', 'Missing --model for models estimate');
+    const { toolCalls, toolCallsList } = resolveToolCallsEstimate(flags);
+    const response = await apiPost(
+      ctx,
+      '/api/v1/credits/pricing/estimate',
+      {
+        modelKey,
+        inputTokens: Number(flags.inputTokens || 0),
+        outputTokens: Number(flags.outputTokens || 0),
+        toolCalls,
+        toolCallsList,
+        chainId: Number(flags.chainId || 0) || undefined,
+        surface: flags.surface || 'cli',
+      },
+      { Authorization: `Bearer ${authToken}` },
+    );
+    printEnvelope({
+      success: true,
+      code: 'OK',
+      message: 'Model estimate generated',
+      data: response,
+      meta: { apiBase: ctx.apiBase, modelKey },
+    });
+  }
+
+  async function commandPricingQuote(ctx, flags) {
+    const authToken = getAuthToken(flags, 'Missing --auth-token (or THIRDFY_AUTH_TOKEN) for pricing quote');
+    const action = requireFlag(flags, 'action', 'Missing --action for pricing quote');
+    const response = await apiPost(
+      ctx,
+      '/api/v1/credits/pricing/quote',
+      {
+        actionKey: action,
+        chainId: Number(flags.chainId || 8453),
+      },
+      { Authorization: `Bearer ${authToken}` },
+    );
+    printEnvelope({
+      success: true,
+      code: 'OK',
+      message: 'Action pricing quote generated',
+      data: response,
+      meta: { apiBase: ctx.apiBase, action },
+    });
+  }
+
+  return {
+    commandCreditsTransactions,
+    commandCreditsUsage,
+    commandModelsList,
+    commandModelsEstimate,
+    commandPricingQuote,
+  };
+}

package/src/runtime/handlers.mjs

@@ -8,6 +8,7 @@ import { createWalletCommands } from '../commands/wallet.mjs';
 import { createDelegationCommands } from '../commands/delegation.mjs';
 import { createBootstrapCommands } from '../commands/bootstrap.mjs';
 import { createDiscoveryCommands } from '../commands/discovery.mjs';
+import { createCreditsCommands } from '../commands/credits.mjs';
 import { createTelemetryCommands } from '../commands/telemetry.mjs';
 import { createCredentialsCommands } from '../commands/credentials.mjs';
 import { createAgentCommands } from '../commands/agent.mjs';
@@ -56,6 +57,11 @@ export function createRuntimeHandlers(deps) {
     resolveAgentApiKey,
   });
 
+  const __credits = createCreditsCommands({
+    printEnvelope,
+    getAuthToken,
+  });
+
   const __telemetry = createTelemetryCommands({
     printEnvelope,
     resolveAgentApiKey,
@@ -179,6 +185,11 @@ export function createRuntimeHandlers(deps) {
     commandCatalogsList: __discovery.commandCatalogsList,
     commandActions: __discovery.commandActions,
     commandCreditsBalance: __discovery.commandCreditsBalance,
+    commandCreditsTransactions: __credits.commandCreditsTransactions,
+    commandCreditsUsage: __credits.commandCreditsUsage,
+    commandModelsList: __credits.commandModelsList,
+    commandModelsEstimate: __credits.commandModelsEstimate,
+    commandPricingQuote: __credits.commandPricingQuote,
     commandDataSummary: __telemetry.commandDataSummary,
     commandTrackList: __telemetry.commandTrackList,
     commandTrackAction: __telemetry.commandTrackAction,