@thirdfy/agent-cli 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -4,6 +4,41 @@ All notable changes to `@thirdfy/agent-cli` are documented here. The format is b
 
 ## Unreleased
 
+## [0.4.2] - 2026-10-14
+
+A cleanup release: two small `wallet profile` / `pricing quote` fixes from the 0.4.1 review, and source files moved into domain folders. Commands answer as in 0.4.1, apart from the two fixes.
+
+### Fixed
+
+- **`wallet profile` and `readiness` report the agent key in lowercase** whether it came from `--agent-key` or from env/config. Before, a checksummed config key was echoed as stored, so one agent could appear with two spellings.
+- **`pricing quote` on an API without the agent quote route** names the agent only from `--agent-key`. The branch that took the configured agent could not be reached (a stored owner token already puts the quote on the owner ledger) and is removed.
+
+### Changed
+
+- **Source files moved into domain subfolders (no behavior change).** The `thirdfy-agent` command is unchanged. Code that deep-imports package files must use the new paths:
+  - `src/runtime/execution/runners.mjs` → `src/runtime/execution/runners/` (one file per lane; `createExecutionRunners` is in `createExecutionRunners.mjs`).
+  - `src/core/{actionTimeouts,executionContext,fundingTokenIn,hostedRuntimeIdempotency,readOnlyActions,signedTx,walletExecuteChainId}.mjs` → `src/core/execution/`.
+  - `src/commands/{avantis,condor,hummingbot,hyperliquid,lighter,polymarket,venue}.mjs` → `src/commands/venues/`; `{bootstrap,consoleMandate,credentials,delegation}.mjs` → `src/commands/onboarding/`; `{agent,credits,wallet,walletControl}.mjs` → `src/commands/account/`.
+  - `src/cli/options/` uses the same `venues/`, `onboarding/` and `account/` subfolders.
+  - `src/core/index.mjs` and `src/commands/index.mjs` export the same names as before.
+- `wallet profile` uses the same owner/agent precedence code as the credits commands (`resolveCreditsLedger`) instead of its own copy. Same behavior.
+- `validate:provider-parity` names the files it looked in when it finds no MCP provider-hints file.
+
+## [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,11 @@ Run without global install:
 npx @thirdfy/agent-cli --help
 ```
 
-## What's new in v0.4.0
+## What's new in v0.4.2
 
-- **`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.
+- **One spelling per agent:** `wallet profile` and `readiness` report the agent key in lowercase, whether it came from `--agent-key` or from your config.
+- **`pricing quote` on an older API** (no agent quote route) names the agent only from `--agent-key`.
+- **Reorganized source** (no behavior change): source files moved into domain folders. If your code imports files from inside the package, see [CHANGELOG.md](./CHANGELOG.md) for the new paths; the `thirdfy-agent` command is unchanged.
 - 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.2",
   "description": "Thirdfy Agent CLI for onboarding, governance preflight, execute-intent, and status polling.",
   "type": "module",
   "bin": {
@@ -22,8 +22,8 @@
     "LICENSE"
   ],
   "scripts": {
-    "test": "node --test test/*.test.cjs",
-    "lint": "node --check ./bin/thirdfy-agent.mjs && node --check ./src/core/*.mjs && node --check ./src/commands/*.mjs && node --check ./src/commands/signals/*.mjs && node --check ./src/cli/*.mjs && node --check ./src/cli/options/*.mjs && node --check ./src/runtime/*.mjs && node --check ./src/runtime/execution/*.mjs && node --check ./src/runtime/actions/*.mjs && node --check ./src/runtime/validation/*.mjs && node --check ./src/runtime/certification/*.mjs && node --check ./src/runtime/providerHints/*.mjs && node --check ./src/runtime/risk/*.mjs",
+    "test": "node --test test/*/*.test.cjs test/*/*/*.test.cjs",
+    "lint": "node --check ./bin/thirdfy-agent.mjs && node --check ./src/core/*.mjs && node --check ./src/core/execution/*.mjs && node --check ./src/commands/*.mjs && node --check ./src/commands/venues/*.mjs && node --check ./src/commands/onboarding/*.mjs && node --check ./src/commands/account/*.mjs && node --check ./src/commands/signals/*.mjs && node --check ./src/cli/*.mjs && node --check ./src/cli/options/*.mjs && node --check ./src/cli/options/venues/*.mjs && node --check ./src/cli/options/onboarding/*.mjs && node --check ./src/cli/options/account/*.mjs && node --check ./src/runtime/*.mjs && node --check ./src/runtime/execution/*.mjs && node --check ./src/runtime/execution/runners/*.mjs && node --check ./src/runtime/actions/*.mjs && node --check ./src/runtime/validation/*.mjs && node --check ./src/runtime/certification/*.mjs && node --check ./src/runtime/providerHints/*.mjs && node --check ./src/runtime/risk/*.mjs",
     "validate:cli-manifest-handlers": "node ./scripts/validate-cli-manifest-handlers.mjs",
     "validate:runtime-boundaries": "node ./scripts/validate-runtime-boundaries.mjs",
     "validate:npm-pack": "node ./scripts/validate-npm-pack.mjs",

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/cli/options/index.mjs

@@ -1,24 +1,24 @@
 import { attachGlobalOptions } from './global.mjs';
 import { attachAuthOptions } from './auth.mjs';
 import { attachExecutionOptions } from './execution.mjs';
-import { attachDelegationOptions } from './delegation.mjs';
+import { attachDelegationOptions } from './onboarding/delegation.mjs';
 import { attachTrackingOptions } from './tracking.mjs';
-import { attachWalletOptions } from './wallet.mjs';
-import { attachBootstrapOptions, attachOnboardingHelpOptions } from './bootstrap.mjs';
-import { attachCredentialsOptions } from './credentials.mjs';
+import { attachWalletOptions } from './account/wallet.mjs';
+import { attachBootstrapOptions, attachOnboardingHelpOptions } from './onboarding/bootstrap.mjs';
+import { attachCredentialsOptions } from './onboarding/credentials.mjs';
 import { attachAnalyticsOptions } from './analytics.mjs';
-import { attachPolymarketOptions } from './polymarket.mjs';
-import { attachHummingbotOptions } from './hummingbot.mjs';
-import { attachCondorOptions } from './condor.mjs';
-import { attachAgentRegisterOptions } from './agent.mjs';
+import { attachPolymarketOptions } from './venues/polymarket.mjs';
+import { attachHummingbotOptions } from './venues/hummingbot.mjs';
+import { attachCondorOptions } from './venues/condor.mjs';
+import { attachAgentRegisterOptions } from './account/agent.mjs';
 import { attachChainListOptions, attachChainOptions } from './chains.mjs';
-import { attachCreditsBuyOptions, attachCreditsOptions } from './credits.mjs';
+import { attachCreditsBuyOptions, attachCreditsOptions } from './account/credits.mjs';
 import { attachChatOptions } from './chat.mjs';
-import { attachVenueOptions } from './venue.mjs';
+import { attachVenueOptions } from './venues/venue.mjs';
 import { attachBrainOptions } from './brain.mjs';
 import { attachCertificationOptions } from './certification.mjs';
 import { attachActionListOptions, attachDataCategoryOptions, attachSignalsOptions } from './data.mjs';
-import { attachWalletControlOptions } from './walletControl.mjs';
+import { attachWalletControlOptions } from './account/walletControl.mjs';
 
 const BUNDLES = {
   auth: attachAuthOptions,

package/src/cli/program.mjs

@@ -3,4 +3,4 @@ import { buildCliProgram } from './register.mjs';
 export { buildCliProgram };
 export { collectRootFlags, collectLegacyFlags } from './flags.mjs';
 export { configureCommanderErrors, handleRootOnlyFlows, collectVersionFlagsFromArgv } from './errors.mjs';
-export { normalizeLegacyShortFlags } from './options/bootstrap.mjs';
+export { normalizeLegacyShortFlags } from './options/onboarding/bootstrap.mjs';

package/src/commands/{agent.mjs → account/agent.mjs}

@@ -1,11 +1,11 @@
 import { createRequire } from 'module';
-import { requireFlag, parseJsonFlag } from '../core/args.mjs';
-import { apiPost, safeJsonParse } from '../core/http.mjs';
-import { createCliError } from '../core/envelope.mjs';
-import { DEFAULT_TIMEOUT_MS } from '../core/constants.mjs';
+import { requireFlag, parseJsonFlag } from '../../core/args.mjs';
+import { apiPost, safeJsonParse } from '../../core/http.mjs';
+import { createCliError } from '../../core/envelope.mjs';
+import { DEFAULT_TIMEOUT_MS } from '../../core/constants.mjs';
 
 const require = createRequire(import.meta.url);
-const { version: CLI_VERSION } = require('../../package.json');
+const { version: CLI_VERSION } = require('../../../package.json');
 export function createAgentCommands({ printEnvelope, extractAgentApiKey, extractAgentKey, buildOwnerAuthHeaders }) {
 async function commandAgentRegister(ctx, flags, capabilities) {
   const ownerHeaders = buildOwnerAuthHeaders(

package/src/commands/{credits.mjs → account/credits.mjs}

@@ -1,11 +1,13 @@
-import { requireFlag, usageError } from '../core/args.mjs';
-import { apiGet, apiPost } from '../core/http.mjs';
-import { toAvantisSpelling } from '../core/venueBrand.mjs';
+import { requireFlag, usageError } from '../../core/args.mjs';
+import { apiGet, apiPost } from '../../core/http.mjs';
+import { resolveCreditsLedger } from '../../core/context.mjs';
+import { createCliError } from '../../core/envelope.mjs';
+import { toAvantisSpelling } from '../../core/venueBrand.mjs';
 import {
   formatCreditsEstimateSummary,
   formatCreditsModelsSummary,
   stripUsdFields,
-} from '../lib/creditsUsdSummary.mjs';
+} from '../../lib/creditsUsdSummary.mjs';
 
 function resolveToolCallsEstimate(flags) {
   const raw = flags.toolCalls ?? flags.toolCallsList;
@@ -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 --agent-key names the key's agent. 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 } = 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' },
+          );
+        }
+        // Only --agent-key can name the key's agent here. The agent ledger without --agent-api-key means
+        // no owner auth is stored, and then the owner check above has already refused.
+        if (!flagAgentKey) {
+          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 = flagAgentKey;
+        response = await ownerQuote(flagAgentKey);
+      }
+    } else {
+      response = await ownerQuote(flagAgentKey);
+    }
     printEnvelope({
       success: true,
       code: 'OK',
@@ -163,7 +213,13 @@ 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 } : {}),
+      },
     });
   }
 

