@thirdfy/agent-cli 0.1.40 → 0.1.42

package/CHANGELOG.md

@@ -4,6 +4,19 @@ All notable changes to `@thirdfy/agent-cli` are documented here. The format is b
 
 ## [Unreleased]
 
+## [0.1.42] - 2026-05-19
+
+### Changed
+
+- Email login persists and surfaces API `executionWallets` for `agent_wallet` writes; `whoami`, `wallet list`, and `doctor auth` distinguish owner embedded wallets (auth only) from agent execution wallets to fund.
+- Onboarding help and docs clarify Bridge2 must fund the managed execution wallet, not the owner login wallet, and that Thirdfy credits are separate from Privy gas sponsorship. Pairs with thirdfy-api-v2 **v3.4.25**.
+
+## [0.1.41] - 2026-05-19
+
+### Changed
+
+- Hyperliquid provider hints and docs list `get_hyperliquid_funding_status` as step 0 before onboarding plan; clarify Bridge2 sender custody, `--estimated-amount-usd` on `deposit_hyperliquid_bridge`, and `MANUAL_BRIDGE2_DEPOSIT_REQUIRED` guidance. Pairs with thirdfy-api-v2 **v3.4.24**.
+
 ## [0.1.40] - 2026-05-17
 
 ### Fixed

package/README.md

@@ -42,7 +42,7 @@ npx @thirdfy/agent-cli --help
 
 ## Release notes
 
-Version history and highlights: [CHANGELOG.md](./CHANGELOG.md). **v0.1.40** fixes email/bootstrap credential persistence when the API returns nested registration payloads, so owner-session onboarding can save the hidden execution identity without exposing a raw agent API key. **v0.1.39** makes `agent_wallet` the fresh solo default, adds framework guidance for Hermes/OpenClaw/Claude Managed Agents, clarifies Gator/ERC-7710 delegation flows, and keeps BYOW/self plus hybrid/thirdfy mode switching explicit. **v0.1.38** is a **documentation and metadata patch**: it republishes to npm so the package homepage matches the updated `README.md` on `main`, and aligns root `package-lock.json` version fields with `package.json`. **v0.1.37** adds **email OTP** `thirdfy-agent login email` (send code, then complete with `--code --accept-terms`), **`help onboarding`**, **`doctor auth`**, **`wallet list`**, and **masked `whoami`** output so agents and operators get first-run guidance without dumping secrets. Earlier releases added provider discovery parity, portfolio analytics, managed-wallet swap normalization, and **self/build-tx** swap human-decimal `amountIn` parity when using `amountInHuman` + `tokenInDecimals`.
+Version history and highlights: [CHANGELOG.md](./CHANGELOG.md). **v0.1.42** persists API `executionWallets` from email login, updates `doctor auth` / onboarding help for agent execution wallet funding vs owner embedded auth wallet, and documents Bridge2 `FUND_AGENT_EXECUTION_WALLET` remediation (pairs with API **v3.4.25**). **v0.1.41** documents Hyperliquid `get_hyperliquid_funding_status` as setup step 0, Bridge2 sender custody, and `deposit_hyperliquid_bridge --estimated-amount-usd` (pairs with API **v3.4.24**). **v0.1.40** fixes email/bootstrap credential persistence when the API returns nested registration payloads, so owner-session onboarding can save the hidden execution identity without exposing a raw agent API key. **v0.1.39** makes `agent_wallet` the fresh solo default, adds framework guidance for Hermes/OpenClaw/Claude Managed Agents, clarifies Gator/ERC-7710 delegation flows, and keeps BYOW/self plus hybrid/thirdfy mode switching explicit. **v0.1.38** is a **documentation and metadata patch**: it republishes to npm so the package homepage matches the updated `README.md` on `main`, and aligns root `package-lock.json` version fields with `package.json`. **v0.1.37** adds **email OTP** `thirdfy-agent login email` (send code, then complete with `--code --accept-terms`), **`help onboarding`**, **`doctor auth`**, **`wallet list`**, and **masked `whoami`** output so agents and operators get first-run guidance without dumping secrets. Earlier releases added provider discovery parity, portfolio analytics, managed-wallet swap normalization, and **self/build-tx** swap human-decimal `amountIn` parity when using `amountInHuman` + `tokenInDecimals`.
 
 **Maintainers — npm:** follow [docs/releasing.md](./docs/releasing.md). From a clone with gitignored `.env`, use `npm run publish:npm:local -- --dry-run` then `npm run publish:npm:local`. Or run `npm run release:npm` after exporting tokens in the shell. Never commit npm tokens — use [.env.example](./.env.example) as a template only.
 
