@thirdfy/agent-cli 0.2.11 → 0.2.14

package/CHANGELOG.md

@@ -4,6 +4,24 @@ All notable changes to `@thirdfy/agent-cli` are documented here. The format is b
 
 ## [Unreleased]
 
+## [0.2.14] - 2026-06-24
+
+### Changed
+
+- HTTP client (`src/core/http.mjs`) retries once on **502/503/504** and timeout/abort errors with short jittered backoff. Pairs with Thirdfy API **v3.5.6+** Supabase REST resilience (`UPSTREAM_DB_UNAVAILABLE`).
+
+## [0.2.13] - 2026-06-23
+
+### Changed
+
+- Lighter provider hints: Base-first `complete_lighter_onboarding` lead action and catalog-aligned names for CCTP funding, API-key setup, and integrator approval. Pairs with Thirdfy API **v3.5.3+** and `thirdfy-mcp` **v0.0.62+**.
+
+## [0.2.12] - 2026-06-22
+
+### Added
+
+- Lighter perps provider: `lighter` command group, provider hints, execution lanes, and wallet helpers for CCTP funding discovery, market reads, API-key setup, and signed perps writes. Pairs with Thirdfy API **v3.5.2+** and `thirdfy-mcp` **v0.0.61+**.
+
 ## [0.2.11] - 2026-06-17
 
 ### Changed

package/README.md

