@thirdfy/agent-cli 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -4,6 +4,21 @@ All notable changes to `@thirdfy/agent-cli` are documented here. The format is b
 
 ## Unreleased
 
+## [0.4.1] - 2026-10-14
+
+The last MCP tool with no CLI command (`wallet profile`), who pays for an action (`pricing quote`), owner session tokens for credits, and a parity check that follows thirdfy-mcp's new file layout.
+
+### Added
+
+- **`pricing quote` says who would pay** (`wouldBePaidBy`: `agent_credits`, `free_request`, `owner_credits` or `none`; thirdfy-api-v2#887). With an agent key it uses the agent's own quote (`POST /api/v1/agent/credits/quote`, `meta.agentKey` names the agent); with owner auth, `/credits/pricing/quote`, for one of the owner's agents with `--agent-key`. On an API without the agent route (404), it quotes through the owner route only when owner auth is set and the key's agent is known (`--agent-key`, or the configured agent when the key also comes from config); otherwise `OWNER_AUTH_REQUIRED` or `AGENT_IDENTITY_UNAVAILABLE`, never another agent's quote.
+- **`wallet profile`** (thirdfy-mcp `getWalletProfile` parity; it was the last MCP tool with no CLI command). With owner auth: the owner's live onboarding profile (`GET /api/v1/agent/onboarding/cli/status`). With `--agent-api-key`, or with only an agent key in env/config: the agent's execution wallet on `--chain-id` (Base by default, said with `chainIdAssumed`), with `ready`, `fundingReady`, `walletControl`, `nextAction` and the chain's gas note. `wallet list` still reads only the local config. `readiness` and `wallet profile` share one execution-wallet read. An owner flag you pass wins over `--agent-api-key`, as in the MCP; an execution-wallet answer of `success: false` is `WALLET_PROFILE_FAILED`. Schema: `wallet-profile.response.schema.json`; the MCP tool map now has 65 of 67 tools with a CLI command (`health` and `listTools` do not apply). Tests: `test/wallet-profile.test.cjs`.
+
+### Fixed
+
+- **Owner session tokens work for `credits balance` and `pricing quote`.** Both read only `--auth-token`; they now take `--owner-session-token` (flag, env or config) too. The agent or owner ledger follows one precedence for both, the same as `wallet profile`: an owner flag you pass, then `--agent-api-key`, then owner auth from env/config, then an agent key from env/config.
+- **`validate:provider-parity` follows thirdfy-mcp's provider split** (thirdfy-mcp#262). It finds the MCP checkout by `src/tools/definitions.ts` and reads `apiProviderIds` from `src/tools/discovery/providerActions/providerIds.ts`. The static hint map in `src/tools/providers/providerHints.ts` spreads per-family maps (`...PERPS_PROVIDER_HINTS`, …): each spread is followed through its import, and its keys are read by importing the MCP module with Node type stripping. A spread it cannot resolve, or one with no keys, fails the check. The older single-file layout still works. Before this, the check failed with "No apiProviderIds list found" against MCP `develop`.
+- **`readiness` (and `wallet profile`) could name a different agent than the API key's.** With an explicit `--agent-api-key`, the agent came from env or config; it now comes only from `--agent-key` or `--user-did`, and without them the command answers `AGENT_IDENTITY_UNAVAILABLE` instead of guessing, as thirdfy-mcp does.
+
 ## [0.4.0] - 2026-10-14
 
 Data parity with thirdfy-mcp `develop` (`6143bf6`): the CLI answers with the same data the MCP gives an agent. Minor version: new commands, and `--action` no longer resolves to an action whose name merely contains it.

package/README.md

@@ -3,7 +3,7 @@
 `@thirdfy/agent-cli` is the standalone command-line product for Thirdfy agent operations.
 Use it to:
 
-- onboard with **Privy email OTP** (`login email`), onboarding help (`help onboarding`), auth diagnostics (`doctor auth`), and wallet discovery (`wallet list`)
+- onboard with **Privy email OTP** (`login email`), onboarding help (`help onboarding`), auth diagnostics (`doctor auth`), and wallet discovery (`wallet list` for the local profile, `wallet profile` for the live one)
 - onboard and manage agent keys
 - discover allowed actions (including policy-aware discovery)
 - run governance preflight checks
@@ -40,14 +40,12 @@ Run without global install:
 npx @thirdfy/agent-cli --help
 ```
 
-## What's new in v0.4.0
+## What's new in v0.4.1
 
-- **`preview`:** asks whether Thirdfy would sign a write before anything is sent: the verdict, the order and risk preview, the risk-policy refusal and the `run` command to place it.
-- **New commands:** `readiness` (can the agent act on this chain), `chains` (chains, CAIP-2 ids and lanes from the API), `credits buy --usd <n>`, and `actions --search/--limit/--offset/--view` for one page of the catalog.
-- **Error fields on every failure:** `errorCode`, `retryable`, `retryAfterSeconds`, `nextAction` and `hint`, the same as thirdfy-mcp. A write that got a 5xx is no longer sent twice.
-- **Credits in credits only, and who pays next:** `credits balance` and `pricing quote` show no USD price per credit or request. With an agent key, `credits balance` reads the agent's own ledger: its free requests left today (20 per UTC day), the owner-credits fallback, and a note on who pays next.
-- **Provider hints at MCP parity:** DogeOS, Solana and provider-app hints, perps trade recipes, token lookup and wallet-control notes. Solana fees are sponsored.
-- **Behavior changes:** `--action` matches only an action, alias or Veranta/Avantis twin (no partial names), and is checked against the agent's own allowed actions; `--confirm-writes` goes only into the confirmation keys an action's schema lists.
+- **`wallet profile`:** the live wallet profile from the API. With owner auth, the owner's onboarding profile; with an agent key, the agent's execution wallet with `ready`, wallet control and the next step. Every thirdfy-mcp tool that applies to a CLI now has a command.
+- **`pricing quote` says who would pay:** the agent's credits, a free request, the owner's credits, or nobody (`wouldBePaidBy`), in credits only.
+- **Owner session tokens** work for `credits balance` and `pricing quote`, and both pick the agent or owner ledger the same way as `wallet profile`.
+- **Safer agent identity:** with an explicit `--agent-api-key`, `readiness`, `wallet profile` and `pricing quote` name the agent from `--agent-key`, never a configured agent that may belong to another key.
 - Older versions: see [CHANGELOG.md](./CHANGELOG.md).
 
 ## Quick start

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thirdfy/agent-cli",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "description": "Thirdfy Agent CLI for onboarding, governance preflight, execute-intent, and status polling.",
   "type": "module",
   "bin": {

package/scripts/validate-cli-contract-schemas.mjs

@@ -15,6 +15,7 @@ const REQUIRED_FILES = [
   'chains-non-evm.response.schema.json',
   'readiness.response.schema.json',
   'error.response.schema.json',
+  'wallet-profile.response.schema.json',
 ];
 
 const REQUIRED_KEYS = ['$schema', 'title', 'type'];

package/src/cli/help.mjs

@@ -79,7 +79,7 @@ Core commands:
   thirdfy-agent credits usage --auth-token <token> [--range 7d|30d|90d] [--json]
   thirdfy-agent models list --auth-token <token> [--json]
   thirdfy-agent models estimate --auth-token <token> --model <key> [--input-tokens <n>] [--output-tokens <n>] [--json]
-  thirdfy-agent pricing quote --auth-token <token> --action <action-key> [--chain-id <id>] [--json]
+  thirdfy-agent pricing quote --action <action-key> [--owner-session-token <t> | --auth-token <t> [--agent-key <0x...>] | --agent-api-key <key>] [--chain-id <id>] [--json]
 
 Global flags:
   --api-base <url>   default: https://api.thirdfy.com

package/src/cli/manifest.mjs

@@ -80,7 +80,14 @@ export const CLI_MANIFEST = [
     options: ['chains', 'onboardingHelp'],
     description: 'Structured onboarding help (JSON envelope)',
   },
-  { path: ['wallet', 'list'], handler: 'commandWalletList', description: 'List configured wallets' },
+  { path: ['wallet', 'list'], handler: 'commandWalletList', description: 'List configured wallets (local profile config only; `wallet profile` asks the API)' },
+  {
+    path: ['wallet', 'profile'],
+    handler: 'commandWalletProfile',
+    tier: 'online',
+    options: ['auth', 'chains'],
+    description: "Live wallet profile from the API: the owner's onboarding profile with owner auth, or the agent's execution wallet with an agent key",
+  },
   // polymarket (offline wrappers)
   {
     path: ['polymarket', 'status'],

package/src/commands/credits.mjs

@@ -1,5 +1,7 @@
 import { requireFlag, usageError } from '../core/args.mjs';
 import { apiGet, apiPost } from '../core/http.mjs';
+import { loadProfileConfig, resolveCreditsLedger } from '../core/context.mjs';
+import { createCliError } from '../core/envelope.mjs';
 import { toAvantisSpelling } from '../core/venueBrand.mjs';
 import {
   formatCreditsEstimateSummary,
@@ -36,7 +38,7 @@ function resolveToolCallsEstimate(flags) {
 /** Thirdfy credits are bought on Base with USDC from the agent's wallet (thirdfy-api-v2 `buy-agent-credits`). */
 const CREDITS_PURCHASE_CHAIN_ID = 8453;
 
-export function createCreditsCommands({ printEnvelope, getAuthToken, commandWalletExecute }) {
+export function createCreditsCommands({ printEnvelope, getAuthToken, buildOwnerAuthHeaders, commandWalletExecute }) {
   /**
    * `credits buy --usd <n>`: buy the agent's Thirdfy credits with USDC from its execution wallet on
    * Base (gas sponsored), as thirdfy-mcp's `walletExecute buy-agent-credits` does. A shortcut for
@@ -143,19 +145,67 @@ export function createCreditsCommands({ printEnvelope, getAuthToken, commandWall
     });
   }
 
+  /**
+   * `pricing quote --action <id>`: the credits one catalog action costs, and `wouldBePaidBy`
+   * (agent_credits | free_request | owner_credits | none) when the API can read the balances
+   * (thirdfy-api-v2#887). The ledger follows `resolveCreditsLedger`. Agent: `POST /agent/credits/quote`
+   * with the agent's key. Owner (session token or auth token): `/credits/pricing/quote`, for one of the
+   * owner's agents with --agent-key. An API without the agent route (404, before #887) is quoted
+   * through the owner route when owner auth is set and the key's agent is known: --agent-key, or the
+   * configured agent when the key also comes from env or config. Credits only.
+   */
   async function commandPricingQuote(ctx, flags) {
-    const authToken = getAuthToken(flags, 'Missing --auth-token (or THIRDFY_AUTH_TOKEN) for pricing quote');
     const action = requireFlag(flags, 'action', 'Missing --action for pricing quote');
-    const response = await apiPost(
-      ctx,
-      '/api/v1/credits/pricing/quote',
-      {
-        // Veranta names price as their Avantis spelling, which every API deployment knows.
-        actionKey: toAvantisSpelling(action),
-        chainId: Number(flags.chainId || 8453),
-      },
-      { Authorization: `Bearer ${authToken}` },
-    );
+    // Veranta names price as their Avantis spelling, which every API deployment knows.
+    const body = { actionKey: toAvantisSpelling(action), chainId: Number(flags.chainId || 8453) };
+    const { ledger: requestedLedger, agentApiKey, agentApiKeyExplicit } = resolveCreditsLedger(flags);
+    const flagAgentKey = String(flags.agentKey || '').trim();
+    const ownerHeaders = () =>
+      buildOwnerAuthHeaders(flags, 'Missing --owner-session-token or --auth-token (or THIRDFY_OWNER_SESSION_TOKEN / THIRDFY_AUTH_TOKEN), or an agent key, for pricing quote');
+    const ownerQuote = (agentKey) =>
+      apiPost(ctx, '/api/v1/credits/pricing/quote', { ...body, ...(agentKey ? { agentKey } : {}) }, ownerHeaders());
+    let ledger = requestedLedger;
+    let quotedAgentKey = flagAgentKey || null;
+    const warnings = [];
+    let response;
+    if (ledger === 'agent') {
+      try {
+        response = await apiPost(ctx, '/api/v1/agent/credits/quote', body, { 'x-agent-api-key': agentApiKey });
+        quotedAgentKey = response?.agentKey || null;
+        if (flagAgentKey && quotedAgentKey && flagAgentKey.toLowerCase() !== String(quotedAgentKey).toLowerCase()) {
+          warnings.push(`--agent-key ${flagAgentKey} is not the agent of this API key; the quote is for ${quotedAgentKey}.`);
+        }
+      } catch (error) {
+        if (Number(error?.statusCode) !== 404) throw error;
+        // Owner auth is needed for the older owner route, and the agent must be the key's own.
+        let hasOwner = true;
+        try {
+          ownerHeaders();
+        } catch {
+          hasOwner = false;
+        }
+        if (!hasOwner) {
+          throw createCliError(
+            'OWNER_AUTH_REQUIRED',
+            'This Thirdfy API has no agent quote route yet: pass --owner-session-token or --auth-token for an owner quote.',
+            { blockedStage: 'auth' },
+          );
+        }
+        const pairedAgentKey = flagAgentKey || (agentApiKeyExplicit ? '' : String(process.env.THIRDFY_AGENT_KEY || loadProfileConfig()?.agent?.agentKey || '').trim());
+        if (!pairedAgentKey) {
+          throw createCliError(
+            'AGENT_IDENTITY_UNAVAILABLE',
+            'This Thirdfy API has no agent quote route yet; to quote through the owner route, pass --agent-key (the agent of this API key).',
+            { blockedStage: 'auth' },
+          );
+        }
+        ledger = 'owner';
+        quotedAgentKey = pairedAgentKey;
+        response = await ownerQuote(pairedAgentKey);
+      }
+    } else {
+      response = await ownerQuote(flagAgentKey);
+    }
     printEnvelope({
       success: true,
       code: 'OK',
@@ -163,10 +213,18 @@ export function createCreditsCommands({ printEnvelope, getAuthToken, commandWall
       message: response?.wouldBePaidBy ? `Action pricing quote generated; would be paid by ${response.wouldBePaidBy}` : 'Action pricing quote generated',
       // An action's cost is in credits only, never dollars (thirdfy-mcp quoteActionPricing).
       data: stripUsdFields(response),
-      meta: { apiBase: ctx.apiBase, action },
+      meta: {
+        apiBase: ctx.apiBase,
+        action,
+        ledger,
+        ...(quotedAgentKey ? { agentKey: quotedAgentKey } : {}),
+        ...(warnings.length ? { warnings } : {}),
+      },
     });
   }
 
+
+
   return {
     commandCreditsBuy,
     commandCreditsTransactions,

package/src/commands/discovery.mjs

@@ -1,6 +1,6 @@
 import { requireFlag, parseJsonFlag } from '../core/args.mjs';
 import { apiGet, apiPost } from '../core/http.mjs';
-import { extractActions, findAgentApiKey, getCachedActionsCatalogSnapshot, loadProfileConfig } from '../core/context.mjs';
+import { extractActions, getCachedActionsCatalogSnapshot, resolveCreditsLedger } from '../core/context.mjs';
 import { getEffectiveRunMode } from '../core/runMode.mjs';
 import { creditsFreeQuotaNote, formatCreditsBalanceSummary, stripUsdFields } from '../lib/creditsUsdSummary.mjs';
 import { filterActionsByChain } from '../runtime/actions/chainFilter.mjs';
@@ -52,7 +52,7 @@ function solanaExecutionContract() {
       '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 }) {
+export function createDiscoveryCommands({ printEnvelope, applyActionFilters, getProviderHintForActions, resolveChainSupport, getAuthToken, buildOwnerAuthHeaders, resolveAgentApiKey }) {
 async function commandCatalogsList(ctx, flags, capabilities) {
   const response = await apiGet(ctx, '/api/v1/agent/actions/catalog');
   const actions = extractActions(response);
@@ -189,15 +189,15 @@ async function commandChains(ctx, flags, capabilities) {
  * 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 { ledger, agentApiKey } = resolveCreditsLedger(flags);
+  const agentLedger = ledger === 'agent';
   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')}`,
-      });
+    : await apiGet(
+        ctx,
+        '/api/v1/credits/balance',
+        buildOwnerAuthHeaders(flags, 'Missing --owner-session-token or --auth-token (or THIRDFY_OWNER_SESSION_TOKEN / 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({

package/src/commands/wallet.mjs

@@ -5,6 +5,7 @@ import { DEFAULT_CHAIN_ID, chainGasNote, isSvmChainId, parseChainIdFlag, resolve
 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';
@@ -181,6 +182,132 @@ function resolveReadinessChain(flags) {
   };
 }
 
+/**
+ * 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
@@ -226,16 +353,7 @@ async function commandReadiness(ctx, flags, capabilities) {
       { 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;
+  const { userDid, data, gas, control, fundingReady, ready } = await readAgentExecutionWallet(ctx, flags, agentApiKey, chain.chainId);
   printEnvelope({
     success: true,
     code: ready ? 'READY' : 'NOT_READY',
@@ -264,6 +382,7 @@ async function commandReadiness(ctx, flags, capabilities) {
 
   return {
     commandReadiness,
+    commandWalletProfile,
     commandWalletExecute,
     commandWalletSign,
     commandWalletSubmit,

package/src/contracts/cli/schemas/wallet-profile.response.schema.json

@@ -0,0 +1,127 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "CLI response data: wallet profile (thirdfy-mcp getWalletProfile parity)",
+  "type": "object",
+  "required": [
+    "auth",
+    "source"
+  ],
+  "properties": {
+    "auth": {
+      "enum": [
+        "owner",
+        "agent_api_key"
+      ]
+    },
+    "source": {
+      "enum": [
+        "/api/v1/agent/onboarding/cli/status",
+        "/api/v1/agent/execution-wallet"
+      ]
+    },
+    "profile": {
+      "type": "object"
+    },
+    "agentKey": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "chainId": {
+      "type": "integer"
+    },
+    "chainIdAssumed": {
+      "enum": [
+        true
+      ]
+    },
+    "chainIdNote": {
+      "type": "string"
+    },
+    "ready": {
+      "type": "boolean"
+    },
+    "fundingReady": {
+      "type": "boolean"
+    },
+    "gas": {
+      "type": "object"
+    },
+    "walletControl": {
+      "type": "object"
+    },
+    "nextAction": {
+      "type": "string"
+    },
+    "userMessage": {
+      "type": "string"
+    },
+    "executionWallet": {
+      "type": "object",
+      "required": [
+        "executionWalletAddress"
+      ],
+      "properties": {
+        "executionWalletAddress": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "userDid": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "data": {
+          "type": "object"
+        }
+      },
+      "additionalProperties": true
+    },
+    "note": {
+      "type": "string"
+    }
+  },
+  "additionalProperties": true,
+  "oneOf": [
+    {
+      "properties": {
+        "auth": {
+          "enum": [
+            "owner"
+          ]
+        },
+        "source": {
+          "enum": [
+            "/api/v1/agent/onboarding/cli/status"
+          ]
+        }
+      },
+      "required": [
+        "profile"
+      ]
+    },
+    {
+      "properties": {
+        "auth": {
+          "enum": [
+            "agent_api_key"
+          ]
+        },
+        "source": {
+          "enum": [
+            "/api/v1/agent/execution-wallet"
+          ]
+        }
+      },
+      "required": [
+        "executionWallet",
+        "ready",
+        "chainId"
+      ]
+    }
+  ]
+}

package/src/core/context.mjs

@@ -132,6 +132,26 @@ export function findAgentApiKey(flags = {}) {
   return String(loadProfileConfig()?.agent?.apiKey || '').trim();
 }
 
+/**
+ * Whose credits a credits read is about. Same precedence as `wallet profile`: an owner credential
+ * passed as a flag (--owner-session-token or --auth-token), then an explicit --agent-api-key, then
+ * owner auth from env or config, then an agent key from env or config. Returns `{ ledger, agentApiKey,
+ * agentApiKeyExplicit }`; `ledger` is `agent` or `owner`.
+ */
+export function resolveCreditsLedger(flags = {}) {
+  const config = loadProfileConfig();
+  const explicitOwner = Boolean(String(flags.ownerSessionToken || flags.authToken || '').trim());
+  const agentApiKeyExplicit = Boolean(String(flags.agentApiKey || '').trim());
+  const storedOwner = Boolean(
+    String(
+      process.env.THIRDFY_OWNER_SESSION_TOKEN || process.env.THIRDFY_AUTH_TOKEN || config?.auth?.ownerSessionToken || config?.auth?.authToken || '',
+    ).trim(),
+  );
+  const agentApiKey = findAgentApiKey(flags);
+  const agent = !explicitOwner && (agentApiKeyExplicit || (!storedOwner && Boolean(agentApiKey)));
+  return { ledger: agent ? 'agent' : 'owner', agentApiKey, agentApiKeyExplicit };
+}
+
 /**
  * The actions list for this caller, cached per API base and key: the agent's own list
  * (`GET /api/v1/agent/actions`) whenever an agent key is set (flag, env or config, `findAgentApiKey`),

package/src/runtime/handlers.mjs

@@ -67,6 +67,7 @@ export function createRuntimeHandlers(deps) {
     getProviderHintForActions,
     resolveChainSupport,
     getAuthToken,
+    buildOwnerAuthHeaders,
     resolveAgentApiKey,
   });
 
@@ -75,6 +76,7 @@ export function createRuntimeHandlers(deps) {
   const __credits = createCreditsCommands({
     printEnvelope,
     getAuthToken,
+    buildOwnerAuthHeaders,
     // __wallet is created further down; resolve it when the command runs.
     commandWalletExecute: (...args) => __wallet.commandWalletExecute(...args),
   });