@@ -104,7 +104,7 @@ thirdfy-agent logout --json
 thirdfy-agent logout --all --json
 ```
 
-`login email` is a two-step headless-safe flow. Without `--code`, the CLI asks the Thirdfy API onboarding broker to send a Privy email OTP and exits with the exact next command. With `--code --accept-terms`, it stores a short-lived owner session in `~/.thirdfy/config.json`, records linked EVM/Solana wallets plus the owner `userDid` when Privy returns them, stores a new agent API key when first-run bootstrap issues one, and defaults new solo profiles to `agent_wallet`. Use `--not-interactive` / `--ni` in automation so missing input fails fast instead of prompting — place **`--ni` after the `login email` subcommand** (for example `thirdfy-agent login email you@example.com --code … --accept-terms --ni`); a leading `thirdfy-agent --ni login email …` is parsed incorrectly because `--ni` would consume the `login` token as its value.
+`login email` is a two-step headless-safe flow. Without `--code`, the CLI asks the Thirdfy API onboarding broker to send a Privy email OTP and exits with the exact next command. With `--code --accept-terms`, it stores a short-lived owner session in `~/.thirdfy/config.json`, records linked EVM/Solana wallets plus the owner `userDid` when Privy returns them, stores a new agent API key when first-run bootstrap issues one, stores the returned `executionWallets` map, and defaults new solo profiles to `agent_wallet`. Email OTP is owner authentication only; fund the returned agent execution wallet for the target chain, not the linked owner embedded wallet. Use `--not-interactive` / `--ni` in automation so missing input fails fast instead of prompting — place **`--ni` after the `login email` subcommand** (for example `thirdfy-agent login email you@example.com --code … --accept-terms --ni`); a leading `thirdfy-agent --ni login email …` is parsed incorrectly because `--ni` would consume the `login` token as its value.
 
 `logout --all` is provider-agnostic: it attempts owner-session revocation when a session token exists, then always clears local credentials.
 
@@ -169,7 +169,8 @@ Auth expectations by mode:
 - `self`: requires execution identity (`agentApiKey`) today; keyless self lane is blocked with deterministic `SELF_OPEN_DISABLED`.
 - `hybrid`: requires execution identity and governed mirror semantics (`--hybrid-wallet-mode self|agent_wallet`, default `self`).
 - `thirdfy`: requires execution identity and delegated governance path.
-- `agent_wallet`: requires execution identity and owner `userDid`, but does not require subscriber delegation when the owner identity matches the agent wallet/creator.
+- `agent_wallet`: requires execution identity and owner `userDid`, but does not require subscriber delegation when the owner identity matches the agent wallet/creator. Thirdfy credits/free quota still gate execution; Privy gas sponsorship only covers network gas when enabled.
+- Hyperliquid Bridge2 setup is the Arbitrum exception to the Base-focused `agent_wallet` rule: Bridge2 credits the transaction sender. Pass **`--estimated-amount-usd`** as a top-level flag (not inside `--params`). When USDC sits on your linked email-login wallet (`primaryEvmWallet`) instead of the managed execution wallet, Thirdfy API returns **`FUND_AGENT_EXECUTION_WALLET`** / **`MANUAL_BRIDGE2_DEPOSIT_REQUIRED`** with `fundedWallet` and `executionWalletAddress`; move native Arbitrum USDC to `executionWalletAddress` and retry.
 - custody mode defaults are profile-aware:
   - `managed` default for `thirdfy`
   - `external` default for `self` and `hybrid`

package/bin/thirdfy-agent.mjs

@@ -483,6 +483,7 @@ function getTradingProviderHint(providerId) {
         'get_hyperliquid_candles',
         'get_hyperliquid_user_state',
         'get_hyperliquid_open_orders',
+        'get_hyperliquid_funding_status',
         'get_hyperliquid_onboarding_plan',
         'get_hyperliquid_referral_status',
         'get_hyperliquid_builder_fee_status',
@@ -493,6 +494,7 @@ function getTradingProviderHint(providerId) {
         'get_hyperliquid_open_orders',
       ],
       setupActions: [
+        'get_hyperliquid_funding_status',
         'get_hyperliquid_setup_status',
         'get_hyperliquid_onboarding_plan',
         'prepare_hyperliquid_onboarding',
@@ -506,7 +508,12 @@ function getTradingProviderHint(providerId) {
         'deposit_hyperliquid_staking',
         'claim_hyperliquid_testnet_faucet',
       ],
-      statusActions: ['get_hyperliquid_setup_status', 'get_hyperliquid_builder_fee_status', 'get_hyperliquid_referral_status'],
+      statusActions: [
+        'get_hyperliquid_funding_status',
+        'get_hyperliquid_setup_status',
+        'get_hyperliquid_builder_fee_status',
+        'get_hyperliquid_referral_status',
+      ],
       credentialType: 'hyperliquid_api_wallet',
       credentialUx:
         'Thirdfy manages Hyperliquid API-wallet setup for normal users. Delegated writes require encrypted privateKey-backed hyperliquid_api_wallet credentials; walletAddress-only records are rejected until Privy walletId-backed Hyperliquid signing ships.',
@@ -533,7 +540,7 @@ function getTradingProviderHint(providerId) {
       laneCompatibility:
         'Use self only for setup signatures or Arbitrum funding transactions. Perps orders should use thirdfy, hybrid, or agent_wallet.',
       setupExample:
-        'actions --provider hyperliquid -> get_hyperliquid_onboarding_plan -> prepare_hyperliquid_onboarding -> get_bridge_quote/execute_bridge if source is Base -> deposit_hyperliquid_bridge on 42161 -> approve_hyperliquid_agent -> approve_hyperliquid_builder_fee if required -> get_hyperliquid_setup_status',
+        'actions --provider hyperliquid -> get_hyperliquid_funding_status -> get_hyperliquid_onboarding_plan -> prepare_hyperliquid_onboarding -> get_bridge_quote/execute_bridge if source is Base -> deposit_hyperliquid_bridge on 42161 -> approve_hyperliquid_agent -> approve_hyperliquid_builder_fee if required -> get_hyperliquid_setup_status',
       example:
         'thirdfy-agent actions --provider hyperliquid && thirdfy-agent preflight --action place_hyperliquid_perps_order --params \'{"coin":"ETH","isBuy":true,"size":0.01,"limitPx":3500,"orderType":"market"}\'',
     };
@@ -2544,9 +2551,10 @@ function buildOnboardingHelp(ctx) {
           'thirdfy-agent login email user@example.com',
           'thirdfy-agent login email user@example.com --code <otp> --accept-terms --key-name "My Agent"',
           'thirdfy-agent whoami',
-          'thirdfy-agent managed wallet init --chain-id 8453',
+          'thirdfy-agent wallet list --json',
           'thirdfy-agent preflight --run-mode agent_wallet --action <action> --params <json> --json',
         ],
+        note: 'Email OTP authenticates the owner. Fund the returned agent execution wallet for the target chain; do not fund the owner embedded/login wallet for agent_wallet writes.',
       },
       {
         id: 'wallet_sign',
@@ -2580,7 +2588,7 @@ function buildOnboardingHelp(ctx) {
       rule: 'Commands must fail fast instead of waiting for prompts when required input is missing.',
     },
     executionModes: {
-      agent_wallet: 'Solo managed wallet execution through /execution-wallet + /execute; no subscriber binding when owner userDid matches.',
+      agent_wallet: 'Solo managed server-wallet execution through /execution-wallet + /execute; no subscriber binding when owner userDid matches. Network gas may be sponsored, but Thirdfy credits/free-quota gates still apply.',
       self: 'BYOW/OWS local signing through build-tx, wallet sign, and wallet submit.',
       hybrid: 'Primary self or agent_wallet execution with optional Thirdfy mirror validation.',
       thirdfy: 'Publisher/fanout execute-intent; requires active subscriber/delegation bindings for writes.',
@@ -2588,7 +2596,7 @@ function buildOnboardingHelp(ctx) {
     },
     frameworkGuidance: {
       hermes:
-        'Hermes agents should receive a pre-provisioned Thirdfy profile/env, run doctor auth/self at startup, use agent_wallet for managed solo writes, and keep strategy logic separate from CLI secrets.',
+        'Hermes agents should receive a pre-provisioned Thirdfy profile/env, run doctor auth/self at startup, use agent_wallet for managed solo writes, fund the agent execution wallet on the target chain, and keep strategy logic separate from CLI secrets.',
       openclaw:
         'OpenClaw agents should keep Thirdfy credentials in runtime secrets, use actions discovery before planning, prefer run --run-mode agent_wallet for own-wallet execution, and use thirdfy only for publisher/fanout.',
       claudeManagedAgents:
@@ -2639,6 +2647,7 @@ async function commandWhoami(ctx, _flags) {
         primaryEvmWallet: wallets.primaryEvmWallet || null,
         evm: Array.isArray(wallets.evm) ? wallets.evm : [],
         solana: Array.isArray(wallets.solana) ? wallets.solana : [],
+        executionWallets: wallets.executionWallets || config.executionWallets || {},
       },
       configPath: getProfileConfigPath(),
       nextSteps: buildOnboardingHelp(ctx).paths[0].commands,
@@ -2658,7 +2667,8 @@ async function commandWalletList(ctx, _flags) {
       primaryEvmWallet: wallets.primaryEvmWallet || null,
       evm: Array.isArray(wallets.evm) ? wallets.evm : [],
       solana: Array.isArray(wallets.solana) ? wallets.solana : [],
-      hint: 'Run `thirdfy-agent login email <email>` to refresh linked wallets from Privy-backed onboarding.',
+      executionWallets: wallets.executionWallets || config.executionWallets || {},
+      hint: 'Run `thirdfy-agent login email <email>` to refresh linked wallets and agent execution wallets. Fund executionWallets for agent_wallet writes; linked owner wallets are auth identities.',
     },
     meta: { apiBase: ctx.apiBase },
   });
@@ -2713,6 +2723,20 @@ async function commandDoctorAuth(ctx, _flags) {
           ? `${config.wallets.evm.length} linked EVM wallet${config.wallets.evm.length === 1 ? '' : 's'}`
           : 'missing wallet profile; run email onboarding or wallet-sign proof'),
     },
+    {
+      name: 'agent-execution-wallets',
+      optional: runMode !== 'agent_wallet',
+      ok: Boolean(config.wallets?.executionWallets && Object.keys(config.wallets.executionWallets).length),
+      detail: config.wallets?.executionWallets && Object.keys(config.wallets.executionWallets).length
+        ? `agent execution wallets available for chains: ${Object.keys(config.wallets.executionWallets).join(', ')}`
+        : 'missing agent execution wallets; run `thirdfy-agent login email <email> --code <otp> --accept-terms --json` or execution-wallet preflight',
+    },
+    {
+      name: 'thirdfy-credits-vs-gas-sponsorship',
+      optional: true,
+      ok: true,
+      detail: 'Thirdfy credits/free quota gate action access; Privy gas sponsorship only pays network gas when chain/action sponsorship is enabled.',
+    },
   ];
   const ok = checks.every((entry) => entry.optional || entry.ok);
   printEnvelope({
@@ -2963,12 +2987,14 @@ async function commandLoginEmail(ctx, flags) {
   const agentApiKey = extractAgentApiKey(data);
   const agentKey = extractAgentKey(data);
   const wallets = data.wallets && typeof data.wallets === 'object' ? data.wallets : {};
+  const executionWallets = data.executionWallets && typeof data.executionWallets === 'object' ? data.executionWallets : {};
   const userDid = String(data.owner?.creatorDid || wallets.userDid || '').trim();
   const primaryEvmWallet = String(wallets.primaryEvmWallet || data.owner?.creatorWallet || '').trim();
   const persistedWallets = {
     ...wallets,
     ...(userDid ? { userDid } : {}),
     ...(primaryEvmWallet ? { primaryEvmWallet } : {}),
+    ...(Object.keys(executionWallets).length ? { executionWallets } : {}),
   };
   const runMode = normalizeRunMode(flags.runMode || current.runMode || process.env.THIRDFY_RUN_MODE || 'agent_wallet');
   const custodyMode = normalizeCustodyMode(flags.custodyMode || current.custodyMode || process.env.THIRDFY_CUSTODY_MODE, runMode);
@@ -3016,6 +3042,11 @@ async function commandLoginEmail(ctx, flags) {
       evmWallets: Array.isArray(persistedWallets.evm) ? persistedWallets.evm : [],
       solanaWallets: Array.isArray(persistedWallets.solana) ? persistedWallets.solana : [],
       primaryEvmWallet: persistedWallets.primaryEvmWallet || null,
+      executionWallets:
+        persistedWallets.executionWallets && typeof persistedWallets.executionWallets === 'object'
+          ? persistedWallets.executionWallets
+          : {},
+      ownerLinkedWallet: data.ownerLinkedWallet || null,
       configPath: getProfileConfigPath(),
       nextSteps: response?.nextSteps || [],
     },
@@ -4002,6 +4033,7 @@ function inferActionProvider(action) {
     'get-hyperliquid-user-state': 'hyperliquid',
     'get-hyperliquid-open-orders': 'hyperliquid',
     'get-hyperliquid-setup-status': 'hyperliquid',
+    'get-hyperliquid-funding-status': 'hyperliquid',
     'get-hyperliquid-onboarding-plan': 'hyperliquid',
     'prepare-hyperliquid-onboarding': 'hyperliquid',
     'claim-hyperliquid-testnet-faucet': 'hyperliquid',

package/package.json

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