@@ -40,10 +40,9 @@ Run without global install:
 npx @thirdfy/agent-cli --help
 ```
 
-## What's new in v0.2.11
+## What's new in v0.2.14
 
-- Command reference adds `get_allora_topics` and `get_allora_topic_inference` examples for provider `allora`. Pairs with Thirdfy API **v3.4.60+**.
-- Public docs no longer imply you need an Allora API key in the CLI. Allora reads bill through Thirdfy credits like other provider actions.
+- HTTP client retries once on Thirdfy API **502/503/504** and client timeouts (bounded `AbortController`), so PostgREST outages surface as transient failures instead of hanging Hermes read cycles. Pairs with Thirdfy API **v3.5.6+**.
 
 Older versions: see [CHANGELOG.md](./CHANGELOG.md) and [GitHub Releases](https://github.com/thirdfy/agent-cli/releases).
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thirdfy/agent-cli",
-  "version": "0.2.11",
+  "version": "0.2.14",
   "description": "Thirdfy Agent CLI for onboarding, governance preflight, execute-intent, and status polling.",
   "type": "module",
   "bin": {

package/src/commands/execute.mjs

@@ -19,6 +19,7 @@ export function createExecuteCommands(deps) {
     enforceOffchainVenueLaneCompatibility,
     enforceChainCompatibility,
     applyHyperliquidAgentWalletAddressDefault,
+    applyLighterAgentWalletAddressDefault,
     runPreflightByMode,
     runExecutionByMode,
     applyExecutionFallbackHints,
@@ -38,7 +39,9 @@ async function commandPreflight(ctx, flags, capabilities) {
   enforceOffchainVenueLaneCompatibility(resolved.resolvedAction, runMode);
   const hybridWalletMode = runMode === 'hybrid' ? normalizeHybridWalletMode(flags.hybridWalletMode) : null;
   enforceChainCompatibility(capabilities, flags, runMode);
-  const managedPreflight = await applyHyperliquidAgentWalletAddressDefault(ctx, flags, resolved, runMode);
+  const managedPreflight =
+    (await applyHyperliquidAgentWalletAddressDefault(ctx, flags, resolved, runMode))
+    || (await applyLighterAgentWalletAddressDefault(ctx, flags, resolved, runMode));
   const backendResult = await runPreflightByMode(runMode, ctx, flags, resolved, { hybridWalletMode, managedPreflight });
   const normalized = applyExecutionFallbackHints(backendResult.normalized, {
     flags,
@@ -88,7 +91,9 @@ async function commandRun(ctx, flags, capabilities) {
   enforceOffchainVenueLaneCompatibility(resolved.resolvedAction, runMode);
   const hybridWalletMode = runMode === 'hybrid' ? normalizeHybridWalletMode(flags.hybridWalletMode) : null;
   enforceChainCompatibility(capabilities, flags, runMode);
-  const managedPreflight = await applyHyperliquidAgentWalletAddressDefault(ctx, flags, resolved, runMode);
+  const managedPreflight =
+    (await applyHyperliquidAgentWalletAddressDefault(ctx, flags, resolved, runMode))
+    || (await applyLighterAgentWalletAddressDefault(ctx, flags, resolved, runMode));
   const skipPreflight = Boolean(flags.skipPreflight);
   const backendResult = await runExecutionByMode(runMode, ctx, flags, resolved, {
     skipPreflight,

package/src/commands/index.mjs

@@ -1,5 +1,6 @@
 export { createPolymarketCommands, resolveConfigAgentKey } from './polymarket.mjs';
 export { createHyperliquidHelpers } from './hyperliquid.mjs';
+export { createLighterHelpers } from './lighter.mjs';
 export { createExecuteCommands } from './execute.mjs';
 export { createWalletCommands } from './wallet.mjs';
 export { createDelegationCommands } from './delegation.mjs';

package/src/commands/lighter.mjs

@@ -0,0 +1,52 @@
+import { parseJsonFlag } from '../core/args.mjs';
+
+export function createLighterHelpers(deps) {
+  const { getPreparedParams, resolveManagedExecutionPreflight } = deps;
+
+
+function lighterDefaultAddressParamForAction(action) {
+  const canonical = String(action || '').trim().toLowerCase().replace(/_/g, '-');
+  if (
+    canonical === 'get-lighter-open-orders'
+    || canonical === 'get-lighter-user-state'
+  ) {
+    return 'userAddress';
+  }
+  if (
+    canonical === 'get-lighter-account'
+    || canonical === 'get-lighter-setup-status'
+    || canonical === 'get-lighter-funding-status'
+    || canonical === 'get-lighter-onboarding-plan'
+    || canonical === 'prepare-lighter-onboarding'
+    || canonical === 'complete-lighter-onboarding'
+    || canonical === 'create-lighter-deposit-intent'
+  ) {
+    return 'l1Address';
+  }
+  return null;
+}
+
+
+async function applyLighterAgentWalletAddressDefault(ctx, flags, resolved, runMode) {
+  if (runMode !== 'agent_wallet') return null;
+  const paramName = lighterDefaultAddressParamForAction(resolved?.resolvedAction);
+  if (!paramName) return null;
+  const params = getPreparedParams(flags);
+  if (String(params?.[paramName] || '').trim()) return null;
+  const preflight = await resolveManagedExecutionPreflight(ctx, flags, resolved, {
+    runMode: 'agent_wallet',
+    requireFundingCheck: false,
+  });
+  if (!preflight.success || !preflight.executionWalletAddress) return preflight;
+  flags.__preparedParams = {
+    ...(params || {}),
+    [paramName]: preflight.executionWalletAddress,
+  };
+  return preflight;
+}
+
+  return {
+    lighterDefaultAddressParamForAction,
+    applyLighterAgentWalletAddressDefault,
+  };
+}

package/src/commands/wallet.mjs

@@ -9,6 +9,7 @@ export function createWalletCommands(deps) {
     enforceOffchainVenueLaneCompatibility,
     enforceChainCompatibility,
     applyHyperliquidAgentWalletAddressDefault,
+    applyLighterAgentWalletAddressDefault,
     executeManagedWalletRun,
     executeSelfRun,
     submitSignedTx,
@@ -21,7 +22,9 @@ async function commandWalletExecute(ctx, flags, capabilities) {
   const resolved = await resolveActionSelection(ctx, normalizedFlags);
   prepareActionParamsForFlags(normalizedFlags, resolved.resolvedAction);
   enforceChainCompatibility(capabilities, normalizedFlags, 'agent_wallet');
-  const managedPreflight = await applyHyperliquidAgentWalletAddressDefault(ctx, normalizedFlags, resolved, 'agent_wallet');
+  const managedPreflight =
+    (await applyHyperliquidAgentWalletAddressDefault(ctx, normalizedFlags, resolved, 'agent_wallet'))
+    || (await applyLighterAgentWalletAddressDefault(ctx, normalizedFlags, resolved, 'agent_wallet'));
   const skipPreflight = Boolean(normalizedFlags.skipPreflight);
   const result = await executeManagedWalletRun(ctx, normalizedFlags, resolved, { skipPreflight, managedPreflight });
   printEnvelope({

package/src/core/http.mjs

@@ -4,6 +4,25 @@ import {
   resolveExecutionContextFromInput,
 } from './executionContext.mjs';
 
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+function isRetryableApiStatus(statusCode) {
+  return statusCode === 502 || statusCode === 503 || statusCode === 504;
+}
+
+function isRetryableApiError(error) {
+  const statusCode = Number(error?.statusCode || 0);
+  const message = String(error?.message || '').toLowerCase();
+  return (
+    isRetryableApiStatus(statusCode) ||
+    error?.name === 'AbortError' ||
+    message.includes('abort') ||
+    message.includes('timeout')
+  );
+}
+
 export async function apiGet(ctx, route, headers = {}) {
   return requestJson(ctx, route, { method: 'GET', headers: mergeExecutionContextHeaders(headers) });
 }
@@ -28,7 +47,7 @@ export async function apiPost(ctx, route, body, headers = {}) {
   });
 }
 
-export async function requestJson(ctx, route, init) {
+async function requestJsonOnce(ctx, route, init) {
   const controller = new AbortController();
   const timeout = setTimeout(() => controller.abort(), ctx.timeoutMs);
   try {
@@ -50,6 +69,23 @@ export async function requestJson(ctx, route, init) {
   }
 }
 
+export async function requestJson(ctx, route, init) {
+  let lastError = null;
+  for (let attempt = 0; attempt < 2; attempt += 1) {
+    try {
+      return await requestJsonOnce(ctx, route, init);
+    } catch (error) {
+      lastError = error;
+      if (attempt === 0 && isRetryableApiError(error)) {
+        await sleep(250 + Math.floor(Math.random() * 250));
+        continue;
+      }
+      throw error;
+    }
+  }
+  throw lastError || new Error('Request failed');
+}
+
 export async function requestWithRouteFallback(ctx, options) {
   const routes = Array.isArray(options.routes) ? options.routes : [];
   let lastError = null;

package/src/runtime/actions/selection.mjs

@@ -93,6 +93,22 @@ function inferActionProvider(action) {
     'get-perps-position': 'hyperliquid',
     'place-perps-order': 'hyperliquid',
     'cancel-perps-order': 'hyperliquid',
+    'get-lighter-perps-meta': 'lighter',
+    'get-lighter-all-mids': 'lighter',
+    'search-lighter-markets': 'lighter',
+    'get-lighter-l2-book': 'lighter',
+    'get-lighter-candles': 'lighter',
+    'get-lighter-user-state': 'lighter',
+    'get-lighter-open-orders': 'lighter',
+    'get-lighter-setup-status': 'lighter',
+    'get-lighter-funding-status': 'lighter',
+    'get-lighter-onboarding-plan': 'lighter',
+    'prepare-lighter-onboarding': 'lighter',
+    'approve-lighter-agent': 'lighter',
+    'deposit-lighter-cctp': 'lighter',
+    'place-lighter-perps-order': 'lighter',
+    'cancel-lighter-perps-order': 'lighter',
+    'update-lighter-leverage': 'lighter',
     'get-earn-opportunities': 'earn',
     'get-earn-provider': 'earn',
     'get-earn-position': 'earn',
@@ -146,6 +162,7 @@ function inferActionProvider(action) {
   };
   if (knownMap[key]) return knownMap[key];
   if (key.includes('hyperliquid')) return 'hyperliquid';
+  if (key.includes('lighter')) return 'lighter';
   if (key.includes('bitfinex')) return 'bitfinex';
   if (key.includes('polymarket') || key.includes('prediction')) return 'polymarket';
   if (key.includes('vaults-fyi')) return 'vaults-fyi';
@@ -214,10 +231,11 @@ function actionMatchesProvider(action, requestedProvider, allActions) {
   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 === 'lighter') return isProviderActionKey(action, 'lighter');
   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;
+    // Hyperliquid Bridge2 and Lighter CCTP setup actions are owned by their perps providers, not cross-chain bridge.
+    if (provider === 'hyperliquid' || provider === 'lighter') return false;
     return isProviderActionKey(action, 'bridge');
   }
   if (requestedProvider.startsWith('dogeos')) return isProviderActionKey(action, requestedProvider);

package/src/runtime/execution/lanes.mjs

@@ -7,6 +7,16 @@ const OFFCHAIN_VENUE_ORDER_ACTIONS = new Set([
   'cancel-hyperliquid-perps-order',
   'update_hyperliquid_leverage',
   'update-hyperliquid-leverage',
+  'place_lighter_perps_order',
+  'place-lighter-perps-order',
+  'cancel_lighter_perps_order',
+  'cancel-lighter-perps-order',
+  'update_lighter_leverage',
+  'update-lighter-leverage',
+  'modify_lighter_perps_order',
+  'modify-lighter-perps-order',
+  'update_lighter_margin',
+  'update-lighter-margin',
   'place_polymarket_order',
   'place-polymarket-order',
 ]);
@@ -15,7 +25,7 @@ function enforceOffchainVenueLaneCompatibility(action, runMode) {
   if (runMode !== 'self' || !OFFCHAIN_VENUE_ORDER_ACTIONS.has(normalizedAction)) return;
   throw createCliError(
     'OFFCHAIN_VENUE_ORDER_SELF_UNSUPPORTED',
-    'Polymarket CLOB and Hyperliquid perps orders are offchain signed API actions, not EVM build-tx actions. Use self for setup/funding signatures, then run venue orders with --run-mode thirdfy, --run-mode hybrid, or --run-mode agent_wallet.',
+    'Polymarket CLOB, Hyperliquid perps, and Lighter perps orders are offchain signed API actions, not EVM build-tx actions. Use self for setup/funding signatures, then run venue orders with --run-mode thirdfy, --run-mode hybrid, or --run-mode agent_wallet.',
     {
       recommendedRunModes: ['thirdfy', 'hybrid', 'agent_wallet'],
       setupOnlyRunMode: 'self',

package/src/runtime/handlers.mjs

@@ -1,6 +1,7 @@
 import { negotiateCapabilities } from '../core/http.mjs';
 import { createPolymarketCommands } from '../commands/polymarket.mjs';
 import { createHyperliquidHelpers } from '../commands/hyperliquid.mjs';
+import { createLighterHelpers } from '../commands/lighter.mjs';
 import { createExecuteCommands } from '../commands/execute.mjs';
 import { createWalletCommands } from '../commands/wallet.mjs';
 import { createDelegationCommands } from '../commands/delegation.mjs';
@@ -93,12 +94,19 @@ export function createRuntimeHandlers(deps) {
   });
   const { applyHyperliquidAgentWalletAddressDefault } = __hyperliquid;
 
+  const __lighter = createLighterHelpers({
+    getPreparedParams,
+    resolveManagedExecutionPreflight,
+  });
+  const { applyLighterAgentWalletAddressDefault } = __lighter;
+
   const __wallet = createWalletCommands({
     resolveActionSelection,
     prepareActionParamsForFlags,
     enforceOffchainVenueLaneCompatibility,
     enforceChainCompatibility,
     applyHyperliquidAgentWalletAddressDefault,
+    applyLighterAgentWalletAddressDefault,
     executeManagedWalletRun,
     executeSelfRun,
     submitSignedTx,
@@ -111,6 +119,7 @@ export function createRuntimeHandlers(deps) {
     enforceOffchainVenueLaneCompatibility,
     enforceChainCompatibility,
     applyHyperliquidAgentWalletAddressDefault,
+    applyLighterAgentWalletAddressDefault,
     runPreflightByMode,
     runExecutionByMode,
     applyExecutionFallbackHints,

package/src/runtime/providerHints.mjs

@@ -14,7 +14,7 @@ export function createProviderHints({ getNegotiatedCapabilitiesCache }) {
         supportedChains: [1, 10, 130, 137, 8453, 84532, 42161],
         laneCompatibility:
           'Kyber quote/build is live on Ethereum, Optimism, Unichain, Polygon, Base, and Arbitrum; sponsored Kyber execution is validated on Base only. Gnosis FX uses the fx provider via CoW.',
-        credentialUx: 'Use normal Thirdfy login/delegation; do not use this provider for Hyperliquid or Polymarket.',
+        credentialUx: 'Use normal Thirdfy login/delegation; do not use this provider for Hyperliquid, Lighter, or Polymarket.',
       };
     }
     if (provider === 'hyperliquid') {
@@ -106,6 +106,96 @@ export function createProviderHints({ getNegotiatedCapabilitiesCache }) {
           'thirdfy-agent actions --provider hyperliquid && thirdfy-agent preflight --action place_hyperliquid_perps_order --params \'{"coin":"ETH","isBuy":true,"size":0.01,"limitPx":3500,"orderType":"market"}\'',
       };
     }
+    if (provider === 'lighter') {
+      return {
+        provider,
+        category: 'leveraged_perps',
+        canonicalWriteAction: 'place_lighter_perps_order',
+        readActions: [
+          'get_lighter_markets',
+          'search_lighter_markets',
+          'get_lighter_order_book',
+          'get_lighter_candles',
+          'get_lighter_funding_rates',
+          'get_lighter_account',
+          'get_lighter_positions',
+          'get_lighter_open_orders',
+          'get_lighter_pnl',
+          'get_lighter_funding_status',
+          'get_lighter_setup_status',
+          'get_lighter_onboarding_plan',
+          'get_lighter_integrator_status',
+          'get_lighter_partner_stats',
+        ],
+        orderManagementActions: [
+          'place_lighter_perps_order',
+          'cancel_lighter_perps_order',
+          'modify_lighter_perps_order',
+          'update_lighter_leverage',
+          'update_lighter_margin',
+          'get_lighter_open_orders',
+        ],
+        setupActions: [
+          'get_lighter_funding_status',
+          'get_lighter_setup_status',
+          'get_lighter_onboarding_plan',
+          'prepare_lighter_onboarding',
+          'complete_lighter_onboarding',
+          'create_lighter_deposit_intent',
+          'setup_lighter_api_key',
+          'create_lighter_api_key',
+          'register_lighter_api_key',
+          'approve_lighter_integrator',
+          'get_bridge_quote',
+          'execute_bridge',
+        ],
+        statusActions: [
+          'get_lighter_funding_status',
+          'get_lighter_setup_status',
+          'get_lighter_integrator_status',
+        ],
+        recoveryActions: [
+          'get_lighter_account',
+          'get_lighter_withdrawal_status',
+          'prepare_lighter_secure_withdrawal',
+        ],
+        decommissionExample:
+          'get_lighter_account -> prepare_lighter_secure_withdrawal -> withdraw-to-user on execution wallet',
+        credentialType: 'lighter_api_key',
+        credentialUx:
+          'Delegated Lighter writes require encrypted lighter_api_key credentials: privateKey, apiKeyIndex (4-254), and accountIndex. Upsert via delegation credentials before place_lighter_perps_order.',
+        recommendedFundingChainId: 8453,
+        supportedFundingSourceChains: [
+          { chainId: 8453, name: 'Base', path: 'native USDC -> CCTP intent -> Lighter margin (recommended)' },
+          { chainId: 42161, name: 'Arbitrum One', path: 'Li.Fi -> Base USDC -> CCTP intent -> Lighter margin' },
+          { chainId: 43114, name: 'Avalanche', path: 'Li.Fi -> Base USDC -> CCTP intent -> Lighter margin' },
+          { chainId: 1, name: 'Ethereum', path: 'Priority changePubKey registration only (chainId 1)' },
+        ],
+        setupBlockers: [
+          'LIGHTER_SOURCE_FUNDS_REQUIRED',
+          'LIGHTER_DEPOSIT_REQUIRED',
+          'LIGHTER_ACCOUNT_NOT_FOUND',
+          'LIGHTER_API_KEY_REGISTRATION_REQUIRED',
+          'LIGHTER_INTEGRATOR_APPROVAL_REQUIRED',
+          'LIGHTER_POLICY_REQUIRED',
+          'LIGHTER_CREDITS_REQUIRED',
+          'LIGHTER_SIGNER_NOT_CONFIGURED',
+        ],
+        setupWarnings: [
+          'LIGHTER_API_KEY_NOT_PROVIDED',
+          'LIGHTER_INTEGRATOR_ACCOUNT_UNFUNDED',
+        ],
+        sourceBridgeProvider: 'lifi',
+        funding:
+          'Run complete_lighter_onboarding on Base (chainId 8453) for automated Li.Fi, CCTP intent, and USDC transfer. API key registration uses an Ethereum priority changePubKey transaction (chainId 1). Minimum CCTP deposit is 5 USDC.',
+        laneCompatibility:
+          'Use agent_wallet for automated complete_lighter_onboarding (CCTP on Base, priority changePubKey on Ethereum). Perps writes use thirdfy, hybrid, or agent_wallet with a stored lighter_api_key credential. Gator covers EVM funding and setup only, not L2 orders.',
+        setupExample:
+          'actions --provider lighter -> complete_lighter_onboarding (chainId 8453, agent_wallet) -> re-run after CCTP credit -> setup_lighter_api_key on chainId 1 when prompted -> credentials upsert lighter_api_key (auto on agent_wallet) -> get_lighter_setup_status -> place_lighter_perps_order',
+        example:
+          'thirdfy-agent actions --provider lighter && thirdfy-agent preflight --action place_lighter_perps_order --params \'{"accountIndex":1,"apiKeyIndex":4,"marketId":0,"baseAmount":100,"price":310000,"isAsk":false,"orderType":"limit"}\'',
+      };
+    }
     if (provider === 'bitfinex') {
       return {
         provider,
@@ -381,6 +471,7 @@ export function createProviderHints({ getNegotiatedCapabilitiesCache }) {
     const canonicalWriteActions = {
       trading: 'swap',
       hyperliquid: 'place_hyperliquid_perps_order',
+      lighter: 'place_lighter_perps_order',
       polymarket: 'place_polymarket_order',
       prediction: 'place_prediction_order',
       earn: 'deposit_earn_position',