package/src/commands/{wallet.mjs → account/wallet.mjs}

@@ -1,14 +1,14 @@
-import { requireFlag, usageError } from '../core/args.mjs';
-import { createCliError, exitAfterOutput } from '../core/envelope.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';
+import { requireFlag, usageError } from '../../core/args.mjs';
+import { createCliError, exitAfterOutput } from '../../core/envelope.mjs';
+import { findAgentApiKey, loadProfileConfig, resolveCreditsLedger } 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 { applySvmLane, assertSvmChainRunByApi } from '../../runtime/execution/svmLane.mjs';
+import { readSignedTxChainId } from '../../core/execution/signedTx.mjs';
+import { runNotionalWarnings } from '../../runtime/risk/notional.mjs';
 
 export function createWalletCommands(deps) {
   const {
@@ -181,6 +181,129 @@ function resolveReadinessChain(flags) {
   };
 }
 
+/**
+ * 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 = String((explicitKey ? flags.agentKey : resolveAgentKey(flags)) || '').trim().toLowerCase();
+  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 };
+}
+
+/**
+ * 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`.
+ */
+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 };
+  // Same precedence as the credits commands (as thirdfy-mcp): an owner flag the caller passed, then an
+  // explicit --agent-api-key, then owner auth from env or config, then an agent key from env or config.
+  const { ledger, agentApiKey } = resolveCreditsLedger(flags);
+  if (ledger !== 'agent') {
+    const ownerHeaders = (() => {
+      try {
+        return buildOwnerAuthHeaders(flags, 'no owner auth');
+      } catch {
+        return null;
+      }
+    })();
+    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 +349,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 +378,7 @@ async function commandReadiness(ctx, flags, capabilities) {
 
   return {
     commandReadiness,
+    commandWalletProfile,
     commandWalletExecute,
     commandWalletSign,
     commandWalletSubmit,

package/src/commands/{walletControl.mjs → account/walletControl.mjs}

@@ -1,6 +1,6 @@
-import { loadProfileConfig } from '../core/context.mjs';
-import { parseJsonFlag, requireFlag } from '../core/args.mjs';
-import { apiGet, apiPost } from '../core/http.mjs';
+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

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, 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/execute.mjs

@@ -8,8 +8,8 @@ import {
 } 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 { isReadOnlyResolvedAction } from '../core/execution/readOnlyActions.mjs';
+import { resolveWalletExecuteChainId } from '../core/execution/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';

package/src/commands/index.mjs

@@ -1,10 +1,10 @@
-export { createPolymarketCommands, resolveConfigAgentKey } from './polymarket.mjs';
-export { createHyperliquidHelpers } from './hyperliquid.mjs';
-export { createLighterHelpers } from './lighter.mjs';
-export { createAvantisHelpers } from './avantis.mjs';
-export { createHummingbotCommands } from './hummingbot.mjs';
-export { createCondorCommands } from './condor.mjs';
+export { createPolymarketCommands, resolveConfigAgentKey } from './venues/polymarket.mjs';
+export { createHyperliquidHelpers } from './venues/hyperliquid.mjs';
+export { createLighterHelpers } from './venues/lighter.mjs';
+export { createAvantisHelpers } from './venues/avantis.mjs';
+export { createHummingbotCommands } from './venues/hummingbot.mjs';
+export { createCondorCommands } from './venues/condor.mjs';
 export { createExecuteCommands } from './execute.mjs';
-export { createWalletCommands } from './wallet.mjs';
-export { createDelegationCommands } from './delegation.mjs';
-export { createBootstrapCommands } from './bootstrap.mjs';
+export { createWalletCommands } from './account/wallet.mjs';
+export { createDelegationCommands } from './onboarding/delegation.mjs';
+export { createBootstrapCommands } from './onboarding/bootstrap.mjs';

package/src/commands/{bootstrap.mjs → onboarding/bootstrap.mjs}

@@ -1,26 +1,26 @@
-import { requireFlag, isNonInteractive, usageError } from '../core/args.mjs';
-import { createCliError } from '../core/envelope.mjs';
-import { PROFILE_DEFAULTS } from '../core/constants.mjs';
+import { requireFlag, isNonInteractive, usageError } from '../../core/args.mjs';
+import { createCliError } from '../../core/envelope.mjs';
+import { PROFILE_DEFAULTS } from '../../core/constants.mjs';
 import {
   normalizeRunMode,
   normalizeProfileName,
   normalizeCustodyMode,
   defaultCustodyModeForRunMode,
   parseBooleanFlag,
-} from '../core/runMode.mjs';
+} from '../../core/runMode.mjs';
 import {
   loadProfileConfig,
   persistProfileConfig,
   clonePlainConfigTree,
   setNestedConfigValue,
   getProfileConfigPath,
-} from '../core/context.mjs';
-import { apiGet, apiPost, requestWithRouteFallback } from '../core/http.mjs';
-import { isEvmAddress, isSolanaAddress } from '../core/chainRegistry.mjs';
+} from '../../core/context.mjs';
+import { apiGet, apiPost, requestWithRouteFallback } from '../../core/http.mjs';
+import { isEvmAddress, isSolanaAddress } from '../../core/chainRegistry.mjs';
 import { createRequire } from 'module';
 
 const require = createRequire(import.meta.url);
-const { version: CLI_VERSION } = require('../../package.json');
+const { version: CLI_VERSION } = require('../../../package.json');
 
 export function createBootstrapCommands(deps) {
   const {