@thirdfy/agent-cli 0.3.0 → 0.4.1

package/src/core/chainRegistry.mjs

@@ -1,12 +1,29 @@
 // Chain facts the CLI needs locally: a public RPC for BYOW submit / balance reads, and
-// whether network gas is paid by the sending wallet (no sponsorship on that chain).
+// whether network gas is paid by the sending wallet (no sponsorship on that chain: DogeOS). Thirdfy
+// sponsors Solana network fees; the wallet pays only rent for new token accounts (`chainGasNote`).
 // The API capabilities document stays the source of truth for lane support.
 
 export const DEFAULT_CHAIN_ID = 8453;
 
 // Only chains whose RPC we have verified. Other chains need --rpc-url or RPC_URL.
+// `chainFamily` defaults to 'evm'. Solana (svm) rows have no rpcUrl: the CLI never signs or
+// broadcasts Solana itself; Solana actions run only on the managed agent_wallet lane.
 export const CHAIN_REGISTRY = {
   8453: { chainKey: 'base-mainnet', displayName: 'Base', rpcUrl: 'https://mainnet.base.org', nativeSymbol: 'ETH' },
+  101: {
+    chainKey: 'sol-mainnet',
+    displayName: 'Solana',
+    chainFamily: 'svm',
+    caip2: 'solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp',
+    nativeSymbol: 'SOL',
+  },
+  103: {
+    chainKey: 'sol-devnet',
+    displayName: 'Solana devnet',
+    chainFamily: 'svm',
+    caip2: 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1',
+    nativeSymbol: 'SOL',
+  },
   6281971: {
     chainKey: 'dogeos-testnet',
     displayName: 'DogeOS Chikyu testnet',
@@ -28,6 +45,171 @@ export function getChainInfo(chainId) {
   return id ? CHAIN_REGISTRY[id] || null : null;
 }
 
+/**
+ * The chains the Thirdfy API executes on, from `chains` in `GET /api/v1/agent/cli/capabilities`
+ * (`{ chainId, chainFamily, caip2, supportedExecutionLanes }`), as thirdfy-mcp
+ * `src/config/chainRegistry.ts` reads them. Applied when the CLI negotiates capabilities (no extra
+ * request). Until then, or when the API sends no usable list, the defaults below apply.
+ */
+
+/** Fallback chain ids when the API sends no chain list (thirdfy-mcp's defaults). */
+export const DEFAULT_EVM_CHAIN_IDS = Object.freeze([8453, 1, 100, 137, 130, 10, 11155420, 42161, 84532, 10200, 480, 4801, 6281971, 4663, 5042002, 5042]);
+export const DEFAULT_SVM_CHAIN_IDS = Object.freeze([101, 103]);
+
+let apiChainRegistry;
+
+const CAIP2 = /^[-a-z0-9]{3,8}:[-_a-zA-Z0-9]{1,64}$/;
+
+/**
+ * `chainFamily` when the API sends it, else from `caip2` or `tags`, else the built-in table's family
+ * (so an entry for 101 with no family info stays Solana), else EVM.
+ */
+function apiChainFamily(entry, chainId) {
+  const family = String(entry.chainFamily ?? '').toLowerCase();
+  if (family === 'svm' || family === 'evm') return family;
+  const caip2 = typeof entry.caip2 === 'string' ? entry.caip2 : '';
+  if (caip2.startsWith('solana:')) return 'svm';
+  if (caip2.startsWith('eip155:')) return 'evm';
+  const tags = Array.isArray(entry.tags) ? entry.tags.map((tag) => String(tag).toLowerCase()) : [];
+  if (tags.includes('svm') || tags.includes('solana')) return 'svm';
+  return CHAIN_REGISTRY[chainId]?.chainFamily || 'evm';
+}
+
+/**
+ * Parse the capabilities `chains` list. Undefined for anything without a usable EVM chain: a list
+ * the CLI could not run on keeps the defaults rather than refusing every chain.
+ */
+export function parseApiChains(chains) {
+  if (!Array.isArray(chains)) return undefined;
+  const evm = new Set();
+  const svm = new Set();
+  const caip2ByChainId = {};
+  const entries = [];
+  for (const entry of chains) {
+    if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue;
+    const chainId = Number(entry.chainId);
+    if (!Number.isInteger(chainId) || chainId <= 0) continue;
+    const chainFamily = apiChainFamily(entry, chainId);
+    (chainFamily === 'svm' ? svm : evm).add(chainId);
+    const caip2 = typeof entry.caip2 === 'string' && CAIP2.test(entry.caip2) ? entry.caip2 : undefined;
+    if (caip2) caip2ByChainId[chainId] = caip2;
+    entries.push({
+      chainId,
+      chainFamily,
+      ...(caip2 ? { caip2 } : {}),
+      ...(entry.chainKey ? { chainKey: String(entry.chainKey) } : {}),
+      ...(entry.displayName ? { displayName: String(entry.displayName) } : {}),
+      ...(Array.isArray(entry.supportedExecutionLanes) ? { supportedExecutionLanes: entry.supportedExecutionLanes.map(String) } : {}),
+    });
+  }
+  if (evm.size === 0) return undefined;
+  return { evmChainIds: [...evm], svmChainIds: [...svm], caip2ByChainId, chains: entries };
+}
+
+/** Apply a capabilities body's `chains`. A body without a usable list leaves the last one in place. */
+export function applyApiChainRegistry(capabilities) {
+  const parsed = parseApiChains(capabilities && typeof capabilities === 'object' ? capabilities.chains : undefined);
+  if (!parsed) return false;
+  apiChainRegistry = parsed;
+  return true;
+}
+
+/** The last chain list the API sent, or undefined before the first usable one. */
+export function getApiChainRegistry() {
+  return apiChainRegistry;
+}
+
+export function resetApiChainRegistry() {
+  apiChainRegistry = undefined;
+}
+
+/** Where the chain ids come from: the API's capabilities, or the defaults. */
+export function chainRegistrySource() {
+  return apiChainRegistry ? 'api' : 'default';
+}
+
+/** EVM chain ids the API runs (the defaults until it says). */
+export function configuredEvmChainIds() {
+  return apiChainRegistry ? apiChainRegistry.evmChainIds.slice() : [...DEFAULT_EVM_CHAIN_IDS];
+}
+
+/** Solana chain ids the API runs: none on an API without Solana (the defaults until it says). */
+export function configuredSvmChainIds() {
+  return apiChainRegistry ? apiChainRegistry.svmChainIds.slice() : [...DEFAULT_SVM_CHAIN_IDS];
+}
+
+/** The CAIP-2 id the API reports for a chain, else the built-in one, else `eip155:<id>` for EVM. */
+export function caip2ForChainId(chainId) {
+  const id = positiveChainId(chainId);
+  if (!id) return undefined;
+  return apiChainRegistry?.caip2ByChainId[id] || getChainInfo(id)?.caip2 || (chainFamilyOf(id) === 'evm' ? `eip155:${id}` : undefined);
+}
+
+/**
+ * 'svm' for Solana chains, 'evm' for every other chain id (known or not). The API's chain list
+ * decides when it names the chain; the built-in table is the fallback.
+ */
+export function chainFamilyOf(chainId) {
+  const id = positiveChainId(chainId);
+  if (id && apiChainRegistry) {
+    if (apiChainRegistry.svmChainIds.includes(id)) return 'svm';
+    if (apiChainRegistry.evmChainIds.includes(id)) return 'evm';
+  }
+  return getChainInfo(chainId)?.chainFamily || 'evm';
+}
+
+/**
+ * Why the API does not run a Solana chain, or undefined when it does (or the list is unknown):
+ * `SOLANA_NOT_ENABLED` when it lists no svm chain at all (thirdfy-mcp `unsupportedChainFields`),
+ * `CHAIN_NOT_SUPPORTED` when it runs Solana but not this chain id.
+ */
+export function svmChainRefusal(chainId) {
+  const id = positiveChainId(chainId);
+  if (!id || !apiChainRegistry || chainFamilyOf(id) !== 'svm' || apiChainRegistry.svmChainIds.includes(id)) return undefined;
+  return apiChainRegistry.svmChainIds.length === 0 ? 'SOLANA_NOT_ENABLED' : 'CHAIN_NOT_SUPPORTED';
+}
+
+/** True for Solana chain ids (101 mainnet, 103 devnet). */
+export function isSvmChainId(chainId) {
+  return chainFamilyOf(chainId) === 'svm';
+}
+
+const EVM_ADDRESS_RE = /^0x[a-fA-F0-9]{40}$/;
+// Base58 (no 0, O, I, l), 32-44 chars: a Solana public key.
+const SOLANA_ADDRESS_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
+
+export function isEvmAddress(value) {
+  return EVM_ADDRESS_RE.test(String(value || '').trim());
+}
+
+export function isSolanaAddress(value) {
+  return SOLANA_ADDRESS_RE.test(String(value || '').trim());
+}
+
+/**
+ * Wallet address equality. 0x addresses are hex and compare case-insensitively; anything else
+ * (Solana base58) is case-sensitive and must match exactly. Never lowercase a base58 address.
+ */
+export function sameWalletAddress(a, b) {
+  const left = String(a || '').trim();
+  const right = String(b || '').trim();
+  if (!left || !right) return false;
+  if (/^0x/i.test(left) && /^0x/i.test(right)) return left.toLowerCase() === right.toLowerCase();
+  return left === right;
+}
+
+/**
+ * Text for a wallet that cannot pay network gas, when the API sent no nativeGasWarning message.
+ */
+export function describeInsufficientNativeGas(walletAddress, chainId) {
+  const info = getChainInfo(chainId);
+  const wallet = walletAddress || 'unknown';
+  if (info?.chainFamily === 'svm') {
+    return `Execution wallet ${wallet} does not hold enough SOL for this write on ${info.displayName} (${positiveChainId(chainId)}). Thirdfy sponsors network fees; the wallet pays rent for new token accounts (about 0.002 SOL each) and any SOL the action spends. Fund it with a little SOL.`;
+  }
+  return `Execution wallet ${wallet} has 0 native gas on chain ${chainId}; gas on this chain is paid by the wallet.`;
+}
+
 /** Chains where the sending wallet pays network gas in the native token (never sponsored). */
 export function chainUserPaysGas(chainId) {
   return Boolean(getChainInfo(chainId)?.userPaysGas);
@@ -43,6 +225,7 @@ export const USER_PAYS_GAS_CHAIN_IDS = Object.entries(CHAIN_REGISTRY)
  */
 export function describeChainGas(chainId) {
   const info = getChainInfo(chainId);
+  if (info?.chainFamily === 'svm') return chainGasNote(chainId).note;
   if (info?.userPaysGas) {
     const faucet = info.faucetUrl ? ` Fund it from ${info.faucetUrl}.` : '';
     return `Network gas on ${info.displayName} (${positiveChainId(chainId)}) is paid in native ${info.nativeSymbol} by the sending wallet; it is not sponsored.${faucet}`;
@@ -51,6 +234,45 @@ export function describeChainGas(chainId) {
   return `Network gas may be sponsored on supported chains, but Thirdfy credits/free-quota gates still apply. On user-pays chains (${userPays}) the sending wallet pays gas in the native token.`;
 }
 
+function userPaysGasNote(info) {
+  return {
+    sponsored: false,
+    payer: 'sending_wallet',
+    nativeToken: info.nativeSymbol,
+    ...(info.faucetUrl ? { faucet: info.faucetUrl } : {}),
+    note: `${info.displayName} gas is not sponsored: fund the execution wallet with native ${info.nativeSymbol}${
+      info.faucetUrl ? ` (faucet: ${info.faucetUrl})` : ''
+    } before writes.`,
+  };
+}
+
+/**
+ * The gas note for a chain whose gas needs a word, as thirdfy-mcp `chainGasNote`
+ * (`src/config/chainGas.ts`): a chain whose sending wallet pays gas (DogeOS), or Solana, whose
+ * network fees Thirdfy sponsors unless the API's preflight answered `gasSponsored: false` (new token
+ * accounts still cost the wallet rent). Undefined for a sponsored EVM chain.
+ */
+export function chainGasNote(chainId, { gasSponsored } = {}) {
+  const info = getChainInfo(chainId);
+  if (!info) return undefined;
+  if (info.chainFamily !== 'svm') return info.userPaysGas ? userPaysGasNote(info) : undefined;
+  if (gasSponsored === false) {
+    return {
+      ...userPaysGasNote(info),
+      rentPayer: 'execution_wallet',
+      note: `${info.displayName} network fees are not sponsored right now: the execution wallet pays fees and rent in SOL. Fund it with a little SOL (about 0.003) before writes.`,
+    };
+  }
+  return {
+    sponsored: true,
+    payer: 'thirdfy',
+    nativeToken: info.nativeSymbol,
+    ...(info.faucetUrl ? { faucet: info.faucetUrl } : {}),
+    rentPayer: 'execution_wallet',
+    note: `Thirdfy sponsors ${info.displayName} network fees: do not ask the user to buy SOL for gas. Fund the wallet with the token the action spends. SOL is needed only for rent when an action opens a new token account (about 0.002 SOL each) and for SOL the action itself spends; a write short of it is refused with INSUFFICIENT_NATIVE_GAS, and only then ask for SOL.`,
+  };
+}
+
 /**
  * RPC for a chain. The --rpc-url flag always wins. Then:
  * - Base (or no chain given): BASE_RPC_URL, BASE_RPC_HTTP_URL, RPC_URL, then the registry.

package/src/core/context.mjs

@@ -120,26 +120,69 @@ export function extractActions(response) {
   return [];
 }
 
-export async function getCachedActionsCatalog(ctx, flags) {
-  const policyAware = Boolean(flags.agentApiKey);
-  const cacheKey = policyAware
-    ? `policy:${ctx.apiBase}:${String(flags.agentApiKey)}`
-    : `public:${ctx.apiBase}`;
+/**
+ * The agent API key from `--agent-api-key`, then THIRDFY_AGENT_API_KEY, then config `agent.apiKey`;
+ * empty when none is set. The same order execution uses, without its missing-key error.
+ */
+export function findAgentApiKey(flags = {}) {
+  const explicit = String(flags.agentApiKey || '').trim();
+  if (explicit) return explicit;
+  const envKey = String(process.env.THIRDFY_AGENT_API_KEY || '').trim();
+  if (envKey) return envKey;
+  return String(loadProfileConfig()?.agent?.apiKey || '').trim();
+}
+
+/**
+ * Whose credits a credits read is about. Same precedence as `wallet profile`: an owner credential
+ * passed as a flag (--owner-session-token or --auth-token), then an explicit --agent-api-key, then
+ * owner auth from env or config, then an agent key from env or config. Returns `{ ledger, agentApiKey,
+ * agentApiKeyExplicit }`; `ledger` is `agent` or `owner`.
+ */
+export function resolveCreditsLedger(flags = {}) {
+  const config = loadProfileConfig();
+  const explicitOwner = Boolean(String(flags.ownerSessionToken || flags.authToken || '').trim());
+  const agentApiKeyExplicit = Boolean(String(flags.agentApiKey || '').trim());
+  const storedOwner = Boolean(
+    String(
+      process.env.THIRDFY_OWNER_SESSION_TOKEN || process.env.THIRDFY_AUTH_TOKEN || config?.auth?.ownerSessionToken || config?.auth?.authToken || '',
+    ).trim(),
+  );
+  const agentApiKey = findAgentApiKey(flags);
+  const agent = !explicitOwner && (agentApiKeyExplicit || (!storedOwner && Boolean(agentApiKey)));
+  return { ledger: agent ? 'agent' : 'owner', agentApiKey, agentApiKeyExplicit };
+}
+
+/**
+ * The actions list for this caller, cached per API base and key: the agent's own list
+ * (`GET /api/v1/agent/actions`) whenever an agent key is set (flag, env or config, `findAgentApiKey`),
+ * else the public catalog. Every caller (`actions`, the params gate, `doctor`) gets the same list,
+ * the one execution is checked against. `keyed` says a key was sent; `policyScoped` says the API
+ * answered with the policy's allowlist (an unrestricted key gets the whole catalog without it).
+ */
+export async function getCachedActionsCatalogSnapshot(ctx, flags = {}) {
+  const agentApiKey = findAgentApiKey(flags);
+  const keyed = Boolean(agentApiKey);
+  const cacheKey = keyed ? `policy:${ctx.apiBase}:${agentApiKey}` : `public:${ctx.apiBase}`;
   const ttlMs = getCachedActionsCatalogTtlMs();
   const now = Date.now();
   const hit = catalogCache.get(cacheKey);
   if (hit && hit.expiresAt > now) {
-    return hit.actions;
+    return hit.snapshot;
   }
   // The agent key goes in the `x-agent-api-key` header, never the URL: URLs land in access logs and
   // proxies, and API 3.15 answers a URL key with Deprecation headers.
-  const response = policyAware
-    ? await apiGet(ctx, '/api/v1/agent/actions', { 'x-agent-api-key': String(flags.agentApiKey) })
+  const response = keyed
+    ? await apiGet(ctx, '/api/v1/agent/actions', { 'x-agent-api-key': agentApiKey })
     : await apiGet(ctx, '/api/v1/agent/actions/catalog');
-  const actions = extractActions(response);
-  catalogCache.set(cacheKey, {
-    actions,
-    expiresAt: now + ttlMs,
-  });
-  return actions;
+  const snapshot = {
+    actions: extractActions(response),
+    keyed,
+    policyScoped: keyed && (response?.policyScoped === true || response?.data?.policyScoped === true),
+  };
+  catalogCache.set(cacheKey, { snapshot, expiresAt: now + ttlMs });
+  return snapshot;
+}
+
+export async function getCachedActionsCatalog(ctx, flags) {
+  return (await getCachedActionsCatalogSnapshot(ctx, flags)).actions;
 }

package/src/core/errorEnvelope.mjs

@@ -0,0 +1,209 @@
+/**
+ * One set of error fields for every CLI failure, the same as thirdfy-mcp's tool error envelope
+ * (`src/mcp/errors/toolErrorEnvelope.ts`, `src/wallet/creditsRefusal.ts`), so an agent reads the
+ * same answer from the CLI and the MCP: what went wrong (`errorCode`), whether the same call can
+ * succeed later (`retryable`, `retryAfterSeconds`), and what to do (`nextAction`, `hint`).
+ *
+ * The fields are added next to the CLI's existing error fields; nothing is renamed or removed.
+ */
+
+/** Every `nextAction` the CLI sends, and what the caller should do. */
+export const NEXT_ACTIONS = Object.freeze({
+  retry_later: 'Nothing changed. Repeat the same call later (after retryAfterSeconds when given).',
+  fix_request: 'The request was refused as sent. Change the arguments before trying again.',
+  check_credentials: 'The API key or token was refused. Check the agent API key or log in again.',
+  check_permissions: 'The credential is valid but may not do this. Ask the owner for the permission.',
+  add_credits: "The agent's credits, today's free requests and the owner's credits are used. Check `credits balance`, buy with `credits buy`; do not retry until credits are added.",
+  contact_support: 'Thirdfy failed in a way a retry will not fix. Contact Thirdfy support.',
+  reread_state_before_retry:
+    'A write may have executed. Re-read positions, orders or balances before sending it again.',
+  fund_native_gas: "The execution wallet cannot pay this chain's gas. Fund it with the native coin first.",
+  owner_reenable_agent_signer: "The wallet owner removed Thirdfy's signer. The owner must re-enable the agent.",
+  use_evm_chain: 'This Thirdfy API does not run that chain family (Solana). Use an EVM chain the API lists in `chains`.',
+});
+
+/** Credits refusal codes the API sends (HTTP 402). */
+export const CREDITS_REFUSAL_CODES = new Set(['DAILY_FREE_LIMIT_EXCEEDED', 'INSUFFICIENT_CREDITS', 'CREDITS_EXHAUSTED']);
+
+export const CREDITS_REFUSAL_HINT =
+  "Nothing ran: the agent's credits, today's free requests and the owner's credits are all used for this action. Show the balance with `thirdfy-agent credits balance`; free requests reset each UTC day. Buy credits with USDC from the agent's wallet: `thirdfy-agent credits buy --usd <whole dollars>`. Do not retry until credits are added.";
+
+export const CREDITS_CLAIM_PENDING_HINT =
+  'The credits payment may have been sent but its claim did not finish. Check `thirdfy-agent credits balance` before anything else, and do not buy again.';
+
+/** An error code: upper-case words joined by underscores (`AGENT_SIGNER_REMOVED_BY_OWNER`). */
+const ERROR_CODE = /^[A-Z][A-Z0-9_]{2,63}$/;
+/** A next-action token (`retry_later`); API prose goes to `hint` instead. */
+const NEXT_ACTION_TOKEN = /^[a-z][a-z0-9_]{1,63}$/;
+const RETRYABLE_STATUSES = new Set([408, 425, 429, 500, 502, 503, 504]);
+
+const STATUS_CODES = Object.freeze({
+  400: 'BAD_REQUEST',
+  401: 'UNAUTHORIZED',
+  402: 'PAYMENT_REQUIRED',
+  403: 'FORBIDDEN',
+  404: 'NOT_FOUND',
+  408: 'UPSTREAM_TIMEOUT',
+  409: 'CONFLICT',
+  422: 'UNPROCESSABLE',
+  429: 'RATE_LIMITED',
+});
+
+/** CLI-side refusals whose next step is not "fix the request". */
+const CLIENT_CODE_FIELDS = Object.freeze({
+  TIMEOUT: { retryable: true, nextAction: 'retry_later' },
+  INSUFFICIENT_NATIVE_GAS: { retryable: false, nextAction: 'fund_native_gas' },
+  SOLANA_NOT_ENABLED: { retryable: false, nextAction: 'use_evm_chain' },
+  BROADCAST_FAILED: { retryable: false, nextAction: 'reread_state_before_retry' },
+  EFFECT_CHECK_FAILED: { retryable: false, nextAction: 'reread_state_before_retry' },
+});
+
+const isRecord = (value) => Boolean(value && typeof value === 'object' && !Array.isArray(value));
+
+const firstString = (...values) => {
+  const found = values.find((value) => typeof value === 'string' && value.trim() !== '');
+  return found ? found.trim() : undefined;
+};
+
+function codeForStatus(status) {
+  if (STATUS_CODES[status]) return STATUS_CODES[status];
+  if (status >= 500) return 'UPSTREAM_ERROR';
+  if (status >= 400) return 'REQUEST_REFUSED';
+  return 'UNKNOWN_ERROR';
+}
+
+function nextActionFor(code, status, retryable) {
+  if (retryable) return 'retry_later';
+  if (status === 402 || CREDITS_REFUSAL_CODES.has(code)) return 'add_credits';
+  if (status === 401 || code === 'UNAUTHORIZED') return 'check_credentials';
+  if (status === 403) return 'check_permissions';
+  if (status >= 400 && status < 500) return 'fix_request';
+  return 'contact_support';
+}
+
+function positiveSeconds(value) {
+  const seconds = Number(value);
+  return Number.isFinite(seconds) && seconds > 0 ? Math.ceil(seconds) : undefined;
+}
+
+/** fetch aborted by the request timer (src/core/http.mjs uses an AbortController). */
+function isTimeout(error) {
+  return error?.name === 'AbortError' || error?.name === 'TimeoutError';
+}
+
+/** fetch could not reach the API (DNS, refused, reset): `TypeError: fetch failed` with a cause. */
+function isUnreachable(error) {
+  return error?.name === 'TypeError' && (String(error?.message || '') === 'fetch failed' || error?.cause != null);
+}
+
+/** The body and the bodies nested under its `data`, outermost first. */
+function nestedBodies(body) {
+  const bodies = [];
+  let current = body;
+  for (let depth = 0; depth < 4 && isRecord(current); depth += 1) {
+    bodies.push(current);
+    current = current.data;
+  }
+  return bodies;
+}
+
+/** The credits refusal code a body carries (`errorCode`, `error`, `blockedReason`, at any depth), if any. */
+export function creditsRefusalCode(body) {
+  for (const entry of nestedBodies(body)) {
+    for (const value of [entry.errorCode, entry.error, entry.blockedReason]) {
+      if (typeof value === 'string' && CREDITS_REFUSAL_CODES.has(value)) return value;
+    }
+  }
+  return undefined;
+}
+
+function isCreditsClaimPending(body) {
+  return nestedBodies(body).some((entry) =>
+    [entry.error, entry.errorCode, entry.blockedReason].some(
+      (value) => typeof value === 'string' && value.includes('CREDITS_CLAIM_PENDING'),
+    ),
+  );
+}
+
+function withoutUndefined(fields) {
+  return Object.fromEntries(Object.entries(fields).filter(([, value]) => value !== undefined));
+}
+
+/**
+ * `{ errorCode, retryable, retryAfterSeconds?, nextAction, hint? }` for a thrown CLI error.
+ * It reads what `src/core/http.mjs` attaches (`statusCode`, `payload`, `write`, `retryAfterSeconds`)
+ * and what `createCliError` attaches (`payload.error`, `payload.blockedStage`).
+ */
+export function describeCliError(error) {
+  const payload = isRecord(error?.payload) ? error.payload : {};
+  const status = Number(error?.statusCode || 0);
+  const data = isRecord(payload.data) ? payload.data : {};
+
+  // A write that timed out or whose claim did not finish: it may have landed.
+  const unknownOutcome =
+    error?.code === 'WRITE_OUTCOME_UNKNOWN' ||
+    [payload.error, payload.errorCode].some((value) => typeof value === 'string' && value.startsWith('WRITE_OUTCOME_UNKNOWN'));
+  if (unknownOutcome) {
+    return withoutUndefined({
+      errorCode: 'WRITE_OUTCOME_UNKNOWN',
+      retryable: false,
+      nextAction: 'reread_state_before_retry',
+      hint: isCreditsClaimPending(payload) ? CREDITS_CLAIM_PENDING_HINT : undefined,
+    });
+  }
+
+  if (status) {
+    // The specific refusal (`blockedReason`) wins over a generic upper-case `error`.
+    const apiCode = [payload.blockedReason, data.blockedReason, payload.errorCode, payload.error, payload.code, data.error].find(
+      (value) => typeof value === 'string' && ERROR_CODE.test(value),
+    );
+    const code = apiCode || creditsRefusalCode(payload) || codeForStatus(status);
+    const credits = status === 402 || CREDITS_REFUSAL_CODES.has(code);
+    // A 5xx on a write may have landed, unless the API named a deliberate refusal code.
+    const mayHaveLanded = error?.write === true && status >= 500 && !apiCode;
+    const retryable = mayHaveLanded ? false : RETRYABLE_STATUSES.has(status);
+    const after = retryable
+      ? positiveSeconds(error?.retryAfterSeconds) ?? positiveSeconds(payload.retryAfterSeconds) ?? positiveSeconds(data.retryAfterSeconds)
+      : undefined;
+    const apiNextAction = firstString(payload.nextAction, data.nextAction);
+    const nextActionToken = apiNextAction && NEXT_ACTION_TOKEN.test(apiNextAction) ? apiNextAction : undefined;
+    const hint =
+      firstString(payload.hint, data.hint, payload.userMessage, data.userMessage, nextActionToken ? undefined : apiNextAction) ||
+      (credits ? CREDITS_REFUSAL_HINT : undefined);
+    return withoutUndefined({
+      errorCode: code,
+      retryable,
+      retryAfterSeconds: after,
+      nextAction: mayHaveLanded ? 'reread_state_before_retry' : nextActionToken || nextActionFor(code, status, retryable),
+      hint,
+    });
+  }
+
+  // The API never answered (the request was retried once already).
+  if (!Object.keys(payload).length && (isTimeout(error) || isUnreachable(error))) {
+    return isTimeout(error)
+      ? { errorCode: 'UPSTREAM_TIMEOUT', retryable: true, nextAction: 'retry_later' }
+      : { errorCode: 'UPSTREAM_UNREACHABLE', retryable: true, nextAction: 'retry_later' };
+  }
+
+  // A missing or malformed flag (requireFlag, parseJsonFlag in src/core/args.mjs).
+  if (error?.usage === true) return { errorCode: 'INVALID_ARGUMENTS', retryable: false, nextAction: 'fix_request' };
+
+  // A refusal the CLI made itself (`createCliError`) or an unexpected error.
+  const clientCode = firstString(payload.error, payload.blockedReason);
+  if (clientCode && ERROR_CODE.test(clientCode)) {
+    const known = CLIENT_CODE_FIELDS[clientCode] || { retryable: false, nextAction: 'fix_request' };
+    return { errorCode: clientCode, ...known };
+  }
+  return { errorCode: 'INTERNAL_ERROR', retryable: false, nextAction: 'contact_support' };
+}
+
+/**
+ * The same fields for a refusal the CLI returns as a result instead of throwing (a blocked
+ * preflight, an empty managed read). `blockedReason` is the code.
+ */
+export function blockedResultFields(blockedReason, overrides = {}) {
+  const code = String(blockedReason || '').trim();
+  const known = CLIENT_CODE_FIELDS[code] || { retryable: false, nextAction: 'fix_request' };
+  return { errorCode: code || 'BLOCKED', ...known, ...overrides };
+}

package/src/core/fundingTokenIn.mjs

@@ -24,6 +24,13 @@ const POSITION_EXIT_ACTIONS = new Set([
   'dogeos_laika_claim',
 ]);
 
+/** Selling native SOL passes the wSOL mint; the wallet holds SOL, not a wSOL token account. */
+const SOLANA_WSOL_MINT = 'So11111111111111111111111111111111111111112';
+
+/** Solana USDC: what the Solana venue funding actions spend (`amountUsdc`, no mint param). */
+const SOLANA_USDC_MINT = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
+const SOLANA_USDC_FUNDING_ACTIONS = new Set(['deposit_polymarket_from_solana', 'deposit_hyperliquid_from_solana']);
+
 /**
  * Shielded spends pay from the Bermuda pool, not the execution wallet: `private: true` on any action,
  * and every Bermuda write except the public deposit into the pool.
@@ -33,12 +40,28 @@ function spendsShieldedFunds(params, actionId) {
   return actionId.startsWith('bermuda_') && actionId !== 'bermuda_deposit';
 }
 
-export function resolveTokenInForFunding(params, action) {
+/**
+ * `spend`: the catalog row's `behavior.spend` (provider app writes) naming the param that holds the
+ * token the action spends; checked before the name fallbacks.
+ */
+export function resolveTokenInForFunding(params, action, spend) {
   if (!params || typeof params !== 'object') return '';
   const actionId = normalizeActionKey(action);
   if (spendsShieldedFunds(params, actionId)) return '';
+  const declared = spend && spend.tokenParam ? String(params[spend.tokenParam] ?? '').trim() : '';
+  if (declared) return declared;
   const explicit = String(params.tokenIn || '').trim();
   if (explicit) return explicit;
+  // Solana: the spent SPL mint is the funding token (`inputMint` on a Jupiter swap, `mint` on an SPL
+  // transfer). A SOL transfer has no mint; the API's native gas check covers it.
+  // wSOL means native SOL here (the action wraps it), so there is no SPL balance to check.
+  const inputMint = String(params.inputMint || '').trim();
+  if (inputMint) return inputMint === SOLANA_WSOL_MINT ? '' : inputMint;
+  if (SOLANA_USDC_FUNDING_ACTIONS.has(actionId)) return SOLANA_USDC_MINT;
+  if (actionId === 'solana_transfer') {
+    const mint = String(params.mint || '').trim();
+    return mint === SOLANA_WSOL_MINT ? '' : mint;
+  }
   if (NATIVE_ETH_SPEND_ACTIONS.has(actionId)) return '';
   if (POSITION_EXIT_ACTIONS.has(actionId)) return '';
   if (params.amountEth != null && String(params.amountEth).trim() !== '') return '';

package/src/core/http.mjs

@@ -151,6 +151,10 @@ async function requestJsonOnce(ctx, route, init) {
       const error = new Error(data?.error || data?.message || `HTTP ${response.status}`);
       error.statusCode = response.status;
       error.payload = data;
+      // Read by describeCliError (src/core/errorEnvelope.mjs): a 5xx on a write may have landed.
+      error.write = !resendAfterTimeoutIsSafe(ctx, init);
+      const retryAfter = Number(response.headers?.get?.('retry-after'));
+      if (Number.isFinite(retryAfter) && retryAfter > 0) error.retryAfterSeconds = Math.ceil(retryAfter);
       throw error;
     }
     return data;
@@ -169,7 +173,8 @@ export async function requestJson(ctx, route, init) {
       if (isTimeoutError(error) && !resendAfterTimeoutIsSafe(ctx, init)) {
         throw writeOutcomeUnknownError(route, ctx, error, init);
       }
-      if (attempt === 0 && isRetryableApiError(error)) {
+      // A write that got a 5xx may have landed: never resend it (thirdfy-mcp does not either).
+      if (attempt === 0 && isRetryableApiError(error) && resendAfterTimeoutIsSafe(ctx, init)) {
         await sleep(250 + Math.floor(Math.random() * 250));
         continue;
       }

package/src/core/readOnlyActions.mjs

@@ -13,6 +13,9 @@ const READ_ONLY_EXACT = new Set([
   'dogeos_barkswap_get_quote',
   'dogeos_laika_read_contract',
   'dogeos_laika_token_state',
+  // Planning steps: they check params and return the next actions (thirdfy-api-v2#867, thirdfy-mcp#239).
+  'dogeos_prepare_trade',
+  'dogeos_prepare_token_launch',
   'basedbid_get_tokens',
   'prepare_polymarket_onboarding',
   'create_polymarket_bridge_deposit',
@@ -47,8 +50,15 @@ export function isReadOnlyActionMeta(meta) {
   return meta.supportsExecute === false && meta.supportsExecuteIntent !== false;
 }
 
+/**
+ * Read vs write for a resolved catalog action: the API's `behavior.readOnly` when the row has it
+ * (either way), else the name rules and `isReadOnlyActionMeta`. Provider app actions
+ * (thirdfy-app.json) are named freely, so only the catalog knows `partner_vault_apy` is a read.
+ * Same rule as thirdfy-mcp `isReadOnlyCatalogAction`.
+ */
 export function isReadOnlyResolvedAction(resolved, options = {}) {
   const meta = resolved?.resolvedActionMeta;
   if (options.requireMeta && (!meta || typeof meta !== 'object')) return false;
+  if (typeof meta?.behavior?.readOnly === 'boolean') return meta.behavior.readOnly;
   return isReadOnlyActionName(resolved?.resolvedAction) || isReadOnlyActionMeta(meta);
 }