@thirdfy/agent-cli 0.1.48 → 0.2.1

package/src/core/http.mjs

@@ -0,0 +1,77 @@
+export async function apiGet(ctx, route, headers = {}) {
+  return requestJson(ctx, route, { method: 'GET', headers });
+}
+
+export async function apiPost(ctx, route, body, headers = {}) {
+  return requestJson(ctx, route, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      ...headers,
+    },
+    body: JSON.stringify(body),
+  });
+}
+
+export async function requestJson(ctx, route, init) {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), ctx.timeoutMs);
+  try {
+    const response = await fetch(`${ctx.apiBase}${route}`, {
+      ...init,
+      signal: controller.signal,
+    });
+    const text = await response.text();
+    const data = text ? safeJsonParse(text) : {};
+    if (!response.ok) {
+      const error = new Error(data?.error || data?.message || `HTTP ${response.status}`);
+      error.statusCode = response.status;
+      error.payload = data;
+      throw error;
+    }
+    return data;
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export async function requestWithRouteFallback(ctx, options) {
+  const routes = Array.isArray(options.routes) ? options.routes : [];
+  let lastError = null;
+  for (const route of routes) {
+    try {
+      if (options.method === 'GET') {
+        return await apiGet(ctx, route, options.headers || {});
+      }
+      if (options.method === 'POST') {
+        return await apiPost(ctx, route, options.body || {}, options.headers || {});
+      }
+      throw new Error(`Unsupported method for fallback request: ${options.method}`);
+    } catch (error) {
+      lastError = error;
+      const statusCode = Number(error?.statusCode || 0);
+      if (statusCode !== 404) throw error;
+    }
+  }
+  throw lastError || new Error('No route variants succeeded');
+}
+
+export function safeJsonParse(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return { raw: text };
+  }
+}
+
+export async function negotiateCapabilities(ctx) {
+  try {
+    const response = await apiGet(ctx, '/api/v1/agent/cli/capabilities');
+    return response;
+  } catch (error) {
+    if (ctx.verbose) {
+      process.stderr.write(`capabilities negotiation skipped: ${error.message}\n`);
+    }
+    return null;
+  }
+}

package/src/core/index.mjs

@@ -0,0 +1,6 @@
+export * from './constants.mjs';
+export * from './args.mjs';
+export * from './envelope.mjs';
+export * from './runMode.mjs';
+export * from './http.mjs';
+export * from './context.mjs';

package/src/core/runMode.mjs

@@ -0,0 +1,72 @@
+import {
+  CUSTODY_MODES,
+  EFFECT_CHECK_MODES,
+  HYBRID_WALLET_MODES,
+  PROFILE_DEFAULTS,
+  RUN_MODES,
+} from './constants.mjs';
+import { createCliError } from './envelope.mjs';
+
+export function normalizeProfileName(value) {
+  const normalized = String(value || '').trim().toLowerCase();
+  if (normalized in PROFILE_DEFAULTS) return normalized;
+  throw new Error(`Unsupported profile "${value}". Supported: ${Object.keys(PROFILE_DEFAULTS).join(', ')}`);
+}
+
+export function normalizeRunMode(value, flagName = '--run-mode') {
+  const normalized = String(value || '').trim().toLowerCase();
+  if (!normalized) return 'thirdfy';
+  if (RUN_MODES.includes(normalized)) return normalized;
+  throw new Error(`Unsupported ${flagName} "${value}". Supported: ${RUN_MODES.join(', ')}`);
+}
+
+export function defaultCustodyModeForRunMode(runMode) {
+  return runMode === 'thirdfy' || runMode === 'agent_wallet' ? 'managed' : 'external';
+}
+
+export function normalizeCustodyMode(value, runModeHint = 'thirdfy') {
+  const fallback = defaultCustodyModeForRunMode(runModeHint);
+  const normalized = String(value || '').trim().toLowerCase();
+  if (!normalized) return fallback;
+  if (CUSTODY_MODES.includes(normalized)) return normalized;
+  throw new Error(`Unsupported custody mode "${value}". Supported: ${CUSTODY_MODES.join(', ')}`);
+}
+
+export function normalizeManagedRunMode(value) {
+  const mode = normalizeRunMode(value || 'thirdfy');
+  if (mode === 'self') {
+    throw new Error('Managed lane does not support run-mode=self. Use thirdfy, hybrid, or agent_wallet.');
+  }
+  return mode;
+}
+
+export function normalizeHybridWalletMode(value) {
+  const normalized = String(value || '').trim().toLowerCase() || 'self';
+  if (HYBRID_WALLET_MODES.includes(normalized)) return normalized;
+  throw new Error(`Unsupported --hybrid-wallet-mode "${value}". Supported: ${HYBRID_WALLET_MODES.join(', ')}`);
+}
+
+export function getEffectiveRunMode(ctx, flags) {
+  if (flags.runMode) return normalizeRunMode(flags.runMode);
+  return normalizeRunMode(ctx.runMode || 'thirdfy');
+}
+
+export function parseBooleanFlag(value, defaultValue = false) {
+  if (value === undefined || value === null) return defaultValue;
+  if (typeof value === 'boolean') return value;
+  const normalized = String(value).trim().toLowerCase();
+  if (!normalized) return defaultValue;
+  if (['1', 'true', 'yes', 'on'].includes(normalized)) return true;
+  if (['0', 'false', 'no', 'off'].includes(normalized)) return false;
+  return defaultValue;
+}
+
+export function normalizeEffectCheckMode(value) {
+  const normalized = String(value || '').trim().toLowerCase();
+  if (!normalized) return 'relaxed';
+  if (EFFECT_CHECK_MODES.includes(normalized)) return normalized;
+  throw createCliError(
+    'EFFECT_CHECK_MODE_INVALID',
+    `Unsupported --effect-check "${value}". Supported: ${EFFECT_CHECK_MODES.join(', ')}.`
+  );
+}

