@thirdfy/agent-cli 0.4.2 → 0.5.0

package/src/core/oauth/pkce.mjs

@@ -0,0 +1,17 @@
+import { createHash, randomBytes } from 'crypto';
+
+/** RFC 7636 PKCE (S256 only, as auth.thirdfy.com requires) and the OAuth `state` value. */
+
+export function base64url(bytes) {
+  return Buffer.from(bytes).toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+export function createPkcePair() {
+  const verifier = base64url(randomBytes(32));
+  const challenge = base64url(createHash('sha256').update(verifier).digest());
+  return { verifier, challenge, method: 'S256' };
+}
+
+export function createState() {
+  return base64url(randomBytes(16));
+}

package/src/core/oauth/session.mjs

@@ -0,0 +1,117 @@
+import { DEFAULT_API_BASE } from '../constants.mjs';
+import { createCliError } from '../envelope.mjs';
+import { loadProfileConfig, persistProfileConfig } from '../context.mjs';
+import { refreshTokens } from './authServer.mjs';
+
+/**
+ * The OAuth sign-in `thirdfy-agent login` stores in `~/.thirdfy/config.json` (`auth.oauth`, mode
+ * 0600): one agent's access and refresh tokens from auth.thirdfy.com. It is the agent credential
+ * when no `--agent-api-key` or `THIRDFY_AGENT_API_KEY` is set. The HTTP layer sends it as
+ * `Authorization: Bearer` and refreshes it before it expires (rotation: each refresh returns a new
+ * refresh token).
+ */
+
+/** auth.thirdfy.com access tokens: `{userId}:{grantId}:{secret}`. Agent API keys and JWTs never match. */
+const OAUTH_TOKEN_SHAPE = /^[^\s:]+:[^\s:]+:[^\s:]+$/;
+
+/** Refresh when fewer than this many seconds are left, so a command never starts with a dying token. */
+const REFRESH_MARGIN_SECONDS = 120;
+
+export function isOAuthAccessToken(value) {
+  return OAUTH_TOKEN_SHAPE.test(String(value || '').trim());
+}
+
+export function readOAuthSession(config = loadProfileConfig()) {
+  const session = config?.auth?.oauth;
+  if (!session || typeof session !== 'object') return null;
+  if (!isOAuthAccessToken(session.accessToken)) return null;
+  return session;
+}
+
+const trimBase = (value) => String(value || '').trim().replace(/\/+$/, '');
+
+/** The API base a command talks to: --api-base, then THIRDFY_API_BASE, then the default (as runtime/context). */
+export function apiBaseFor(flags = {}, env = process.env) {
+  return trimBase(flags.apiBase || env.THIRDFY_API_BASE || DEFAULT_API_BASE);
+}
+
+/**
+ * The sign-in for this API. A sign-in is issued for one API (its `resource`): one for api-test is
+ * never sent to production, or the reverse.
+ */
+export function oauthSessionForApi(apiBase, config = loadProfileConfig()) {
+  const session = readOAuthSession(config);
+  return session && trimBase(session.resource) === trimBase(apiBase) ? session : null;
+}
+
+/**
+ * The OAuth sign-in acts as the agent unless an agent API key is passed or set in the environment,
+ * and only on the API it was issued for.
+ */
+export function oauthSessionIsAgentCredential(flags = {}, env = process.env, config = loadProfileConfig()) {
+  if (String(flags.agentApiKey || '').trim()) return false;
+  if (String(env.THIRDFY_AGENT_API_KEY || '').trim()) return false;
+  return Boolean(oauthSessionForApi(apiBaseFor(flags, env), config));
+}
+
+export function writeOAuthSession(session) {
+  const config = loadProfileConfig();
+  const auth = config.auth && typeof config.auth === 'object' ? config.auth : {};
+  persistProfileConfig({ ...config, auth: { ...auth, oauth: session } });
+}
+
+export function clearOAuthSession() {
+  const config = loadProfileConfig();
+  if (!config.auth?.oauth) return;
+  const { oauth: _removed, ...auth } = config.auth;
+  persistProfileConfig({ ...config, auth });
+}
+
+/** The stored session after a token response (code exchange or refresh). */
+export function sessionFromTokens(base, tokens, nowSeconds = Math.floor(Date.now() / 1000)) {
+  const expiresIn = Number(tokens.expires_in);
+  return {
+    ...base,
+    accessToken: String(tokens.access_token),
+    refreshToken: tokens.refresh_token ? String(tokens.refresh_token) : base.refreshToken || null,
+    expiresAt: Number.isFinite(expiresIn) && expiresIn > 0 ? nowSeconds + expiresIn : null,
+    scope: tokens.scope ? String(tokens.scope) : base.scope || '',
+    obtainedAt: nowSeconds,
+  };
+}
+
+let refreshInFlight = null;
+
+/**
+ * The access token to send, refreshed first when it is about to expire (or when `force`, after the
+ * API answered 401). A refresh the auth server refuses (`invalid_grant`: revoked, or the owner no
+ * longer owns the agent) is `OAUTH_SESSION_EXPIRED`: sign in again.
+ */
+
+export async function freshOAuthAccessToken({ timeoutMs, force = false } = {}) {
+  // One refresh at a time: the refresh token rotates, so a second refresh with the same token
+  // would be refused. Concurrent callers share the first one's result.
+  if (refreshInFlight) return refreshInFlight;
+  const session = readOAuthSession();
+  if (!session) return null;
+  const now = Math.floor(Date.now() / 1000);
+  const expiring = Number.isFinite(Number(session.expiresAt)) && Number(session.expiresAt) - now < REFRESH_MARGIN_SECONDS;
+  if (!force && !expiring) return session.accessToken;
+  if (!session.refreshToken || !session.tokenEndpoint || !session.clientId) {
+    throw createCliError('OAUTH_SESSION_EXPIRED', 'The sign-in expired. Sign in again: thirdfy-agent login', { blockedStage: 'auth' });
+  }
+  refreshInFlight = (async () => {
+    const tokens = await refreshTokens(
+      { tokenEndpoint: session.tokenEndpoint, clientId: session.clientId, refreshToken: session.refreshToken, resource: session.resource },
+      timeoutMs || 30_000,
+    );
+    const next = sessionFromTokens(session, tokens);
+    writeOAuthSession(next);
+    return next.accessToken;
+  })();
+  try {
+    return await refreshInFlight;
+  } finally {
+    refreshInFlight = null;
+  }
+}

package/src/lib/creditsUsdSummary.mjs

@@ -1,54 +1,153 @@
 /**
- * Credits balances and action costs are shown in credits, never as a dollar price per credit or per
- * request (owner decision 2026-10-14; thirdfy-mcp #252 `stripUsdFields`). Buying credits keeps its USD
- * amount (`credits buy --usd`): that is a purchase, not a request price.
+ * Credits are Thirdfy's internal ledger unit; people see a USD balance. The public docs say so
+ * (thirdfy-docs credits page: "Your balance shows in USD; credits are the internal unit") and never
+ * state what an action costs (DOCUMENTATION_GUIDE: no credit costs, no USD-per-credit rate). Owner
+ * rule 2026-10-15; same rules as thirdfy-mcp `usdFirstCredits.ts` (thirdfy/thirdfy-mcp#279).
+ *
+ * `credits balance` and `pricing quote` keep `availableUsd`, free request counts, `wouldBePaidBy` and
+ * `displayCurrency`. Every credit count, per-credit rate and per-action price is dropped, so a reader
+ * can say "$4.20 left" but not "286 credits" or "$0.18 a request". The owner's fallback balance, which
+ * the API sends in credits only, gets an `availableUsd` at the API's own `retailUsdPerCredit` (the rate
+ * the API uses for the agent's `availableUsd`). Buying keeps its USD amount (`credits buy --usd`).
  */
+
+const KEEP_USD = new Set(['availableUsd']);
+/** Credit counts the API names without "credit" (`totalAvailable`: the owner route's balance plus free requests). */
+const CREDIT_COUNTS = new Set(['balance', 'totalEarned', 'totalSpent', 'totalAvailable']);
+const CREDIT_KEY = /credit/i;
 const USD_KEY = /usd/i;
 
-/** The value with every key that names USD (and displayCurrency / pricingCurrency) removed, at any depth. */
-export function stripUsdFields(value) {
-  if (Array.isArray(value)) return value.map(stripUsdFields);
-  if (!value || typeof value !== 'object') return value;
+const isRecord = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+
+const finite = (value) => {
+  const n = typeof value === 'number' ? value : typeof value === 'string' && value.trim() ? Number(value) : NaN;
+  return Number.isFinite(n) ? n : undefined;
+};
+
+export const roundUsd = (usd) => Math.round(usd * 100) / 100;
+
+const formatUsd = (amount) => `$${roundUsd(amount).toFixed(2)}`;
+
+/** The API's display rate wherever the payload carries it (top level or `data`). */
+export function retailUsdPerCreditOf(value) {
+  if (!isRecord(value)) return undefined;
+  const own = finite(value.retailUsdPerCredit);
+  if (own !== undefined && own > 0) return own;
+  return isRecord(value.data) ? retailUsdPerCreditOf(value.data) : undefined;
+}
+
+/** A credits amount in USD at the API's rate, or undefined when either is missing. */
+export function usdFromCredits(credits, rate) {
+  const amount = finite(credits);
+  return amount === undefined || rate === undefined ? undefined : roundUsd(amount * rate);
+}
+
+/** The value with balances in USD and no credit count, per-credit rate or per-action price, at any depth. */
+export function toUsdFirst(value, rate = retailUsdPerCreditOf(value)) {
+  if (Array.isArray(value)) return value.map((item) => toUsdFirst(item, rate));
+  if (!isRecord(value)) return value;
   const out = {};
   for (const [key, inner] of Object.entries(value)) {
-    if (USD_KEY.test(key) || key === 'displayCurrency' || key === 'pricingCurrency') continue;
-    out[key] = stripUsdFields(inner);
+    const scalar = !isRecord(inner) && !Array.isArray(inner);
+    if (CREDIT_KEY.test(key) && scalar) continue;
+    if (USD_KEY.test(key) && !KEEP_USD.has(key)) continue;
+    if (CREDIT_COUNTS.has(key) && typeof inner === 'number') continue;
+    // The owner route's ledger unit (`currency: 'credits'`): the balance is shown in USD.
+    if (key === 'currency' && typeof inner === 'string' && CREDIT_KEY.test(inner)) continue;
+    out[key] = toUsdFirst(inner, rate);
+  }
+  // A balance the API sends only in credits (the owner's fallback) is shown in USD.
+  if (out.availableUsd === undefined && finite(value.balanceCredits) !== undefined) {
+    const usd = usdFromCredits(value.balanceCredits, rate);
+    if (usd !== undefined) out.availableUsd = usd;
   }
   return out;
 }
 
 const isCount = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0;
 
+/** The balance route's fields: in `data` (`{ success, data }`) or at the top. */
+function balanceFields(payload) {
+  if (!isRecord(payload)) return undefined;
+  const inner = payload.data;
+  if (isRecord(inner) && ('freeDailyLimit' in inner || 'freeAllowance' in inner || 'availableUsd' in inner || 'balanceCredits' in inner)) return inner;
+  return payload;
+}
+
+/** The balance in USD: `availableUsd`, else the credits balance at the API's rate. */
+function balanceUsd(payload) {
+  const fields = balanceFields(payload);
+  if (!fields) return undefined;
+  if (isCount(fields.availableUsd)) return fields.availableUsd;
+  return usdFromCredits(fields.balanceCredits ?? fields.balance, retailUsdPerCreditOf(payload));
+}
+
+/** Who pays next: the agent's part (or null) and the rest, in billing order. Undefined for an older API. */
+function freeQuotaParts(payload) {
+  const fields = balanceFields(payload);
+  if (!fields) return undefined;
+  const { ownerCreditsFallback, balanceCredits } = fields;
+  // The agent route says freeDailyLimit / freeRequestsRemainingToday; the owner route freeAllowance / freeRemainingToday.
+  const freeDailyLimit = fields.freeDailyLimit ?? fields.freeAllowance;
+  const freeRequestsRemainingToday = fields.freeRequestsRemainingToday ?? fields.freeRemainingToday;
+  if (!isCount(freeDailyLimit) || !isCount(freeRequestsRemainingToday)) return undefined;
+  const rate = retailUsdPerCreditOf(payload);
+  const agentUsd = isCount(fields.availableUsd) ? fields.availableUsd : usdFromCredits(balanceCredits, rate);
+  let agent = null;
+  if (isCount(agentUsd) && agentUsd > 0) agent = `The agent's balance (${formatUsd(agentUsd)}) pays first`;
+  else if (isCount(balanceCredits) && balanceCredits > 0) agent = "The agent's balance pays first";
+  const rest = [`${freeRequestsRemainingToday} of ${freeDailyLimit} free requests left today`];
+  if (isRecord(ownerCreditsFallback) && ownerCreditsFallback.enabled === true) {
+    const ownerUsd = usdFromCredits(ownerCreditsFallback.balanceCredits, rate);
+    rest.push(isCount(ownerUsd) ? `then the owner's balance (${formatUsd(ownerUsd)}) pays` : "then the owner's balance pays");
+  }
+  rest.push('then top up the balance');
+  return { agent, rest };
+}
+
 /**
  * Who pays next for the agent's actions, from the agent credits route's fields (thirdfy-api-v2#884):
  * `freeRequestsRemainingToday` of `freeDailyLimit` (free requests per UTC day) and
- * `ownerCreditsFallback` (the owner's credits pay once the agent's credits and free requests are
- * used). Billing order: agent's credits, free requests, owner's credits, refusal. Same wording as
- * thirdfy-mcp `creditsFreeQuotaNote` (#253). Undefined when an older API omits the fields.
+ * `ownerCreditsFallback` (the owner's balance pays once the agent's balance and free requests are
+ * used). Billing order: agent's balance, free requests, owner's balance, refusal. Amounts in USD,
+ * never credits; same wording as thirdfy-mcp `creditsFreeQuotaNote` (#279). Undefined when an older
+ * API omits the fields.
  */
 export function creditsFreeQuotaNote(payload) {
-  const fields = payload?.data && typeof payload.data === 'object' && 'freeDailyLimit' in payload.data ? payload.data : payload;
-  if (!fields || typeof fields !== 'object') return undefined;
-  const { freeDailyLimit, freeRequestsRemainingToday, ownerCreditsFallback, balanceCredits } = fields;
-  if (!isCount(freeDailyLimit) || !isCount(freeRequestsRemainingToday)) return undefined;
-  const parts = [];
-  if (isCount(balanceCredits) && balanceCredits > 0) parts.push(`The agent's credits (${balanceCredits}) pay first`);
-  parts.push(`${freeRequestsRemainingToday} of ${freeDailyLimit} free requests left today`);
-  if (ownerCreditsFallback && typeof ownerCreditsFallback === 'object' && ownerCreditsFallback.enabled === true) {
-    const owner = ownerCreditsFallback.balanceCredits;
-    parts.push(isCount(owner) ? `then the owner's credits (${owner}) pay` : "then the owner's credits pay");
-  }
-  parts.push('then buy credits');
-  return `${parts.join('; ')}.`;
+  const parts = freeQuotaParts(payload);
+  if (!parts) return undefined;
+  return `${[...(parts.agent ? [parts.agent] : []), ...parts.rest].join('; ')}.`;
 }
 
-/** The balance in credits only, with who pays next when the API says. */
+/**
+ * The balance in dollars, never credits, with who pays next when the API says, for example
+ * "$4.20 left; 8 of 20 free requests left today; then the owner's balance ($86.22) pays; then top up the balance."
+ */
 export function formatCreditsBalanceSummary(response) {
-  const credits = `${response?.balance ?? response?.balanceCredits ?? 0} credits`;
-  const note = creditsFreeQuotaNote(response);
-  return note ? `${credits}. ${note}` : credits;
+  const usd = balanceUsd(response);
+  const lead = usd === undefined ? 'balance in USD not reported by this API' : `${formatUsd(usd)} left`;
+  const parts = freeQuotaParts(response);
+  return `${[lead, ...(parts ? parts.rest : [])].join('; ')}.`;
+}
+
+const PAYER_LABELS = {
+  agent_credits: "the agent's balance",
+  free_request: 'a free request',
+  owner_credits: "the owner's balance",
+  none: 'nobody: it would be refused until the balance is topped up',
+};
+
+/** `wouldBePaidBy` in words, with the API's value in parentheses. Never a price. */
+export function describeWouldBePaidBy(wouldBePaidBy) {
+  const raw = String(wouldBePaidBy || '').trim();
+  if (!raw) return undefined;
+  return PAYER_LABELS[raw] ? `${PAYER_LABELS[raw]} (${raw})` : raw;
 }
 
+/**
+ * `models list` / `models estimate` are owner model-pricing reports (owner auth only) and are left as
+ * they were by the USD-first rule, as thirdfy-mcp left its owner-token credits tools.
+ */
 export function formatCreditsModelsSummary(response) {
   const firstModel = response?.models?.[0];
   if (firstModel?.estimatedUsdPerTurn != null) {

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/payloads.mjs

@@ -3,6 +3,7 @@ import { wrapWriteIdempotencyKeyForHostedRuntime } from '../../core/execution/ho
 import { resolveExecutionContextFromEnv } from '../../core/execution/executionContext.mjs';
 import { requireFlag, parseJsonFlag } from '../../core/args.mjs';
 import { findAgentApiKey, loadProfileConfig } from '../../core/context.mjs';
+import { apiBaseFor, oauthSessionForApi, oauthSessionIsAgentCredential } from '../../core/oauth/session.mjs';
 import { createCliError } from '../../core/envelope.mjs';
 import { toLegacyVenueActionKey } from '../../core/venueBrand.mjs';
 import { normalizeRunMode, normalizeManagedRunMode, normalizeHybridWalletMode } from '../../core/runMode.mjs';
@@ -62,6 +63,11 @@ function buildBuildTxPayload(flags, resolvedAction, apiAction) {
 function resolveAgentKey(flags) {
   const explicit = String(flags.agentKey || '').trim();
   if (explicit) return explicit.toLowerCase();
+  // With an OAuth sign-in as the agent credential, the agent is the one the owner picked for it.
+  if (oauthSessionIsAgentCredential(flags)) {
+    const oauthAgent = String(oauthSessionForApi(apiBaseFor(flags))?.agentKey || '').trim();
+    if (oauthAgent) return oauthAgent.toLowerCase();
+  }
   const envKey = String(process.env.THIRDFY_AGENT_KEY || process.env.AGENT_KEY || '').trim();
   if (envKey) return envKey.toLowerCase();
   const config = loadProfileConfig();

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,
@@ -222,6 +218,7 @@ export function createRuntimeHandlers(deps) {
     resolveEffectiveUserDid,
     negotiateCapabilities,
     commandAgentRegister: __agent.commandAgentRegister,
+    CLI_VERSION,
   });
 
   return {

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 };
 }