@thirdfy/agent-cli 0.2.82 → 0.2.83

package/CHANGELOG.md

@@ -4,6 +4,12 @@ All notable changes to `@thirdfy/agent-cli` are documented here. The format is b
 
 ## Unreleased
 
+## [0.2.83] - 2026-10-08
+
+### Fixed
+
+- **`preflight --run-mode agent_wallet` said `ready` for a venue order the venue could not take.** On production 2026-10-08 (API 3.19.3, CLI 0.2.82) `preflight --action place_hyperliquid_perps_order --run-mode agent_wallet` returned `PREFLIGHT_OK` with `policyEvaluated: false` and `chainId: 8453`, while `venue readiness hyperliquid` returned `HYPERLIQUID_DEPOSIT_REQUIRED`: the preflight sent `/execution-wallet` only `userDid`, `chainId`, `runMode` and `tokenIn`, so the API never saw the action. `preflight` now also sends `action`, `params` and `estimatedAmountUsd`. With Thirdfy API that supports it (capability `commandFeatures.preflightVenueReadiness`), the API checks agent policy, action limits and, for venue orders, venue readiness. A blocked answer (409 `VENUE_NOT_READY`, 403 policy, 429 limits) is `PREFLIGHT_BLOCKED` with `data.status: "blocked"`, `blockedReason`, `blockedStage`, `blockingReasons` and `venueReadiness`, instead of an HTTP error. `data.policyEvaluated` is now always present (false against an older API) and survives a later CLI-local failure (wallet mismatch, funding, native gas), whose `status` stays `failed`; only an API refusal is `blocked`. Venue actions also report `data.executionVenue` (`venue` as the API names it, `brand` for Veranta, `settlement`, `settlementChainId`, `walletLookupChainId`): `chainId` stays the chain the managed wallet was looked up on (Base by default), not where a Hyperliquid, Lighter or Polymarket order runs. `run` and the address-default lookups keep the wallet-only preflight. MCP `walletExecute` has no preflight-only mode and needs no change. Pin: `test/preflight-venue-readiness.test.cjs`.
+
 ## [0.2.82] - 2026-10-01
 
 ### Fixed

package/README.md