package/src/runtime/actions/selection.mjs

@@ -0,0 +1,339 @@
+import { requireFlag } from '../../core/args.mjs';
+import { getCachedActionsCatalog } from '../../core/context.mjs';
+export function createActionSelection({ getTradingProviderHint, formatProviderAmbiguousActionHint, formatProviderUnknownActionHint }) {
+function getActionKey(action) {
+  return String(action?.action || action?.id || action?.key || action?.name || '')
+    .trim();
+}
+
+function getActionAliases(action) {
+  if (!Array.isArray(action?.aliases)) return [];
+  return action.aliases
+    .map((v) => String(v || '').trim())
+    .filter(Boolean);
+}
+
+function formatActionList(items) {
+  return items
+    .map((v) => `\`${v}\``)
+    .join(', ');
+}
+
+function normalizeProviderId(value) {
+  return String(value || '').trim().toLowerCase();
+}
+
+function rowActionKey(action) {
+  return getActionKey(action)
+    .replace(/-/g, '_')
+    .toLowerCase();
+}
+
+function canonicalActionKey(action) {
+  return getActionKey(action)
+    .replace(/_/g, '-')
+    .toLowerCase();
+}
+
+function inferActionProvider(action) {
+  // API catalog metadata (`providerId`, `domain`, `category`) is the source of truth.
+  // This fallback only keeps older catalog rows / older API deployments discoverable.
+  const key = canonicalActionKey(action);
+  const knownMap = {
+    swap: 'trading',
+    'execute-optimal-swap': 'trading',
+    'get-best-trading-quote': 'trading',
+    'dogeos-barkswap-get-quote': 'dogeos-barkswap',
+    'dogeos-barkswap-execute-swap': 'dogeos-barkswap',
+    'dogeos-get-ecosystem-overview': 'dogeos-ecosystem',
+    'dogeos-get-wallet-actionability': 'dogeos-ecosystem',
+    'dogeos-prepare-trade': 'dogeos-ecosystem',
+    'dogeos-prepare-token-launch': 'dogeos-ecosystem',
+    'dogeos-get-chain-insights': 'dogeos-ecosystem',
+    'dogeos-get-trending-tokens': 'dogeos-ecosystem',
+    'dogeos-get-new-tokens': 'dogeos-ecosystem',
+    'dogeos-get-early-bird-tokens': 'dogeos-ecosystem',
+    'dogeos-get-only-moon-tokens': 'dogeos-ecosystem',
+    'dogeos-get-big-wins-tokens': 'dogeos-ecosystem',
+    'dogeos-get-related-tokens': 'dogeos-ecosystem',
+    'dogeos-laika-read-contract': 'dogeos-laika',
+    'dogeos-laika-execute-raw': 'dogeos-laika',
+    'dogeos-laika-launch-token': 'dogeos-laika',
+    'dogeos-laika-buy-token': 'dogeos-laika',
+    'dogeos-laika-claim': 'dogeos-laika',
+    'dogeos-laika-token-state': 'dogeos-laika',
+    'get-governance-v2-overview': 'governance-v2',
+    'get-governance-v2-timeseries': 'governance-v2',
+    'get-governance-v2-breakdowns': 'governance-v2',
+    'get-hyperliquid-perps-meta': 'hyperliquid',
+    'get-hyperliquid-all-mids': 'hyperliquid',
+    'search-hyperliquid-markets': 'hyperliquid',
+    'get-hyperliquid-l2-book': 'hyperliquid',
+    'get-hyperliquid-candles': 'hyperliquid',
+    'get-hyperliquid-user-state': 'hyperliquid',
+    'get-hyperliquid-open-orders': 'hyperliquid',
+    'get-hyperliquid-setup-status': 'hyperliquid',
+    'get-hyperliquid-funding-status': 'hyperliquid',
+    'get-hyperliquid-onboarding-plan': 'hyperliquid',
+    'prepare-hyperliquid-onboarding': 'hyperliquid',
+    'claim-hyperliquid-testnet-faucet': 'hyperliquid',
+    'get-hyperliquid-builder-fee-status': 'hyperliquid',
+    'approve-hyperliquid-agent': 'hyperliquid',
+    'approve-hyperliquid-builder-fee': 'hyperliquid',
+    'register-hyperliquid-referrer': 'hyperliquid',
+    'set-hyperliquid-referrer': 'hyperliquid',
+    'get-hyperliquid-referral-status': 'hyperliquid',
+    'deposit-hyperliquid-staking': 'hyperliquid',
+    'deposit-hyperliquid-bridge': 'hyperliquid',
+    'place-hyperliquid-perps-order': 'hyperliquid',
+    'cancel-hyperliquid-perps-order': 'hyperliquid',
+    'get-perps-markets': 'hyperliquid',
+    'get-perps-account': 'hyperliquid',
+    'get-perps-position': 'hyperliquid',
+    'place-perps-order': 'hyperliquid',
+    'cancel-perps-order': 'hyperliquid',
+    'get-earn-opportunities': 'earn',
+    'get-earn-provider': 'earn',
+    'get-earn-position': 'earn',
+    'deposit-earn-position': 'earn',
+    'withdraw-earn-position': 'earn',
+    'get-capyfi-markets': 'capyfi',
+    'get-fx-supported-assets': 'fx',
+    'quote-fx-swap': 'fx',
+    'get-monerium-profile-status': 'fx',
+    'get-morpho-vaults': 'morpho',
+    'deposit-morpho-vault': 'morpho',
+    'withdraw-morpho-vault': 'morpho',
+    'get-curve-pools': 'curve',
+    'get-curve-pool-details': 'curve',
+    'deposit-curve-pool': 'curve',
+    'withdraw-curve-pool': 'curve',
+    'get-aegis-pools': 'aegis',
+    'get-aegis-pool-state': 'aegis',
+    'get-aegis-vault-state': 'aegis',
+    'deposit-aegis-lender': 'aegis',
+    'redeem-aegis-lender': 'aegis',
+    'open-aegis-vault-and-borrow': 'aegis',
+    'repay-aegis-vault': 'aegis',
+    'stabilize-aegis-vault': 'aegis',
+    'get-vaults-fyi-vaults': 'vaults-fyi',
+    'get-vaults-fyi-opportunities': 'vaults-fyi',
+    'get-yield-xyz-opportunities': 'yield-xyz',
+    'get-prediction-markets': 'polymarket',
+    'get-prediction-market': 'polymarket',
+    'get-prediction-events': 'polymarket',
+    'get-prediction-tags': 'polymarket',
+    'search-prediction-markets': 'polymarket',
+    'get-prediction-order-book': 'polymarket',
+    'get-prediction-position': 'polymarket',
+    'place-prediction-order': 'polymarket',
+    'cancel-prediction-order': 'polymarket',
+    'get-polymarket-markets': 'polymarket',
+    'get-polymarket-market': 'polymarket',
+    'get-polymarket-events': 'polymarket',
+    'get-polymarket-event': 'polymarket',
+    'get-polymarket-tags': 'polymarket',
+    'search-polymarket': 'polymarket',
+    'get-polymarket-order-book': 'polymarket',
+    'get-polymarket-prices': 'polymarket',
+    'get-polymarket-setup-status': 'polymarket',
+    'get-polymarket-order': 'polymarket',
+    'get-polymarket-user-orders': 'polymarket',
+    'cancel-polymarket-order': 'polymarket',
+    'get-polymarket-price-history': 'polymarket',
+    'place-polymarket-order': 'polymarket',
+  };
+  if (knownMap[key]) return knownMap[key];
+  if (key.includes('hyperliquid')) return 'hyperliquid';
+  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';
+  if (key.includes('capyfi')) return 'capyfi';
+  if (key.includes('fx') || key.includes('monerium')) return 'fx';
+  if (key.includes('morpho')) return 'morpho';
+  if (key.includes('aegis')) return 'aegis';
+  if (key.includes('curve')) return 'curve';
+  if (key.includes('earn') || key.includes('yield') || key.includes('vault')) return 'earn';
+  if (key.includes('bridge')) return 'bridge';
+  if (key.includes('dogeos-barkswap')) return 'dogeos-barkswap';
+  if (key.includes('dogeos-laika')) return 'dogeos-laika';
+  if (key.includes('dogeos')) return 'dogeos-ecosystem';
+  return '';
+}
+
+function getActionProviderWithInference(action) {
+  return getActionProvider(action) || inferActionProvider(action);
+}
+
+function isEarnCatalogAction(action) {
+  const actionKey = rowActionKey(action);
+  return (
+    actionKey.includes('_earn_') ||
+    normalizeProviderId(action?.domain) === 'earn' ||
+    normalizeProviderId(action?.category) === 'earn'
+  );
+}
+
+function isGenericEarnWriteAction(action) {
+  const actionKey = rowActionKey(action);
+  return actionKey === 'deposit_earn_position' || actionKey === 'withdraw_earn_position';
+}
+
+function isGenericEarnWriteForProvider(action, requestedProvider) {
+  if (!isGenericEarnWriteAction(action)) return false;
+  const provider = getActionProviderWithInference(action);
+  if (!provider) return true;
+  if (provider === requestedProvider) return true;
+  if (provider === 'earn' && requestedProvider === 'earn') return true;
+  return false;
+}
+
+function isSpotTradingCatalogAction(action) {
+  const actionKey = rowActionKey(action);
+  return actionKey === 'swap' || actionKey === 'execute_optimal_swap' || actionKey === 'get_best_trading_quote';
+}
+
+function isProviderActionKey(action, provider) {
+  const actionKey = rowActionKey(action);
+  const normalizedProvider = normalizeProviderId(provider).replace(/-/g, '_');
+  if (!actionKey || !normalizedProvider) return false;
+  return (
+    actionKey === normalizedProvider ||
+    actionKey.startsWith(`${normalizedProvider}_`) ||
+    actionKey.includes(`_${normalizedProvider}_`) ||
+    actionKey.endsWith(`_${normalizedProvider}`)
+  );
+}
+
+function actionMatchesProvider(action, requestedProvider, allActions) {
+  const provider = getActionProviderWithInference(action);
+  const actionKey = rowActionKey(action);
+  if (provider === requestedProvider) return true;
+  if (requestedProvider === 'trading') return isSpotTradingCatalogAction(action);
+  // Here resolved metadata already disagrees with the filter; fall back to action-key shape only.
+  if (requestedProvider === 'hyperliquid') return isProviderActionKey(action, 'hyperliquid');
+  if (requestedProvider === 'polymarket') return isProviderActionKey(action, 'polymarket');
+  if (requestedProvider === 'bridge') {
+    // Hyperliquid Bridge2 setup actions are owned by Hyperliquid, not the cross-chain bridge provider.
+    if (provider === 'hyperliquid') return false;
+    return isProviderActionKey(action, 'bridge');
+  }
+  if (requestedProvider.startsWith('dogeos')) return isProviderActionKey(action, requestedProvider);
+  if (requestedProvider === 'earn') {
+    return provider === 'earn' || provider === 'morpho' || provider === 'aegis' || provider === 'curve' || provider === 'capyfi' || provider === 'vaults-fyi' || provider === 'yield-xyz' || isEarnCatalogAction(action);
+  }
+  if (requestedProvider === 'morpho' || requestedProvider === 'aegis' || requestedProvider === 'curve' || requestedProvider === 'capyfi' || requestedProvider === 'vaults-fyi' || requestedProvider === 'yield-xyz') {
+    const hasProtocolSpecificEarnRows = allActions.some((candidate) => getActionProviderWithInference(candidate) === requestedProvider);
+    return (
+      isProviderActionKey(action, requestedProvider) ||
+      isGenericEarnWriteForProvider(action, requestedProvider) ||
+      (!hasProtocolSpecificEarnRows && isEarnCatalogAction(action))
+    );
+  }
+  if (requestedProvider === 'prediction') {
+    return (
+      provider === 'polymarket' ||
+      provider === 'prediction' ||
+      actionKey.includes('_prediction_') ||
+      normalizeProviderId(action?.domain) === 'prediction' ||
+      normalizeProviderId(action?.category) === 'prediction'
+    );
+  }
+  return isProviderActionKey(action, requestedProvider);
+}
+
+function applyActionFilters(actions, flags) {
+  let filtered = actions;
+  if (flags.catalog) {
+    const expectedCatalog = String(flags.catalog).trim().toLowerCase();
+    filtered = filtered.filter((a) => String(a.catalog || a.catalogId || 'default').trim().toLowerCase() === expectedCatalog);
+  }
+  if (flags.provider) {
+    const expectedProvider = normalizeProviderId(flags.provider);
+    filtered = filtered.filter((a) => actionMatchesProvider(a, expectedProvider, filtered));
+  }
+  return filtered;
+}
+
+function getActionProvider(action) {
+  return normalizeProviderId(action?.provider || action?.providerId || action?.provider_id || action?.catalog || '');
+}
+
+async function resolveActionSelection(ctx, flags) {
+  const requestedAction = requireFlag(flags, 'action', 'Missing --action');
+  const requestedLower = requestedAction.toLowerCase();
+  const actions = applyActionFilters(await getCachedActionsCatalog(ctx, flags), flags);
+  const keyed = actions
+    .map((action) => ({
+      key: getActionKey(action),
+      aliases: getActionAliases(action),
+      action,
+    }))
+    .filter((entry) => entry.key);
+
+  if (!keyed.length) {
+    return { requestedAction, resolvedAction: requestedAction, resolvedActionMeta: null };
+  }
+
+  // Prefer direct action id matches over alias matches.
+  // This keeps UX simple for commands like `--action swap` when another action aliases to "swap".
+  const exactKey = keyed.filter((entry) => entry.key.toLowerCase() === requestedLower);
+  if (exactKey.length === 1) {
+    return { requestedAction, resolvedAction: exactKey[0].key, resolvedActionMeta: exactKey[0].action || null };
+  }
+  if (exactKey.length > 1) {
+    throw new Error(
+      `Ambiguous --action "${requestedAction}". Multiple exact matches found: ${formatActionList(
+        exactKey.map((v) => v.key)
+      )}.`
+    );
+  }
+
+  const exactAlias = keyed.filter((entry) => entry.aliases.some((a) => a.toLowerCase() === requestedLower));
+  if (exactAlias.length === 1) {
+    return { requestedAction, resolvedAction: exactAlias[0].key, resolvedActionMeta: exactAlias[0].action || null };
+  }
+  if (exactAlias.length > 1) {
+    const providerHint = flags.provider ? getTradingProviderHint(flags.provider) : null;
+    throw new Error(
+      `Ambiguous --action "${requestedAction}". Alias matches multiple actions: ${formatActionList(
+        exactAlias.map((v) => v.key)
+      )}.${formatProviderAmbiguousActionHint(providerHint)}`
+    );
+  }
+
+  const fuzzy = keyed.filter(
+    (entry) =>
+      entry.key.toLowerCase().includes(requestedLower) ||
+      entry.aliases.some((a) => a.toLowerCase().includes(requestedLower))
+  );
+  if (fuzzy.length === 1) {
+    return { requestedAction, resolvedAction: fuzzy[0].key, resolvedActionMeta: fuzzy[0].action || null };
+  }
+  if (fuzzy.length > 1) {
+    const providerHint = flags.provider ? getTradingProviderHint(flags.provider) : null;
+    throw new Error(
+      `Ambiguous --action "${requestedAction}". Did you mean one of: ${formatActionList(
+        fuzzy.slice(0, 10).map((v) => v.key)
+      )}?${formatProviderAmbiguousActionHint(providerHint)}`
+    );
+  }
+  const providerHint = flags.provider ? getTradingProviderHint(flags.provider) : null;
+  throw new Error(
+    `Unknown --action "${requestedAction}". No compatible action found in current catalog/provider scope.${formatProviderUnknownActionHint(
+      providerHint
+    )}`
+  );
+}
+
+  return {
+    getActionKey,
+    getActionAliases,
+    formatActionList,
+    normalizeProviderId,
+    applyActionFilters,
+    getActionProvider,
+    resolveActionSelection,
+  };
+}

