@thirdfy/agent-cli 0.2.81 → 0.2.83

package/CHANGELOG.md

@@ -4,6 +4,19 @@ 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
+
+- **`preflight` / `run --run-mode agent_wallet` keep the API's native gas readiness.** On user-pays-gas chains (DogeOS 6281971) Thirdfy API 3.18.2 returns `gasSponsored`, `gasReady`, `nativeGasBalance` and, at 0, `nativeGasWarning` from `/execution-wallet`; the CLI rebuilt the preflight from a fixed field list and dropped them. They now appear under `data.executionWalletPreflight`, and a write whose wallet holds 0 native coin stops before `/execute` with `INSUFFICIENT_NATIVE_GAS` and the faucet message. Sponsored chains and older APIs are unchanged. Pin: `test/preflight-native-gas.test.cjs`.
+- **DogeOS Laika writes check the right funding token.** `dogeos-laika-buy-token` and `dogeos-laika-launch-token` spend native DOGE (`dogeAmountWei`, `initialPurchaseWei`), and `dogeos-laika-claim` receives `tokenAddress`; the CLI sent that bonding-curve token as the execution-wallet `tokenIn` and blocked a buy with `INSUFFICIENT_FUNDS`. They now skip the ERC-20 balance check, as does any action that carries `dogeAmountWei`. `dogeos-laika-sell-token` still checks the token it sells. Pin: `test/funding-token-in.test.cjs`.
+
 ## [0.2.81] - 2026-10-01
 
 ### Added

package/README.md

@@ -40,11 +40,10 @@ Run without global install:
 npx @thirdfy/agent-cli --help
 ```
 
-## What's new in v0.2.81
+## What's new in v0.2.83
 
-- **DogeOS onboarding**: the quickstart starts with `login email`, warns not to use `managed wallet init` for `agent_wallet`, funds gas and test USDC from the DogeOS faucet, starts with a USDC→WDOGE swap, and adds `dogeos-laika-sell-token`. See [docs/dogeos-quickstart.md](./docs/dogeos-quickstart.md).
-- **Chain-aware gas notes**: `help onboarding --chain-id` and `doctor auth --chain-id` say when the sending wallet pays gas (DogeOS) and link the faucet.
-- **`wallet submit --chain-id` works**, reads the chain from the signed transaction when `--chain-id` is omitted, and picks the RPC for that chain. Base keeps its order (`BASE_RPC_URL`, `BASE_RPC_HTTP_URL`, `RPC_URL`); other chains use `--rpc-url`, then `RPC_URL`, then the built-in DogeOS RPC. Self-mode broadcast (`self-exec`) uses the same rule. A Base RPC is never used on DogeOS.
+- **`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.81",
+  "version": "0.2.83",
   "description": "Thirdfy Agent CLI for onboarding, governance preflight, execute-intent, and status polling.",
   "type": "module",
   "bin": {

package/src/core/fundingTokenIn.mjs

@@ -9,6 +9,9 @@ const NATIVE_ETH_SPEND_ACTIONS = new Set([
   'basedbid_create_lbp',
   'basedbid_create_flash',
   'basedbid_create_board',
+  // DogeOS Laika: buys and launches spend native DOGE; tokenAddress is the bonding-curve token received.
+  'dogeos_laika_buy_token',
+  'dogeos_laika_launch_token',
 ]);
 
 /**
@@ -18,6 +21,7 @@ const NATIVE_ETH_SPEND_ACTIONS = new Set([
 const POSITION_EXIT_ACTIONS = new Set([
   'withdraw_earn_position',
   'claim_earn_rewards',
+  'dogeos_laika_claim',
 ]);
 
 export function resolveTokenInForFunding(params, action) {
@@ -28,5 +32,6 @@ export function resolveTokenInForFunding(params, action) {
   if (NATIVE_ETH_SPEND_ACTIONS.has(actionId)) return '';
   if (POSITION_EXIT_ACTIONS.has(actionId)) return '';
   if (params.amountEth != null && String(params.amountEth).trim() !== '') return '';
+  if (params.dogeAmountWei != null && String(params.dogeAmountWei).trim() !== '') return '';
   return String(params.tokenAddress || params.token || '').trim();
 }

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

@@ -0,0 +1,13 @@
+const NATIVE_GAS_FIELDS = ['gasSponsored', 'gasReady', 'nativeGasBalance', 'nativeGasBalanceUnavailable', 'nativeGasWarning'];
+
+/**
+ * Native gas readiness from an `/execution-wallet` reply (Thirdfy API 3.18.2+). Present only on
+ * user-pays-gas chains (DogeOS 6281971); empty for sponsored chains and older APIs.
+ */
+export function pickNativeGasFields(response) {
+  const out = {};
+  for (const key of NATIVE_GAS_FIELDS) {
+    if (response && response[key] !== undefined) out[key] = response[key];
+  }
+  return out;
+}

package/src/runtime/execution/runners.mjs

@@ -1,4 +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 {
@@ -203,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,
@@ -221,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,
     };
@@ -767,21 +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();
@@ -801,6 +846,8 @@ async function resolveManagedExecutionPreflight(ctx, flags, resolved, options =
           executionWalletAddress,
           signerMethod,
           fundingTokenBalance: response?.fundingTokenBalance || null,
+          ...actionFields,
+          ...(executionVenue ? { executionVenue } : {}),
         };
       }
     }
@@ -817,6 +864,8 @@ async function resolveManagedExecutionPreflight(ctx, flags, resolved, options =
       executionWalletAddress,
       signerMethod,
       fundingTokenBalance: response?.fundingTokenBalance || null,
+      ...actionFields,
+      ...(executionVenue ? { executionVenue } : {}),
     };
   }
 
@@ -829,6 +878,27 @@ async function resolveManagedExecutionPreflight(ctx, flags, resolved, options =
       executionWalletAddress,
       signerMethod,
       fundingTokenBalance: response?.fundingTokenBalance || null,
+      ...actionFields,
+      ...(executionVenue ? { executionVenue } : {}),
+    };
+  }
+
+  // User-pays-gas chains (DogeOS): the API reports native gas readiness (API 3.18.2+). Keep it, and
+  // stop a write before /execute when the wallet holds 0 native coin.
+  const nativeGas = pickNativeGasFields(response);
+  if (options.requireFundingCheck && nativeGas.gasReady === false) {
+    return {
+      success: false,
+      blockedReason: 'INSUFFICIENT_NATIVE_GAS',
+      blockedStage: 'sizing',
+      error: nativeGas.nativeGasWarning?.message
+        || `Execution wallet ${executionWalletAddress || 'unknown'} has 0 native gas on chain ${chainId}; gas on this chain is paid by the wallet.`,
+      executionWalletAddress,
+      signerMethod,
+      fundingTokenBalance: response?.fundingTokenBalance || null,
+      ...actionFields,
+      ...(executionVenue ? { executionVenue } : {}),
+      ...nativeGas,
     };
   }
 
@@ -840,6 +910,9 @@ async function resolveManagedExecutionPreflight(ctx, flags, resolved, options =
     userDid,
     chainId,
     tokenIn: tokenIn || null,
+    ...nativeGas,
+    ...actionFields,
+    ...(executionVenue ? { executionVenue } : {}),
   };
 }