@thirdfy/agent-cli 0.2.86 → 0.4.0

package/src/commands/discovery.mjs

@@ -1,10 +1,58 @@
 import { requireFlag, parseJsonFlag } from '../core/args.mjs';
 import { apiGet, apiPost } from '../core/http.mjs';
-import { extractActions, getCachedActionsCatalog } from '../core/context.mjs';
+import { extractActions, findAgentApiKey, getCachedActionsCatalogSnapshot, loadProfileConfig } from '../core/context.mjs';
 import { getEffectiveRunMode } from '../core/runMode.mjs';
-import { formatCreditsBalanceSummary } from '../lib/creditsUsdSummary.mjs';
+import { creditsFreeQuotaNote, formatCreditsBalanceSummary, stripUsdFields } from '../lib/creditsUsdSummary.mjs';
 import { filterActionsByChain } from '../runtime/actions/chainFilter.mjs';
-export function createDiscoveryCommands({ printEnvelope, applyActionFilters, getTradingProviderHint, resolveChainSupport, getAuthToken, resolveAgentApiKey }) {
+import { pageActionList, readActionListPaging } from '../runtime/actions/actionList.mjs';
+import {
+  caip2ForChainId,
+  chainRegistrySource,
+  configuredEvmChainIds,
+  configuredSvmChainIds,
+  getApiChainRegistry,
+  isSvmChainId,
+} from '../core/chainRegistry.mjs';
+import { SOLANA_PROVIDER_HINTS } from '../runtime/providerHints/solana.mjs';
+
+/** Execution lanes when the API's capabilities name none (thirdfy-mcp SUPPORTED_EXECUTION_LANES). */
+const DEFAULT_EXECUTION_LANES = Object.freeze(['thirdfy', 'hybrid', 'self', 'agent_wallet', 'validation_only']);
+
+/** Chain ids the catalog rows name (`supportedChains` and the like), EVM only. Same as thirdfy-mcp `inferCatalogEvmChainIds`. */
+function catalogEvmChainIds(rows) {
+  const found = new Set();
+  const collect = (value) => {
+    if (typeof value === 'number' && Number.isInteger(value) && value > 0) found.add(value);
+    else if (typeof value === 'string' && /^\d+$/.test(value)) found.add(Number(value));
+    else if (Array.isArray(value)) value.forEach(collect);
+  };
+  for (const row of Array.isArray(rows) ? rows : []) {
+    for (const key of ['chainId', 'chainIds', 'supportedChainIds', 'supportedChains', 'chains', 'networks']) collect(row?.[key]);
+  }
+  return [...found].filter((chainId) => !isSvmChainId(chainId)).sort((a, b) => a - b);
+}
+
+/** The Solana execution contract, as thirdfy-mcp `solanaExecutionContract` with CLI commands. */
+function solanaExecutionContract() {
+  const chainIds = configuredSvmChainIds();
+  return {
+    enabled: chainIds.length > 0,
+    chainFamily: 'svm',
+    chainIds,
+    caip2: Object.fromEntries(chainIds.map((id) => [id, caip2ForChainId(id)]).filter(([, caip2]) => caip2)),
+    requiredRunMode: 'agent_wallet',
+    supportedExecutionLanes: ['agent_wallet'],
+    wallet: "The agent's managed Privy Solana wallet. executionWalletAddress is base58 and case-sensitive.",
+    commands: ['preview', 'run', 'wallet execute', 'agent run'],
+    evmOnlyCommands: ['self-exec', 'wallet sign', 'wallet submit'],
+    providers: Object.keys(SOLANA_PROVIDER_HINTS),
+    flow: '`thirdfy-agent login email` (executionWallets) or `preflight --chain-id 101 --run-mode agent_wallet` gives the base58 executionWalletAddress -> give the user that address (not the EVM one) and fund it with the token to spend -> `run --chain-id 101 --run-mode agent_wallet` with base58 params (for example jupiter_swap {inputMint, outputMint, amount}).',
+    gas: 'Thirdfy sponsors Solana network fees (the execution-wallet reply says gasSponsored): never ask the user to buy SOL for gas. The wallet pays only rent for new token accounts (about 0.002 SOL each) and SOL the action spends; a write short of it is refused with INSUFFICIENT_NATIVE_GAS.',
+    notes:
+      'Solana execution runs only with --run-mode agent_wallet on chain 101 (103 devnet where a provider supports it). self, hybrid and thirdfy stay EVM-only. Check `actions --chain-id 101` (supportedChains) for each action\'s chains.',
+  };
+}
+export function createDiscoveryCommands({ printEnvelope, applyActionFilters, getProviderHintForActions, resolveChainSupport, getAuthToken, resolveAgentApiKey }) {
 async function commandCatalogsList(ctx, flags, capabilities) {
   const response = await apiGet(ctx, '/api/v1/agent/actions/catalog');
   const actions = extractActions(response);
@@ -32,20 +80,32 @@ async function commandCatalogsList(ctx, flags, capabilities) {
 }
 
 async function commandActions(ctx, flags, capabilities) {
-  const policyAware = Boolean(flags.agentApiKey);
+  // The agent's own list whenever execution would run with a key (flag, env or config), so `actions`
+  // lists what `run` / `preflight` accept, as thirdfy-mcp `getAgentActions` does.
+  const paging = readActionListPaging(flags);
+  const snapshot = await getCachedActionsCatalogSnapshot(ctx, flags);
   const chainIdFilter = Number(flags.chainId || 0) || undefined;
-  const actions = filterActionsByChain(applyActionFilters(await getCachedActionsCatalog(ctx, flags), flags), chainIdFilter);
-  const providerHint = getTradingProviderHint(flags.provider);
+  const actions = filterActionsByChain(applyActionFilters(snapshot.actions, flags), chainIdFilter);
+  const providerHint = getProviderHintForActions(flags.provider, actions);
+  // --search / --limit / --offset / --view: one page, as thirdfy-mcp getAgentActions answers.
+  const page = paging ? pageActionList(actions, paging) : null;
   const effectiveRunMode = getEffectiveRunMode(ctx, flags);
   const chainSupport = resolveChainSupport(capabilities, chainIdFilter, effectiveRunMode);
   printEnvelope({
     success: true,
     code: 'OK',
     message: 'Actions loaded',
-    data: { actions, ...(providerHint ? { providerHint } : {}) },
+    data: {
+      ...(page
+        ? { actions: page.actions, pagination: page.pagination, view: page.view, ...(page.hint ? { hint: page.hint } : {}) }
+        : { actions }),
+      ...(providerHint ? { providerHint } : {}),
+    },
     meta: {
       apiBase: ctx.apiBase,
-      policyAware,
+      // A key was sent; policyScoped: the API answered with the agent policy's allowlist.
+      policyAware: snapshot.keyed,
+      policyScoped: snapshot.policyScoped,
       runMode: effectiveRunMode,
       profile: ctx.profile || null,
       chainCompatibility: chainSupport,
@@ -54,19 +114,101 @@ async function commandActions(ctx, flags, capabilities) {
   });
 }
 
-async function commandCreditsBalance(ctx, flags, capabilities) {
-  const authToken = getAuthToken(flags, 'Missing --auth-token (or THIRDFY_AUTH_TOKEN) for credits balance');
-  const response = await apiGet(ctx, '/api/v1/credits/balance', {
-    Authorization: `Bearer ${authToken}`,
+/**
+ * `chains`: which chains Thirdfy acts on, from the API's capabilities and catalog (thirdfy-mcp
+ * `getChainCapabilities`). `--non-evm`: the Solana execution contract (`getNonEvmCapabilities`).
+ */
+async function commandChains(ctx, flags, capabilities) {
+  const svmChainIds = configuredSvmChainIds();
+  const nonEvmChains = svmChainIds.length > 0 ? ['solana'] : [];
+  const meta = { apiBase: ctx.apiBase, capabilitiesVersion: capabilities?.contractVersion || null };
+  if (flags.nonEvm) {
+    const executionEnabled = svmChainIds.length > 0;
+    printEnvelope({
+      success: true,
+      code: 'OK',
+      message: executionEnabled ? 'Solana execution is enabled' : 'Solana execution is not enabled on this API',
+      data: {
+        supportedChains: nonEvmChains,
+        executionEnabled,
+        contractVersion: 'v2',
+        chainRegistrySource: chainRegistrySource(),
+        solana: solanaExecutionContract(),
+        notes: executionEnabled
+          ? 'Solana execution is enabled through `run` / `wallet execute` / `agent run` with --run-mode agent_wallet on chain 101 (the agent\'s managed Privy Solana wallet). self-exec, wallet sign and wallet submit stay EVM-only.'
+          : 'Solana execution is not enabled on this Thirdfy API: its capabilities list no svm chain. Chains 101/103 are refused with SOLANA_NOT_ENABLED.',
+      },
+      meta,
+    });
+    return;
+  }
+  const configured = configuredEvmChainIds();
+  let catalogChainIds = [];
+  let catalogSource = 'live';
+  let catalogError;
+  try {
+    catalogChainIds = catalogEvmChainIds((await getCachedActionsCatalogSnapshot(ctx, flags)).actions);
+  } catch (error) {
+    catalogSource = 'unavailable';
+    catalogError = error?.message || String(error);
+  }
+  const apiChains = getApiChainRegistry()?.chains;
+  printEnvelope({
+    success: true,
+    code: 'OK',
+    message: 'Chain capabilities loaded',
+    data: {
+      supportedEvmChainIds: [...new Set([...configured, ...catalogChainIds])].sort((a, b) => a - b),
+      configuredEvmChainIds: configured,
+      catalogEvmChainIds: catalogChainIds,
+      catalogSource,
+      ...(catalogError ? { catalogError } : {}),
+      supportedNonEvmChains: nonEvmChains,
+      supportedSvmChainIds: svmChainIds,
+      chainRegistrySource: chainRegistrySource(),
+      caip2: Object.fromEntries(
+        [...configured, ...svmChainIds].map((id) => [id, caip2ForChainId(id)]).filter(([, caip2]) => caip2),
+      ),
+      supportedExecutionLanes: Array.isArray(capabilities?.runModes) && capabilities.runModes.length
+        ? capabilities.runModes
+        : [...DEFAULT_EXECUTION_LANES],
+      defaultChainId: 8453,
+      defaultExecutionLane: getEffectiveRunMode(ctx, flags),
+      nonEvmExecutionContract: solanaExecutionContract(),
+      // Each chain the API lists, with its execution lanes (CLI only; the MCP has no per-chain lanes).
+      ...(apiChains ? { chains: apiChains } : {}),
+    },
+    meta,
   });
+}
+
+/**
+ * `credits balance`. Owner auth reads the owner's balance (`/credits/balance`). An explicit
+ * --agent-api-key, or no owner auth but an agent key in env or config, reads the agent's own ledger
+ * (`/agent/credits/balance`: its credits, free requests today and the owner-credits fallback), as
+ * thirdfy-mcp getCreditsBalance. Credits only, never dollars.
+ */
+async function commandCreditsBalance(ctx, flags, capabilities) {
+  const config = loadProfileConfig();
+  const ownerToken = String(flags.authToken || process.env.THIRDFY_AUTH_TOKEN || config?.auth?.authToken || '').trim();
+  const agentApiKey = findAgentApiKey(flags);
+  const agentLedger = Boolean(String(flags.agentApiKey || '').trim()) || (!ownerToken && Boolean(agentApiKey));
+  const response = agentLedger
+    ? await apiGet(ctx, '/api/v1/agent/credits/balance', { 'x-agent-api-key': agentApiKey })
+    : await apiGet(ctx, '/api/v1/credits/balance', {
+        Authorization: `Bearer ${getAuthToken(flags, 'Missing --auth-token (or THIRDFY_AUTH_TOKEN), or an agent key for the agent\'s own credits, for credits balance')}`,
+      });
   const summary = formatCreditsBalanceSummary(response);
+  const note = creditsFreeQuotaNote(response);
   printEnvelope({
     success: true,
     code: 'OK',
     message: flags.json ? 'Credits balance loaded' : `Credits balance loaded: ${summary}`,
-    data: response,
+    // Credits only: no USD price per credit (thirdfy-mcp getCreditsBalance).
+    data: { ...stripUsdFields(response), ...(note ? { note } : {}) },
     meta: {
       apiBase: ctx.apiBase,
+      ledger: agentLedger ? 'agent' : 'owner',
       capabilitiesVersion: capabilities?.contractVersion || null,
       ...(flags.json ? {} : { summary }),
     },
@@ -76,6 +218,7 @@ async function commandCreditsBalance(ctx, flags, capabilities) {
   return {
     commandCatalogsList,
     commandActions,
+    commandChains,
     commandCreditsBalance,
   };
 }

package/src/commands/doctor.mjs

@@ -124,11 +124,14 @@ function buildOnboardingHelp(ctx, flags = {}) {
       },
       {
         id: 'wallet_sign',
-        description: 'Headless wallet proof for operators with an EVM signer.',
+        description: 'An agent with its own EVM key and no email: prove the key, then create the agent. The agent wallet owns the agent.',
         commands: [
           'thirdfy-agent agent auth challenge --agent-key 0xYOUR_AGENT_KEY --json',
-          'thirdfy-agent login --agent-key 0xYOUR_AGENT_KEY --challenge-id <id> --signature <hex> --json',
+          '# sign data.message exactly as given with the private key of 0xYOUR_AGENT_KEY (EIP-191 personal_sign)',
+          'thirdfy-agent agent auth verify --agent-key 0xYOUR_AGENT_KEY --challenge-id <id> --signature <hex> --json',
+          'thirdfy-agent agent register --agent-key 0xYOUR_AGENT_KEY --owner-session-token <ownerSessionToken> --name "My Agent" --json',
         ],
+        note: 'verify returns an owner session; register with --name creates the agent and its API key. An existing agent logs in with `thirdfy-agent login --agent-key 0xYOUR_AGENT_KEY --challenge-id <id> --signature <hex>`. No owner session is stored until the challenge completes.',
       },
       {
         id: 'existing_credentials',

package/src/commands/execute.mjs

@@ -1,4 +1,4 @@
-import { requireFlag } from '../core/args.mjs';
+import { parseJsonFlag, requireFlag } from '../core/args.mjs';
 import { createCliError, exitAfterOutput } from '../core/envelope.mjs';
 import {
   getEffectiveRunMode,
@@ -7,6 +7,13 @@ import {
   parseBooleanFlag,
 } from '../core/runMode.mjs';
 import { apiGet } from '../core/http.mjs';
+import { applySvmLane } from '../runtime/execution/svmLane.mjs';
+import { isReadOnlyResolvedAction } from '../core/readOnlyActions.mjs';
+import { resolveWalletExecuteChainId } from '../core/walletExecuteChainId.mjs';
+import { resolveExecuteEstimatedAmountUsd } from '../runtime/execution/payloads.mjs';
+import { assertPreviewSized, buildPreviewOrder, shapeOrderPreview } from '../runtime/risk/orderPreview.mjs';
+import { actionNameForApi } from '../runtime/actions/selection.mjs';
+import { runNotionalWarnings } from '../runtime/risk/notional.mjs';
 import { findTypedReading, formatTypedReadingLead } from './signals/typedReading.mjs';
 import { createRequire } from 'module';
 
@@ -25,6 +32,7 @@ export function createExecuteCommands(deps) {
     applyAvantisAgentWalletAddressDefault,
     runPreflightByMode,
     runExecutionByMode,
+    resolveManagedExecutionPreflight,
     applyExecutionFallbackHints,
     performSelfBroadcast,
     executeManagedWalletRun,
@@ -39,7 +47,8 @@ async function commandPreflight(ctx, flags, capabilities) {
   const resolved = await resolveActionSelection(ctx, flags);
   prepareActionParamsForFlags(flags, resolved.resolvedAction);
   enforceCatalogActionParams(resolved, flags);
-  const runMode = getEffectiveRunMode(ctx, flags);
+  // Solana-only rows default to chain 101; Solana runs only on agent_wallet.
+  const runMode = applySvmLane(flags, resolved, getEffectiveRunMode(ctx, flags));
   enforceOffchainVenueLaneCompatibility(resolved.resolvedAction, runMode);
   const hybridWalletMode = runMode === 'hybrid' ? normalizeHybridWalletMode(flags.hybridWalletMode) : null;
   enforceChainCompatibility(capabilities, flags, runMode);
@@ -89,11 +98,88 @@ async function commandPreflight(ctx, flags, capabilities) {
 }
 
 
+/**
+ * `preview`: whether Thirdfy would sign a write, with its order and risk preview, before it is sent.
+ * Same verdict as thirdfy-mcp `previewOrder`. Read only: nothing is signed, billed or reserved. A
+ * blocked order is the answer (success, exit 0); `data.wouldSign` says whether `run` would sign it.
+ */
+async function commandPreview(ctx, flags, capabilities) {
+  const previewFlags = { ...flags, runMode: 'agent_wallet' };
+  const resolved = await resolveActionSelection(ctx, previewFlags);
+  prepareActionParamsForFlags(previewFlags, resolved.resolvedAction);
+  enforceCatalogActionParams(resolved, previewFlags);
+  if (isReadOnlyResolvedAction(resolved)) {
+    throw createCliError(
+      'PREVIEW_ORDER_WRITE_ONLY',
+      `${resolved.resolvedAction} is a read; preview previews writes. Run the read with \`thirdfy-agent run\`.`,
+      { resolvedAction: resolved.resolvedAction, requestedAction: resolved.requestedAction },
+    );
+  }
+  applySvmLane(previewFlags, resolved, 'agent_wallet', { locked: true });
+  enforceChainCompatibility(capabilities, previewFlags, 'agent_wallet');
+  const managedPreflight =
+    (await applyHyperliquidAgentWalletAddressDefault(ctx, previewFlags, resolved, 'agent_wallet'))
+    || (await applyLighterAgentWalletAddressDefault(ctx, previewFlags, resolved, 'agent_wallet'))
+    || (await applyAvantisAgentWalletAddressDefault(ctx, previewFlags, resolved, 'agent_wallet'));
+  // The action-aware preflight, with no CLI funding or gas gate: the verdict reads the API's answer.
+  const preflight = await resolveManagedExecutionPreflight(ctx, previewFlags, resolved, {
+    runMode: 'agent_wallet',
+    requireFundingCheck: false,
+    preflightSeed: managedPreflight,
+    evaluateAction: true,
+  });
+  // Anything but an answer about the order (no identity, a wallet mismatch) is a failed command.
+  if (!preflight.success && preflight.preflightBlocked !== true) {
+    throw createCliError(preflight.blockedReason || 'PREVIEW_FAILED', preflight.error || 'Preview failed', {
+      blockedStage: preflight.blockedStage || 'routing',
+    });
+  }
+  // The catalog key drives the CLI's own rules; the verdict and the order name the action the API
+  // was asked about (the requested name), as thirdfy-mcp previewOrder does.
+  const action = resolved.resolvedAction;
+  const apiAction = actionNameForApi(resolved);
+  const chainId = Number(preflight.chainId) || resolveWalletExecuteChainId({
+    action,
+    chainId: previewFlags.chainId,
+    params: parseJsonFlag(previewFlags, 'params') || {},
+  });
+  const estimatedAmountUsd = resolveExecuteEstimatedAmountUsd(action, previewFlags);
+  const behavior = resolved.resolvedActionMeta?.behavior;
+  const shaped = shapeOrderPreview({ action: apiAction, chainId, preflight });
+  assertPreviewSized({ shaped, estimatedAmountUsd, behavior });
+  const order = buildPreviewOrder({
+    shaped,
+    params: parseJsonFlag(flags, 'params') || {},
+    estimatedAmountUsd,
+    paramsSchema: previewFlags.__actionParamsSchema,
+  });
+  printEnvelope({
+    success: true,
+    code: shaped.wouldSign ? 'PREVIEW_WOULD_SIGN' : 'PREVIEW_BLOCKED',
+    message: shaped.wouldSign
+      ? 'Thirdfy would sign this order'
+      : shaped.message || `Thirdfy would not sign this order (${shaped.blockedReason || 'blocked'})`,
+    data: { ...shaped, ...(order ? { order } : {}) },
+    meta: {
+      apiBase: ctx.apiBase,
+      requestedAction: resolved.requestedAction,
+      resolvedAction: action,
+      runMode: 'agent_wallet',
+      executionWalletAddress: preflight.executionWalletAddress || null,
+      profile: ctx.profile || null,
+      swapInput: previewFlags.__swapInput || null,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+}
+
+
 async function commandRun(ctx, flags, capabilities) {
   const resolved = await resolveActionSelection(ctx, flags);
   prepareActionParamsForFlags(flags, resolved.resolvedAction);
   enforceCatalogActionParams(resolved, flags);
-  const runMode = getEffectiveRunMode(ctx, flags);
+  // Solana-only rows default to chain 101; Solana runs only on agent_wallet.
+  const runMode = applySvmLane(flags, resolved, getEffectiveRunMode(ctx, flags));
   enforceOffchainVenueLaneCompatibility(resolved.resolvedAction, runMode);
   const hybridWalletMode = runMode === 'hybrid' ? normalizeHybridWalletMode(flags.hybridWalletMode) : null;
   enforceChainCompatibility(capabilities, flags, runMode);
@@ -102,6 +188,8 @@ async function commandRun(ctx, flags, capabilities) {
     || (await applyLighterAgentWalletAddressDefault(ctx, flags, resolved, runMode))
     || (await applyAvantisAgentWalletAddressDefault(ctx, flags, resolved, runMode));
   const skipPreflight = Boolean(flags.skipPreflight);
+  // A write with no --estimated-amount-usd: a warning, or a refusal before anything is sent.
+  const warnings = runNotionalWarnings(resolved, flags, runMode);
   const backendResult = await runExecutionByMode(runMode, ctx, flags, resolved, {
     skipPreflight,
     hybridWalletMode,
@@ -164,6 +252,9 @@ async function commandRun(ctx, flags, capabilities) {
         skippedPreflight: skipPreflight,
         swapInput: flags.__swapInput || null,
         capabilitiesVersion: capabilities?.contractVersion || null,
+        ...(flags.__runModeDefaultedForSvm ? { runModeDefaultedForSvm: true } : {}),
+        ...(flags.__chainIdInferred ? { chainIdInferred: flags.__chainIdInferred } : {}),
+        ...(warnings.length ? { warnings } : {}),
       },
     },
     typedReading ? { humanLead: formatTypedReadingLead(typedReading) } : {},
@@ -238,6 +329,7 @@ async function commandSelfExec(ctx, flags, capabilities) {
   const resolved = await resolveActionSelection(ctx, flags);
   prepareActionParamsForFlags(flags, resolved.resolvedAction);
   enforceCatalogActionParams(resolved, flags);
+  applySvmLane(flags, resolved, 'self', { locked: true });
   enforceOffchainVenueLaneCompatibility(resolved.resolvedAction, 'self');
   enforceChainCompatibility(capabilities, flags, 'self');
   const selfResult = await executeSelfRun(ctx, flags, resolved, {
@@ -278,6 +370,7 @@ async function commandSelfExec(ctx, flags, capabilities) {
 
   return {
     commandPreflight,
+    commandPreview,
     commandRun,
     commandAgentRun,
     commandIntentStatus,

package/src/commands/prompt.mjs

@@ -1,21 +1,22 @@
 import { requireFlag } from '../core/args.mjs';
 import { apiPost } from '../core/http.mjs';
+import { getEffectiveRunMode } from '../core/runMode.mjs';
 export function createPromptCommands({ printEnvelope }) {
 async function commandPrompt(ctx, flags, capabilities, promptTokens) {
   const prompt = String(flags.prompt || promptTokens.join(' ') || '').trim();
   if (!prompt) {
     throw new Error('Missing prompt text. Use: thirdfy-agent prompt "<text>"');
   }
-  // Jeff rail: deterministic wrapper around existing run contract.
   printEnvelope({
     success: true,
     code: 'PROMPT_RECEIVED',
-    message: 'Prompt captured; execute with `jeff trade` or `run` using --run-mode.',
+    message: 'Prompt captured; find the action with `actions`, check it with `preview`, then send it with `run`.',
     data: {
       prompt,
       suggestedCommands: [
-        'thirdfy-agent jeff trade --run-mode self --agent-api-key ... --action ... --params ...',
-        'thirdfy-agent jeff trade --run-mode hybrid --agent-api-key ... --action ... --params ...',
+        'thirdfy-agent actions --provider <provider> --json',
+        'thirdfy-agent preview --action <action> --params <json> --estimated-amount-usd <usd> --json',
+        'thirdfy-agent run --run-mode agent_wallet --action <action> --params <json> --estimated-amount-usd <usd> --json',
       ],
     },
     meta: {

package/src/commands/wallet.mjs

@@ -1,8 +1,14 @@
-import { requireFlag } from '../core/args.mjs';
+import { requireFlag, usageError } from '../core/args.mjs';
 import { createCliError, exitAfterOutput } from '../core/envelope.mjs';
-import { loadProfileConfig } from '../core/context.mjs';
-import { DEFAULT_CHAIN_ID, parseChainIdFlag, resolveChainRpcUrl } from '../core/chainRegistry.mjs';
+import { findAgentApiKey, loadProfileConfig } from '../core/context.mjs';
+import { DEFAULT_CHAIN_ID, chainGasNote, isSvmChainId, parseChainIdFlag, resolveChainRpcUrl } from '../core/chainRegistry.mjs';
+import { apiGet } from '../core/http.mjs';
+import { getEffectiveRunMode } from '../core/runMode.mjs';
+import { readWalletControl } from '../runtime/execution/walletControl.mjs';
+import { assertSvmChainRunByApi } from '../runtime/execution/svmLane.mjs';
+import { applySvmLane } from '../runtime/execution/svmLane.mjs';
 import { readSignedTxChainId } from '../core/signedTx.mjs';
+import { runNotionalWarnings } from '../runtime/risk/notional.mjs';
 
 export function createWalletCommands(deps) {
   const {
@@ -18,6 +24,9 @@ export function createWalletCommands(deps) {
     executeSelfRun,
     submitSignedTx,
     printEnvelope,
+    resolveEffectiveUserDid,
+    resolveAgentKey,
+    buildOwnerAuthHeaders,
   } = deps;
 
 
@@ -26,12 +35,15 @@ async function commandWalletExecute(ctx, flags, capabilities) {
   const resolved = await resolveActionSelection(ctx, normalizedFlags);
   prepareActionParamsForFlags(normalizedFlags, resolved.resolvedAction);
   enforceCatalogActionParams(resolved, normalizedFlags);
+  applySvmLane(normalizedFlags, resolved, 'agent_wallet');
   enforceChainCompatibility(capabilities, normalizedFlags, 'agent_wallet');
   const managedPreflight =
     (await applyHyperliquidAgentWalletAddressDefault(ctx, normalizedFlags, resolved, 'agent_wallet'))
     || (await applyLighterAgentWalletAddressDefault(ctx, normalizedFlags, resolved, 'agent_wallet'))
     || (await applyAvantisAgentWalletAddressDefault(ctx, normalizedFlags, resolved, 'agent_wallet'));
   const skipPreflight = Boolean(normalizedFlags.skipPreflight);
+  // A write with no --estimated-amount-usd: a warning, or a refusal before anything is sent.
+  const warnings = runNotionalWarnings(resolved, normalizedFlags, 'agent_wallet');
   const result = await executeManagedWalletRun(ctx, normalizedFlags, resolved, { skipPreflight, managedPreflight });
   printEnvelope({
     success: result.success,
@@ -47,6 +59,7 @@ async function commandWalletExecute(ctx, flags, capabilities) {
       executionWalletAddress: result.executionWalletAddress || null,
       profile: ctx.profile || null,
       capabilitiesVersion: capabilities?.contractVersion || null,
+      ...(warnings.length ? { warnings } : {}),
     },
   });
   if (!result.success) await exitAfterOutput(1);
@@ -58,6 +71,7 @@ async function commandWalletSign(ctx, flags, capabilities) {
   const resolved = await resolveActionSelection(ctx, normalizedFlags);
   prepareActionParamsForFlags(normalizedFlags, resolved.resolvedAction);
   enforceCatalogActionParams(resolved, normalizedFlags);
+  applySvmLane(normalizedFlags, resolved, 'self', { locked: true });
   enforceOffchainVenueLaneCompatibility(resolved.resolvedAction, 'self');
   enforceChainCompatibility(capabilities, normalizedFlags, 'self');
   const selfResult = await executeSelfRun(ctx, normalizedFlags, resolved, {
@@ -91,6 +105,13 @@ async function commandWalletSubmit(ctx, flags, capabilities) {
   if (Number.isNaN(flagChainId)) {
     throw createCliError('INVALID_CHAIN_ID', `wallet submit --chain-id must be a positive integer (got ${flags.chainId})`);
   }
+  if (isSvmChainId(flagChainId)) {
+    throw createCliError(
+      'SVM_REQUIRES_AGENT_WALLET',
+      `wallet submit broadcasts signed EVM transactions only. Solana (chain ${flagChainId}) actions run with --run-mode agent_wallet on the managed Solana agent wallet.`,
+      { chainId: flagChainId, chainFamily: 'svm', recommendedRunModes: ['agent_wallet'] },
+    );
+  }
   // The signed tx carries its chain id (EIP-155 / typed tx). Use it when --chain-id is absent,
   // and refuse a mismatch so a DogeOS-signed tx is never sent to a Base RPC (or vice versa).
   const txChainId = readSignedTxChainId(signedTxHex);
@@ -147,7 +168,102 @@ async function commandWalletList(ctx, _flags) {
   });
 }
 
+/** The chain a readiness check uses, saying so when it assumed Base (thirdfy-mcp `resolveReadinessChain`). */
+function resolveReadinessChain(flags) {
+  const chainId = parseChainIdFlag(flags.chainId);
+  // A bad --chain-id is an error, not a silent check of Base.
+  if (Number.isNaN(chainId)) throw usageError('--chain-id must be a positive integer chain id', 'chainId');
+  if (chainId) return { chainId };
+  return {
+    chainId: DEFAULT_CHAIN_ID,
+    chainIdAssumed: true,
+    chainIdNote: `--chain-id was not provided; assumed Base (${DEFAULT_CHAIN_ID}). Pass --chain-id for any other chain (for example DogeOS testnet 6281971, Solana 101).`,
+  };
+}
+
+/**
+ * `readiness`: one verdict on whether the agent can act, as thirdfy-mcp `getSelfReadiness`.
+ * - agent_wallet: the agent's execution wallet on the chain (`GET /agent/execution-wallet` with the
+ *   agent's own key): its address, funding, gas, and wallet control (API 4.0), with `ready`,
+ *   `walletControl` and `nextAction` at the top. No owner auth.
+ * - self / hybrid / thirdfy: the delegation check (`GET /agent/delegation/check`, owner auth).
+ */
+async function commandReadiness(ctx, flags, capabilities) {
+  const runMode = getEffectiveRunMode(ctx, flags);
+  const chain = resolveReadinessChain(flags);
+  const meta = { apiBase: ctx.apiBase, runMode, capabilitiesVersion: capabilities?.contractVersion || null };
+  const echo = {
+    runMode,
+    custodyMode: ctx.custodyMode || null,
+    chainId: chain.chainId,
+    ...(chain.chainIdAssumed ? { chainIdAssumed: true, chainIdNote: chain.chainIdNote } : {}),
+    walletAddress: flags.walletAddress ? String(flags.walletAddress) : null,
+  };
+
+  if (runMode !== 'agent_wallet') {
+    const headers = buildOwnerAuthHeaders(flags, `readiness with --run-mode ${runMode} needs owner auth (--auth-token or --owner-session-token).`);
+    const agentKey = requireFlag({ agentKey: resolveAgentKey(flags) }, 'agentKey', 'Missing --agent-key (or THIRDFY_AGENT_KEY / config.agent.agentKey)');
+    const query = new URLSearchParams({ agentKey, chainId: String(chain.chainId) });
+    const readiness = await apiGet(ctx, `/api/v1/agent/delegation/check?${query.toString()}`, headers);
+    printEnvelope({
+      success: true,
+      code: 'READINESS_OK',
+      message: `Delegation readiness for ${runMode}`,
+      data: { ...echo, ...(chainGasNote(chain.chainId) ? { gas: chainGasNote(chain.chainId) } : {}), source: '/api/v1/agent/delegation/check', readiness },
+      meta,
+    });
+    return;
+  }
+
+  // A Solana chain the API does not run is refused as `run` refuses it (thirdfy-mcp unsupportedChainFields).
+  assertSvmChainRunByApi(chain.chainId);
+  // Only the agent's own key: readiness acts for the caller's agent.
+  const agentApiKey = findAgentApiKey(flags);
+  if (!agentApiKey) {
+    throw createCliError(
+      'AGENT_API_KEY_REQUIRED',
+      "readiness with --run-mode agent_wallet needs the agent's own API key (--agent-api-key, THIRDFY_AGENT_API_KEY or config).",
+      { blockedStage: 'auth', runMode, chainId: chain.chainId },
+    );
+  }
+  const userDid = resolveEffectiveUserDid(flags, { runMode: 'agent_wallet' });
+  const query = new URLSearchParams({ chainId: String(chain.chainId), runMode: 'agent_wallet' });
+  if (userDid) query.set('userDid', userDid);
+  const data = await apiGet(ctx, `/api/v1/agent/execution-wallet?${query.toString()}`, { 'x-agent-api-key': agentApiKey });
+  // The API says per chain whether it sponsors the fee (Solana `gasSponsored`); that answer wins.
+  const gas = chainGasNote(chain.chainId, { gasSponsored: data?.gasSponsored });
+  const control = readWalletControl(data, { svm: isSvmChainId(chain.chainId) });
+  const raw = String(data?.fundingTokenBalance?.raw ?? '').trim();
+  const fundingReady = /^(0x[0-9a-fA-F]+|[0-9]+)$/.test(raw) ? BigInt(raw) > 0n : undefined;
+  const ready = Boolean(data?.executionWalletAddress) && data?.success !== false && !control.walletControlBlocked;
+  printEnvelope({
+    success: true,
+    code: ready ? 'READY' : 'NOT_READY',
+    message: ready ? 'The agent can act on this chain' : control.userMessage || 'The agent is not ready on this chain',
+    data: {
+      ...echo,
+      ...(gas ? { gas } : {}),
+      source: '/api/v1/agent/execution-wallet',
+      ready,
+      // `ready` says the wallet can sign; whether it holds the funding token is this separate field.
+      ...(fundingReady !== undefined ? { fundingReady } : {}),
+      ...(control.walletControl ? { walletControl: control.walletControl } : {}),
+      ...(control.nextAction ? { nextAction: control.nextAction, userMessage: control.userMessage } : {}),
+      readiness: {
+        executionWalletAddress: data?.executionWalletAddress || null,
+        userDid: userDid || data?.userDid || null,
+        ready,
+        ...(fundingReady !== undefined ? { fundingReady } : {}),
+        ...(control.walletControlBlocked ? { blockedBy: 'wallet_control', blocker: control.walletControlBlocker, signerActive: false } : {}),
+        data,
+      },
+    },
+    meta,
+  });
+}
+
   return {
+    commandReadiness,
     commandWalletExecute,
     commandWalletSign,
     commandWalletSubmit,