@thirdfy/agent-cli 0.2.15 → 0.2.17

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to `@thirdfy/agent-cli` are documented here. The format is b
 
 ## [Unreleased]
 
+## [0.2.17] - 2026-07-02
+
+### Changed
+
+- Lighter onboarding writes (`complete_lighter_onboarding`, `setup_lighter_api_key`, `register_lighter_api_key`) use a 180s HTTP timeout by default (`THIRDFY_CLI_LONG_TIMEOUT_MS` or `THIRDFY_API_LONG_TIMEOUT_MS`) so managed `run` / `wallet execute` does not abort before the API finishes CCTP or Ethereum legs. Long-action timeout never falls below the configured base timeout. Pairs with Thirdfy API Ireland `sendTx` egress and `thirdfy-mcp` **v0.0.66+**.
+
+## [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.17
 
-- `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+**.
+- Lighter onboarding writes (`complete_lighter_onboarding`, `setup_lighter_api_key`, `register_lighter_api_key`) use a 180s HTTP timeout by default so `run` and `wallet execute` do not abort before CCTP credit or Ethereum `changePubKey` completes. Override with `THIRDFY_CLI_LONG_TIMEOUT_MS`. Pairs with Thirdfy API **v3.9.4+** and `thirdfy-mcp` **v0.0.66+**.
 
 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.17",
   "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,142 @@
+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}`,
+    });
+    const firstModel = response?.models?.[0];
+    const summary = firstModel?.estimatedUsdPerTurn != null
+      ? `${response?.models?.length ?? 0} models · e.g. ${firstModel.modelKey} ~$${Number(firstModel.estimatedUsdPerTurn).toFixed(2)}/turn`
+      : `${response?.models?.length ?? 0} models loaded`;
+    printEnvelope({
+      success: true,
+      code: 'OK',
+      message: flags.json ? 'Model pricing loaded' : `Model pricing loaded: ${summary}`,
+      data: response,
+      meta: { apiBase: ctx.apiBase, ...(flags.json ? {} : { summary }) },
+    });
+  }
+
+  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}` },
+    );
+    const estimate = response?.estimate;
+    const summary = estimate?.chargedUsd != null
+      ? `~$${Number(estimate.chargedUsd).toFixed(2)} charged (${estimate.chargedCredits ?? estimate.totalCredits} credits)`
+      : `${estimate?.chargedCredits ?? estimate?.totalCredits ?? '?'} credits`;
+    printEnvelope({
+      success: true,
+      code: 'OK',
+      message: flags.json ? 'Model estimate generated' : `Model estimate for ${modelKey}: ${summary}`,
+      data: response,
+      meta: { apiBase: ctx.apiBase, modelKey, ...(flags.json ? {} : { summary }) },
+    });
+  }
+
+  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/commands/discovery.mjs

@@ -57,14 +57,19 @@ async function commandCreditsBalance(ctx, flags, capabilities) {
   const response = await apiGet(ctx, '/api/v1/credits/balance', {
     Authorization: `Bearer ${authToken}`,
   });
+  const summary =
+    typeof response?.availableUsd === 'number'
+      ? `$${response.availableUsd.toFixed(2)} available (${response.balance ?? 0} credits)`
+      : `${response?.balance ?? 0} credits`;
   printEnvelope({
     success: true,
     code: 'OK',
-    message: 'Credits balance loaded',
+    message: flags.json ? 'Credits balance loaded' : `Credits balance loaded: ${summary}`,
     data: response,
     meta: {
       apiBase: ctx.apiBase,
       capabilitiesVersion: capabilities?.contractVersion || null,
+      ...(flags.json ? {} : { summary }),
     },
   });
 }

package/src/core/actionTimeouts.mjs

@@ -0,0 +1,29 @@
+import { DEFAULT_TIMEOUT_MS } from './constants.mjs';
+
+const LONG_RUNNING_ACTIONS = new Set([
+  'complete_lighter_onboarding',
+  'setup_lighter_api_key',
+  'register_lighter_api_key',
+]);
+
+function normalizeActionId(action) {
+  return String(action || '')
+    .trim()
+    .replace(/-/g, '_')
+    .toLowerCase();
+}
+
+/** Longer HTTP timeout for Lighter onboarding writes that poll CCTP credit or Ethereum changePubKey. */
+export function resolveActionTimeoutMs(action, baseTimeoutMs = DEFAULT_TIMEOUT_MS) {
+  const base = Number.isFinite(baseTimeoutMs) && baseTimeoutMs > 0 ? baseTimeoutMs : DEFAULT_TIMEOUT_MS;
+  if (!LONG_RUNNING_ACTIONS.has(normalizeActionId(action))) return base;
+  const longMs = Number(
+    process.env.THIRDFY_CLI_LONG_TIMEOUT_MS || process.env.THIRDFY_API_LONG_TIMEOUT_MS || 180_000,
+  );
+  const resolvedLong = Number.isFinite(longMs) && longMs > 0 ? longMs : 180_000;
+  return Math.max(base, resolvedLong);
+}
+
+export function withActionTimeout(ctx, action) {
+  return { ...ctx, timeoutMs: resolveActionTimeoutMs(action, ctx.timeoutMs) };
+}

package/src/runtime/execution/runners.mjs

@@ -10,6 +10,7 @@ import {
   parseBooleanFlag,
 } from '../../core/runMode.mjs';
 import { apiGet, apiPost } from '../../core/http.mjs';
+import { withActionTimeout } from '../../core/actionTimeouts.mjs';
 import { createRequire } from 'module';
 
 const require = createRequire(import.meta.url);
@@ -269,6 +270,7 @@ async function runExecutionByMode(runMode, ctx, flags, resolved, options) {
 
 async function executeThirdfyRun(ctx, flags, resolved, options, runMode = 'thirdfy') {
   const skipPreflight = Boolean(options?.skipPreflight);
+  const actionCtx = withActionTimeout(ctx, resolved.resolvedAction);
   if (!skipPreflight) {
     const preflightPayload = buildIntentPayload(flags, {
       validationOnly: true,
@@ -278,7 +280,7 @@ async function executeThirdfyRun(ctx, flags, resolved, options, runMode = 'third
       mirrorOnly: false,
       hybridWalletMode: options?.hybridWalletMode,
     });
-    const preflight = await apiPost(ctx, '/api/v1/agent/execute-intent', preflightPayload);
+    const preflight = await apiPost(actionCtx, '/api/v1/agent/execute-intent', preflightPayload);
     const preflightNormalized = normalizeIntentResponse(preflight);
     const blockedCount = preflightNormalized.blocked || 0;
     if (!preflightNormalized.success || blockedCount > 0) {
@@ -296,7 +298,7 @@ async function executeThirdfyRun(ctx, flags, resolved, options, runMode = 'third
     mirrorOnly: false,
     hybridWalletMode: options?.hybridWalletMode,
   });
-  const response = await apiPost(ctx, '/api/v1/agent/execute-intent', payload);
+  const response = await apiPost(actionCtx, '/api/v1/agent/execute-intent', payload);
   const normalized = normalizeIntentResponse(response);
   normalized.idempotencyKey = payload.idempotencyKey;
   return normalized;
@@ -333,7 +335,8 @@ async function executeManagedWalletRun(ctx, flags, resolved, options) {
     runMode: 'agent_wallet',
     forceIdempotency: true,
   });
-  const response = await apiPost(ctx, '/api/v1/agent/execute', payload);
+  const actionCtx = withActionTimeout(ctx, resolved.resolvedAction);
+  const response = await apiPost(actionCtx, '/api/v1/agent/execute', payload);
   if (shouldFallbackAgentWalletToExecuteIntent(resolved, response)) {
     const userDid = resolveEffectiveUserDid(flags);
     const chainId = Number(flags.chainId || 8453);

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,