@reefclaw/openclaw-plugin 0.1.22 → 0.1.24

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,
+        });
+    }
+}

package/tools/intel-api.d.ts

@@ -26,7 +26,16 @@ export interface FetchOptions {
     method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
     body?: unknown;
     timeoutMs?: number;
+    /** Opt-in TTL cache for GET reads. The same intel endpoints get hit several
+     *  times per heartbeat by different callers (agent tool + microstructure
+     *  assembler + repeated agent calls) — a short shared TTL collapses those
+     *  into one round-trip. Never set on polling reads that must observe fresh
+     *  server state (e.g. backtest status). */
+    cacheTtlMs?: number;
 }
+/** Test support: drop every cached GET response (the cache is module-level,
+ *  so suites that stub fetch with per-test responses must clear it). */
+export declare function clearIntelGetCache(): void;
 /** Encode a value for safe use in a URL path segment */
 export declare const enc: typeof encodeURIComponent;
 export declare function fetchIntelApi(path: string, deps: IntelApiDeps, options?: FetchOptions): Promise<Record<string, unknown> | {

package/tools/intel-api.js

@@ -1,5 +1,6 @@
 // Shared helper for Intelligence API calls.
 // All intelligence tools use Bearer token auth against intel.reefclaw.com.
+import { keepAliveFetch } from '../http/keepalive-fetch.js';
 import { HL_INTEL_PREFIX, fromIntelSymbol, toIntelSymbol } from '../venues/symbols.js';
 // ─── Venue-aware intel-symbol mapping (plan §5.3: the agent keeps using
 //     canonical symbols like BTC/USDC; these helpers translate at the intel
@@ -67,6 +68,13 @@ export function intelSymbolOnVenue(deps, intelSymbol) {
     const isHl = intelSymbol.startsWith(HL_INTEL_PREFIX);
     return (deps.venue ?? 'binance') === 'hyperliquid' ? isHl : !isHl;
 }
+const getCache = new Map();
+const GET_CACHE_MAX_ENTRIES = 256;
+/** Test support: drop every cached GET response (the cache is module-level,
+ *  so suites that stub fetch with per-test responses must clear it). */
+export function clearIntelGetCache() {
+    getCache.clear();
+}
 /** Encode a value for safe use in a URL path segment */
 export const enc = encodeURIComponent;
 export async function fetchIntelApi(path, deps, options) {
@@ -78,6 +86,29 @@ export async function fetchIntelApi(path, deps, options) {
         return { error: 'No intelligence URL configured. Set intelligenceUrl in openclaw.json plugin config.' };
     }
     const url = `${intelligenceUrl}${path}`;
+    const ttl = options?.cacheTtlMs ?? 0;
+    if (ttl > 0 && (options?.method ?? 'GET') === 'GET') {
+        const key = `${connectionToken}:${url}`;
+        const hit = getCache.get(key);
+        if (hit && Date.now() - hit.at < ttl) {
+            // structuredClone: callers must never alias each other's response object.
+            return hit.value.then((v) => structuredClone(v));
+        }
+        const value = fetchIntelApiUncached(url, connectionToken, options);
+        getCache.set(key, { at: Date.now(), value });
+        // Failures don't stick for the TTL — next caller retries fresh.
+        void value.then((v) => { if (v && typeof v === 'object' && 'error' in v)
+            getCache.delete(key); }, () => getCache.delete(key));
+        if (getCache.size > GET_CACHE_MAX_ENTRIES) {
+            const oldest = getCache.keys().next().value;
+            if (oldest !== undefined)
+                getCache.delete(oldest);
+        }
+        return value.then((v) => structuredClone(v));
+    }
+    return fetchIntelApiUncached(url, connectionToken, options);
+}
+async function fetchIntelApiUncached(url, connectionToken, options) {
     const headers = { Authorization: `Bearer ${connectionToken}` };
     const fetchInit = {
         method: options?.method ?? 'GET',
@@ -89,7 +120,7 @@ export async function fetchIntelApi(path, deps, options) {
         fetchInit.body = JSON.stringify(options.body);
     }
     try {
-        const res = await fetch(url, fetchInit);
+        const res = await keepAliveFetch(url, fetchInit);
         if (res.status === 401) {
             return { error: 'Invalid or expired ReefClaw connection token.' };
         }

package/tools/record-position-reviews.js

@@ -94,7 +94,6 @@ export async function recordPositionReviewsTool(args, deps) {
     // not load-bearing (each row carries its own reviewAt).
     let filed = 0;
     if (deps.decisionsClient && deps.userId) {
-        const promises = [];
         for (const r of reviews) {
             const stateEntry = deps.stateStore?.get(r.symbol);
             const positionId = stateEntry?.webappPositionId;
@@ -137,7 +136,8 @@ export async function recordPositionReviewsTool(args, deps) {
                 deps.stateStore.recordReview(r.symbol, r.verdict, undefined, r.thesis_status);
             }
         }
-        await Promise.allSettled(promises);
+        // POSTs above are fire-and-forget by design — durability is the client's
+        // in-flight set + drain(), not an await here.
     }
     else {
         logger.info(TAG, `record_position_reviews validated ${reviews.length} reviews; no decisionsClient configured (off-mode).`);

package/tools/scan-pairs.js

@@ -129,8 +129,20 @@ function learningMatches(learning, setupType, regime) {
 }
 export async function scanPairsTool(args, deps, decisionsDeps) {
     const minScore = args.min_score ?? 4;
-    // 1. Fetch all symbol facts (cached, shared with get_setup_detail)
-    const factsRes = await getAllFactsCached(deps);
+    // Facts, strategies, and entry learnings are three independent reads (two
+    // intel, one webapp) — start them all now and await in the original order,
+    // so error precedence (facts → strategies → learnings-fail-quiet) and every
+    // early-return body stay byte-identical while the round-trips overlap.
+    const factsPromise = getAllFactsCached(deps);
+    const stratPromise = getStrategiesCached(deps);
+    const learningsPromise = decisionsDeps?.decisionsClient && decisionsDeps.userId
+        ? getEntryLearningsCached(decisionsDeps.decisionsClient, decisionsDeps.userId)
+        : Promise.resolve([]);
+    // An early return below must not leave a floating rejection behind.
+    stratPromise.catch(() => { });
+    learningsPromise.catch(() => { });
+    // 1. All symbol facts (cached, shared with get_setup_detail)
+    const factsRes = await factsPromise;
     if ('error' in factsRes)
         return factsRes;
     // Venue scope: only rank symbols this box can actually trade. Without this
@@ -154,8 +166,8 @@ export async function scanPairsTool(args, deps, decisionsDeps) {
                 : 'No symbol facts available. Intelligence service may still be computing initial data.',
         };
     }
-    // 2. Fetch user's active strategies (cached, shared with get_setup_detail)
-    const stratRes = await getStrategiesCached(deps);
+    // 2. User's active strategies (cached, shared with get_setup_detail)
+    const stratRes = await stratPromise;
     if ('error' in stratRes)
         return stratRes;
     const strategies = stratRes;
@@ -171,13 +183,10 @@ export async function scanPairsTool(args, deps, decisionsDeps) {
     }
     // 3. Evaluate all strategies against all facts
     const results = scanAllPairs(strategies, facts, minScore);
-    // 4. Fetch user's confirmed entry-time learnings (optional path — fail
-    //    quietly when the decisions client isn't wired, e.g. in dev or in
-    //    tests that exercise the pre-learning behaviour).
-    let entryLearnings = [];
-    if (decisionsDeps?.decisionsClient && decisionsDeps.userId) {
-        entryLearnings = await getEntryLearningsCached(decisionsDeps.decisionsClient, decisionsDeps.userId);
-    }
+    // 4. User's confirmed entry-time learnings (optional path — resolves []
+    //    when the decisions client isn't wired, e.g. in dev or in tests that
+    //    exercise the pre-learning behaviour).
+    const entryLearnings = await learningsPromise;
     const rankings = [];
     const vetoed = [];
     for (const r of results) {

package/types.d.ts

@@ -63,6 +63,13 @@ export interface CcxtPosition {
     contractSize: number;
     entryPrice: number;
     markPrice: number;
+    /** Paper only: true when NO quote was available for this symbol, so
+     *  `markPrice` is a fabricated fallback (entryPrice) rather than a real mark.
+     *  Consumers that make protective decisions MUST NOT read `markPrice` as
+     *  truth when this is set — a fabricated "flat since entry" mark reads as a
+     *  healthy position and is how a breached stop stayed invisible for 35h.
+     *  Undefined on live (real marks come from the exchange). */
+    markPriceStale?: boolean;
     notional: number;
     unrealizedPnl: number;
     percentage: number;