@thirdfy/agent-cli 0.3.0 → 0.4.1

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,5 +1,6 @@
 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();
@@ -9,12 +10,13 @@ async function commandPrompt(ctx, flags, capabilities, promptTokens) {
   printEnvelope({
     success: true,
     code: 'PROMPT_RECEIVED',
-    message: 'Prompt captured; execute with `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 run --run-mode self --agent-api-key ... --action ... --params ...',
-        'thirdfy-agent run --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,15 @@
-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 { blockedResultFields } from '../core/errorEnvelope.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 +25,9 @@ export function createWalletCommands(deps) {
     executeSelfRun,
     submitSignedTx,
     printEnvelope,
+    resolveEffectiveUserDid,
+    resolveAgentKey,
+    buildOwnerAuthHeaders,
   } = deps;
 
 
@@ -26,12 +36,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 +60,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 +72,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 +106,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 +169,220 @@ 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).`,
+  };
+}
+
+/**
+ * The agent's execution wallet on a chain, read with its own key (`GET /agent/execution-wallet`, as
+ * thirdfy-mcp agentWalletBootstrap): the API answer, the chain's gas note, wallet control (API 4.0),
+ * whether it holds the funding token, and whether it can sign (`ready`). Used by `readiness` and
+ * `wallet profile`.
+ */
+/**
+ * The agent an agent API key acts for. With an explicit --agent-api-key, only --agent-key or
+ * --user-did name it: an agent from env or config may belong to another key. Otherwise the env or
+ * config agent. Throws AGENT_IDENTITY_UNAVAILABLE when no agent can be named, as thirdfy-mcp does
+ * for a key it cannot tie to an agent; it never guesses.
+ */
+function resolveAgentIdentity(flags) {
+  const explicitKey = Boolean(String(flags.agentApiKey || '').trim());
+  const agentKey = explicitKey ? String(flags.agentKey || '').trim().toLowerCase() : String(resolveAgentKey(flags) || '').trim();
+  const explicitDid = String(flags.userDid || '').trim();
+  const userDid = explicitKey
+    ? explicitDid || (agentKey ? `did:wallet:${agentKey}` : '')
+    : resolveEffectiveUserDid(flags, { runMode: 'agent_wallet' });
+  if (!userDid) {
+    throw createCliError(
+      'AGENT_IDENTITY_UNAVAILABLE',
+      explicitKey
+        ? 'With --agent-api-key, pass --agent-key (the agent that key belongs to) so its wallet can be named.'
+        : 'No agent to name the wallet: pass --agent-key, or set THIRDFY_AGENT_KEY or config agent.agentKey.',
+      { blockedStage: 'auth' },
+    );
+  }
+  return { agentKey: agentKey || null, userDid };
+}
+
+async function readAgentExecutionWallet(ctx, flags, agentApiKey, chainId) {
+  const { agentKey, userDid } = resolveAgentIdentity(flags);
+  const query = new URLSearchParams({ chainId: String(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(chainId, { gasSponsored: data?.gasSponsored });
+  const control = readWalletControl(data, { svm: isSvmChainId(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;
+  return { agentKey, userDid, data, gas, control, fundingReady, ready };
+}
+
+/**
+ * `wallet profile` (thirdfy-mcp `getWalletProfile`). With owner auth: the owner's live onboarding
+ * profile (`GET /agent/onboarding/cli/status`: linked wallets, EVM/Solana readiness). With
+ * --agent-api-key, or with no owner auth but an agent key in env or config: the agent's own
+ * execution wallet on --chain-id (Base by default), with `ready`, `walletControl` and `nextAction`.
+ * `wallet list` reads only the local profile config; this asks the API.
+ */
+async function commandWalletProfile(ctx, flags, capabilities) {
+  const meta = { apiBase: ctx.apiBase, capabilitiesVersion: capabilities?.contractVersion || null };
+  const ownerHeaders = (() => {
+    try {
+      return buildOwnerAuthHeaders(flags, 'no owner auth');
+    } catch {
+      return null;
+    }
+  })();
+  const agentApiKey = findAgentApiKey(flags);
+  // An owner flag the caller passed wins (as thirdfy-mcp), then an explicit --agent-api-key, then
+  // owner auth from env or config, then an agent key from env or config.
+  const explicitOwner = Boolean(String(flags.ownerSessionToken || flags.authToken || '').trim());
+  const explicitAgent = Boolean(String(flags.agentApiKey || '').trim());
+  const agentPath = !explicitOwner && (explicitAgent || (!ownerHeaders && Boolean(agentApiKey)));
+  if (!agentPath) {
+    if (!ownerHeaders) {
+      throw createCliError(
+        'OWNER_AUTH_REQUIRED',
+        'wallet profile needs owner auth (--owner-session-token or --auth-token) for the owner profile, or an agent key for the agent\'s execution wallet.',
+        { blockedStage: 'auth' },
+      );
+    }
+    const profile = await apiGet(ctx, '/api/v1/agent/onboarding/cli/status', ownerHeaders);
+    printEnvelope({
+      success: true,
+      code: 'WALLET_PROFILE_OK',
+      message: 'Owner wallet profile loaded',
+      data: { auth: 'owner', source: '/api/v1/agent/onboarding/cli/status', profile },
+      meta,
+    });
+    return;
+  }
+  const chain = resolveReadinessChain(flags);
+  assertSvmChainRunByApi(chain.chainId);
+  const { agentKey, userDid, data, gas, control, fundingReady, ready } = await readAgentExecutionWallet(ctx, flags, agentApiKey, chain.chainId);
+  // An API answer of success:false is a failed call, as thirdfy-mcp lifts it to the top level.
+  const apiFailed = data?.success === false;
+  const failure = apiFailed
+    ? {
+        ...blockedResultFields(typeof data?.blockedReason === 'string' && data.blockedReason ? data.blockedReason : 'WALLET_PROFILE_FAILED'),
+        ...(data?.error ? { error: String(data.error) } : {}),
+      }
+    : {};
+  printEnvelope({
+    success: !apiFailed,
+    code: apiFailed ? 'WALLET_PROFILE_FAILED' : 'WALLET_PROFILE_OK',
+    message: apiFailed
+      ? `Agent execution wallet read failed${data?.error ? `: ${data.error}` : ''}`
+      : ready ? 'Agent execution wallet loaded (ready)' : control.userMessage || 'Agent execution wallet loaded (not ready)',
+    data: {
+      ...failure,
+      auth: 'agent_api_key',
+      source: '/api/v1/agent/execution-wallet',
+      agentKey,
+      chainId: chain.chainId,
+      ...(chain.chainIdAssumed ? { chainIdAssumed: true, chainIdNote: chain.chainIdNote } : {}),
+      ready,
+      ...(fundingReady !== undefined ? { fundingReady } : {}),
+      ...(gas ? { gas } : {}),
+      ...(control.walletControl ? { walletControl: control.walletControl } : {}),
+      ...(control.nextAction ? { nextAction: control.nextAction, userMessage: control.userMessage } : {}),
+      executionWallet: {
+        executionWalletAddress: data?.executionWalletAddress || null,
+        userDid: userDid || data?.userDid || null,
+        data,
+      },
+      note: "This is the agent's execution wallet. The owner's onboarding profile needs --owner-session-token or --auth-token.",
+    },
+    meta,
+  });
+  if (apiFailed) await exitAfterOutput(1);
+}
+
+/**
+ * `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, data, gas, control, fundingReady, ready } = await readAgentExecutionWallet(ctx, flags, agentApiKey, chain.chainId);
+  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,
+    commandWalletProfile,
     commandWalletExecute,
     commandWalletSign,
     commandWalletSubmit,

