@thirdfy/agent-cli 0.4.2 → 0.4.3

package/CHANGELOG.md

@@ -4,6 +4,25 @@ All notable changes to `@thirdfy/agent-cli` are documented here. The format is b
 
 ## Unreleased
 
+## [0.4.3] - 2026-10-14
+
+Bitfinex support is removed, ethers loads again for local signing and RPC checks, and an unreachable RPC no longer floods `--json` output. Older `credentials upsert` scripts keep working: the removed flags are accepted and ignored.
+
+### Removed
+
+- **Bitfinex support.** It was unused and extra code to maintain. Removed:
+  - the Bitfinex static provider hint (`actions --provider bitfinex` no longer carries one; thirdfy-mcp removed its hint too, thirdfy/thirdfy-mcp#270);
+  - the `credentials upsert` permission probe, and the `bitfinex:funding-primary` / `bitfinex:spot-primary` credential-ref defaults (pass `--credential-ref` yourself);
+  - the Bitfinex onboarding hint (`data.onboardingHint` on error envelopes and on `preflight` / `run` results);
+  - `src/runtime/bitfinexProbe.mjs`, `src/runtime/onboardingHints.mjs`, `src/runtime/execution/runners/fallbackHints.mjs`, and the Bitfinex docs.
+
+  `credentials upsert` and `credentials status` stay for the other venues (Hummingbot connectors, Polymarket, Hyperliquid, Lighter, Avantis). The probe's flags (`--permission-profile`, `--verify-permissions`, `--skip-permissions-probe`, `--bitfinex-base-url`) are still accepted, ignored, and named in `meta.warnings`, so older scripts keep working; they go in the next minor version. The API still serves the Bitfinex catalog rows until it removes them.
+
+### Fixed
+
+- **`loadEthers` loads ethers again.** `src/runtime/owsSigning.mjs` called `require` in an ES module, where it is undefined, and the `ReferenceError` was swallowed. So ethers never loaded, and these failed: `doctor self`'s `ethers-runtime` and `rpc-connectivity` checks, OWS sign-and-broadcast, the self lane's effect-check balance reads, and `wallet submit`. It now loads through `createRequire(import.meta.url)`.
+- **RPC calls fail once instead of retrying forever.** Every RPC connection (`doctor self`, OWS broadcast, `wallet submit`, effect-check balance reads) is now pinned to its chain id (`pinnedRpcProvider` in `src/core/chainRegistry.mjs`). An unreachable RPC is one error, not an ethers retry line on stdout every second that breaks `--json` output and keeps the process running. `doctor self`'s `rpc-chain-id` check asks the RPC itself (`eth_chainId`), so a wrong RPC is still reported. Tests: `test/runtime/owsSigning.test.cjs`.
+
 ## [0.4.2] - 2026-10-14
 
 A cleanup release: two small `wallet profile` / `pricing quote` fixes from the 0.4.1 review, and source files moved into domain folders. Commands answer as in 0.4.1, apart from the two fixes.

package/README.md

@@ -22,7 +22,6 @@ If you want the full developer docs, start here:
 - [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)
@@ -40,11 +39,11 @@ Run without global install:
 npx @thirdfy/agent-cli --help
 ```
 
-## What's new in v0.4.2
+## What's new in v0.4.3
 
-- **One spelling per agent:** `wallet profile` and `readiness` report the agent key in lowercase, whether it came from `--agent-key` or from your config.
-- **`pricing quote` on an older API** (no agent quote route) names the agent only from `--agent-key`.
-- **Reorganized source** (no behavior change): source files moved into domain folders. If your code imports files from inside the package, see [CHANGELOG.md](./CHANGELOG.md) for the new paths; the `thirdfy-agent` command is unchanged.
+- **Local signing works again:** ethers now loads, so `doctor self`, OWS sign-and-broadcast, `wallet submit` and the self lane's balance checks run as documented.
+- **A dead RPC is one clear error:** every RPC call is pinned to its chain, so an unreachable RPC no longer prints retry lines into `--json` output or keeps the command running.
+- **Bitfinex support removed from the CLI:** no Bitfinex provider hint, credential permission probe or docs any more. The Thirdfy API still serves the Bitfinex actions for now. `credentials upsert` still works for the other venues, and its old Bitfinex flags are accepted and ignored with a warning.
 - Older versions: see [CHANGELOG.md](./CHANGELOG.md).
 
 ## Quick start
@@ -346,7 +345,6 @@ thirdfy-agent run --agent-api-key "$THIRDFY_AGENT_API_KEY" --action swap \
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thirdfy/agent-cli",
-  "version": "0.4.2",
+  "version": "0.4.3",
   "description": "Thirdfy Agent CLI for onboarding, governance preflight, execute-intent, and status polling.",
   "type": "module",
   "bin": {
@@ -36,6 +36,8 @@
     "e2e:local-api:smoke": "node ./scripts/e2e/local-api-smoke.mjs",
     "e2e:base:simulate": "node ./scripts/e2e/base-simulate.mjs",
     "e2e:base:real": "node ./scripts/e2e/base-realtx.mjs",
+    "e2e:agent-wallet:simulate": "node ./scripts/e2e/agent-wallet/run.mjs",
+    "e2e:agent-wallet:real": "node ./scripts/e2e/agent-wallet/run.mjs --real",
     "e2e:delegation:discovery": "node ./scripts/e2e/delegation-discovery.mjs",
     "e2e:delegation:lifecycle": "node ./scripts/e2e/delegation-lifecycle.mjs",
     "e2e:delegation:commands": "node ./scripts/e2e/delegation-command-parity.mjs",

package/src/cli/help.mjs

@@ -54,7 +54,7 @@ Core commands:
   thirdfy-agent wallet sign --agent-api-key <key> --action <id> --params <json> [--chain-id <id>] [--json]
   thirdfy-agent wallet submit --signed-tx-hex <hex> [--chain-id <id>] [--rpc-url <url>] [--json]
   thirdfy-agent agent run --agent-api-key <key> --action <id> --params <json> [--signer-method managed_wallet_server|byow|fanout_intent] [--strategy-intent single_wallet|fanout] [--run-mode <mode>] [--user-did <did>] [--json]
-  thirdfy-agent credentials upsert --auth-token <token> --venue <id> --api-key <key> --api-secret <secret> [--permission-profile funding|spot] [--credential-ref <ref>] [--verify-permissions] [--skip-permissions-probe] [--bitfinex-base-url <url>] [--json]
+  thirdfy-agent credentials upsert --auth-token <token> --venue <id> --api-key <key> --api-secret <secret> [--credential-ref <ref>] [--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/src/cli/options/onboarding/credentials.mjs

@@ -3,13 +3,15 @@ export function attachCredentialsOptions(cmd) {
     .option('--venue <id>', 'credential venue')
     .option('--api-key <key>', 'exchange API key')
     .option('--api-secret <secret>', 'exchange API secret')
-    .option('--permission-profile <profile>', 'funding|spot')
     .option('--credential-ref <ref>', 'credential reference')
     .option('--credential-type <type>', 'credential type')
-    .option('--verify-permissions', 'verify exchange permissions')
-    .option('--skip-permissions-probe', 'skip permissions probe')
-    .option('--bitfinex-base-url <url>', 'Bitfinex API base URL')
     .option('--passphrase <value>', 'exchange passphrase')
     .option('--metadata <json>', 'credential metadata JSON')
-    .option('--policy <json>', 'credential policy JSON');
+    .option('--policy <json>', 'credential policy JSON')
+    // Accepted and ignored since Bitfinex support was removed, so older scripts keep working; the
+    // command says so in meta.warnings. Drop them in the next minor version.
+    .option('--permission-profile <profile>', 'ignored (Bitfinex support was removed)')
+    .option('--verify-permissions', 'ignored (Bitfinex support was removed)')
+    .option('--skip-permissions-probe', 'ignored (Bitfinex support was removed)')
+    .option('--bitfinex-base-url <url>', 'ignored (Bitfinex support was removed)');
 }

package/src/commands/doctor.mjs

@@ -3,7 +3,7 @@ import { requireFlag } from '../core/args.mjs';
 import { apiGet, requestWithRouteFallback } from '../core/http.mjs';
 import { loadProfileConfig, getProfileConfigPath, getCachedActionsCatalog } from '../core/context.mjs';
 import { DEFAULT_API_BASE, PROFILE_DEFAULTS } from '../core/constants.mjs';
-import { describeChainGas, parseChainIdFlag, resolveChainRpcUrl } from '../core/chainRegistry.mjs';
+import { DEFAULT_CHAIN_ID, describeChainGas, parseChainIdFlag, pinnedRpcProvider, resolveChainRpcUrl } from '../core/chainRegistry.mjs';
 import { exitAfterOutput } from '../core/envelope.mjs';
 import { normalizeRunMode, normalizeManagedRunMode } from '../core/runMode.mjs';
 import { buildExecutionCertificationReport } from '../runtime/certification/executionCertify.mjs';
@@ -63,13 +63,13 @@ async function commandDoctorSelf(ctx, flags) {
   try {
     if (!rpcUrl) throw new Error(`no known RPC for chain ${flags.chainId}; pass --rpc-url <url>`);
     const ethers = await loadEthers();
-    const provider = new ethers.JsonRpcProvider(rpcUrl);
+    const expectedChainId = parseChainIdFlag(flags.chainId);
+    const provider = pinnedRpcProvider(ethers, { rpcUrl, chainId: expectedChainId || DEFAULT_CHAIN_ID });
     const block = await provider.getBlockNumber();
     checks.push({ name: 'rpc-connectivity', ok: Number.isFinite(block), detail: `latestBlock=${block}` });
-    const expectedChainId = parseChainIdFlag(flags.chainId);
     if (expectedChainId) {
-      const network = await provider.getNetwork();
-      const rpcChainId = Number(network.chainId);
+      // The provider's network is pinned, so ask the RPC itself which chain it serves.
+      const rpcChainId = Number(await provider.send('eth_chainId', []));
       checks.push({
         name: 'rpc-chain-id',
         ok: rpcChainId === expectedChainId,

package/src/commands/execute.mjs

@@ -33,7 +33,6 @@ export function createExecuteCommands(deps) {
     runPreflightByMode,
     runExecutionByMode,
     resolveManagedExecutionPreflight,
-    applyExecutionFallbackHints,
     performSelfBroadcast,
     executeManagedWalletRun,
     executeSelfRun,
@@ -57,11 +56,7 @@ async function commandPreflight(ctx, flags, capabilities) {
     || (await applyLighterAgentWalletAddressDefault(ctx, flags, resolved, runMode))
     || (await applyAvantisAgentWalletAddressDefault(ctx, flags, resolved, runMode));
   const backendResult = await runPreflightByMode(runMode, ctx, flags, resolved, { hybridWalletMode, managedPreflight });
-  const normalized = applyExecutionFallbackHints(backendResult.normalized, {
-    flags,
-    runMode,
-    resolvedAction: resolved.resolvedAction,
-  });
+  const normalized = backendResult.normalized;
   const data = flags.__polymarketSetupGuide
     ? {
         ...normalized,
@@ -195,11 +190,7 @@ async function commandRun(ctx, flags, capabilities) {
     hybridWalletMode,
     managedPreflight,
   });
-  const normalized = applyExecutionFallbackHints(backendResult.normalized, {
-    flags,
-    runMode,
-    resolvedAction: resolved.resolvedAction,
-  });
+  const normalized = backendResult.normalized;
   if (runMode === 'self' && parseBooleanFlag(flags.broadcast, false) && normalized?.success) {
     const executed = await performSelfBroadcast(ctx, flags, resolved.resolvedAction, normalized);
     printEnvelope({

package/src/commands/onboarding/credentials.mjs

@@ -2,47 +2,34 @@ import { createRequire } from 'module';
 import { requireFlag, parseJsonFlag } from '../../core/args.mjs';
 import { requestWithRouteFallback } from '../../core/http.mjs';
 import { createCliError } from '../../core/envelope.mjs';
-import { BITFINEX_PERMISSION_PROFILES, DEFAULT_BITFINEX_BASE_URL } from '../../core/constants.mjs';
-import { parseBooleanFlag } from '../../core/runMode.mjs';
 
 const require = createRequire(import.meta.url);
 const { normalizeCredentialStatus } = require('../../utils/cli/delegationNormalization.cjs');
-export function createCredentialsCommands({ printEnvelope, getAuthToken, buildOwnerAuthHeaders, probeBitfinexPermissions }) {
+/** `credentials upsert` flags of the removed Bitfinex permission probe: accepted, ignored, and named in a warning. */
+const REMOVED_BITFINEX_FLAGS = [
+  ['permissionProfile', '--permission-profile'],
+  ['verifyPermissions', '--verify-permissions'],
+  ['skipPermissionsProbe', '--skip-permissions-probe'],
+  ['bitfinexBaseUrl', '--bitfinex-base-url'],
+];
+
+export function createCredentialsCommands({ printEnvelope, getAuthToken, buildOwnerAuthHeaders }) {
 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 permissionProfile = String(flags.permissionProfile || 'funding').trim().toLowerCase();
-  const bitfinexProfile =
-    String(venue).trim().toLowerCase() === 'bitfinex'
-      ? BITFINEX_PERMISSION_PROFILES[permissionProfile] || BITFINEX_PERMISSION_PROFILES.funding
-      : null;
   const payload = {
     venue,
     apiKey: requireFlag(flags, 'apiKey', 'Missing --api-key'),
     apiSecret: requireFlag(flags, 'apiSecret', 'Missing --api-secret'),
     credentialType: String(flags.credentialType || 'api_key'),
-    credentialRef: String(flags.credentialRef || bitfinexProfile?.credentialRef || ''),
+    credentialRef: String(flags.credentialRef || ''),
   };
   if (flags.passphrase) payload.passphrase = String(flags.passphrase);
   if (flags.metadata) payload.metadata = parseJsonFlag(flags, 'metadata');
   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,
-      permissionProfile: bitfinexProfile?.id || 'funding',
-      timeoutMs: ctx.timeoutMs,
-      baseUrl: String(flags.bitfinexBaseUrl || process.env.BITFINEX_BASE_URL || DEFAULT_BITFINEX_BASE_URL),
-    });
-  }
-
+  const ignoredFlags = REMOVED_BITFINEX_FLAGS.filter(([key]) => flags[key] !== undefined).map(([, flag]) => flag);
   const response = await requestWithRouteFallback(ctx, {
     method: 'POST',
     routes: ['/api/v1/agent/delegation/credentials/upsert', '/api/v1/agent/agent/delegation/credentials/upsert'],
@@ -58,8 +45,8 @@ async function commandCredentialsUpsert(ctx, flags, capabilities) {
     data: response,
     meta: {
       apiBase: ctx.apiBase,
-      permissionProbe,
       capabilitiesVersion: capabilities?.contractVersion || null,
+      ...(ignoredFlags.length ? { warnings: [`Ignored ${ignoredFlags.join(', ')}: Bitfinex support was removed. Drop these flags; they will stop being accepted in the next minor version.`] } : {}),
     },
   });
 }

package/src/core/chainRegistry.mjs

@@ -293,6 +293,17 @@ export function resolveChainRpcUrl({ chainId, rpcUrl, env = process.env } = {})
   return getChainInfo(id)?.rpcUrl || '';
 }
 
+/**
+ * An ethers JsonRpcProvider pinned to `chainId` (`staticNetwork`). Without a pinned network, ethers
+ * probes the RPC for its chain and, when the RPC is down, prints a retry line to stdout every second
+ * and keeps the process alive, which breaks `--json` output. Pinned, a dead RPC is one rejected
+ * call. `getNetwork()` then echoes the pin; read the RPC's real chain with `send('eth_chainId', [])`.
+ */
+export function pinnedRpcProvider(ethers, { rpcUrl, chainId }) {
+  const id = positiveChainId(chainId) || DEFAULT_CHAIN_ID;
+  return new ethers.JsonRpcProvider(rpcUrl, id, { staticNetwork: true });
+}
+
 /**
  * Parse a --chain-id value. Returns null when absent, a positive integer when valid,
  * and NaN when present but not a positive integer (the caller rejects it).

package/src/core/constants.mjs

@@ -1,25 +1,6 @@
 export const DEFAULT_API_BASE = 'https://api.thirdfy.com';
 export const DEFAULT_TIMEOUT_MS = 30000;
 export const DEFAULT_CATALOG_CACHE_TTL_MS = 60_000;
-export const DEFAULT_BITFINEX_BASE_URL = 'https://api.bitfinex.com';
-export const BITFINEX_PERMISSION_PROFILES = {
-  funding: {
-    id: 'funding',
-    credentialRef: 'bitfinex:funding-primary',
-    required: {
-      funding: { read: 1, write: 1 },
-      wallets: { read: 1, write: 0 },
-    },
-  },
-  spot: {
-    id: 'spot',
-    credentialRef: 'bitfinex:spot-primary',
-    required: {
-      orders: { read: 1, write: 1 },
-      wallets: { read: 1, write: 0 },
-    },
-  },
-};
 export const RUN_MODES = ['thirdfy', 'self', 'hybrid', 'agent_wallet'];
 export const HYBRID_WALLET_MODES = ['self', 'agent_wallet'];
 export const CUSTODY_MODES = ['managed', 'external'];

package/src/runtime/actions/selection.mjs

@@ -222,7 +222,6 @@ function inferActionProvider(action) {
   if (key.includes('lighter')) return 'lighter';
   if (key.includes('avantis') && key.includes('vault')) return 'avantis-vault';
   if (key.includes('avantis')) return 'avantis';
-  if (key.includes('bitfinex')) return 'bitfinex';
   if (key.includes('polymarket') || key.includes('prediction')) return 'polymarket';
   if (key.includes('vaults-fyi')) return 'vaults-fyi';
   if (key.includes('yield-xyz')) return 'yield-xyz';

package/src/runtime/execution/runners/createExecutionRunners.mjs

@@ -3,7 +3,6 @@ import { normalizeHybridWalletMode } from '../../../core/runMode.mjs';
 import { apiPost } from '../../../core/http.mjs';
 import { actionNameForApi } from '../../actions/selection.mjs';
 import { isReadOnlyAction } from './managedResponse.mjs';
-import { createFallbackHints } from './fallbackHints.mjs';
 import { createManagedPreflight } from './managedPreflight.mjs';
 import { createThirdfyLane } from './thirdfyLane.mjs';
 import { createSelfLane } from './selfLane.mjs';
@@ -20,7 +19,6 @@ export function createExecutionRunners(deps) {
     buildIntentPayload,
     shouldUseBuildTxPreflight,
   } = deps;
-  const { applyExecutionFallbackHints } = createFallbackHints(deps);
   const { shouldUseManagedReadFastPath, resolveManagedExecutionPreflight } = createManagedPreflight(deps);
   const { executeThirdfyRun, runReadOnlyActionViaIntentRail } = createThirdfyLane(deps);
   const { executeSelfRun, performSelfBroadcast, resolveEffectCheckResult, submitSignedTx } = createSelfLane(deps, { runReadOnlyActionViaIntentRail });
@@ -300,7 +298,6 @@ async function runExecutionByMode(runMode, ctx, flags, resolved, options) {
 }
 
   return {
-    applyExecutionFallbackHints,
     runPreflightByMode,
     runExecutionByMode,
     executeThirdfyRun,

package/src/runtime/execution/runners/selfLane.mjs

@@ -1,7 +1,7 @@
 import { createCliError } from '../../../core/envelope.mjs';
 import { normalizeEffectCheckMode } from '../../../core/runMode.mjs';
 import { apiPost } from '../../../core/http.mjs';
-import { resolveChainRpcUrl } from '../../../core/chainRegistry.mjs';
+import { resolveChainRpcUrl, pinnedRpcProvider } from '../../../core/chainRegistry.mjs';
 import { actionNameForApi } from '../../actions/selection.mjs';
 import { isReadOnlyAction } from './managedResponse.mjs';
 import { createRequire } from 'module';
@@ -103,7 +103,7 @@ async function performSelfBroadcast(ctx, flags, resolvedAction, selfResult) {
 
   let balancesBefore = null;
   if (effectMode !== 'off' && effectTokenIn && effectTokenOut) {
-    balancesBefore = await readEffectBalances(rpcUrl, walletAddress, effectTokenIn, effectTokenOut);
+    balancesBefore = await readEffectBalances(rpcUrl, walletAddress, effectTokenIn, effectTokenOut, chainId);
   }
 
   let submission;
@@ -136,6 +136,7 @@ async function performSelfBroadcast(ctx, flags, resolvedAction, selfResult) {
   const effectCheck = await resolveEffectCheckResult({
     mode: effectMode,
     rpcUrl,
+    chainId,
     walletAddress,
     tokenIn: effectTokenIn,
     tokenOut: effectTokenOut,
@@ -168,6 +169,7 @@ async function performSelfBroadcast(ctx, flags, resolvedAction, selfResult) {
 async function resolveEffectCheckResult({
   mode,
   rpcUrl,
+  chainId,
   walletAddress,
   tokenIn,
   tokenOut,
@@ -193,7 +195,7 @@ async function resolveEffectCheckResult({
   const maxAttempts = Math.max(1, Number(retries || 0) + 1);
   let last = null;
   for (let attempt = 1; attempt <= maxAttempts; attempt += 1) {
-    const balancesAfter = await readEffectBalances(rpcUrl, walletAddress, tokenIn, tokenOut);
+    const balancesAfter = await readEffectBalances(rpcUrl, walletAddress, tokenIn, tokenOut, chainId);
     const inDeltaRaw = (BigInt(balancesBefore.tokenIn) - BigInt(balancesAfter.tokenIn)).toString();
     const outDeltaRaw = (BigInt(balancesAfter.tokenOut) - BigInt(balancesBefore.tokenOut)).toString();
     const hasEffect = BigInt(inDeltaRaw) > 0n || BigInt(outDeltaRaw) > 0n;
@@ -217,8 +219,7 @@ async function resolveEffectCheckResult({
 
 async function submitSignedTx({ rpcUrl, chainId, signedTxHex }) {
   const ethers = await loadEthers();
-  const { JsonRpcProvider } = ethers;
-  const provider = new JsonRpcProvider(rpcUrl, chainId);
+  const provider = pinnedRpcProvider(ethers, { rpcUrl, chainId });
   const sent = await provider.broadcastTransaction(String(signedTxHex));
   return sent?.hash || null;
 }

package/src/runtime/handlers.mjs

@@ -35,7 +35,6 @@ export function createRuntimeHandlers(deps) {
     maskSecret,
     getAuthToken,
     buildOwnerAuthHeaders,
-    probeBitfinexPermissions,
     applyActionFilters,
     getProviderHintForActions,
     resolveChainSupport,
@@ -51,7 +50,6 @@ export function createRuntimeHandlers(deps) {
     submitSignedTx,
     runPreflightByMode,
     runExecutionByMode,
-    applyExecutionFallbackHints,
     performSelfBroadcast,
     resolveManagedExecutionPreflight,
     resolveEffectiveUserDid,
@@ -97,7 +95,6 @@ export function createRuntimeHandlers(deps) {
     printEnvelope,
     getAuthToken,
     buildOwnerAuthHeaders,
-    probeBitfinexPermissions,
   });
 
   const __walletControl = createWalletControlCommands({ printEnvelope, buildOwnerAuthHeaders });
@@ -173,7 +170,6 @@ export function createRuntimeHandlers(deps) {
     runPreflightByMode,
     runExecutionByMode,
     resolveManagedExecutionPreflight,
-    applyExecutionFallbackHints,
     performSelfBroadcast,
     executeManagedWalletRun,
     executeSelfRun,

package/src/runtime/main.mjs

@@ -16,7 +16,6 @@ import { createInitialRuntimeContext, applyFlagsToRuntimeContext } from './conte
 import { createProviderHints } from './providerHints/dispatch.mjs';
 import { createRuntimeHandlers } from './handlers.mjs';
 import { isCommanderCliError } from './errors.mjs';
-import { createOnboardingHints } from './onboardingHints.mjs';
 import { walletControlErrorFields } from './execution/walletControl.mjs';
 import { createAgentExtract } from './agentExtract.mjs';
 import { createAuthHelpers } from './authHelpers.mjs';
@@ -25,7 +24,6 @@ import { createExecutionLanes } from './execution/lanes.mjs';
 import { createExecutionPayloads } from './execution/payloads.mjs';
 import { createExecutionRunners } from './execution/runners/createExecutionRunners.mjs';
 import { createActionSelection } from './actions/selection.mjs';
-import { createBitfinexProbe } from './bitfinexProbe.mjs';
 import { createOwsSigning } from './owsSigning.mjs';
 import { enforceCatalogActionParams } from './validation/actionParamsGate.mjs';
 
@@ -66,7 +64,6 @@ export function createThirdfyAgentRuntime() {
     providerHints;
 
   const { extractAgentApiKey, extractAgentKey, maskSecret } = createAgentExtract();
-  const onboarding = createOnboardingHints();
   const amounts = createExecutionAmounts();
   const lanes = createExecutionLanes();
   const auth = createAuthHelpers();
@@ -82,7 +79,6 @@ export function createThirdfyAgentRuntime() {
   const catalogActionParamsGate = (resolved, flags) =>
     enforceCatalogActionParams(resolved, flags, amounts.getPreparedParams);
   const ows = createOwsSigning();
-  const bitfinex = createBitfinexProbe();
   const runners = createExecutionRunners({
     buildIntentPayload: payloads.buildIntentPayload,
     buildBuildTxPayload: payloads.buildBuildTxPayload,
@@ -92,8 +88,6 @@ export function createThirdfyAgentRuntime() {
     resolveTokenInForFunding: payloads.resolveTokenInForFunding,
     shouldUseBuildTxPreflight: lanes.shouldUseBuildTxPreflight,
     shouldUseBuildTxExecution: lanes.shouldUseBuildTxExecution,
-    buildBitfinexOnboardingCommand: onboarding.buildBitfinexOnboardingCommand,
-    inferBitfinexPermissionProfileFromAction: onboarding.inferBitfinexPermissionProfileFromAction,
     resolveAgentApiKey: payloads.resolveAgentApiKey,
     resolveAgentKey: payloads.resolveAgentKey,
     loadEthers: ows.loadEthers,
@@ -111,7 +105,6 @@ export function createThirdfyAgentRuntime() {
     maskSecret,
     getAuthToken: auth.getAuthToken,
     buildOwnerAuthHeaders: auth.buildOwnerAuthHeaders,
-    probeBitfinexPermissions: bitfinex.probeBitfinexPermissions,
     applyActionFilters: actions.applyActionFilters,
     getProviderHintForActions,
     resolveChainSupport: lanes.resolveChainSupport,
@@ -127,7 +120,6 @@ export function createThirdfyAgentRuntime() {
     submitSignedTx: runners.submitSignedTx,
     runPreflightByMode: runners.runPreflightByMode,
     runExecutionByMode: runners.runExecutionByMode,
-    applyExecutionFallbackHints: runners.applyExecutionFallbackHints,
     performSelfBroadcast: runners.performSelfBroadcast,
     resolveManagedExecutionPreflight: runners.resolveManagedExecutionPreflight,
     resolveEffectiveUserDid: payloads.resolveEffectiveUserDid,
@@ -195,7 +187,6 @@ export function createThirdfyAgentRuntime() {
     const blockedReason = String(payload.blockedReason || payload.error || '').trim() || undefined;
     const blockedStage = String(payload.blockedStage || '').trim() || undefined;
     const clientCode = String(payload.error || payload.blockedReason || '').trim() || undefined;
-    const onboardingHint = onboarding.buildTopLevelOnboardingHint(payload);
     printEnvelope({
       success: false,
       // A missing or malformed flag is INVALID_ARGUMENTS at the top too, not an unhandled error.
@@ -209,7 +200,6 @@ export function createThirdfyAgentRuntime() {
         field: payload.field || null,
         resolvedAction: payload.resolvedAction || null,
         requestedAction: payload.requestedAction || null,
-        onboardingHint,
         // errorCode, retryable, retryAfterSeconds, nextAction, hint: as thirdfy-mcp's error envelope.
         ...describeCliError(error),
         // API 4.0 wallet-control refusals: walletControl, nextAction, userMessage, retryable, hint.

package/src/runtime/owsSigning.mjs

@@ -1,19 +1,20 @@
 import { spawnSync } from 'child_process';
 import fs from 'fs';
+import { createRequire } from 'module';
 import os from 'os';
 import path from 'path';
+import { pinnedRpcProvider } from '../core/chainRegistry.mjs';
 import { createCliError } from '../core/envelope.mjs';
+
+const require = createRequire(import.meta.url);
 export function createOwsSigning() {
+// ethers is a dependency of this package; resolve it from here, never from the caller's directory.
 async function loadEthers() {
-  const candidates = ['ethers', path.join(process.cwd(), 'node_modules', 'ethers')];
-  for (const candidate of candidates) {
-    try {
-      return require(candidate);
-    } catch {
-      // continue
-    }
+  try {
+    return require('ethers');
+  } catch {
+    throw new Error('Could not load the ethers dependency of @thirdfy/agent-cli; reinstall the package');
   }
-  throw new Error('Could not load ethers dependency for self-exec');
 }
 
 function resolveOwsBinary() {
@@ -62,8 +63,8 @@ function signUnsignedTxWithOws(unsignedHex, walletName, chainId) {
 
 async function signAndBroadcastWithOws({ txd, chainId, walletAddress, owsWalletName, rpcUrl }) {
   const ethers = await loadEthers();
-  const { JsonRpcProvider, Transaction, Signature } = ethers;
-  const provider = new JsonRpcProvider(rpcUrl, chainId);
+  const { Transaction, Signature } = ethers;
+  const provider = pinnedRpcProvider(ethers, { rpcUrl, chainId });
   const nonce = await provider.getTransactionCount(walletAddress, 'pending');
   const fee = await provider.getFeeData();
   const txFields = {
@@ -86,10 +87,10 @@ async function signAndBroadcastWithOws({ txd, chainId, walletAddress, owsWalletN
   return { sent };
 }
 
-async function readTokenBalanceRaw(rpcUrl, walletAddress, tokenAddress) {
+async function readTokenBalanceRaw(rpcUrl, walletAddress, tokenAddress, chainId) {
   const ethers = await loadEthers();
-  const { JsonRpcProvider, Interface } = ethers;
-  const provider = new JsonRpcProvider(rpcUrl);
+  const { Interface } = ethers;
+  const provider = pinnedRpcProvider(ethers, { rpcUrl, chainId });
   const erc20 = new Interface(['function balanceOf(address owner) view returns (uint256)']);
   const response = await provider.call({
     to: tokenAddress,
@@ -99,10 +100,10 @@ async function readTokenBalanceRaw(rpcUrl, walletAddress, tokenAddress) {
   return BigInt(decoded[0].toString()).toString();
 }
 
-async function readEffectBalances(rpcUrl, walletAddress, tokenIn, tokenOut) {
+async function readEffectBalances(rpcUrl, walletAddress, tokenIn, tokenOut, chainId) {
   const [inBal, outBal] = await Promise.all([
-    readTokenBalanceRaw(rpcUrl, walletAddress, tokenIn),
-    readTokenBalanceRaw(rpcUrl, walletAddress, tokenOut),
+    readTokenBalanceRaw(rpcUrl, walletAddress, tokenIn, chainId),
+    readTokenBalanceRaw(rpcUrl, walletAddress, tokenOut, chainId),
   ]);
   return { tokenIn: inBal, tokenOut: outBal };
 }

package/src/runtime/providerHints/cex.mjs

@@ -1,59 +1,8 @@
 /**
- * Static provider hints. Centralized exchanges and their executors: Bitfinex, Hummingbot and Condor.
+ * Static provider hints. Centralized exchange executors: Hummingbot and Condor.
  * Each entry builds the hint for one provider id; `dispatch.mjs` picks the entry.
  */
 export const CEX_PROVIDER_HINTS = Object.freeze({
-  bitfinex: ({ provider }) => ({
-    provider,
-    category: 'cex_funding_and_spot',
-    canonicalReadAction: 'get_bitfinex_funding_ticker',
-    canonicalWriteAction: 'submit_bitfinex_funding_offer',
-    readActions: [
-      'get_bitfinex_funding_stats_hist',
-      'get_bitfinex_funding_ticker',
-      'get_bitfinex_funding_book',
-      'get_bitfinex_wallets',
-      'list_bitfinex_funding_offers',
-      'list_bitfinex_funding_offers_hist',
-      'list_bitfinex_funding_credits',
-      'list_bitfinex_funding_loans',
-      'get_bitfinex_funding_info',
-      'get_bitfinex_ledgers_hist',
-      'get_bitfinex_orders',
-    ],
-    orderManagementActions: [
-      'submit_bitfinex_funding_offer',
-      'cancel_bitfinex_funding_offer',
-      'transfer_bitfinex_between_wallets',
-      'get_bitfinex_orders',
-      'submit_bitfinex_order',
-      'update_bitfinex_order',
-      'cancel_bitfinex_order',
-    ],
-    credentialType: 'api_key',
-    credentialRef: 'bitfinex:funding-primary',
-    credentialUx: 'Bitfinex credentials are owned by Thirdfy API encrypted delegation storage. CLI commands pass credentialRef only; never apiKey/apiSecret.',
-    laneCompatibility: 'Use `thirdfy-agent actions --provider bitfinex` for discovery, then `thirdfy-agent run --run-mode thirdfy` with credentialRef in params. The CLI does not store, log, or sign raw exchange credentials.',
-    example: 'thirdfy-agent actions --provider bitfinex && thirdfy-agent run --run-mode thirdfy --action submit_bitfinex_funding_offer --params \'{"symbol":"fUSD","amount":"100","rate":"0.0002","period":2,"credentialRef":"bitfinex:funding-primary"}\'',
-    credentialProfiles: [
-      {
-        id: 'bitfinex_funding_v1',
-        credentialRef: 'bitfinex:funding-primary',
-        required: ['funding.read', 'funding.write', 'wallets.read'],
-      },
-      {
-        id: 'bitfinex_spot_v1',
-        credentialRef: 'bitfinex:spot-primary',
-        required: ['orders.read', 'orders.write', 'wallets.read'],
-      },
-    ],
-    setupBlockers: [
-      'CEX_CREDENTIAL_NOT_FOUND',
-      'BITFINEX_CREDENTIALS_NOT_IN_THIRDFY_DELEGATION_CONTEXT',
-      'BITFINEX_PERMISSION_SCOPE_MISSING',
-      'CEX_POLICY_ACTION_NOT_ALLOWED',
-    ],
-  }),
   hummingbot: ({ provider }) => ({
     provider,
     category: 'cex_executor',

package/src/runtime/bitfinexProbe.mjs

@@ -1,121 +0,0 @@
-import { createHmac } from 'crypto';
-import { DEFAULT_BITFINEX_BASE_URL, BITFINEX_PERMISSION_PROFILES } from '../core/constants.mjs';
-import { createCliError } from '../core/envelope.mjs';
-import { requestJson, safeJsonParse } from '../core/http.mjs';
-export function createBitfinexProbe() {
-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, permissionProfile = 'funding') {
-  const profile = BITFINEX_PERMISSION_PROFILES[permissionProfile] || BITFINEX_PERMISSION_PROFILES.funding;
-  const missing = [];
-  for (const [scope, required] of Object.entries(profile.required)) {
-    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, permissionProfile = 'funding', 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, permissionProfile);
-    if (missingScopes.length > 0) {
-      throw createCliError(
-        'BITFINEX_PERMISSION_SCOPE_MISSING',
-        `Bitfinex key is missing required scopes (${missingScopes
-          .map((entry) => entry.scope)
-          .join(', ')}). Enable the ${permissionProfile} profile scopes and retry onboarding.`,
-        { missingScopes, scopePermissions, permissionProfile }
-      );
-    }
-    return {
-      venue: 'bitfinex',
-      permissionProfile,
-      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);
-  }
-}
-
-  return {
-    parseBitfinexPermissionRows,
-    getMissingBitfinexScopes,
-    probeBitfinexPermissions,
-  };
-}

package/src/runtime/execution/runners/fallbackHints.mjs

@@ -1,54 +0,0 @@
-/** Hints added to a failed execution answer (Bitfinex onboarding and similar next steps). */
-export function createFallbackHints(deps) {
-  const {
-    buildBitfinexOnboardingCommand,
-    inferBitfinexPermissionProfileFromAction,
-  } = deps;
-
-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 permissionProfile = inferBitfinexPermissionProfileFromAction(resolvedActionLower);
-  const cexCredentialMissingSignals = new Set([
-    'CEX_CREDENTIAL_NOT_FOUND',
-    'BITFINEX_CREDENTIALS_NOT_IN_CONTEXT',
-    'BITFINEX_CREDENTIALS_NOT_IN_THIRDFY_DELEGATION_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(permissionProfile),
-    };
-  }
-  if (
-    looksBitfinexAction &&
-    runMode !== 'thirdfy' &&
-    runMode !== 'agent_wallet' &&
-    (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;
-}
-
-  return {
-    applyExecutionFallbackHints,
-  };
-}

package/src/runtime/onboardingHints.mjs

@@ -1,54 +0,0 @@
-import { BITFINEX_PERMISSION_PROFILES } from '../core/constants.mjs';
-export function createOnboardingHints() {
-function buildBitfinexOnboardingCommand(permissionProfile = 'funding') {
-  const profile = BITFINEX_PERMISSION_PROFILES[permissionProfile] || BITFINEX_PERMISSION_PROFILES.funding;
-  return [
-    'thirdfy-agent credentials upsert',
-    '--auth-token "$THIRDFY_AUTH_TOKEN"',
-    '--venue bitfinex',
-    `--permission-profile ${profile.id}`,
-    `--credential-ref ${profile.credentialRef}`,
-    '--api-key "<BITFINEX_API_KEY>"',
-    '--api-secret "<BITFINEX_API_SECRET>"',
-    '--verify-permissions',
-    '--json',
-  ].join(' ');
-}
-
-function inferBitfinexPermissionProfileFromAction(actionName) {
-  const action = String(actionName || '')
-    .trim()
-    .toLowerCase()
-    .replace(/[_\s]+/g, '-');
-  if (!action.includes('bitfinex')) return 'funding';
-  return action.includes('bitfinex-order') ? 'spot' : 'funding';
-}
-
-function buildTopLevelOnboardingHint(payload) {
-  const reason = String(payload?.blockedReason || payload?.error || '').trim();
-  const permissionProfile = inferBitfinexPermissionProfileFromAction(
-    payload?.resolvedAction || payload?.action || payload?.requestedAction
-  );
-  if (!reason) return null;
-  if (
-    [
-      'CEX_CREDENTIAL_NOT_FOUND',
-      'BITFINEX_CREDENTIALS_NOT_IN_CONTEXT',
-      'BITFINEX_CREDENTIALS_NOT_IN_THIRDFY_DELEGATION_CONTEXT',
-      'BITFINEX_ENV_CREDENTIALS_NOT_CONFIGURED',
-    ].includes(reason)
-  ) {
-    return {
-      type: 'bitfinex_credentials',
-      command: buildBitfinexOnboardingCommand(permissionProfile),
-    };
-  }
-  return null;
-}
-
-  return {
-    buildBitfinexOnboardingCommand,
-    inferBitfinexPermissionProfileFromAction,
-    buildTopLevelOnboardingHint,
-  };
-}