@thirdfy/agent-cli 0.1.39 → 0.1.41

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable changes to `@thirdfy/agent-cli` are documented here. The format is b
 
 ## [Unreleased]
 
+## [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
+
+- Email login and bootstrap commands now persist agent credentials from nested API response shapes such as `registration.registration.agentApiKey`, so owner-session onboarding can resolve the hidden execution identity without requiring users to pass a raw agent API key manually.
+
 ## [0.1.39] - 2026-05-17
 
 ### Added

package/README.md

@@ -42,7 +42,7 @@ npx @thirdfy/agent-cli --help
 
 ## Release notes
 
-Version history and highlights: [CHANGELOG.md](./CHANGELOG.md). **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.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.
 
@@ -170,6 +170,7 @@ Auth expectations by mode:
 - `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.
+- 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 **v3.4.23+** signs from the funded owner wallet when possible; otherwise it returns **`MANUAL_BRIDGE2_DEPOSIT_REQUIRED`** with `fundedWallet` and `executionWalletAddress`.
 - custody mode defaults are profile-aware:
   - `managed` default for `thirdfy`
   - `external` default for `self` and `hybrid`

package/bin/thirdfy-agent.mjs

@@ -113,6 +113,43 @@ function buildTopLevelOnboardingHint(payload) {
   return null;
 }
 
+function extractAgentApiKey(value) {
+  if (!value || typeof value !== 'object') return '';
+  const candidates = [
+    value.agentApiKey,
+    value.apiKey,
+    value.data?.agentApiKey,
+    value.data?.apiKey,
+    value.bootstrap?.agentApiKey,
+    value.bootstrap?.apiKey,
+    value.registration?.agentApiKey,
+    value.registration?.apiKey,
+    value.registration?.registration?.agentApiKey,
+    value.registration?.registration?.apiKey,
+    value.data?.registration?.agentApiKey,
+    value.data?.registration?.apiKey,
+    value.data?.registration?.registration?.agentApiKey,
+    value.data?.registration?.registration?.apiKey,
+  ];
+  return String(candidates.find((candidate) => String(candidate || '').trim()) || '').trim();
+}
+
+function extractAgentKey(value) {
+  if (!value || typeof value !== 'object') return '';
+  const candidates = [
+    value.agentKey,
+    value.data?.agentKey,
+    value.bootstrap?.agentKey,
+    value.registration?.agentKey,
+    value.registration?.registration?.agentKey,
+    value.data?.registration?.agentKey,
+    value.data?.registration?.registration?.agentKey,
+    value.owner?.creatorWallet,
+    value.data?.owner?.creatorWallet,
+  ];
+  return String(candidates.find((candidate) => String(candidate || '').trim()) || '').trim();
+}
+
 async function main() {
   const profileState = resolveProfileState(globalFlags);
   context.profile = profileState.profile;
@@ -446,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',
@@ -456,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',
@@ -469,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.',
@@ -496,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"}\'',
     };
@@ -1874,6 +1918,8 @@ async function commandDeveloperBootstrap(ctx, flags, capabilities) {
     { ...registerFlags, __suppressOutput: true },
     capabilities
   );
+  const agentApiKey = extractAgentApiKey(registerResponse || {});
+  const responseAgentKey = extractAgentKey(registerResponse || {}) || agentKey;
 
   const config = loadProfileConfig();
   const next = {
@@ -1890,6 +1936,13 @@ async function commandDeveloperBootstrap(ctx, flags, capabilities) {
       bootstrapCompletedAt: new Date().toISOString(),
     },
   };
+  if (agentApiKey || responseAgentKey) {
+    next.agent = {
+      ...(config.agent && typeof config.agent === 'object' ? config.agent : {}),
+      ...(agentApiKey ? { apiKey: agentApiKey } : {}),
+      ...(responseAgentKey ? { agentKey: responseAgentKey } : {}),
+    };
+  }
   persistProfileConfig(next);
   if (!flags.__suppressOutput) {
     printEnvelope({
@@ -2154,6 +2207,19 @@ async function commandBootstrapComplete(ctx, flags, capabilities) {
       capabilities
     );
   }
+  const registrationAgentApiKey = extractAgentApiKey(registration || {});
+  const registrationAgentKey = extractAgentKey(registration || {}) || agentKey;
+  if (registrationAgentApiKey || registrationAgentKey) {
+    const latest = loadProfileConfig();
+    persistProfileConfig({
+      ...latest,
+      agent: {
+        ...(latest.agent && typeof latest.agent === 'object' ? latest.agent : {}),
+        ...(registrationAgentApiKey ? { apiKey: registrationAgentApiKey } : {}),
+        ...(registrationAgentKey ? { agentKey: registrationAgentKey } : {}),
+      },
+    });
+  }
 
   printEnvelope({
     success: true,
@@ -2901,8 +2967,8 @@ async function commandLoginEmail(ctx, flags) {
   const data = response?.data || response || {};
   const ownerSessionToken = String(data.ownerSessionToken || '').trim();
   const bootstrap = data.bootstrap && typeof data.bootstrap === 'object' ? data.bootstrap : {};
-  const agentApiKey = String(bootstrap.agentApiKey || '').trim();
-  const agentKey = String(bootstrap.agentKey || data.owner?.creatorWallet || '').trim();
+  const agentApiKey = extractAgentApiKey(data);
+  const agentKey = extractAgentKey(data);
   const wallets = data.wallets && typeof data.wallets === 'object' ? data.wallets : {};
   const userDid = String(data.owner?.creatorDid || wallets.userDid || '').trim();
   const primaryEvmWallet = String(wallets.primaryEvmWallet || data.owner?.creatorWallet || '').trim();
@@ -3943,6 +4009,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.39",
+  "version": "0.1.41",
   "description": "Thirdfy Agent CLI for onboarding, governance preflight, execute-intent, and status polling.",
   "type": "module",
   "bin": {