@reefclaw/openclaw-plugin 0.1.22 → 0.1.23

package/bridge/bridge.js

@@ -505,6 +505,44 @@ export class Bridge {
                 }
                 return;
             }
+            if (method === 'hl_submit_agent_approval') {
+                const provider = this.provider;
+                if (!provider.submitHlAgentApproval) {
+                    this.connector.sendResponse(id, true, {
+                        ok: false,
+                        message: 'Provider does not support hl_submit_agent_approval (likely mock provider)',
+                    });
+                    return;
+                }
+                const action = params?.action;
+                const nonce = params?.nonce;
+                const signature = params?.signature;
+                if (!action || typeof action !== 'object' ||
+                    typeof nonce !== 'number' ||
+                    !signature || typeof signature.r !== 'string' || typeof signature.s !== 'string' ||
+                    typeof signature.v !== 'number') {
+                    this.connector.sendResponse(id, false, undefined, {
+                        code: 400,
+                        message: 'hl_submit_agent_approval requires { action, nonce, signature:{r,s,v} }',
+                    });
+                    return;
+                }
+                // The plugin re-validates strictly (approveAgent only, own agent
+                // address only) — this layer just shape-checks and forwards.
+                audit('hl_submit_agent_approval.start', {
+                    id,
+                    chain: action.hyperliquidChain,
+                    agentAddress: action.agentAddress,
+                });
+                const outcome = await provider.submitHlAgentApproval({
+                    action: action,
+                    nonce,
+                    signature: { r: signature.r, s: signature.s, v: signature.v },
+                });
+                audit('hl_submit_agent_approval.complete', { id, ok: outcome.ok, hlStatus: outcome.hlStatus });
+                this.connector.sendResponse(id, true, outcome);
+                return;
+            }
             if (method === 'hl_agent_wallet_status') {
                 const provider = this.provider;
                 if (!provider.getHlAgentWalletStatus) {

package/bridge/gateway/tool-discovery.d.ts

@@ -3,7 +3,7 @@ import { GatewayHttpClient, GatewayHttpError } from './gateway-http-client.js';
  * Logical tool names used by ReefClaw internally.
  * Each maps to one or more candidate actual tool names on the gateway.
  */
-export type LogicalTool = 'fetch_ticker' | 'fetch_balance' | 'fetch_ohlcv' | 'fetch_positions' | 'fetch_open_orders' | 'cancel_all_orders' | 'cancel_order' | 'close_position' | 'create_order' | 'get_market_structure' | 'get_crypto_metrics' | 'get_market_intel' | 'set_trading_mode' | 'set_exchange_credentials' | 'test_exchange_credentials' | 'clear_exchange_credentials' | 'hl_provision_agent_wallet' | 'hl_agent_wallet_status' | 'get_bracket_config' | 'set_bracket_requirement';
+export type LogicalTool = 'fetch_ticker' | 'fetch_balance' | 'fetch_ohlcv' | 'fetch_positions' | 'fetch_open_orders' | 'cancel_all_orders' | 'cancel_order' | 'close_position' | 'create_order' | 'get_market_structure' | 'get_crypto_metrics' | 'get_market_intel' | 'set_trading_mode' | 'set_exchange_credentials' | 'test_exchange_credentials' | 'clear_exchange_credentials' | 'hl_provision_agent_wallet' | 'hl_agent_wallet_status' | 'hl_submit_agent_approval' | 'get_bracket_config' | 'set_bracket_requirement';
 /**
  * Build the test args used when probing each logical tool.
  *

package/bridge/gateway/tool-discovery.js

@@ -22,6 +22,7 @@ const OPTIONAL_TOOLS = [
     'clear_exchange_credentials',
     'hl_provision_agent_wallet',
     'hl_agent_wallet_status',
+    'hl_submit_agent_approval',
     'get_bracket_config',
     'set_bracket_requirement',
 ];
@@ -48,6 +49,7 @@ const CANDIDATES = {
     clear_exchange_credentials: ['clear_exchange_credentials'],
     hl_provision_agent_wallet: ['hl_provision_agent_wallet'],
     hl_agent_wallet_status: ['hl_agent_wallet_status'],
+    hl_submit_agent_approval: ['hl_submit_agent_approval'],
     get_bracket_config: ['get_bracket_config'],
     set_bracket_requirement: ['set_bracket_requirement'],
 };
@@ -119,6 +121,8 @@ export function buildProbeArgs(symbol = DEFAULT_PROBE_SYMBOL) {
         // timeout and mark the tool missing forever).
         hl_provision_agent_wallet: { walletAddress: '' },
         hl_agent_wallet_status: { probe: true },
+        // Same dedicated probe path: a real submit would POST to Hyperliquid.
+        hl_submit_agent_approval: { probe: true },
         // Bracket-config probes: no-arg read; set with an invalid flag triggers early-return.
         get_bracket_config: {},
         set_bracket_requirement: { flag: '__probe__', value: false },

package/bridge/provider.d.ts

@@ -39,6 +39,15 @@ export interface HlProvisionOutcome {
     currentVenue?: string;
     currentMode?: string;
 }
+/** Result of hl_submit_agent_approval — the box relays the wallet-signed
+ *  approveAgent action to Hyperliquid (browsers are often blocked). */
+export interface HlSubmitApprovalOutcome {
+    ok: boolean;
+    message: string;
+    hlStatus?: string;
+    chain?: string;
+    agentAddress?: string;
+}
 /** Result of hl_agent_wallet_status — approval polling for the guided flow. */
 export interface HlAgentWalletStatusOutcome {
     ok: boolean;
@@ -196,6 +205,18 @@ export interface OpenClawProvider {
     /** Operator-only: approval/balance status of the box's provisioned HL agent
      *  wallet (polled by the dashboard's guided flow after the wallet signature). */
     getHlAgentWalletStatus?(): Promise<HlAgentWalletStatusOutcome>;
+    /** Operator-only: submit the wallet-signed approveAgent action to
+     *  Hyperliquid FROM THE BOX. Carries no secret — only a signature the
+     *  operator's wallet already produced. */
+    submitHlAgentApproval?(args: {
+        action: Record<string, unknown>;
+        nonce: number;
+        signature: {
+            r: string;
+            s: string;
+            v: number;
+        };
+    }): Promise<HlSubmitApprovalOutcome>;
     /** Operator-only: remove stored credentials from the plugin config and
      *  de-escalate to PAPER mode if currently running in a live mode. */
     clearExchangeCredentials?(): Promise<{

package/bridge/providers/gateway.d.ts

@@ -1,4 +1,4 @@
-import type { OpenClawProvider, ProviderEvents, ProviderEventName, ExchangeCredentialsRequest, HlProvisionOutcome, HlAgentWalletStatusOutcome } from '../provider.js';
+import type { OpenClawProvider, ProviderEvents, ProviderEventName, ExchangeCredentialsRequest, HlProvisionOutcome, HlAgentWalletStatusOutcome, HlSubmitApprovalOutcome } from '../provider.js';
 import type { EmergencyAction, ReconciliationSnapshot, TradingMode } from '../types.js';
 import type { GatewayConfig } from '../gateway/gateway-config.js';
 import { type GetBracketConfigOutcome, type SetBracketRequirementOutcome, type BracketRequirementFlag, type SetTradingModeOutcome, type SetExchangeCredentialsOutcome, type TestExchangeCredentialsOutcome, type ClearExchangeCredentialsOutcome } from './onboarding-commands.js';
@@ -229,6 +229,16 @@ export declare class GatewayProvider implements OpenClawProvider {
         regenerate?: boolean;
         confirm_venue_switch?: boolean;
     }): Promise<HlProvisionOutcome>;
+    /** Operator-only. Relay the wallet-signed approveAgent action from the box. */
+    submitHlAgentApproval(args: {
+        action: Record<string, unknown>;
+        nonce: number;
+        signature: {
+            r: string;
+            s: string;
+            v: number;
+        };
+    }): Promise<HlSubmitApprovalOutcome>;
     /** Operator-only. Approval/balance status of the provisioned HL wallet. */
     getHlAgentWalletStatus(): Promise<HlAgentWalletStatusOutcome>;
     /** Operator-only. Read the current bracket-orders config from the plugin. */

package/bridge/providers/gateway.js

@@ -17,7 +17,7 @@ import { ensureHeartbeatCron, isHeartbeatLikeName } from '../gateway/heartbeat-c
 import { parseIdentityName } from '../utils/identity-name.js';
 import { computeEquity as _computeEquity, computePositionNotional as _computePositionNotional, computeRiskMetrics as _computeRiskMetrics, DEFAULT_RISK_LIMITS, DRAWDOWN_ZONE_THRESHOLDS, TENANT_LIMIT_BOUNDS, boundedNum, validateDrawdownLadder, } from './risk-calculator.js';
 import { executeKill as _executeKill, executeFlatten as _executeFlatten, executePause as _executePause, executeResume as _executeResume, } from './emergency-commands.js';
-import { executeSetTradingMode, executeGetBracketConfig, executeSetBracketRequirement, executeSetExchangeCredentials, executeTestExchangeCredentials, executeClearExchangeCredentials, executeProvisionHlAgentWallet, executeHlAgentWalletStatus, } from './onboarding-commands.js';
+import { executeSetTradingMode, executeGetBracketConfig, executeSetBracketRequirement, executeSetExchangeCredentials, executeTestExchangeCredentials, executeClearExchangeCredentials, executeProvisionHlAgentWallet, executeHlAgentWalletStatus, executeSubmitHlAgentApproval, } from './onboarding-commands.js';
 const TAG = 'gateway';
 // ---- Day-start NAV persistence ----
 // Persists sessionStartNav (the UTC-day P&L anchor) per date so Day P&L
@@ -705,6 +705,10 @@ export class GatewayProvider {
     async provisionHlAgentWallet(args) {
         return executeProvisionHlAgentWallet({ http: this.http, toolMap: this.toolMap, operatorToken: this.config.connectionToken }, args);
     }
+    /** Operator-only. Relay the wallet-signed approveAgent action from the box. */
+    async submitHlAgentApproval(args) {
+        return executeSubmitHlAgentApproval({ http: this.http, toolMap: this.toolMap, operatorToken: this.config.connectionToken }, args);
+    }
     /** Operator-only. Approval/balance status of the provisioned HL wallet. */
     async getHlAgentWalletStatus() {
         return executeHlAgentWalletStatus({

package/bridge/providers/onboarding-commands.d.ts

@@ -1,6 +1,6 @@
 import type { GatewayHttpClient } from '../gateway/gateway-http-client.js';
 import type { ToolMap } from '../gateway/tool-discovery.js';
-import type { ExchangeCredentialsRequest, HlProvisionOutcome, HlAgentWalletStatusOutcome } from '../provider.js';
+import type { ExchangeCredentialsRequest, HlProvisionOutcome, HlAgentWalletStatusOutcome, HlSubmitApprovalOutcome } from '../provider.js';
 import type { TradingMode } from '@reefclaw/shared';
 export interface SetTradingModeOutcome {
     ok: boolean;
@@ -116,6 +116,17 @@ export declare function executeProvisionHlAgentWallet(ctx: OnboardingContext, ar
     regenerate?: boolean;
     confirm_venue_switch?: boolean;
 }): Promise<HlProvisionOutcome>;
+/** Forward an hl_submit_agent_approval invocation to the plugin. The payload
+ *  is a signature the operator's wallet produced — no secret material. */
+export declare function executeSubmitHlAgentApproval(ctx: OnboardingContext, args: {
+    action: Record<string, unknown>;
+    nonce: number;
+    signature: {
+        r: string;
+        s: string;
+        v: number;
+    };
+}): Promise<HlSubmitApprovalOutcome>;
 /** Forward an hl_agent_wallet_status invocation to the plugin. Read-only. */
 export declare function executeHlAgentWalletStatus(ctx: OnboardingContext): Promise<HlAgentWalletStatusOutcome>;
 /** Forward a set_exchange_credentials invocation to the plugin via HTTP.

package/bridge/providers/onboarding-commands.js

@@ -254,6 +254,31 @@ export async function executeProvisionHlAgentWallet(ctx, args) {
         return { ok: false, message: reason, venue: 'hyperliquid', mode: 'PAPER' };
     }
 }
+/** Forward an hl_submit_agent_approval invocation to the plugin. The payload
+ *  is a signature the operator's wallet produced — no secret material. */
+export async function executeSubmitHlAgentApproval(ctx, args) {
+    const tool = ctx.toolMap.hl_submit_agent_approval;
+    if (!tool || !ctx.http) {
+        return {
+            ok: false,
+            message: 'hl_submit_agent_approval tool not available on gateway — update the ReefClaw plugin (npx @reefclaw/connect@latest)',
+        };
+    }
+    try {
+        const result = await ctx.http.invoke(tool, {
+            action: args.action,
+            nonce: args.nonce,
+            signature: args.signature,
+            operator_token: ctx.operatorToken,
+        });
+        return result.data;
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        logger.error(TAG, `hl_submit_agent_approval failed: ${reason}`);
+        return { ok: false, message: reason };
+    }
+}
 /** Forward an hl_agent_wallet_status invocation to the plugin. Read-only. */
 export async function executeHlAgentWalletStatus(ctx) {
     const tool = ctx.toolMap.hl_agent_wallet_status;

package/bridge/types.d.ts

@@ -3,7 +3,7 @@ export type { Channel, RequestFrame, ResponseFrame, EventFrame, Frame, Emergency
 export { VALID_CHANNELS, VALID_EMERGENCY_ACTIONS } from '@reefclaw/shared';
 type EventFrame = _EventFrame;
 /** Methods the skill accepts from the relay (browser → skill) */
-export declare const ALLOWED_METHODS: readonly ["emergency.kill", "emergency.flatten", "emergency.pause", "emergency.resume", "reconcile", "chat.send", "skill.update", "close_position", "set_trading_mode", "set_exchange_credentials", "test_exchange_credentials", "clear_exchange_credentials", "hl_provision_agent_wallet", "hl_agent_wallet_status", "get_bracket_config", "set_bracket_requirement"];
+export declare const ALLOWED_METHODS: readonly ["emergency.kill", "emergency.flatten", "emergency.pause", "emergency.resume", "reconcile", "chat.send", "skill.update", "close_position", "set_trading_mode", "set_exchange_credentials", "test_exchange_credentials", "clear_exchange_credentials", "hl_provision_agent_wallet", "hl_agent_wallet_status", "hl_submit_agent_approval", "get_bracket_config", "set_bracket_requirement"];
 /** Subset of ALLOWED_METHODS that require operator.write scope. The bridge
  *  enforces this before dispatching — a session without the scope gets a
  *  403 error. PR2 ships the scope as session-wide (inherited from the Clerk

package/bridge/types.js

@@ -21,6 +21,7 @@ export const ALLOWED_METHODS = [
     // Hyperliquid guided onboarding (box-generated agent wallet) — operator.write-gated.
     'hl_provision_agent_wallet',
     'hl_agent_wallet_status',
+    'hl_submit_agent_approval',
     // Bracket-orders config (Phase 3.5b) — operator.write-gated.
     'get_bracket_config',
     'set_bracket_requirement',
@@ -38,6 +39,7 @@ export const OPERATOR_WRITE_METHODS = new Set([
     'clear_exchange_credentials',
     'hl_provision_agent_wallet',
     'hl_agent_wallet_status',
+    'hl_submit_agent_approval',
     'get_bracket_config',
     'set_bracket_requirement',
     'emergency.kill',

package/config/tool-gate.js

@@ -35,6 +35,7 @@ export const UNGOVERNABLE_TOOLS = new Set([
     // operator-only channel; disabling them would strand the HL setup flow.
     'hl_provision_agent_wallet',
     'hl_agent_wallet_status',
+    'hl_submit_agent_approval',
 ]);
 /** RC_TOOL_GATE: 'off' = kill-switch (gate never blocks), 'shadow' = log
  *  would-be blocks but execute anyway, anything else/default = 'enforce'.

package/index.js

@@ -68,6 +68,7 @@ import { testExchangeCredentialsTool } from './tools/test-exchange-credentials.j
 import { clearExchangeCredentialsTool } from './tools/clear-exchange-credentials.js';
 import { hlProvisionAgentWalletTool } from './tools/hl-provision-agent-wallet.js';
 import { hlAgentWalletStatusTool } from './tools/hl-agent-wallet-status.js';
+import { hlSubmitAgentApprovalTool } from './tools/hl-submit-agent-approval.js';
 import { ensureCredentialTransportKey } from './security/sealed-credentials.js';
 // Tool implementations
 import { fetchTickerTool } from './tools/fetch-ticker.js';
@@ -850,6 +851,16 @@ const TOOL_PARAMS = {
             probe: { type: 'boolean', description: 'Tool-discovery probe — returns immediately without config or network access' },
         },
     },
+    hl_submit_agent_approval: {
+        type: 'object',
+        properties: {
+            operator_token: { type: 'string', description: 'Operator provenance — injected automatically by the ReefClaw dashboard path. Agent-initiated calls are refused without it.' },
+            action: { type: 'object', description: "The wallet-signed approveAgent action, verbatim. Only type='approveAgent' is accepted." },
+            nonce: { type: 'number', description: 'Outer nonce — must equal action.nonce (user-signed actions carry one nonce)' },
+            signature: { type: 'object', description: 'Wallet signature { r, s, v } over the approveAgent typed data' },
+            probe: { type: 'boolean', description: 'Tool-discovery probe — returns immediately without config or network access' },
+        },
+    },
     clear_exchange_credentials: {
         type: 'object',
         properties: {
@@ -2726,6 +2737,20 @@ const paperTradingPlugin = {
                     return jsonResult(await hlProvisionAgentWalletTool(params, { runtime, bootVenue: venue }));
                 },
             },
+            {
+                name: 'hl_submit_agent_approval',
+                label: 'Submit Hyperliquid Agent Approval',
+                description: "Operator-only. Submit the operator's wallet-signed approveAgent action to Hyperliquid FROM THIS MACHINE (the dashboard browser is often blocked from reaching the exchange API by ad-blockers/shields). Strictly limited to type='approveAgent' targeting this box's own provisioned agent wallet — it is not a general signed-action relay. Refused without dashboard operator provenance.",
+                parameters: TOOL_PARAMS.hl_submit_agent_approval,
+                execute: async (_id, params) => {
+                    if (params?.probe === true)
+                        return jsonResult(await hlSubmitAgentApprovalTool(params));
+                    const prov = verifyOperatorProvenance(params.operator_token);
+                    if (!prov.ok)
+                        return jsonResult({ error: prov.error });
+                    return jsonResult(await hlSubmitAgentApprovalTool(params));
+                },
+            },
             {
                 name: 'hl_agent_wallet_status',
                 label: 'Hyperliquid Agent Wallet Status',

package/openclaw.plugin.json

@@ -1,7 +1,7 @@
 {
   "id": "reefclaw-paper-trading",
   "name": "ReefClaw Trading",
-  "version": "0.1.22",
+  "version": "0.1.23",
   "description": "Supervised trading plugin for the ReefClaw dashboard. It runs on YOUR machine and starts in PAPER mode with no API keys. It cannot trade real funds until you supply exchange credentials and step PAPER→MICRO_LIVE→LIVE yourself from the dashboard — the agent cannot make that change (the tool is refused without operator provenance). Exchange keys stay local, are used only to sign requests to the exchange, and are never transmitted to ReefClaw (asserted by a test in this package). Trading telemetry — positions, fills, decision journal — is sent to ReefClaw to render the dashboard. Every live position carries exchange-native protective stops. Remote updates to the agent's trading instructions are applied only after an Ed25519 signature is verified against a public key pinned in this build.",
   "author": "ReefClaw",
   "activation": {
@@ -72,6 +72,7 @@
       "clear_exchange_credentials",
       "hl_provision_agent_wallet",
       "hl_agent_wallet_status",
+      "hl_submit_agent_approval",
       "get_bracket_config",
       "set_bracket_requirement"
     ]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reefclaw/openclaw-plugin",
-  "version": "0.1.22",
+  "version": "0.1.23",
   "description": "ReefClaw supervised trading plugin for OpenClaw. Runs entirely on YOUR machine and starts in PAPER mode \u00e2\u20ac\u201d it cannot trade real funds until you supply exchange credentials and walk the PAPER\u00e2\u2020\u2019MICRO_LIVE\u00e2\u2020\u2019LIVE ladder yourself from the ReefClaw dashboard (the agent cannot make that change; it is refused without operator provenance). Your exchange API keys stay on your machine to sign requests to the exchange and are NEVER sent to ReefClaw \u00e2\u20ac\u201d a test in the package asserts this. What does reach ReefClaw is trading telemetry for the dashboard (positions, fills, decision journal). Live trading always carries exchange-native protective stops. Trading instructions can be updated remotely, and every update must carry a valid Ed25519 signature verified against a key pinned in this build before it is applied. Install: /plugins install clawhub:@reefclaw/openclaw-plugin",
   "type": "module",
   "main": "index.js",

package/tools/hl-provision-agent-wallet.js

@@ -96,6 +96,24 @@ export async function hlProvisionAgentWalletTool(args, deps) {
         const derived = await deriveAddressFromPrivateKey(existingKey);
         if (derived.ok) {
             const masterMatches = existingMaster != null && existingMaster.toLowerCase() === walletAddress.toLowerCase();
+            // ★ Honour a CHANGED network on the resume path. The same keypair is
+            // valid on both Hyperliquid networks, so switching mainnet<->testnet
+            // must not require regenerating the wallet — but the stored flag has to
+            // follow, or the box boots against the network the operator did NOT
+            // pick. Before this, unticking "Use Hyperliquid testnet" after
+            // provisioning silently kept testnet:true, and the approval was signed
+            // for Testnet while the operator believed they were on mainnet
+            // (observed live 2026-08-03).
+            if (masterMatches && existingTestnet !== testnet) {
+                try {
+                    updatePluginConfig({ exchange: buildVenueExchangeConfig(existingExchange, 'hyperliquid', {}, testnet) }, deps.configPath);
+                    existingTestnet = testnet;
+                    logger.info(TAG, `network switched to ${testnet ? 'TESTNET' : 'MAINNET'} (same agent wallet)`);
+                }
+                catch (err) {
+                    logger.warn(TAG, `could not persist network change: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
             return {
                 ok: true,
                 message: masterMatches

package/tools/hl-submit-agent-approval.d.ts

@@ -0,0 +1,27 @@
+export interface HlSubmitAgentApprovalArgs {
+    /** The approveAgent action, byte-identical to what the wallet signed. */
+    action?: Record<string, unknown>;
+    /** Outer nonce — for user-signed actions it must equal action.nonce. */
+    nonce?: number;
+    signature?: {
+        r?: unknown;
+        s?: unknown;
+        v?: unknown;
+    };
+    /** Tool-discovery probe — returns immediately, no config or network. */
+    probe?: boolean;
+}
+export interface HlSubmitAgentApprovalResult {
+    ok: boolean;
+    message: string;
+    /** Hyperliquid's own status string when it answered ('ok' | 'err'). */
+    hlStatus?: string;
+    /** Which network the SIGNED action targeted. */
+    chain?: 'Mainnet' | 'Testnet';
+    agentAddress?: string;
+}
+export interface HlSubmitAgentApprovalDeps {
+    configPath?: string;
+    fetchImpl?: typeof fetch;
+}
+export declare function hlSubmitAgentApprovalTool(args: HlSubmitAgentApprovalArgs, deps?: HlSubmitAgentApprovalDeps): Promise<HlSubmitAgentApprovalResult>;

package/tools/hl-submit-agent-approval.js

@@ -0,0 +1,140 @@
+// hl_submit_agent_approval — operator-only plugin tool.
+//
+// Submits the operator's WALLET-SIGNED `approveAgent` action to Hyperliquid
+// from THIS BOX, instead of from the dashboard's browser.
+//
+// ★ Why the box and not the browser (real failure, 2026-08-03): the guided
+// flow POSTed to api.hyperliquid*.xyz directly from the dashboard page and an
+// operator hit "Failed to fetch" twice. The endpoint was fine (CORS is `*`,
+// POSTs answer normally) and the box reached it in 0.49s — the request was
+// blocked INSIDE the browser (ad-blocker / shield / DNS policy; crypto API
+// domains are routinely blocked). Making a required onboarding step depend on
+// the operator's browser extensions is the wrong architecture: the box is
+// already the Hyperliquid client (every read and every future order goes
+// through it), so it submits. The browser's only irreplaceable job is holding
+// the wallet and producing the signature. ReefClaw's servers stay out of the
+// path — the signed action travels over the existing relay to the user's own
+// machine.
+//
+// ★ SECURITY — this is deliberately NOT a generic signed-action relay.
+// A tool that forwarded any {action, signature} pair to /exchange would be a
+// capability escalation: HL's withdraw / usdSend / usdClassTransfer are all
+// user-signed actions in the same envelope shape. If a signature for one of
+// those ever existed, a generic relay would happily submit it. So:
+//   1. `action.type` MUST be exactly 'approveAgent' — nothing else is accepted.
+//   2. `action.agentAddress` MUST be the address THIS box's provisioned agent
+//      key controls, so the tool can only ever authorize our own wallet.
+//   3. The endpoint is chosen from the SIGNED action's `hyperliquidChain`, so
+//      it cannot be pointed at a different network than the one signed for.
+// The signature itself is produced and validated by Hyperliquid; we never
+// touch key material here (the agent key is only used to DERIVE its public
+// address for check 2).
+import { readPluginConfig } from '../config/plugin-config-io.js';
+import { deriveAddressFromPrivateKey, isHexAddress, sameAddress } from '../venues/hyperliquid/hl-agent-wallet.js';
+import { hlApiBase } from '../venues/hyperliquid/hl-preflight.js';
+import { logger } from '../logger.js';
+const TAG = 'hl-submit-agent-approval';
+function fail(message, extra = {}) {
+    return { ok: false, message, ...extra };
+}
+export async function hlSubmitAgentApprovalTool(args, deps = {}) {
+    if (args?.probe === true) {
+        return { ok: false, message: 'probe' };
+    }
+    const action = args?.action;
+    if (!action || typeof action !== 'object') {
+        return fail('action is required (the approveAgent object the wallet signed)');
+    }
+    // 1. Only ever approveAgent — never a generic relay (see header).
+    if (action.type !== 'approveAgent') {
+        logger.warn(TAG, `refused non-approveAgent action type: ${String(action.type)}`);
+        return fail(`Refused: this tool only submits 'approveAgent' actions, not '${String(action.type)}'.`);
+    }
+    const chain = action.hyperliquidChain;
+    if (chain !== 'Mainnet' && chain !== 'Testnet') {
+        return fail("action.hyperliquidChain must be 'Mainnet' or 'Testnet'");
+    }
+    const agentAddress = action.agentAddress;
+    if (!isHexAddress(agentAddress)) {
+        return fail('action.agentAddress must be a 0x… address', { chain });
+    }
+    const sig = args?.signature;
+    const r = sig?.r;
+    const s = sig?.s;
+    const v = sig?.v;
+    if (typeof r !== 'string' || typeof s !== 'string' || typeof v !== 'number') {
+        return fail('signature must be { r: string, s: string, v: number }', { chain });
+    }
+    const nonce = args?.nonce;
+    // User-signed actions carry ONE nonce — the outer value must match the one
+    // inside the signed payload, or HL verifies a different message than we send.
+    if (typeof nonce !== 'number' || nonce !== action.nonce) {
+        return fail('nonce must be a number equal to action.nonce', { chain });
+    }
+    // 2. The agent being approved must be OUR provisioned wallet.
+    let storedKey;
+    try {
+        const cfg = readPluginConfig(deps.configPath);
+        if (typeof cfg.exchange?.agentPrivateKey === 'string')
+            storedKey = cfg.exchange.agentPrivateKey;
+    }
+    catch {
+        // fall through to the not-provisioned error
+    }
+    if (!storedKey) {
+        return fail('No Hyperliquid agent wallet is provisioned on this machine — run the guided setup first.', { chain });
+    }
+    const derived = await deriveAddressFromPrivateKey(storedKey);
+    if (!derived.ok) {
+        return fail('Could not derive this machine’s agent wallet address — cannot verify what is being approved.', { chain });
+    }
+    if (!sameAddress(derived.address, agentAddress)) {
+        logger.warn(TAG, 'refused: action.agentAddress is not this box’s provisioned agent');
+        return fail('Refused: the approval targets a different agent wallet than the one provisioned on this machine.', { chain, agentAddress: derived.address });
+    }
+    // 3. Submit — endpoint from the SIGNED chain, never from local config.
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const url = `${hlApiBase(chain === 'Testnet')}/exchange`;
+    logger.info(TAG, `submitting approveAgent for ${agentAddress} to ${chain}`);
+    try {
+        const res = await fetchImpl(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ action, nonce, signature: { r, s, v } }),
+            signal: AbortSignal.timeout(20_000),
+        });
+        const text = await res.text();
+        let body = null;
+        try {
+            body = JSON.parse(text);
+        }
+        catch {
+            // non-JSON — surfaced verbatim below
+        }
+        if (!res.ok || body?.status !== 'ok') {
+            const detail = typeof body?.response === 'string' ? body.response : text.slice(0, 300) || `HTTP ${res.status}`;
+            logger.warn(TAG, `Hyperliquid rejected the approval: ${detail}`);
+            return fail(`Hyperliquid rejected the approval: ${detail}`, {
+                hlStatus: body?.status,
+                chain,
+                agentAddress: derived.address,
+            });
+        }
+        logger.info(TAG, `approveAgent accepted by Hyperliquid (${chain})`);
+        return {
+            ok: true,
+            message: `Approval submitted and accepted by Hyperliquid (${chain}).`,
+            hlStatus: 'ok',
+            chain,
+            agentAddress: derived.address,
+        };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        logger.error(TAG, `submit failed: ${msg}`);
+        return fail(`Could not reach Hyperliquid from this machine: ${msg}`, {
+            chain,
+            agentAddress: derived.address,
+        });
+    }
+}