@@ -40,10 +40,10 @@ Run without global install:
 npx @thirdfy/agent-cli --help
 ```
 
-## What's new in v0.2.82
+## What's new in v0.2.83
 
-- **`agent_wallet` preflight shows native gas** on chains where the wallet pays gas (DogeOS 6281971): `gasSponsored`, `gasReady`, `nativeGasBalance`, from Thirdfy API 3.18.2. A write from a wallet with 0 native coin stops before `/execute` with `INSUFFICIENT_NATIVE_GAS` and the faucet link.
-- **DogeOS Laika buys pass preflight.** A buy spends native DOGE (`dogeAmountWei`); the CLI no longer checks the balance of the token being bought. Launch and claim are treated the same way, and a sell still checks the token it sells.
+- **`preflight --run-mode agent_wallet` checks the action, not just the wallet.** The CLI sends `action` and `params` to the API, which checks agent policy, limits and venue readiness (Thirdfy API 3.19.4). A venue that is not ready (for example `HYPERLIQUID_DEPOSIT_REQUIRED`) returns `PREFLIGHT_BLOCKED` with `blockingReasons` and `venueReadiness`, matching `venue readiness <venue>`.
+- **`data.policyEvaluated`** is always present, and venue actions report `data.executionVenue` (where the order settles, next to the chain the wallet was looked up on). `run` is unchanged.
 - See [CHANGELOG.md](./CHANGELOG.md) and GitHub Releases for older versions.
 
 ## Quick start

package/package.json

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

package/src/runtime/execution/actionPreflight.mjs

@@ -0,0 +1,93 @@
+import { toLegacyVenueActionKey } from '../../core/venueBrand.mjs';
+import { resolveExecuteEstimatedAmountUsd } from './payloads.mjs';
+
+/**
+ * Action-aware `agent_wallet` preflight (Thirdfy API: `GET /agent/execution-wallet?action=…`).
+ *
+ * Up to 0.2.82 the CLI sent only `userDid`, `chainId`, `runMode` and `tokenIn`, so the API never
+ * saw the action: `preflight --action place_hyperliquid_perps_order --run-mode agent_wallet` said
+ * `ready` with `policyEvaluated: false` while `venue readiness hyperliquid` said
+ * `HYPERLIQUID_DEPOSIT_REQUIRED` (production, 2026-10-08). Sending the action lets the API run
+ * agent policy, action limits and, for venue orders, venue readiness. An API without the feature
+ * ignores the extra query fields and answers `policyEvaluated` absent (reported as false).
+ */
+
+/** Venue an action trades on, and where it settles. Null for actions outside the four venues. */
+const VENUE_SETTLEMENT = Object.freeze({
+  hyperliquid: { venue: 'hyperliquid', settlement: 'hyperliquid_l1', settlementChainId: null },
+  lighter: { venue: 'lighter', settlement: 'lighter_l2', settlementChainId: null },
+  polymarket: { venue: 'polymarket', settlement: 'polygon', settlementChainId: 137 },
+  // `venue` matches the API's stored id; `brand` is the public name.
+  avantis: { venue: 'avantis', brand: 'veranta', settlement: 'base', settlementChainId: 8453 },
+});
+
+export function resolveActionVenue(action) {
+  const key = toLegacyVenueActionKey(action).replace(/-/g, '_');
+  for (const token of Object.keys(VENUE_SETTLEMENT)) {
+    if (new RegExp(`(^|_)${token}(_|$)`).test(key)) return VENUE_SETTLEMENT[token];
+  }
+  return null;
+}
+
+/**
+ * The venue an action executes on, next to the chain the managed wallet was looked up on. The
+ * managed wallet is one EVM address on every chain, so a Hyperliquid order still resolves it on the
+ * default chain; this says the order itself does not run there.
+ */
+export function describeExecutionVenue(action, walletLookupChainId) {
+  const venue = resolveActionVenue(action);
+  if (!venue) return null;
+  return { ...venue, walletLookupChainId: Number(walletLookupChainId) || null };
+}
+
+/** Adds `action`, `params` and `estimatedAmountUsd` to an `/execution-wallet` query. */
+export function appendActionPreflightQuery(query, { action, params, flags }) {
+  const actionId = String(action || '').trim();
+  if (!actionId) return query;
+  query.set('action', actionId);
+  if (params && typeof params === 'object' && !Array.isArray(params) && Object.keys(params).length) {
+    query.set('params', JSON.stringify(params));
+  }
+  const estimatedAmountUsd = resolveExecuteEstimatedAmountUsd(actionId, flags);
+  if (estimatedAmountUsd != null) query.set('estimatedAmountUsd', String(estimatedAmountUsd));
+  return query;
+}
+
+/** Venue fields an action preflight carries onto the CLI envelope. */
+export const ACTION_PREFLIGHT_VENUE_FIELDS = Object.freeze(['venue', 'venueReadiness', 'blockingReasons']);
+
+/** Stages at which the API refused the action itself (as opposed to a CLI-local check). */
+const API_BLOCK_STAGES = new Set(['catalog', 'policy', 'venue_readiness']);
+
+/** True when the API blocked the action (policy, catalog, venue readiness). */
+export function isApiActionBlock(preflight) {
+  return preflight?.success === false && API_BLOCK_STAGES.has(String(preflight?.blockedStage || ''));
+}
+
+/** Policy and venue fields of an action-aware `/execution-wallet` answer (allowed or blocked). */
+export function pickActionPreflightFields(response) {
+  const out = { policyEvaluated: response?.policyEvaluated === true };
+  for (const key of [...ACTION_PREFLIGHT_VENUE_FIELDS, 'actionPreflight']) {
+    if (response?.[key] != null) out[key] = response[key];
+  }
+  return out;
+}
+
+/**
+ * A blocked action preflight arrives as a non-2xx answer (409 `VENUE_NOT_READY`, 403 policy, 429
+ * limits) with `preflightBlocked: true`. Turn it into a blocked preflight result; null otherwise.
+ */
+export function blockedActionPreflightFromError(error) {
+  const payload = error?.payload;
+  if (!payload || typeof payload !== 'object' || payload.preflightBlocked !== true) return null;
+  return {
+    success: false,
+    blockedReason: String(payload.blockedReason || 'PREFLIGHT_BLOCKED'),
+    blockedStage: String(payload.blockedStage || 'policy'),
+    error: String(payload.error || payload.message || error?.message || 'Preflight blocked'),
+    statusCode: Number(error?.statusCode) || null,
+    signerMethod: payload.signerMethod || 'managed_wallet_server',
+    ...pickActionPreflightFields(payload),
+    ...(payload.data ? { data: payload.data } : {}),
+  };
+}

package/src/runtime/execution/runners.mjs

@@ -1,5 +1,13 @@
 import { randomUUID } from 'crypto';
 import { pickNativeGasFields } from './nativeGas.mjs';
+import {
+  ACTION_PREFLIGHT_VENUE_FIELDS,
+  appendActionPreflightQuery,
+  blockedActionPreflightFromError,
+  describeExecutionVenue,
+  isApiActionBlock,
+  pickActionPreflightFields,
+} from './actionPreflight.mjs';
 import { requireFlag } from '../../core/args.mjs';
 import { createCliError } from '../../core/envelope.mjs';
 import {
@@ -204,6 +212,8 @@ async function runPreflightByMode(runMode, ctx, flags, resolved, options = {}) {
       // Reads carry no transaction; keep funding optional so preflight matches run.
       requireFundingCheck: !isReadOnlyAction(resolved),
       preflightSeed: options.managedPreflight,
+      // Ask the API to check policy and venue readiness for this action, not just the wallet.
+      evaluateAction: true,
     });
     const normalized = normalizeIntentResponse({
       success: preflight.success,
@@ -222,8 +232,21 @@ async function runPreflightByMode(runMode, ctx, flags, resolved, options = {}) {
     normalized.signerMethod = preflight.signerMethod || 'managed_wallet_server';
     normalized.executionWalletPreflight = preflight;
     normalized.fundingTokenBalance = preflight.fundingTokenBalance || null;
+    normalized.policyEvaluated = preflight.policyEvaluated === true;
+    for (const key of [...ACTION_PREFLIGHT_VENUE_FIELDS, 'executionVenue']) {
+      if (preflight[key] != null) normalized[key] = preflight[key];
+    }
+    // Only an API refusal of the action is `blocked`; CLI-local checks keep `failed`.
+    const apiBlocked = isApiActionBlock(preflight);
+    if (apiBlocked) normalized.status = 'blocked';
     return {
-      message: preflight.success ? 'Managed wallet preflight completed' : 'Managed wallet preflight failed',
+      message: preflight.success
+        ? 'Managed wallet preflight completed'
+        : preflight.blockedStage === 'venue_readiness'
+          ? 'Managed wallet preflight blocked: venue not ready'
+          : apiBlocked
+            ? 'Managed wallet preflight blocked by policy'
+            : 'Managed wallet preflight failed',
       route: 'execution_wallet_preflight',
       normalized,
     };
@@ -768,22 +791,42 @@ async function resolveManagedExecutionPreflight(ctx, flags, resolved, options =
     runMode,
   });
   if (tokenIn) query.set('tokenIn', tokenIn);
+  const evaluateAction = options.evaluateAction === true;
+  if (evaluateAction) appendActionPreflightQuery(query, { action, params, flags });
+  const executionVenue = describeExecutionVenue(action, chainId);
   const preflightSeed = options.preflightSeed && typeof options.preflightSeed === 'object'
     ? options.preflightSeed
     : null;
   if (preflightSeed && preflightSeed.success === false) {
     return preflightSeed;
   }
-  const response = preflightSeed
-    ? {
+  // A seed (address default lookup) carries no policy answer; an action preflight asks the API again.
+  const useSeed = Boolean(preflightSeed) && !evaluateAction;
+  let response;
+  if (useSeed) {
+    response = {
       executionWalletAddress: preflightSeed.executionWalletAddress || null,
       signerMethod: preflightSeed.signerMethod || null,
       fundingTokenBalance: preflightSeed.fundingTokenBalance || null,
       ...pickNativeGasFields(preflightSeed),
+    };
+  } else {
+    try {
+      response = await apiGet(ctx, `/api/v1/agent/execution-wallet?${query.toString()}`, {
+        'x-agent-api-key': agentApiKey,
+      });
+    } catch (error) {
+      const blocked = evaluateAction ? blockedActionPreflightFromError(error) : null;
+      if (!blocked) throw error;
+      return {
+        ...blocked,
+        userDid,
+        chainId,
+        ...(executionVenue ? { executionVenue } : {}),
+      };
     }
-    : await apiGet(ctx, `/api/v1/agent/execution-wallet?${query.toString()}`, {
-      'x-agent-api-key': agentApiKey,
-    });
+  }
+  const actionFields = evaluateAction ? pickActionPreflightFields(response) : {};
   const executionWalletAddress = String(response?.executionWalletAddress || '').trim().toLowerCase();
   const signerMethod = String(response?.signerMethod || 'managed_wallet_server').trim();
   const rawBalance = String(response?.fundingTokenBalance?.raw || '').trim();
@@ -803,6 +846,8 @@ async function resolveManagedExecutionPreflight(ctx, flags, resolved, options =
           executionWalletAddress,
           signerMethod,
           fundingTokenBalance: response?.fundingTokenBalance || null,
+          ...actionFields,
+          ...(executionVenue ? { executionVenue } : {}),
         };
       }
     }
@@ -819,6 +864,8 @@ async function resolveManagedExecutionPreflight(ctx, flags, resolved, options =
       executionWalletAddress,
       signerMethod,
       fundingTokenBalance: response?.fundingTokenBalance || null,
+      ...actionFields,
+      ...(executionVenue ? { executionVenue } : {}),
     };
   }
 
@@ -831,6 +878,8 @@ async function resolveManagedExecutionPreflight(ctx, flags, resolved, options =
       executionWalletAddress,
       signerMethod,
       fundingTokenBalance: response?.fundingTokenBalance || null,
+      ...actionFields,
+      ...(executionVenue ? { executionVenue } : {}),
     };
   }
 
@@ -847,6 +896,8 @@ async function resolveManagedExecutionPreflight(ctx, flags, resolved, options =
       executionWalletAddress,
       signerMethod,
       fundingTokenBalance: response?.fundingTokenBalance || null,
+      ...actionFields,
+      ...(executionVenue ? { executionVenue } : {}),
       ...nativeGas,
     };
   }
@@ -860,6 +911,8 @@ async function resolveManagedExecutionPreflight(ctx, flags, resolved, options =
     chainId,
     tokenIn: tokenIn || null,
     ...nativeGas,
+    ...actionFields,
+    ...(executionVenue ? { executionVenue } : {}),
   };
 }