@reefclaw/connect 0.1.30 → 0.1.31

package/assets/plugin/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/assets/plugin/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/assets/plugin/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/assets/plugin/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/assets/plugin/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;

package/assets/shared/readiness.js

@@ -33,7 +33,11 @@ export const READINESS_CHECK_COPY = {
     clock_in_sync: {
         label: 'Host clock in sync',
         phase: 'connect',
-        fixHint: 'The host clock drifts from Binance server time. Enable NTP/chrony so signed orders are not rejected (-1021).',
+        // Venue-neutral on purpose: the same check runs on a Hyperliquid box,
+        // where naming Binance is a false alarm for an exchange the user does not
+        // use. Both venues reject/miscompute signed requests on a skewed clock
+        // (Binance -1021 recvWindow; Hyperliquid signs an epoch-ms nonce).
+        fixHint: 'The host clock drifts from your exchange’s server time. Enable NTP/chrony so signed orders are not rejected (Binance rejects with -1021; Hyperliquid nonces are epoch-ms and must not skew).',
     },
     plugin_loaded: {
         label: 'ReefClaw plugin loaded',

package/dist/cli.js

@@ -15,7 +15,7 @@ import { installBridge } from './bridge.js';
 import { installSkill } from './skill.js';
 import { enableConnectorSupervisor } from './supervisor-config.js';
 import { tuneGatewayMemory } from './gateway-tuning.js';
-import { checkGateway, checkBinanceRegion } from './validate.js';
+import { checkGateway, checkBinanceRegion, checkHyperliquidRegion } from './validate.js';
 import { readConfig, writeConfig, mergeReefClawConfig, gatewayAuthAlreadyRelaxed, openClawInstalled, openClawConfigPath, readGatewayPort, } from './openclaw.js';
 import { run, which } from './exec.js';
 import { step, ok, info, warn, fail, banner, bold, green, cyan, dim } from './ui.js';
@@ -136,13 +136,34 @@ function nextSteps() {
         `  3. The dashboard lights up ${green('green / Connected')} on its own within a few seconds.\n\n` +
         dim(`Dashboard: ${DASHBOARD}\n`));
 }
+/** `--venue hyperliquid` / `--venue=binance`. Absent = unknown: the user has
+ *  not chosen yet (venue is picked on the dashboard AFTER connecting), so we
+ *  run the Binance probe but phrase its failure as "Binance is blocked here",
+ *  never as "trading cannot work here". */
+function parseVenueArg(argv) {
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        const v = a.startsWith('--venue=') ? a.slice('--venue='.length) : a === '--venue' ? argv[i + 1] : undefined;
+        if (v === 'binance' || v === 'hyperliquid')
+            return v;
+    }
+    return null;
+}
 async function main() {
     banner(bold(cyan('ReefClaw connect')) + dim('  — link your OpenClaw agent to ReefClaw (paper trading)'));
     preflight();
-    // Prevention: a host in a Binance-restricted region (HTTP 451) can't trade —
-    // not even paper, which uses live Binance prices. Advisory (never fatal); the
-    // dashboard readiness surface re-checks it live after connect.
-    const binanceReachable = await checkBinanceRegion();
+    // Venue-aware reachability. ReefClaw trades Binance AND Hyperliquid; probing
+    // Binance for a Hyperliquid user produced a red "trading cannot work from
+    // here" on hosts where Hyperliquid works perfectly — the first thing such a
+    // user saw. `--venue hyperliquid` probes the venue they actually want.
+    const venue = parseVenueArg(process.argv.slice(2));
+    let binanceReachable = true;
+    if (venue === 'hyperliquid') {
+        await checkHyperliquidRegion();
+    }
+    else {
+        binanceReachable = await checkBinanceRegion();
+    }
     const pre = readConfig();
     const plugin = installPlugin();
     const merged = wireConfig(pre);
@@ -171,7 +192,7 @@ async function main() {
         warn('Connector supervision was not enabled — see the message above to finish it.');
     }
     if (!binanceReachable) {
-        warn('This host looks geo-blocked by Binance (HTTP 451) — trading will not work until you run the agent from a Binance-permitted region (most EU / several Asia VPS regions).');
+        warn('This host looks geo-blocked by BINANCE (HTTP 451). Binance trading will not work here — run the agent from a Binance-permitted region (most EU / several Asia VPS regions), or choose HYPERLIQUID on the dashboard, which is reachable from most regions including this one.');
     }
     nextSteps();
 }

package/dist/validate.js

@@ -1,7 +1,7 @@
 // Light post-install checks. We can only verify the LOCAL gateway here — the
 // relay handshake only succeeds once the user pastes their connect message
 // (that's the onboarding "auto-detect" step on the dashboard).