package/src/runtime/agentExtract.mjs

@@ -0,0 +1,52 @@
+export function createAgentExtract() {
+function extractAgentApiKey(value) {
+  if (!value || typeof value !== 'object') return '';
+  const candidates = [
+    value.agentApiKey,
+    value.apiKey,
+    value.data?.agentApiKey,
+    value.data?.apiKey,
+    value.bootstrap?.agentApiKey,
+    value.bootstrap?.apiKey,
+    value.registration?.agentApiKey,
+    value.registration?.apiKey,
+    value.registration?.registration?.agentApiKey,
+    value.registration?.registration?.apiKey,
+    value.data?.registration?.agentApiKey,
+    value.data?.registration?.apiKey,
+    value.data?.registration?.registration?.agentApiKey,
+    value.data?.registration?.registration?.apiKey,
+  ];
+  return String(candidates.find((candidate) => String(candidate || '').trim()) || '').trim();
+}
+
+function extractAgentKey(value) {
+  if (!value || typeof value !== 'object') return '';
+  const candidates = [
+    value.agentKey,
+    value.data?.agentKey,
+    value.bootstrap?.agentKey,
+    value.registration?.agentKey,
+    value.registration?.registration?.agentKey,
+    value.data?.registration?.agentKey,
+    value.data?.registration?.registration?.agentKey,
+    value.owner?.creatorWallet,
+    value.data?.owner?.creatorWallet,
+  ];
+  return String(candidates.find((candidate) => String(candidate || '').trim()) || '').trim();
+}
+
+function maskSecret(value) {
+  const raw = String(value || '').trim();
+  if (!raw) return null;
+  if (raw.length <= 12) return '***';
+  if (raw.length <= 20) return `${raw.slice(0, 4)}***${raw.slice(-2)}`;
+  return `${raw.slice(0, 6)}...${raw.slice(-4)}`;
+}
+
+  return {
+    extractAgentApiKey,
+    extractAgentKey,
+    maskSecret,
+  };
+}

