@thirdfy/agent-cli 0.3.0 → 0.4.0

package/src/runtime/execution/runners.mjs

@@ -3,6 +3,7 @@ import { pickNativeGasFields } from './nativeGas.mjs';
 import {
   ACTION_PREFLIGHT_VENUE_FIELDS,
   appendActionPreflightQuery,
+  blockedActionPreflight,
   blockedActionPreflightFromError,
   describeExecutionVenue,
   isApiActionBlock,
@@ -23,7 +24,11 @@ import { idempotentReplayFields } from '../../core/hostedRuntimeIdempotency.mjs'
 import { withActionTimeout } from '../../core/actionTimeouts.mjs';
 import { isReadOnlyResolvedAction } from '../../core/readOnlyActions.mjs';
 import { resolveWalletExecuteChainId } from '../../core/walletExecuteChainId.mjs';
-import { resolveChainRpcUrl } from '../../core/chainRegistry.mjs';
+import { describeInsufficientNativeGas, isSvmChainId, resolveChainRpcUrl, sameWalletAddress } from '../../core/chainRegistry.mjs';
+import { readWalletControl } from './walletControl.mjs';
+import { actionNameForApi } from '../actions/selection.mjs';
+import { blockedResultFields } from '../../core/errorEnvelope.mjs';
+import { riskRefusalFields } from '../risk/riskRefusal.mjs';
 import { isEmptyQueuedExecuteIntent, shouldFallbackManagedReadToExecuteIntent } from './managedReadExecuteRail.mjs';
 import { createRequire } from 'module';
 
@@ -158,6 +163,9 @@ function normalizeManagedExecuteResponse(response, { preflight, payload, isRead
     shaped?.amountNormalization || shaped?.data?.amountNormalization || null;
   normalized.raw = shaped;
   normalized.idempotencyKey = payload.executionIdempotencyKey || null;
+  // A risk-policy refusal nests riskRefusal under data; lift it as thirdfy-mcp walletExecute does.
+  const refusal = shaped?.success ? undefined : riskRefusalFields(shaped || {});
+  if (refusal) Object.assign(normalized, refusal);
   // A replay means nothing new ran; say so, or the caller reads it as a fresh fill.
   if (!isRead) {
     Object.assign(
@@ -185,11 +193,9 @@ function shouldUseManagedReadFastPath(flags, resolved, options = {}) {
   if (options.requireFundingCheck === true) return false;
   const runMode = String(flags.runMode || 'agent_wallet').trim().toLowerCase();
   if (runMode !== 'agent_wallet') return false;
-  const expectedWallet = String(flags.walletAddress || flags.executionWalletAddress || '').trim().toLowerCase();
-  const agentKey = String(typeof resolveAgentKey === 'function' ? resolveAgentKey(flags) : flags.agentKey || '')
-    .trim()
-    .toLowerCase();
-  if (expectedWallet && expectedWallet !== agentKey) return false;
+  const expectedWallet = String(flags.walletAddress || flags.executionWalletAddress || '').trim();
+  const agentKey = String(typeof resolveAgentKey === 'function' ? resolveAgentKey(flags) : flags.agentKey || '').trim();
+  if (expectedWallet && !sameWalletAddress(expectedWallet, agentKey)) return false;
   let chainId;
   try {
     chainId = resolveWalletExecuteChainId({
@@ -259,6 +265,7 @@ async function runPreflightByMode(runMode, ctx, flags, resolved, options = {}) {
         validationOnly: true,
         forceIdempotency: false,
         resolvedAction,
+        apiAction: actionNameForApi(resolved),
         runMode: 'self',
         mirrorOnly: false,
       });
@@ -306,6 +313,7 @@ async function runPreflightByMode(runMode, ctx, flags, resolved, options = {}) {
         validationOnly: true,
         forceIdempotency: false,
         resolvedAction,
+        apiAction: actionNameForApi(resolved),
         runMode: 'hybrid',
         mirrorOnly: false,
         hybridWalletMode: options.hybridWalletMode,
@@ -333,6 +341,7 @@ async function runPreflightByMode(runMode, ctx, flags, resolved, options = {}) {
         validationOnly: true,
         forceIdempotency: false,
         resolvedAction,
+        apiAction: actionNameForApi(resolved),
         runMode: 'agent_wallet',
         mirrorOnly: false,
         hybridWalletMode: 'agent_wallet',
@@ -343,6 +352,7 @@ async function runPreflightByMode(runMode, ctx, flags, resolved, options = {}) {
         validationOnly: true,
         forceIdempotency: false,
         resolvedAction,
+        apiAction: actionNameForApi(resolved),
         runMode: 'hybrid',
         mirrorOnly: true,
         hybridWalletMode: 'agent_wallet',
@@ -371,6 +381,7 @@ async function runPreflightByMode(runMode, ctx, flags, resolved, options = {}) {
     validationOnly: true,
     forceIdempotency: false,
     resolvedAction,
+    apiAction: actionNameForApi(resolved),
     runMode,
     mirrorOnly: runMode === 'hybrid',
   });
@@ -479,6 +490,7 @@ async function executeThirdfyRun(ctx, flags, resolved, options, runMode = 'third
       validationOnly: true,
       forceIdempotency: false,
       resolvedAction: resolved.resolvedAction,
+      apiAction: actionNameForApi(resolved),
       runMode,
       mirrorOnly: false,
       hybridWalletMode: options?.hybridWalletMode,
@@ -502,6 +514,7 @@ async function executeThirdfyRun(ctx, flags, resolved, options, runMode = 'third
     validationOnly: false,
     forceIdempotency: true,
     resolvedAction: resolved.resolvedAction,
+    apiAction: actionNameForApi(resolved),
     runMode,
     mirrorOnly: false,
     hybridWalletMode: options?.hybridWalletMode,
@@ -581,6 +594,7 @@ async function executeManagedWalletRun(ctx, flags, resolved, options) {
   }
   const payload = buildManagedExecutePayload(flags, {
     resolvedAction: resolved.resolvedAction,
+    apiAction: actionNameForApi(resolved),
     runMode: 'agent_wallet',
     forceIdempotency: true,
   });
@@ -600,9 +614,20 @@ async function executeManagedWalletRun(ctx, flags, resolved, options) {
       : preflight;
     const intentResult = await runReadOnlyActionViaIntentRail(ctx, flags, resolved, options, fallbackPreflight);
     if (isEmptyQueuedExecuteIntent(intentResult.raw || intentResult)) {
+      // A read that did not answer in time (often a cold provider cache): nothing changed, and the
+      // same read usually answers on the next try. Same fields as thirdfy-mcp walletExecute.
       intentResult.success = false;
       intentResult.status = 'failed';
       intentResult.error = intentResult.error || 'MANAGED_READ_EMPTY_EXECUTE_INTENT';
+      Object.assign(intentResult, {
+        errorCode: 'MANAGED_READ_EMPTY_EXECUTE_INTENT',
+        retryable: true,
+        retryAfterSeconds: 3,
+        nextAction: 'retry_later',
+        hint:
+          intentResult.hint ||
+          'The read did not answer in time; nothing was changed. Repeat the same read in a few seconds. Do not treat the empty queued result as data.',
+      });
     }
     intentResult.executionWalletAddress =
       preflight?.executionWalletAddress ||
@@ -620,12 +645,11 @@ async function executeManagedWalletRun(ctx, flags, resolved, options) {
  * the API reports for the read.
  */
 function fastPathWalletMismatch(flags, response) {
-  const expectedWallet = String(flags.walletAddress || flags.executionWalletAddress || '').trim().toLowerCase();
+  // 0x addresses compare case-insensitively; Solana base58 is case-sensitive and kept as sent.
+  const expectedWallet = String(flags.walletAddress || flags.executionWalletAddress || '').trim();
   if (!expectedWallet || parseBooleanFlag(flags.allowWalletMismatch, false)) return null;
-  const apiWallet = String(response?.executionWalletAddress || response?.data?.executionWalletAddress || '')
-    .trim()
-    .toLowerCase();
-  if (!apiWallet || apiWallet === expectedWallet) return null;
+  const apiWallet = String(response?.executionWalletAddress || response?.data?.executionWalletAddress || '').trim();
+  if (!apiWallet || sameWalletAddress(apiWallet, expectedWallet)) return null;
   const normalized = normalizeIntentResponse({
     success: false,
     status: 'failed',
@@ -655,6 +679,7 @@ async function executeSelfRun(ctx, flags, resolved, options) {
       validationOnly: true,
       forceIdempotency: false,
       resolvedAction: resolved.resolvedAction,
+      apiAction: actionNameForApi(resolved),
       runMode: 'self',
       mirrorOnly: false,
     });
@@ -679,7 +704,7 @@ async function executeSelfRun(ctx, flags, resolved, options) {
     normalized.preflightBlocked = true;
     return normalized;
   }
-  const buildTxPayload = buildBuildTxPayload(flags, resolved.resolvedAction);
+  const buildTxPayload = buildBuildTxPayload(flags, resolved.resolvedAction, actionNameForApi(resolved));
   // build-tx returns an unsigned transaction; nothing is broadcast, so a timeout may be resent.
   const buildTx = await apiPost({ ...ctx, writeAction: false }, '/api/v1/agent/build-tx', buildTxPayload);
   return normalizeIntentResponse({
@@ -714,6 +739,7 @@ async function executeHybridRun(ctx, flags, resolved, options) {
       validationOnly: true,
       forceIdempotency: true,
       resolvedAction: resolved.resolvedAction,
+      apiAction: actionNameForApi(resolved),
       runMode: 'hybrid',
       mirrorOnly: true,
       hybridWalletMode,
@@ -741,6 +767,7 @@ async function executeHybridRun(ctx, flags, resolved, options) {
     validationOnly: true,
     forceIdempotency: true,
     resolvedAction: resolved.resolvedAction,
+    apiAction: actionNameForApi(resolved),
     runMode: 'hybrid',
     mirrorOnly: true,
   });
@@ -784,7 +811,7 @@ async function resolveManagedExecutionPreflight(ctx, flags, resolved, options =
       signerMethod: 'managed_wallet_server',
     };
   }
-  const tokenIn = resolveTokenInForFunding(params, action);
+  const tokenIn = resolveTokenInForFunding(params, action, resolved?.resolvedActionMeta?.behavior?.spend);
   const query = new URLSearchParams({
     userDid,
     chainId: String(chainId),
@@ -792,7 +819,7 @@ async function resolveManagedExecutionPreflight(ctx, flags, resolved, options =
   });
   if (tokenIn) query.set('tokenIn', tokenIn);
   const evaluateAction = options.evaluateAction === true;
-  if (evaluateAction) appendActionPreflightQuery(query, { action, params, flags });
+  if (evaluateAction) appendActionPreflightQuery(query, { action, apiAction: actionNameForApi(resolved), params, flags });
   const executionVenue = describeExecutionVenue(action, chainId);
   const preflightSeed = options.preflightSeed && typeof options.preflightSeed === 'object'
     ? options.preflightSeed
@@ -826,8 +853,23 @@ async function resolveManagedExecutionPreflight(ctx, flags, resolved, options =
       };
     }
   }
+  // An action preflight the API answered 2xx but refused is a block too (thirdfy-mcp previewOrder).
+  if (evaluateAction && response?.success === false) {
+    return {
+      ...blockedActionPreflight(response, {
+        errorFields: blockedResultFields(String(response.blockedReason || 'PREFLIGHT_BLOCKED')),
+      }),
+      userDid,
+      chainId,
+      ...(executionVenue ? { executionVenue } : {}),
+    };
+  }
   const actionFields = evaluateAction ? pickActionPreflightFields(response) : {};
-  const executionWalletAddress = String(response?.executionWalletAddress || '').trim().toLowerCase();
+  // API 4.0 wallet control, as thirdfy-mcp reports it: the API refuses writes itself (before
+  // signing), so preflight only reports it. Solana is exempt from the API's gate.
+  const walletControlFields = readWalletControl(response, { svm: isSvmChainId(chainId) });
+  // Keep the API's case: Solana base58 addresses are case-sensitive (lowercasing corrupts them).
+  const executionWalletAddress = String(response?.executionWalletAddress || '').trim();
   const signerMethod = String(response?.signerMethod || 'managed_wallet_server').trim();
   const rawBalance = String(response?.fundingTokenBalance?.raw || '').trim();
   let parsedRawBalance = null;
@@ -848,17 +890,24 @@ async function resolveManagedExecutionPreflight(ctx, flags, resolved, options =
           fundingTokenBalance: response?.fundingTokenBalance || null,
           ...actionFields,
           ...(executionVenue ? { executionVenue } : {}),
+      ...walletControlFields,
         };
       }
     }
   }
-  const expectedWallet = String(flags.walletAddress || flags.executionWalletAddress || '').trim().toLowerCase();
+  const expectedWallet = String(flags.walletAddress || flags.executionWalletAddress || '').trim();
   const allowWalletMismatch = parseBooleanFlag(flags.allowWalletMismatch, false);
 
-  if (expectedWallet && executionWalletAddress && expectedWallet !== executionWalletAddress && !allowWalletMismatch) {
+  if (
+    expectedWallet
+    && executionWalletAddress
+    && !sameWalletAddress(expectedWallet, executionWalletAddress)
+    && !allowWalletMismatch
+  ) {
     return {
       success: false,
       blockedReason: 'EXECUTION_WALLET_MISMATCH',
+      ...blockedResultFields('EXECUTION_WALLET_MISMATCH'),
       blockedStage: 'routing',
       error: `Funded wallet (${expectedWallet}) does not match execution wallet (${executionWalletAddress}). Use --allow-wallet-mismatch to override.`,
       executionWalletAddress,
@@ -866,6 +915,7 @@ async function resolveManagedExecutionPreflight(ctx, flags, resolved, options =
       fundingTokenBalance: response?.fundingTokenBalance || null,
       ...actionFields,
       ...(executionVenue ? { executionVenue } : {}),
+      ...walletControlFields,
     };
   }
 
@@ -873,6 +923,7 @@ async function resolveManagedExecutionPreflight(ctx, flags, resolved, options =
     return {
       success: false,
       blockedReason: 'INSUFFICIENT_FUNDS',
+      ...blockedResultFields('INSUFFICIENT_FUNDS'),
       blockedStage: 'sizing',
       error: `Execution wallet ${executionWalletAddress || 'unknown'} has insufficient tokenIn balance.`,
       executionWalletAddress,
@@ -880,24 +931,26 @@ async function resolveManagedExecutionPreflight(ctx, flags, resolved, options =
       fundingTokenBalance: response?.fundingTokenBalance || null,
       ...actionFields,
       ...(executionVenue ? { executionVenue } : {}),
+      ...walletControlFields,
     };
   }
 
-  // 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.
+  // User-pays-gas chains (DogeOS, Solana): the API reports native gas readiness (API 3.18.2+). Keep
+  // it, and stop a write before /execute when the API says the wallet cannot pay gas (gasReady false).
   const nativeGas = pickNativeGasFields(response);
   if (options.requireFundingCheck && nativeGas.gasReady === false) {
     return {
       success: false,
       blockedReason: 'INSUFFICIENT_NATIVE_GAS',
+      ...blockedResultFields('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.`,
+      error: nativeGas.nativeGasWarning?.message || describeInsufficientNativeGas(executionWalletAddress, chainId),
       executionWalletAddress,
       signerMethod,
       fundingTokenBalance: response?.fundingTokenBalance || null,
       ...actionFields,
       ...(executionVenue ? { executionVenue } : {}),
+      ...walletControlFields,
       ...nativeGas,
     };
   }
@@ -913,6 +966,7 @@ async function resolveManagedExecutionPreflight(ctx, flags, resolved, options =
     ...nativeGas,
     ...actionFields,
     ...(executionVenue ? { executionVenue } : {}),
+      ...walletControlFields,
   };
 }
 

package/src/runtime/execution/svmLane.mjs

@@ -0,0 +1,106 @@
+import { parseJsonFlag } from '../../core/args.mjs';
+import { createCliError } from '../../core/envelope.mjs';
+import { chainRegistrySource, configuredSvmChainIds, getChainInfo, isSvmChainId, svmChainRefusal } from '../../core/chainRegistry.mjs';
+import {
+  inferChainIdFromCatalogRow,
+  resolveWalletExecuteChainId,
+} from '../../core/walletExecuteChainId.mjs';
+
+/**
+ * Solana (svm) lane rules. Solana actions run only with run mode `agent_wallet` on the managed
+ * Privy Solana agent wallet. The self and hybrid lanes sign EVM transactions (ethers / OWS), and
+ * `thirdfy` fan-out does not run on Solana, so a Solana run never goes to them.
+ */
+
+function preparedParams(flags) {
+  if (flags.__preparedParams && typeof flags.__preparedParams === 'object') return flags.__preparedParams;
+  try {
+    return parseJsonFlag(flags, 'params') || {};
+  } catch {
+    // The params gate reports invalid JSON; this lookup only needs a chain hint.
+    return {};
+  }
+}
+
+function hasValue(value) {
+  return value !== undefined && value !== null && String(value).trim() !== '';
+}
+
+/**
+ * With no `--chain-id` and no `params.chainId`, a catalog row that runs only on Solana
+ * (`supportedChains: [101]`) sets `flags.chainId` to that chain. Returns the chain the managed
+ * wallet is resolved on, or undefined when it cannot be resolved here.
+ */
+export function applySvmChainDefault(flags, resolved) {
+  const params = preparedParams(flags);
+  if (!hasValue(flags.chainId) && !hasValue(params?.chainId)) {
+    const inferred = inferChainIdFromCatalogRow(resolved?.resolvedActionMeta);
+    if (inferred) {
+      flags.chainId = String(inferred);
+      flags.__chainIdInferred = inferred;
+    }
+  }
+  try {
+    return resolveWalletExecuteChainId({
+      action: String(resolved?.resolvedAction || flags.action || '').trim(),
+      chainId: flags.chainId,
+      params,
+    });
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Run mode for a resolved chain. On a Solana chain:
+ * - `agent_wallet` passes;
+ * - a run mode that only came from the profile, env or config default becomes `agent_wallet`;
+ * - an explicit `--run-mode` other than `agent_wallet` (or a command fixed to self signing) fails
+ *   with SVM_REQUIRES_AGENT_WALLET before any API call.
+ */
+export function resolveSvmRunMode(flags, runMode, chainId, { locked = false } = {}) {
+  if (!isSvmChainId(chainId) || runMode === 'agent_wallet') return runMode;
+  const explicit = locked || hasValue(flags.runMode);
+  if (explicit) {
+    const info = getChainInfo(chainId);
+    throw createCliError(
+      'SVM_REQUIRES_AGENT_WALLET',
+      `${info?.displayName || 'Solana'} (chain ${chainId}) actions run only with --run-mode agent_wallet on the managed Solana agent wallet. run-mode=${runMode} is not supported on Solana: self and hybrid signing are EVM-only.`,
+      {
+        chainId: Number(chainId),
+        chainFamily: 'svm',
+        requestedRunMode: runMode,
+        recommendedRunModes: ['agent_wallet'],
+      },
+    );
+  }
+  flags.runMode = 'agent_wallet';
+  flags.__runModeDefaultedForSvm = true;
+  return 'agent_wallet';
+}
+
+/**
+ * Refuses a Solana chain the API does not run, before any wallet call (thirdfy-mcp
+ * `unsupportedChainFields`): SOLANA_NOT_ENABLED (`use_evm_chain`) on an API with no Solana,
+ * CHAIN_NOT_SUPPORTED (`fix_request`) for a Solana chain id it does not list.
+ */
+export function assertSvmChainRunByApi(chainId) {
+  const refusal = svmChainRefusal(chainId);
+  if (!refusal) return;
+  const fields = { chainId: Number(chainId), chainFamily: 'svm', chainRegistrySource: chainRegistrySource() };
+  if (refusal === 'SOLANA_NOT_ENABLED') {
+    throw createCliError('SOLANA_NOT_ENABLED', `This Thirdfy API does not run Solana yet (its capabilities list no svm chain); chain ${chainId} is refused.`, fields);
+  }
+  const supported = configuredSvmChainIds();
+  throw createCliError('CHAIN_NOT_SUPPORTED', `This Thirdfy API does not run Solana chain ${chainId}; it runs ${supported.join(', ')}.`, {
+    ...fields,
+    supportedSvmChainIds: supported,
+  });
+}
+
+/** Chain default plus run mode check, in that order. Returns the run mode to use. */
+export function applySvmLane(flags, resolved, runMode, options = {}) {
+  const chainId = applySvmChainDefault(flags, resolved);
+  assertSvmChainRunByApi(chainId);
+  return resolveSvmRunMode(flags, runMode, chainId, options);
+}

package/src/runtime/execution/walletControl.mjs

@@ -0,0 +1,104 @@
+/**
+ * Thirdfy API 4.0 wallet control (Privy owner/signer split, `PRIVY_WALLET_CONTROL_MODE` off /
+ * enforced / user_owned / per_template), shown the way thirdfy-mcp 0.1.19 shows it
+ * (`src/wallet/walletControl.ts`), so CLI and MCP callers read the same fields.
+ *
+ * The API reports a managed agent wallet's control as `walletControl { owner, policy,
+ * signerActive, reason?, blockers? }` on `/agent/execution-wallet`, and refuses writes before
+ * signing with the codes below, nesting `nextAction`, `userMessage` and `walletControl` under the
+ * error body's `data`.
+ */
+
+/** Wallet-control refusals, and whether repeating the same call can succeed. */
+export const WALLET_CONTROL_RETRYABLE = Object.freeze({
+  AGENT_SIGNER_REMOVED_BY_OWNER: false,
+  AGENT_WALLET_CONTROL_CONTRADICTORY: false,
+  AGENT_WALLET_CONTROL_UNAVAILABLE: true,
+  WITHDRAW_DESTINATION_NOT_OWNER: false,
+  AGENT_POLICY_UPDATE_REQUIRED: false,
+});
+
+const WALLET_CONTROL_HINTS = Object.freeze({
+  AGENT_SIGNER_REMOVED_BY_OWNER:
+    "Do not retry. The wallet owner removed Thirdfy's signer from this agent wallet; the owner must re-enable the agent in their Thirdfy account before it can trade.",
+  AGENT_WALLET_CONTROL_CONTRADICTORY:
+    "Do not retry. The agent wallet's control does not match Thirdfy's records; nothing was signed. Contact Thirdfy support.",
+  AGENT_WALLET_CONTROL_UNAVAILABLE: "The agent wallet's control could not be verified; nothing was signed. Retry shortly.",
+  WITHDRAW_DESTINATION_NOT_OWNER:
+    "Exits from a wallet under wallet control pay only the wallet itself, the owner payout address or the owner's wallet. Send the exit there, or ask the owner to change the payout.",
+  AGENT_POLICY_UPDATE_REQUIRED:
+    "Do not retry. The owner must sign a policy update (update_policy) for this action's venue before the agent can use it: have the owner open ownerAction.requestsPath in their Thirdfy account, or run `thirdfy-agent wallet-control request --action update_policy`, sign it, and run `wallet-control submit`. Nothing was signed.",
+});
+
+/** What an agent should do for each readiness blocker, as the API's own gate says it. */
+const BLOCKER_NEXT_ACTION = Object.freeze({
+  AGENT_SIGNER_REMOVED_BY_OWNER: 'owner_reenable_agent_signer',
+  AGENT_WALLET_CONTROL_UNAVAILABLE: 'retry_later',
+  AGENT_WALLET_CONTROL_CONTRADICTORY: 'contact_support',
+});
+
+const LIFTED_FIELDS = ['nextAction', 'userMessage', 'walletControl', 'ownerAction'];
+
+const isRecord = (value) => Boolean(value && typeof value === 'object' && !Array.isArray(value));
+
+/** The body and the bodies nested under its `data`, outermost first. */
+function nestedBodies(body) {
+  const bodies = [];
+  let current = body;
+  for (let depth = 0; depth < 3 && isRecord(current); depth += 1) {
+    bodies.push(current);
+    current = current.data;
+  }
+  return bodies;
+}
+
+/** The wallet-control code an API error body carries (`error` or `blockedReason`), if any. */
+export function walletControlCode(body) {
+  for (const entry of nestedBodies(body)) {
+    for (const value of [entry.error, entry.blockedReason]) {
+      if (typeof value === 'string' && Object.prototype.hasOwnProperty.call(WALLET_CONTROL_RETRYABLE, value)) return value;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * The fields a wallet-control refusal adds to the CLI's error envelope `data`: `walletControl`,
+ * `nextAction`, `userMessage` from the API body (at any depth), plus `retryable` and `hint` for the
+ * known codes. Empty for any other error, so other envelopes are unchanged.
+ */
+export function walletControlErrorFields(body) {
+  const code = walletControlCode(body);
+  if (!code) return {};
+  const fields = { walletControlCode: code, retryable: WALLET_CONTROL_RETRYABLE[code] };
+  const bodies = nestedBodies(body);
+  for (const field of LIFTED_FIELDS) {
+    const source = bodies.find((entry) => entry[field] !== undefined && entry[field] !== null);
+    if (source) fields[field] = source[field];
+  }
+  if (WALLET_CONTROL_HINTS[code]) fields.hint = WALLET_CONTROL_HINTS[code];
+  return fields;
+}
+
+/**
+ * `walletControl` from an `/agent/execution-wallet` body, for preflight output. When Thirdfy's
+ * signer is off (`signerActive: false`) it adds the blocker (`walletControl.blockers`) and the next
+ * step. The API reads control from the EVM wallet and its gate exempts Solana, so a Solana check
+ * (`svm: true`) reports it without blocking.
+ */
+export function readWalletControl(body, { svm = false } = {}) {
+  const walletControl = isRecord(body) && isRecord(body.walletControl) ? body.walletControl : undefined;
+  if (!walletControl) return {};
+  if (walletControl.signerActive !== false || svm) return { walletControl };
+  const blockers = Array.isArray(walletControl.blockers) ? walletControl.blockers : [];
+  const blocker =
+    blockers.find((entry) => typeof entry === 'string' && Object.prototype.hasOwnProperty.call(BLOCKER_NEXT_ACTION, entry)) ||
+    'AGENT_SIGNER_REMOVED_BY_OWNER';
+  return {
+    walletControl,
+    walletControlBlocked: true,
+    walletControlBlocker: blocker,
+    nextAction: BLOCKER_NEXT_ACTION[blocker],
+    userMessage: WALLET_CONTROL_HINTS[blocker],
+  };
+}

package/src/runtime/handlers.mjs

@@ -18,6 +18,7 @@ import { createBrainCommands } from '../commands/brain.mjs';
 import { createTelemetryCommands } from '../commands/telemetry.mjs';
 import { createCredentialsCommands } from '../commands/credentials.mjs';
 import { createAgentCommands } from '../commands/agent.mjs';
+import { createWalletControlCommands } from '../commands/walletControl.mjs';
 import { createDoctorCommands } from '../commands/doctor.mjs';
 import { createPromptCommands } from '../commands/prompt.mjs';
 import { createVenueCommands } from '../commands/venue.mjs';
@@ -36,7 +37,7 @@ export function createRuntimeHandlers(deps) {
     buildOwnerAuthHeaders,
     probeBitfinexPermissions,
     applyActionFilters,
-    getTradingProviderHint,
+    getProviderHintForActions,
     resolveChainSupport,
     resolveAgentApiKey,
     getPreparedParams,
@@ -54,6 +55,7 @@ export function createRuntimeHandlers(deps) {
     performSelfBroadcast,
     resolveManagedExecutionPreflight,
     resolveEffectiveUserDid,
+    resolveAgentKey,
     loadEthers,
     resolveOwsBinary,
     CLI_VERSION,
@@ -62,7 +64,7 @@ export function createRuntimeHandlers(deps) {
   const __discovery = createDiscoveryCommands({
     printEnvelope,
     applyActionFilters,
-    getTradingProviderHint,
+    getProviderHintForActions,
     resolveChainSupport,
     getAuthToken,
     resolveAgentApiKey,
@@ -73,6 +75,8 @@ export function createRuntimeHandlers(deps) {
   const __credits = createCreditsCommands({
     printEnvelope,
     getAuthToken,
+    // __wallet is created further down; resolve it when the command runs.
+    commandWalletExecute: (...args) => __wallet.commandWalletExecute(...args),
   });
 
   const __chat = createChatCommands({
@@ -95,6 +99,8 @@ export function createRuntimeHandlers(deps) {
     probeBitfinexPermissions,
   });
 
+  const __walletControl = createWalletControlCommands({ printEnvelope, buildOwnerAuthHeaders });
+
   const __agent = createAgentCommands({
     printEnvelope,
     extractAgentApiKey,
@@ -149,6 +155,9 @@ export function createRuntimeHandlers(deps) {
     executeSelfRun,
     submitSignedTx,
     printEnvelope,
+    resolveEffectiveUserDid,
+    resolveAgentKey,
+    buildOwnerAuthHeaders,
   });
 
   const __execute = createExecuteCommands({
@@ -162,6 +171,7 @@ export function createRuntimeHandlers(deps) {
     applyAvantisAgentWalletAddressDefault,
     runPreflightByMode,
     runExecutionByMode,
+    resolveManagedExecutionPreflight,
     applyExecutionFallbackHints,
     performSelfBroadcast,
     executeManagedWalletRun,
@@ -237,6 +247,7 @@ export function createRuntimeHandlers(deps) {
     commandActions: __discovery.commandActions,
     commandSignals: __signals.commandSignals,
     commandCreditsBalance: __discovery.commandCreditsBalance,
+    commandCreditsBuy: __credits.commandCreditsBuy,
     commandCreditsTransactions: __credits.commandCreditsTransactions,
     commandCreditsUsage: __credits.commandCreditsUsage,
     commandModelsList: __credits.commandModelsList,
@@ -257,6 +268,9 @@ export function createRuntimeHandlers(deps) {
     commandAgentRegister: __agent.commandAgentRegister,
     commandAgentKeyRotate: __agent.commandAgentKeyRotate,
     commandAgentKeyRevoke: __agent.commandAgentKeyRevoke,
+    commandWalletControlState: __walletControl.commandWalletControlState,
+    commandWalletControlRequest: __walletControl.commandWalletControlRequest,
+    commandWalletControlSubmit: __walletControl.commandWalletControlSubmit,
     commandAgentAuthChallenge: __agent.commandAgentAuthChallenge,
     commandAgentAuthVerify: __agent.commandAgentAuthVerify,
     commandAnalyticsPortfolio: __telemetry.commandAnalyticsPortfolio,

package/src/runtime/index.mjs

@@ -1,4 +1,4 @@
 export { createThirdfyAgentRuntime } from './main.mjs';
-export { createProviderHints } from './providerHints.mjs';
+export { createProviderHints } from './providerHints/dispatch.mjs';
 export { createRuntimeHandlers } from './handlers.mjs';
 export { createInitialRuntimeContext, applyFlagsToRuntimeContext } from './context.mjs';