-import { step, ok, warn, info, fail } from './ui.js';
+import { step, ok, warn, info } from './ui.js';
 /** Any HTTP response from the local gateway means OpenClaw is up and reachable.
  *  A connection refused means OpenClaw isn't running. */
 export async function checkGateway(port) {
@@ -27,11 +27,17 @@ export async function checkGateway(port) {
     }
 }
 /** Probe whether Binance USD-M Futures is reachable from THIS host. A `451` is
- *  Binance's geo-restriction signal — the host's region is blocked, and trading
- *  (even paper mode, which uses live Binance prices) cannot work from here. The
- *  probe is advisory: only a definitive `451` returns false; a network hiccup /
- *  timeout is NOT a geo-block, so we stay out of the way and let the dashboard
- *  readiness surface confirm a real, persistent problem later. Never fatal. */
+ *  Binance's geo-restriction signal — the host's region is blocked, so Binance
+ *  trading (and Binance-priced paper mode) cannot work from here. The probe is
+ *  advisory: only a definitive `451` returns false; a network hiccup / timeout
+ *  is NOT a geo-block, so we stay out of the way and let the dashboard
+ *  readiness surface confirm a real, persistent problem later. Never fatal.
+ *
+ *  ★ The copy deliberately names BINANCE, not "trading" — ReefClaw also trades
+ *  Hyperliquid, which is reachable from most regions INCLUDING Binance-blocked
+ *  ones (verified live). Telling a Hyperliquid user to relocate their server
+ *  because of Binance is a false alarm, and it used to be the first thing a
+ *  Hyperliquid-only user saw. Pass `--venue hyperliquid` to skip this entirely. */
 export async function checkBinanceRegion() {
     step('Checking Binance reachability from this host');
     const url = 'https://fapi.binance.com/fapi/v1/ping';
@@ -40,9 +46,11 @@ export async function checkBinanceRegion() {
     try {
         const res = await fetch(url, { signal: ctrl.signal });
         if (res.status === 451) {
-            fail('Binance returned HTTP 451 — this host is in a Binance-restricted region.');
-            info('Trading (and paper mode, which uses live Binance prices) cannot work from here.');
-            info('Run the agent from a Binance-permitted region — most EU / several Asia VPS regions work.');
+            warn('Binance returned HTTP 451 — this host is in a Binance-restricted region.');
+            info('BINANCE trading (and paper mode, which uses live Binance prices) cannot work from here.');
+            info('Either run the agent from a Binance-permitted region (most EU / several Asia VPS');
+            info('regions work), or trade HYPERLIQUID instead — it is reachable from most regions,');
+            info('including this one. You pick the exchange on the dashboard after connecting.');
             return false;
         }
         ok('Binance is reachable from this host');
@@ -58,3 +66,32 @@ export async function checkBinanceRegion() {
         clearTimeout(t);
     }
 }
+/** Probe Hyperliquid reachability — the venue-correct check for a user who
+ *  told us (`--venue hyperliquid`) that is what they intend to trade. */
+export async function checkHyperliquidRegion() {
+    step('Checking Hyperliquid reachability from this host');
+    const ctrl = new AbortController();
+    const t = setTimeout(() => ctrl.abort(), 5000);
+    try {
+        const res = await fetch('https://api.hyperliquid.xyz/info', {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify({ type: 'meta' }),
+            signal: ctrl.signal,
+        });
+        if (res.ok) {
+            ok('Hyperliquid is reachable from this host');
+            return true;
+        }
+        warn(`Hyperliquid responded HTTP ${res.status} from this host.`);
+        info('The dashboard re-checks this after you connect.');
+        return false;
+    }
+    catch {
+        info('Could not probe Hyperliquid reachability (network hiccup) — skipping; the dashboard verifies it after connect.');
+        return true;
+    }
+    finally {
+        clearTimeout(t);
+    }
+}

package/package.json

@@ -1,32 +1,32 @@
-{
-  "name": "@reefclaw/connect",
-  "version": "0.1.30",
-  "description": "One-command installer that connects your OpenClaw agent to ReefClaw (paper trading, no exchange keys).",
-  "type": "module",
-  "bin": {
-    "reefclaw-connect": "dist/cli.js"
-  },
-  "files": [
-    "dist",
-    "assets"
-  ],
-  "engines": {
-    "node": ">=20"
-  },
-  "scripts": {
-    "bundle-assets": "node scripts/bundle-assets.mjs",
-    "build": "tsc && node scripts/bundle-assets.mjs",
-    "test": "vitest",
-    "test:run": "vitest run"
-  },
-  "dependencies": {
-    "json5": "2.2.3"
-  },
-  "devDependencies": {
-    "@types/node": "^20",
-    "typescript": "^5",
-    "vitest": "^4.0.18"
-  },
-  "license": "MIT",
-  "homepage": "https://reefclaw.com"
-}
+{
+  "name": "@reefclaw/connect",
+  "version": "0.1.31",
+  "description": "One-command installer that connects your OpenClaw agent to ReefClaw (paper trading, no exchange keys).",
+  "type": "module",
+  "bin": {
+    "reefclaw-connect": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "assets"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "bundle-assets": "node scripts/bundle-assets.mjs",
+    "build": "tsc && node scripts/bundle-assets.mjs",
+    "test": "vitest",
+    "test:run": "vitest run"
+  },
+  "dependencies": {
+    "json5": "2.2.3"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "typescript": "^5",
+    "vitest": "^4.0.18"
+  },
+  "license": "MIT",
+  "homepage": "https://reefclaw.com"
+}