package/src/runtime/authHelpers.mjs

@@ -0,0 +1,53 @@
+import { loadProfileConfig } from '../core/context.mjs';
+export function createAuthHelpers() {
+function getAuthToken(flags, missingMessage) {
+  const config = loadProfileConfig();
+  const authToken = String(flags.authToken || process.env.THIRDFY_AUTH_TOKEN || config?.auth?.authToken || '').trim();
+  if (!authToken) throw new Error(missingMessage);
+  return authToken;
+}
+
+function buildOwnerAuthHeaders(flags, missingMessage) {
+  const config = loadProfileConfig();
+  const explicitOwnerSessionToken = String(flags.ownerSessionToken || '').trim();
+  const explicitAuthToken = String(flags.authToken || '').trim();
+  const ownerSessionToken = String(process.env.THIRDFY_OWNER_SESSION_TOKEN || config?.auth?.ownerSessionToken || '').trim();
+  const authToken = String(process.env.THIRDFY_AUTH_TOKEN || config?.auth?.authToken || '').trim();
+
+  // Prefer explicit flags first; then prefer owner-session over bearer from env/config
+  // to keep owner operations on least-privilege credentials by default.
+  if (explicitOwnerSessionToken) {
+    return { 'x-owner-session-token': explicitOwnerSessionToken };
+  }
+  if (explicitAuthToken) {
+    return { Authorization: `Bearer ${explicitAuthToken}` };
+  }
+  if (ownerSessionToken) {
+    return { 'x-owner-session-token': ownerSessionToken };
+  }
+  if (authToken) {
+    return { Authorization: `Bearer ${authToken}` };
+  }
+  throw new Error(missingMessage);
+}
+
+function resolveUnsignedTx(result) {
+  if (result?.unsignedTx && typeof result.unsignedTx === 'object') return result.unsignedTx;
+  if (result?.data?.unsignedTx && typeof result.data.unsignedTx === 'object') return result.data.unsignedTx;
+  if (result?.details?.unsignedTx && typeof result.details.unsignedTx === 'object') return result.details.unsignedTx;
+  return null;
+}
+
+async function sleepMs(ms) {
+  const delay = Number(ms || 0);
+  if (!Number.isFinite(delay) || delay <= 0) return;
+  await new Promise((resolve) => setTimeout(resolve, delay));
+}
+
+  return {
+    getAuthToken,
+    buildOwnerAuthHeaders,
+    resolveUnsignedTx,
+    sleepMs,
+  };
+}