package/src/commands/walletControl.mjs

@@ -0,0 +1,66 @@
+import { loadProfileConfig } from '../core/context.mjs';
+import { parseJsonFlag, requireFlag } from '../core/args.mjs';
+import { apiGet, apiPost } from '../core/http.mjs';
+
+/**
+ * The owner's side of API 4.0 wallet control (`/api/v1/agent/:agentKey/wallet-control/*`), for a
+ * user-owned agent wallet. Owner auth only (`--owner-session-token` or a Privy `--auth-token`); the
+ * API refuses agent API keys. Thirdfy never signs these: `request` returns the unsigned Privy
+ * request(s), the owner signs `signatureInput` with their own key, and `submit` relays it. This is
+ * how an owner answers AGENT_POLICY_UPDATE_REQUIRED (`--action update_policy`) from the CLI.
+ * Same routes as Console and thirdfy-mcp `walletControlRequest` / `walletControlSubmit`.
+ */
+export function createWalletControlCommands({ printEnvelope, buildOwnerAuthHeaders }) {
+  const ownerHeaders = (flags, command) =>
+    buildOwnerAuthHeaders(flags, `Missing owner auth for wallet-control ${command}: provide --auth-token (THIRDFY_AUTH_TOKEN) or --owner-session-token`);
+
+  function agentKeyOf(flags) {
+    const key = String(flags.agentKey || loadProfileConfig()?.agent?.agentKey || '').trim();
+    if (!key) throw new Error('Missing --agent-key (or a configured agent)');
+    return key;
+  }
+
+  const base = (agentKey) => `/api/v1/agent/${encodeURIComponent(agentKey)}/wallet-control`;
+  const meta = (ctx, capabilities) => ({ apiBase: ctx.apiBase, capabilitiesVersion: capabilities?.contractVersion || null });
+
+  async function commandWalletControlState(ctx, flags, capabilities) {
+    const headers = ownerHeaders(flags, 'state');
+    const agentKey = agentKeyOf(flags);
+    const query = flags.walletAddress ? `?walletAddress=${encodeURIComponent(String(flags.walletAddress).trim())}` : '';
+    const response = await apiGet(ctx, `${base(agentKey)}/state${query}`, headers);
+    printEnvelope({ success: true, code: 'WALLET_CONTROL_STATE', message: 'Owner wallet state', data: response?.data ?? response, meta: meta(ctx, capabilities) });
+  }
+
+  async function commandWalletControlRequest(ctx, flags, capabilities) {
+    const headers = ownerHeaders(flags, 'request');
+    const action = requireFlag(flags, 'action', 'Missing --action (update_policy, stop_agent, resume_agent, change_payout, export)');
+    const agentKey = agentKeyOf(flags);
+    const payload = { action: String(action).trim() };
+    if (flags.walletAddress) payload.walletAddress = String(flags.walletAddress).trim();
+    if (flags.payoutAddress) payload.payoutAddress = String(flags.payoutAddress).trim();
+    if (flags.recipientPublicKey) payload.recipientPublicKey = String(flags.recipientPublicKey).trim();
+    const response = await apiPost(ctx, `${base(agentKey)}/requests`, payload, headers);
+    printEnvelope({
+      success: true,
+      code: 'WALLET_CONTROL_REQUESTS',
+      message: 'Unsigned owner request(s): sign each signatureInput with the owner key, then run wallet-control submit',
+      data: response?.data ?? response,
+      meta: meta(ctx, capabilities),
+    });
+  }
+
+  async function commandWalletControlSubmit(ctx, flags, capabilities) {
+    const headers = ownerHeaders(flags, 'submit');
+    const action = requireFlag(flags, 'action', 'Missing --action');
+    const signatureInput = parseJsonFlag(flags, 'signatureInput');
+    if (!signatureInput || typeof signatureInput !== 'object') throw new Error('Missing --signature-input (the signatureInput JSON of the request the owner signed)');
+    const signature = requireFlag(flags, 'signature', 'Missing --signature (the owner signature of signatureInput)');
+    const agentKey = agentKeyOf(flags);
+    const payload = { action: String(action).trim(), signatureInput, signature: String(signature).trim() };
+    if (flags.payoutAddress) payload.payoutAddress = String(flags.payoutAddress).trim();
+    const response = await apiPost(ctx, `${base(agentKey)}/submit`, payload, headers);
+    printEnvelope({ success: true, code: 'WALLET_CONTROL_SUBMITTED', message: 'Owner action relayed', data: response?.data ?? response, meta: meta(ctx, capabilities) });
+  }
+
+  return { commandWalletControlState, commandWalletControlRequest, commandWalletControlSubmit };
+}

package/src/contracts/cli/schemas/actions.response.schema.json

@@ -44,6 +44,51 @@
         },
         "additionalProperties": true
       }
+    },
+    "pagination": {
+      "type": "object",
+      "description": "Present with --search, --limit, --offset or --view (thirdfy-mcp getAgentActions paging).",
+      "required": [
+        "total",
+        "matched",
+        "offset",
+        "limit",
+        "returned",
+        "hasMore"
+      ],
+      "properties": {
+        "total": {
+          "type": "integer"
+        },
+        "matched": {
+          "type": "integer"
+        },
+        "offset": {
+          "type": "integer"
+        },
+        "limit": {
+          "type": "integer"
+        },
+        "returned": {
+          "type": "integer"
+        },
+        "hasMore": {
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": true
+    },
+    "view": {
+      "enum": [
+        "concise",
+        "detailed"
+      ]
+    },
+    "hint": {
+      "type": "string"
+    },
+    "providerHint": {
+      "type": "object"
     }
   },
   "additionalProperties": true