@reefclaw/connect 0.1.20 → 0.1.21

package/assets/plugin/venues/hyperliquid/hl-user-stream.js

@@ -137,9 +137,12 @@ export class HyperliquidUserStream {
         switch (channel) {
             case 'userFills': {
                 const payload = data;
+                // `isSnapshot` was typed here from the start but never read — so every
+                // (re)connect replayed recent history as if it were live (F44).
+                const isSnapshot = payload?.isSnapshot === true;
                 for (const fill of payload?.fills ?? []) {
                     this.lastEventAt = Math.max(this.lastEventAt, fill.time ?? Date.now());
-                    this.opts.callbacks.onFill(fill);
+                    this.opts.callbacks.onFill(fill, { isSnapshot });
                 }
                 break;
             }

package/assets/shared/index.d.ts

@@ -9,6 +9,6 @@ export { redactTokens, redactTokensInPayload, REDACTED_TOKEN } from './redact.js
 export type { Direction, OhlcvBar, TradeFlowBucket, GlobalMarketContext, MarketContext, SignalCondition, StrategyEvaluation, StrategyDefinition, SignalEvent, StrategyState, SignalSnapshot, } from './signals/types.js';
 export type { ConditionResult, ConditionContext, ConditionFn, ConditionConfig, EntryRuleConfig, StopRuleConfig, DirectionRule, PrimaryTimeframe, StrategyConfig, } from './signals/conditions/types.js';
 export type { VenueId } from './venues/symbols.js';
-export { VENUE_IDS, isVenueId, parseVenue, FILL_EXCHANGE_ID, fillExchangeId, VENUE_QUOTE_ASSET, HL_INTEL_PREFIX, toCcxtSymbol, toIntelSymbol, fromIntelSymbol, toHyperliquidCoin, } from './venues/symbols.js';
-export type { ReadinessStatus, ReadinessPhase, ReadinessCheckId, ReadinessCheck, ReadinessReport, } from './readiness.js';
-export { READINESS_CHECK_COPY, makeReadinessCheck, deriveOverallReadiness, } from './readiness.js';
+export { VENUE_IDS, isVenueId, parseVenue, FILL_EXCHANGE_ID, fillExchangeId, VENUE_QUOTE_ASSET, VENUE_DEFAULT_SYMBOL, HL_INTEL_PREFIX, toCcxtSymbol, toIntelSymbol, fromIntelSymbol, toHyperliquidCoin, } from './venues/symbols.js';
+export type { ReadinessStatus, ReadinessPhase, ReadinessCheckId, ReadinessCheck, ReadinessReport, VenueReachabilityOutcome, VenueReachabilityResult, } from './readiness.js';
+export { READINESS_CHECK_COPY, GEO_BLOCK_FIX_HINT, REACHABILITY_STALL_FACTOR, makeReadinessCheck, deriveOverallReadiness, } from './readiness.js';

package/assets/shared/index.js

@@ -3,5 +3,5 @@ export { VALID_CHANNELS, VALID_EMERGENCY_ACTIONS } from './protocol.js';
 export { logger, setLogLevel, formatError } from './logger.js';
 export { VALID_TRADING_MODES, isTradingMode, validateModeTransition, modeRequiresCredentials, } from './trading-mode.js';
 export { redactTokens, redactTokensInPayload, REDACTED_TOKEN } from './redact.js';
-export { VENUE_IDS, isVenueId, parseVenue, FILL_EXCHANGE_ID, fillExchangeId, VENUE_QUOTE_ASSET, HL_INTEL_PREFIX, toCcxtSymbol, toIntelSymbol, fromIntelSymbol, toHyperliquidCoin, } from './venues/symbols.js';
-export { READINESS_CHECK_COPY, makeReadinessCheck, deriveOverallReadiness, } from './readiness.js';
+export { VENUE_IDS, isVenueId, parseVenue, FILL_EXCHANGE_ID, fillExchangeId, VENUE_QUOTE_ASSET, VENUE_DEFAULT_SYMBOL, HL_INTEL_PREFIX, toCcxtSymbol, toIntelSymbol, fromIntelSymbol, toHyperliquidCoin, } from './venues/symbols.js';
+export { READINESS_CHECK_COPY, GEO_BLOCK_FIX_HINT, REACHABILITY_STALL_FACTOR, makeReadinessCheck, deriveOverallReadiness, } from './readiness.js';

package/assets/shared/readiness.d.ts

@@ -2,7 +2,30 @@ export type ReadinessStatus = 'pass' | 'warn' | 'fail' | 'unknown';
 /** Which lifecycle phase a check belongs to. `connect` runs with NO Binance API
  *  keys (covers paper trading too); `golive` needs keys (Phase 2). */
 export type ReadinessPhase = 'connect' | 'golive';
-export type ReadinessCheckId = 'binance_reachable' | 'hyperliquid_reachable' | 'clock_in_sync' | 'plugin_loaded' | 'tools_registered';
+export type ReadinessCheckId = 'binance_reachable' | 'hyperliquid_reachable' | 'clock_in_sync' | 'plugin_loaded' | 'tools_registered' | 'host_responsive';
+/** What a venue reachability probe concluded.
+ *
+ *  ★ `stalled` is the one that is NOT about the venue: it means the probe's own
+ *  abort timer fired far later than it was set for, which can only happen when
+ *  this process was starved of CPU — so the request never got a fair chance and
+ *  we learned NOTHING about the venue. Before it existed, a frozen host fell
+ *  into the same catch as a real network failure and the dashboard confidently
+ *  told the operator to check their DNS/firewall/region (issue #265).
+ *  `unknown` = we deliberately didn't probe (ban/weight gate paused us). */
+export type VenueReachabilityOutcome = 'reachable' | 'geo_blocked' | 'unreachable' | 'stalled' | 'unknown';
+export interface VenueReachabilityResult {
+    outcome: VenueReachabilityOutcome;
+    driftMs: number | null;
+    /** Wall-clock the probe actually took, set only when `outcome === 'stalled'`
+     *  — it IS the evidence (a 10s timer that returned after 86s). */
+    stallMs?: number;
+}
+/** A failed probe is read as a venue failure only while it finished within
+ *  this multiple of its own timeout budget; past it, the clock says the
+ *  process — not the network — is what broke. 2× leaves generous room for
+ *  ordinary scheduling jitter and TLS/DNS slack while sitting far below the
+ *  8×-and-worse overshoots a real freeze produces. */
+export declare const REACHABILITY_STALL_FACTOR = 2;
 export interface ReadinessCheck {
     /** Stable machine id. Widened to string so the webapp can render checks from a
      *  newer plugin it doesn't have the union for. */
@@ -42,11 +65,24 @@ interface CheckCopy {
 /** The canonical connect-phase checks + their plain-English fixes. Single source
  *  of copy; the plugin inlines these into each report so the webapp stays dumb. */
 export declare const READINESS_CHECK_COPY: Record<ReadinessCheckId, CheckCopy>;
+/** Assertive copy for a CONFIRMED geo-block, passed explicitly as the `fixHint`
+ *  override. This is the one case where naming the cause is honest: the server
+ *  answered 451/403, so we are reporting what it told us — not an inference from
+ *  a request that never completed. */
+export declare const GEO_BLOCK_FIX_HINT: Record<'binance' | 'hyperliquid', string>;
 /** Build a self-describing check, pulling label/phase/fixHint from the copy map.
- *  fixHint is attached only when there is something to fix (warn/fail). */
+ *  fixHint is attached only when there is something to fix (warn/fail).
+ *
+ *  `fixHint` in opts OVERRIDES the copy-map default. The static copy asserts one
+ *  cause per check id, which is right for a definitive signal (a 451 IS a geo
+ *  block) but wrong when the same id fires on an inference: a reachability warn
+ *  sent the operator hunting a firewall that was never the problem (issue #265).
+ *  Callers that know the status was inferred pass a hint that describes the
+ *  possibilities instead of asserting one. */
 export declare function makeReadinessCheck(id: ReadinessCheckId, status: ReadinessStatus, opts?: {
     detail?: string;
     checkedAt?: number;
+    fixHint?: string;
 }): ReadinessCheck;
 /** Worst status across the checks: fail > warn > unknown > pass. An all-unknown
  *  (or empty) set is 'unknown', so a report that couldn't run anything doesn't

package/assets/shared/readiness.js

@@ -5,22 +5,30 @@
 // renders generically without duplicating the copy. Advisory only: readiness
 // explains failures, it never blocks trading or the safety floor.
 // See docs/AGENT_READINESS_GATE_PLAN.md.
+/** A failed probe is read as a venue failure only while it finished within
+ *  this multiple of its own timeout budget; past it, the clock says the
+ *  process — not the network — is what broke. 2× leaves generous room for
+ *  ordinary scheduling jitter and TLS/DNS slack while sitting far below the
+ *  8×-and-worse overshoots a real freeze produces. */
+export const REACHABILITY_STALL_FACTOR = 2;
 /** The canonical connect-phase checks + their plain-English fixes. Single source
  *  of copy; the plugin inlines these into each report so the webapp stays dumb. */
 export const READINESS_CHECK_COPY = {
+    // ★ The DEFAULT reachability copy must describe possible causes, never assert
+    // one: this hint is attached to the debounced 'unreachable' warn, where all we
+    // know is that two probes did not complete. Asserting DNS/firewall/region sent
+    // an operator hunting a firewall that did not exist (issue #265) — the actual
+    // cause was the agent's own host being starved. A CONFIRMED geo-block (the
+    // server answered 451/403) gets the assertive copy below, passed explicitly.
     binance_reachable: {
         label: 'Binance reachable',
         phase: 'connect',
-        fixHint: 'Your agent host is geo-blocked by Binance (HTTP 451). Run OpenClaw from a Binance-permitted region — most EU / several Asia VPS regions work.',
+        fixHint: 'Your agent host did not reach the Binance API on two consecutive checks. Possible causes: outbound HTTPS/DNS blocked, a transient Binance outage, or the host itself being starved of CPU/memory (check "Agent host responsive"). If it persists, verify connectivity and that the host region is Binance-permitted.',
     },
-    // Dormant until the Hyperliquid venue ships (docs/HYPERLIQUID_INTEGRATION_PLAN.md
-    // Phase 1): the reporter probes only the CONFIGURED venue, so this id is never
-    // emitted while venue='binance'. Landed early so older webapps render it via the
-    // string-widened ReadinessCheck.id the moment a newer plugin starts sending it.
     hyperliquid_reachable: {
         label: 'Hyperliquid reachable',
         phase: 'connect',
-        fixHint: 'Your agent host cannot reach the Hyperliquid API (api.hyperliquid.xyz). Check outbound HTTPS/DNS/firewall; if the host region is restricted, run OpenClaw from a permitted region.',
+        fixHint: 'Your agent host did not reach the Hyperliquid API (api.hyperliquid.xyz) on two consecutive checks. Possible causes: outbound HTTPS/DNS blocked, a transient Hyperliquid outage, or the host itself being starved of CPU/memory (check "Agent host responsive"). If it persists, verify connectivity and that the host region is permitted.',
     },
     clock_in_sync: {
         label: 'Host clock in sync',
@@ -37,9 +45,33 @@ export const READINESS_CHECK_COPY = {
         phase: 'connect',
         fixHint: 'No trading tools are registered. Ensure tools.alsoAllow includes "group:plugins", then restart the gateway.',
     },
+    // The signal that actually matters on a trading rig, and the one that was
+    // invisible while a starved host masqueraded as an unreachable venue
+    // (issue #265): the agent process was runnable but not getting scheduled for
+    // minutes at a time. Fed by the event-loop delay the plugin samples locally.
+    host_responsive: {
+        label: 'Agent host responsive',
+        phase: 'connect',
+        fixHint: 'Your agent host is starved of CPU/memory — the agent process froze for seconds at a time, so order handling, stop attachment and bracket resync can be delayed by minutes. Give the host more CPU/RAM, or reduce what else runs on it (other containers, agents or a leaking process competing for the same box).',
+    },
+};
+/** Assertive copy for a CONFIRMED geo-block, passed explicitly as the `fixHint`
+ *  override. This is the one case where naming the cause is honest: the server
+ *  answered 451/403, so we are reporting what it told us — not an inference from
+ *  a request that never completed. */
+export const GEO_BLOCK_FIX_HINT = {
+    binance: 'Your agent host is geo-blocked by Binance (HTTP 451) — Binance itself refused the request. Run OpenClaw from a Binance-permitted region; most EU / several Asia VPS regions work.',
+    hyperliquid: 'Your agent host is blocked by Hyperliquid (api.hyperliquid.xyz answered HTTP 451/403) — the API itself refused the request, so this is a region/policy block rather than a network fault. Run OpenClaw from a permitted region.',
 };
 /** Build a self-describing check, pulling label/phase/fixHint from the copy map.
- *  fixHint is attached only when there is something to fix (warn/fail). */
+ *  fixHint is attached only when there is something to fix (warn/fail).
+ *
+ *  `fixHint` in opts OVERRIDES the copy-map default. The static copy asserts one
+ *  cause per check id, which is right for a definitive signal (a 451 IS a geo
+ *  block) but wrong when the same id fires on an inference: a reachability warn
+ *  sent the operator hunting a firewall that was never the problem (issue #265).
+ *  Callers that know the status was inferred pass a hint that describes the
+ *  possibilities instead of asserting one. */
 export function makeReadinessCheck(id, status, opts = {}) {
     const copy = READINESS_CHECK_COPY[id];
     const needsFix = status === 'warn' || status === 'fail';
@@ -49,7 +81,7 @@ export function makeReadinessCheck(id, status, opts = {}) {
         phase: copy.phase,
         status,
         ...(opts.detail !== undefined ? { detail: opts.detail } : {}),
-        ...(needsFix ? { fixHint: copy.fixHint } : {}),
+        ...(needsFix ? { fixHint: opts.fixHint ?? copy.fixHint } : {}),
         checkedAt: opts.checkedAt ?? Date.now(),
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reefclaw/connect",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "description": "One-command installer that connects your OpenClaw agent to ReefClaw (paper trading, no exchange keys).",
   "type": "module",
   "bin": {