@thirdfy/agent-cli 0.1.9 → 0.1.10

package/CHANGELOG.md

@@ -4,6 +4,11 @@ All notable changes to `@thirdfy/agent-cli` are documented here. The format is b
 
 ## [Unreleased]
 
+## [0.1.9] - 2026-04-08
+
+**npm:** [`@thirdfy/agent-cli@0.1.9`](https://www.npmjs.com/package/@thirdfy/agent-cli/v/0.1.9)  
+**Git tag:** [`v0.1.9`](https://github.com/thirdfy/agent-cli/releases/tag/v0.1.9)
+
 ### Fixed
 
 - **Self preflight routing for swap-like actions:** `preflight --run-mode self` now selects the validation route by action capability. When an action advertises `supportsExecuteIntent=false` and `supportsBuildTx=true`, preflight uses `build-tx` directly instead of forcing execute-intent validation.

package/README.md

@@ -16,8 +16,13 @@ If you want the full developer docs, start here:
 - [API Reference home](https://docs.thirdfy.com/api)
 - [LLM docs map (llms.txt)](https://docs.thirdfy.com/llms.txt)
 - [LLM full API snapshot (llms-full.txt)](https://docs.thirdfy.com/llms-full.txt)
+- [Provider docs index (repo)](./docs/providers/index.md)
+- [Action inventory and compatibility](./docs/action-inventory-and-compatibility.md)
+- [Command reference](./docs/command-reference.md)
 - [DogeOS quickstart (repo)](./docs/dogeos-quickstart.md)
+- [Bitfinex CEX workflow (repo)](./docs/bitfinex-cex-workflow.md)
 - [Action onboarding standard](./docs/action-onboarding-standard.md)
+- [Provider docs governance model](./docs/provider-docs-governance.md)
 - [Skill integration RFC](./docs/skill-integration-rfc.md)
 
 ## Install
@@ -215,6 +220,14 @@ Jeff-friendly aliases map directly to core commands:
 - `thirdfy-agent jeff status --intent-id ...` -> alias of `intent-status`
 - `thirdfy-agent prompt "<text>"` -> captures prompt intent and suggests deterministic execution commands
 
+## Provider-specific workflows
+
+Provider and venue guides are kept outside `README` so this page stays stable as integrations grow.
+
+- Provider index: [`docs/providers/index.md`](./docs/providers/index.md)
+- Bitfinex runbook: [`docs/providers/bitfinex.md`](./docs/providers/bitfinex.md)
+- DogeOS runbook: [`docs/providers/dogeos.md`](./docs/providers/dogeos.md)
+
 ## Command groups
 
 - Discovery: `catalogs list`, `actions`
@@ -226,6 +239,12 @@ Jeff-friendly aliases map directly to core commands:
 - Delegation execution helpers: `delegation balance`, `delegation redeem`
 - Account: `credits balance`
 
+## Where to find what is supported
+
+- Full command groups and usage map: [`docs/command-reference.md`](./docs/command-reference.md)
+- Live action inventory in your environment: [`docs/action-inventory-and-compatibility.md`](./docs/action-inventory-and-compatibility.md)
+- Provider runbooks and provider status: [`docs/providers/index.md`](./docs/providers/index.md)
+
 ## Delegation lifecycle (canonical)
 
 Use `create` + `activate` as the default delegated execution lifecycle:

package/bin/thirdfy-agent.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { randomUUID } from 'crypto';
+import { createHmac, randomUUID } from 'crypto';
 import { spawnSync } from 'child_process';
 import fs from 'fs';
 import os from 'os';
@@ -18,6 +18,11 @@ const {
 const DEFAULT_API_BASE = 'https://api.thirdfy.com';
 const DEFAULT_TIMEOUT_MS = 30000;
 const DEFAULT_CATALOG_CACHE_TTL_MS = 60_000;
+const DEFAULT_BITFINEX_BASE_URL = 'https://api.bitfinex.com';
+const BITFINEX_REQUIRED_SCOPE_PERMISSIONS = {
+  funding: { read: 1, write: 1 },
+  wallets: { read: 1, write: 1 },
+};
 const RUN_MODES = ['thirdfy', 'self', 'hybrid'];
 const EFFECT_CHECK_MODES = ['strict', 'relaxed', 'off'];
 const PROFILE_DEFAULTS = {
@@ -52,6 +57,7 @@ main().catch((error) => {
   const payload = error?.payload && typeof error.payload === 'object' ? error.payload : {};
   const blockedReason = String(payload.blockedReason || payload.error || '').trim() || undefined;
   const blockedStage = String(payload.blockedStage || '').trim() || undefined;
+  const onboardingHint = buildTopLevelOnboardingHint(payload);
   printEnvelope({
     success: false,
     code: statusCode ? 'API_REQUEST_FAILED' : 'CLI_UNHANDLED_ERROR',
@@ -60,6 +66,7 @@ main().catch((error) => {
       statusCode,
       blockedReason,
       blockedStage,
+      onboardingHint,
       payload,
     },
     meta: { version: CLI_VERSION, apiBase: context.apiBase },
@@ -67,6 +74,22 @@ main().catch((error) => {
   process.exit(1);
 });
 
+function buildTopLevelOnboardingHint(payload) {
+  const reason = String(payload?.blockedReason || payload?.error || '').trim();
+  if (!reason) return null;
+  if (
+    ['CEX_CREDENTIAL_NOT_FOUND', 'BITFINEX_CREDENTIALS_NOT_IN_CONTEXT', 'BITFINEX_ENV_CREDENTIALS_NOT_CONFIGURED'].includes(
+      reason
+    )
+  ) {
+    return {
+      type: 'bitfinex_credentials',
+      command: buildBitfinexOnboardingCommand(),
+    };
+  }
+  return null;
+}
+
 async function main() {
   const profileState = resolveProfileState(globalFlags);
   context.profile = profileState.profile;
@@ -518,10 +541,15 @@ async function commandPreflight(ctx, flags, capabilities) {
   const runMode = getEffectiveRunMode(ctx, flags);
   enforceChainCompatibility(capabilities, flags, runMode);
   const backendResult = await runPreflightByMode(runMode, ctx, flags, resolved);
-  const normalized = backendResult.normalized;
+  const normalized = applyExecutionFallbackHints(backendResult.normalized, {
+    flags,
+    runMode,
+    resolvedAction: resolved.resolvedAction,
+  });
+  const preflightBlocked = !normalized.success && Boolean(normalized.preflightBlocked);
   printEnvelope({
     success: normalized.success,
-    code: normalized.success ? 'PREFLIGHT_OK' : 'PREFLIGHT_FAILED',
+    code: normalized.success ? 'PREFLIGHT_OK' : preflightBlocked ? 'PREFLIGHT_BLOCKED' : 'PREFLIGHT_FAILED',
     message: backendResult.message,
     data: normalized,
     meta: {
@@ -548,7 +576,11 @@ async function commandRun(ctx, flags, capabilities) {
   const backendResult = await runExecutionByMode(runMode, ctx, flags, resolved, {
     skipPreflight,
   });
-  const normalized = backendResult.normalized;
+  const normalized = applyExecutionFallbackHints(backendResult.normalized, {
+    flags,
+    runMode,
+    resolvedAction: resolved.resolvedAction,
+  });
   if (runMode === 'self' && parseBooleanFlag(flags.broadcast, false) && normalized?.success) {
     const executed = await performSelfBroadcast(ctx, flags, resolved.resolvedAction, normalized);
     printEnvelope({
@@ -925,8 +957,9 @@ async function commandDelegationRedeem(ctx, flags, capabilities) {
 
 async function commandCredentialsUpsert(ctx, flags, capabilities) {
   const authToken = getAuthToken(flags, 'Missing --auth-token (or THIRDFY_AUTH_TOKEN) for credentials upsert');
+  const venue = requireFlag(flags, 'venue', 'Missing --venue');
   const payload = {
-    venue: requireFlag(flags, 'venue', 'Missing --venue'),
+    venue,
     apiKey: requireFlag(flags, 'apiKey', 'Missing --api-key'),
     apiSecret: requireFlag(flags, 'apiSecret', 'Missing --api-secret'),
     credentialType: String(flags.credentialType || 'api_key'),
@@ -937,6 +970,19 @@ async function commandCredentialsUpsert(ctx, flags, capabilities) {
   if (flags.policy) payload.policy = parseJsonFlag(flags, 'policy');
   if (flags.agentKey) payload.agentKey = String(flags.agentKey).trim();
   if (flags.chainId) payload.chainId = Number(flags.chainId);
+  const probeEnabled =
+    String(venue).trim().toLowerCase() === 'bitfinex' &&
+    !parseBooleanFlag(flags.skipPermissionsProbe, false) &&
+    parseBooleanFlag(flags.verifyPermissions, true);
+  let permissionProbe = null;
+  if (probeEnabled) {
+    permissionProbe = await probeBitfinexPermissions({
+      apiKey: payload.apiKey,
+      apiSecret: payload.apiSecret,
+      timeoutMs: ctx.timeoutMs,
+      baseUrl: String(flags.bitfinexBaseUrl || process.env.BITFINEX_BASE_URL || DEFAULT_BITFINEX_BASE_URL),
+    });
+  }
 
   const response = await requestWithRouteFallback(ctx, {
     method: 'POST',
@@ -953,6 +999,7 @@ async function commandCredentialsUpsert(ctx, flags, capabilities) {
     data: response,
     meta: {
       apiBase: ctx.apiBase,
+      permissionProbe,
       capabilitiesVersion: capabilities?.contractVersion || null,
     },
   });
@@ -1711,6 +1758,66 @@ function enforceChainCompatibility(capabilities, flags, runMode) {
   }
 }
 
+function shouldUseBuildTxExecution(runMode, resolved) {
+  if (runMode !== 'self' && runMode !== 'hybrid') return false;
+  const meta = resolved?.resolvedActionMeta || null;
+  if (!meta || typeof meta !== 'object') return true;
+  if (meta.supportsBuildTx === false) return false;
+  return true;
+}
+
+function buildBitfinexOnboardingCommand() {
+  return [
+    'thirdfy-agent credentials upsert',
+    '--auth-token "$THIRDFY_AUTH_TOKEN"',
+    '--venue bitfinex',
+    '--api-key "<BITFINEX_API_KEY>"',
+    '--api-secret "<BITFINEX_API_SECRET>"',
+    '--verify-permissions',
+    '--json',
+  ].join(' ');
+}
+
+function applyExecutionFallbackHints(normalized, { flags, runMode, resolvedAction }) {
+  if (!normalized || typeof normalized !== 'object') return normalized;
+  const next = { ...normalized };
+  const reasons = new Set();
+  const topBlockedReason = String(next.blockedReason || '').trim();
+  if (topBlockedReason) reasons.add(topBlockedReason);
+  const blockedByReason = next.blockedByReason && typeof next.blockedByReason === 'object' ? next.blockedByReason : {};
+  for (const key of Object.keys(blockedByReason)) {
+    if (String(key || '').trim()) reasons.add(String(key).trim());
+  }
+  const resolvedActionLower = String(resolvedAction || '').trim().toLowerCase();
+  const looksBitfinexAction = resolvedActionLower.includes('bitfinex');
+  const cexCredentialMissingSignals = new Set([
+    'CEX_CREDENTIAL_NOT_FOUND',
+    'BITFINEX_CREDENTIALS_NOT_IN_CONTEXT',
+    'BITFINEX_ENV_CREDENTIALS_NOT_CONFIGURED',
+  ]);
+  const hasMissingCredentialSignal = Array.from(reasons).some((code) => cexCredentialMissingSignals.has(code));
+  if (looksBitfinexAction && hasMissingCredentialSignal) {
+    next.onboardingHint = {
+      type: 'bitfinex_credentials',
+      message:
+        'Bitfinex credentials are missing for this delegated account. Onboard credentials first, then retry the same command.',
+      command: buildBitfinexOnboardingCommand(),
+    };
+  }
+  if (
+    looksBitfinexAction &&
+    runMode !== 'thirdfy' &&
+    (topBlockedReason === 'SELF_MODE_REQUIRES_BUILD_TX' || topBlockedReason === 'HYBRID_MODE_REQUIRES_BUILD_TX')
+  ) {
+    next.onboardingHint = {
+      ...(next.onboardingHint || {}),
+      runMode: 'thirdfy',
+      runModeMessage: 'Bitfinex actions require delegated execute-intent rail. Re-run with --run-mode thirdfy.',
+    };
+  }
+  return next;
+}
+
 function shouldUseBuildTxPreflight(runMode, resolved) {
   if (runMode !== 'self') return false;
   const meta = resolved?.resolvedActionMeta || null;
@@ -1725,7 +1832,7 @@ async function runPreflightByMode(runMode, ctx, flags, resolved) {
     const normalized = await executeSelfRun(
       ctx,
       flags,
-      { resolvedAction },
+      resolved,
       { skipPreflight: route === 'build_tx' }
     );
     const blockedByGovernance = !normalized.success && Boolean(normalized.preflightBlocked);
@@ -1843,6 +1950,7 @@ async function executeThirdfyRun(ctx, flags, resolved, options) {
 
 async function executeSelfRun(ctx, flags, resolved, options) {
   const skipPreflight = Boolean(options?.skipPreflight);
+  const blockedReasonCode = String(options?.blockedReasonCode || 'SELF_MODE_REQUIRES_BUILD_TX');
   if (!skipPreflight) {
     const preflightPayload = buildIntentPayload(flags, {
       validationOnly: true,
@@ -1861,6 +1969,17 @@ async function executeSelfRun(ctx, flags, resolved, options) {
       return preflightNormalized;
     }
   }
+  if (!shouldUseBuildTxExecution(options?.runMode || 'self', resolved)) {
+    const normalized = normalizeIntentResponse({
+      success: false,
+      status: 'failed',
+      blockedReason: blockedReasonCode,
+      blockedStage: 'routing',
+      error: 'Selected action does not support build-tx self lane. Use --run-mode thirdfy for delegated CEX execution.',
+    });
+    normalized.preflightBlocked = true;
+    return normalized;
+  }
   const buildTxPayload = buildBuildTxPayload(flags, resolved.resolvedAction);
   const buildTx = await apiPost(ctx, '/api/v1/agent/build-tx', buildTxPayload);
   return normalizeIntentResponse({
@@ -1873,7 +1992,11 @@ async function executeSelfRun(ctx, flags, resolved, options) {
 }
 
 async function executeHybridRun(ctx, flags, resolved, options) {
-  const selfResult = await executeSelfRun(ctx, flags, resolved, options);
+  const selfResult = await executeSelfRun(ctx, flags, resolved, {
+    ...(options || {}),
+    runMode: 'hybrid',
+    blockedReasonCode: 'HYBRID_MODE_REQUIRES_BUILD_TX',
+  });
   if (!selfResult.success) return selfResult;
 
   const mirrorPayload = buildIntentPayload(flags, {
@@ -2454,6 +2577,114 @@ function safeJsonParse(text) {
   }
 }
 
+function parseBitfinexPermissionRows(rawData) {
+  const rows = Array.isArray(rawData) ? rawData : [];
+  const parsed = {};
+  for (const row of rows) {
+    if (!Array.isArray(row) || row.length < 3) continue;
+    const scope = String(row[0] || '').trim().toLowerCase();
+    if (!scope) continue;
+    const read = Number(row[1]) === 1 ? 1 : 0;
+    const write = Number(row[2]) === 1 ? 1 : 0;
+    parsed[scope] = { read, write };
+  }
+  return parsed;
+}
+
+function getMissingBitfinexScopes(scopePermissions) {
+  const missing = [];
+  for (const [scope, required] of Object.entries(BITFINEX_REQUIRED_SCOPE_PERMISSIONS)) {
+    const actual = scopePermissions[scope] || { read: 0, write: 0 };
+    if (actual.read < required.read || actual.write < required.write) {
+      missing.push({
+        scope,
+        required,
+        actual,
+      });
+    }
+  }
+  return missing;
+}
+
+async function probeBitfinexPermissions({ apiKey, apiSecret, timeoutMs, baseUrl }) {
+  const normalizedBaseUrl = String(baseUrl || DEFAULT_BITFINEX_BASE_URL).trim().replace(/\/+$/, '');
+  const apiPath = '/v2/auth/r/permissions';
+  const nonce = Date.now().toString();
+  const payload = '{}';
+  const signature = createHmac('sha384', String(apiSecret || ''))
+    .update(`/api${apiPath}${nonce}${payload}`)
+    .digest('hex');
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), Number(timeoutMs || DEFAULT_TIMEOUT_MS));
+  try {
+    const response = await fetch(`${normalizedBaseUrl}${apiPath}`, {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        'bfx-apikey': String(apiKey || ''),
+        'bfx-nonce': nonce,
+        'bfx-signature': signature,
+      },
+      body: payload,
+      signal: controller.signal,
+    });
+    const text = await response.text();
+    const parsed = text ? safeJsonParse(text) : {};
+    const bitfinexApiError =
+      Array.isArray(parsed) && String(parsed[0] || '').trim().toLowerCase() === 'error'
+        ? {
+            code: Number(parsed[1]) || null,
+            message: String(parsed[2] || 'Unknown Bitfinex API error'),
+          }
+        : parsed && typeof parsed === 'object' && String(parsed.event || '').trim().toLowerCase() === 'error'
+          ? {
+              code: Number(parsed.code) || null,
+              message: String(parsed.msg || parsed.message || 'Unknown Bitfinex API error'),
+            }
+          : null;
+    if (!response.ok) {
+      throw createCliError(
+        'BITFINEX_PERMISSIONS_PROBE_FAILED',
+        `Bitfinex permissions probe failed with HTTP ${response.status}. Verify API key/secret and key validity before onboarding.`,
+        { statusCode: response.status }
+      );
+    }
+    if (bitfinexApiError) {
+      throw createCliError(
+        'BITFINEX_PERMISSIONS_PROBE_FAILED',
+        `Bitfinex permissions probe failed: ${bitfinexApiError.message}. Verify API key/secret and key validity before onboarding.`,
+        { statusCode: response.status, bitfinexApiError }
+      );
+    }
+    const scopePermissions = parseBitfinexPermissionRows(parsed);
+    const missingScopes = getMissingBitfinexScopes(scopePermissions);
+    if (missingScopes.length > 0) {
+      throw createCliError(
+        'BITFINEX_PERMISSION_SCOPE_MISSING',
+        `Bitfinex key is missing required scopes (${missingScopes
+          .map((entry) => entry.scope)
+          .join(', ')}). Enable funding+wallets read/write and retry onboarding.`,
+        { missingScopes, scopePermissions }
+      );
+    }
+    return {
+      venue: 'bitfinex',
+      checked: true,
+      scopes: scopePermissions,
+      missingScopes: [],
+    };
+  } catch (error) {
+    if (error?.payload) throw error;
+    throw createCliError(
+      'BITFINEX_PERMISSIONS_PROBE_FAILED',
+      `Could not verify Bitfinex key permissions. ${String(error?.message || 'Unknown probe error')}`,
+      {}
+    );
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 function printEnvelope(payload) {
   if (jsonMode) {
     process.stdout.write(`${JSON.stringify(payload, null, 2)}\n`);
@@ -2491,7 +2722,7 @@ Core commands:
   thirdfy-agent managed wallet init [--auth-token <token> | --owner-session-token <token>] [--chain-id <id>] [--json]
   thirdfy-agent managed wallet 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]
   thirdfy-agent managed run --agent-api-key <key> --action <id> --params <json> [--run-mode thirdfy|hybrid] [--idempotency-key <key>] [--json]
-  thirdfy-agent credentials upsert --auth-token <token> --venue <id> --api-key <key> --api-secret <secret> [--json]
+  thirdfy-agent credentials upsert --auth-token <token> --venue <id> --api-key <key> --api-secret <secret> [--verify-permissions] [--skip-permissions-probe] [--bitfinex-base-url <url>] [--json]
   thirdfy-agent credentials status --auth-token <token> [--venue <id>] [--json]
   thirdfy-agent agent auth challenge --agent-key <key> [--wallet-address <addr>] [--chain-id <id>] [--json]
   thirdfy-agent agent auth verify --challenge-id <id> --signature <hex> --agent-key <key> [--wallet-address <addr>] [--json]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thirdfy/agent-cli",
-  "version": "0.1.9",
+  "version": "0.1.10",
   "description": "Thirdfy Agent CLI for onboarding, governance preflight, execute-intent, and status polling.",
   "type": "module",
   "bin": {
@@ -18,6 +18,7 @@
   "scripts": {
     "test": "node --test \"test/**/*.test.cjs\"",
     "lint": "node --check ./bin/thirdfy-agent.mjs",
+    "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",
     "e2e:base:simulate": "node ./scripts/e2e/base-simulate.mjs",
@@ -30,7 +31,7 @@
     "e2e:delegation:prod:certify": "node ./scripts/e2e/prod-delegation-certify.mjs",
     "e2e:report:last": "node ./scripts/e2e/report-last.mjs",
     "smoke:cli": "node ./bin/thirdfy-agent.mjs --help && node ./bin/thirdfy-agent.mjs --version --json",
-    "prepublishOnly": "npm run validate:cli-contract-schemas && npm run test && npm run smoke:cli"
+    "prepublishOnly": "npm run validate:public-docs && npm run validate:cli-contract-schemas && npm run test && npm run smoke:cli"
   },
   "keywords": [
     "thirdfy",

package/src/utils/cli/intentNormalization.cjs

@@ -33,6 +33,7 @@ function normalizeIntentResponse(response) {
   const topLevelGovernanceSignal = String(response?.governanceSignal || '').trim() || null;
   const topLevelDelegationSignal = String(response?.delegationSignal || '').trim() || null;
   const policyEvaluated = response?.policyEvaluated === true;
+  const preflightBlocked = response?.preflightBlocked === true;
   return {
     success,
     status: response?.status || (success ? 'queued' : 'failed'),
@@ -48,6 +49,7 @@ function normalizeIntentResponse(response) {
     governanceSignal: topLevelGovernanceSignal,
     delegationSignal: topLevelDelegationSignal,
     policyEvaluated,
+    preflightBlocked,
     error: response?.error || null,
     mode: response?.mode || null,
     unsignedTx: response?.unsignedTx || null,