@reefclaw/openclaw-plugin 0.1.1 → 0.1.3

package/ingest/readiness-reporter.js

@@ -0,0 +1,142 @@
+// Agent-readiness reporter — runs connect-phase health checks ON the trader's
+// host and POSTs a self-describing report to the webapp, so a silently-broken
+// agent (geo-blocked by Binance, clock-skewed, no tools) surfaces a plain-English
+// dashboard alert instead of a false green. Advisory only: it NEVER blocks
+// trading or the safety floor. See docs/AGENT_READINESS_GATE_PLAN.md (Phase 1).
+//
+// No token → no-op (nothing to authenticate; matches the config poller). A
+// module-level singleton guard mirrors `pluginInitialised` in index.ts — OpenClaw
+// calls register() multiple times per process and we must never spawn a second
+// timer. The interval is unref()'d so it never holds the process open.
+import { makeReadinessCheck, deriveOverallReadiness, } from '@reefclaw/shared';
+import { logger, formatError } from '../logger.js';
+const TAG = 'readiness';
+const DEFAULT_INTERVAL_MS = 300_000; // 5 min — geo/clock state changes rarely.
+const MIN_INTERVAL_MS = 60_000;
+/** Best-effort display fact; kept in sync with the register() banner in index.ts. */
+const PLUGIN_VERSION = '3.8.0';
+function resolveIntervalMs(explicit) {
+    if (explicit && explicit > 0)
+        return Math.max(MIN_INTERVAL_MS, explicit);
+    const raw = Number(process.env.RC_READINESS_INTERVAL_MS);
+    if (!Number.isFinite(raw) || raw <= 0)
+        return DEFAULT_INTERVAL_MS;
+    return Math.max(MIN_INTERVAL_MS, raw);
+}
+/** Run every connect-phase check once and assemble the report. Exported for
+ *  unit tests. */
+export async function collectReadiness(opts) {
+    const now = Date.now();
+    const checks = [];
+    // plugin_loaded — trivially true (this code runs inside the loaded plugin),
+    // but a positive row is what proves the report path is alive at all.
+    checks.push(makeReadinessCheck('plugin_loaded', 'pass', { checkedAt: now }));
+    // tools_registered
+    checks.push(makeReadinessCheck('tools_registered', opts.toolCount > 0 ? 'pass' : 'fail', {
+        detail: `${opts.toolCount} tools`,
+        checkedAt: now,
+    }));
+    // binance_reachable (+ clock drift from the same probe response)
+    const probe = await opts.binanceApi.probeReachability();
+    if (probe.outcome === 'reachable') {
+        checks.push(makeReadinessCheck('binance_reachable', 'pass', { checkedAt: now }));
+        const drift = probe.driftMs;
+        if (drift == null) {
+            checks.push(makeReadinessCheck('clock_in_sync', 'unknown', { checkedAt: now }));
+        }
+        else {
+            const abs = Math.abs(drift);
+            const status = abs <= 1000 ? 'pass' : abs <= 5000 ? 'warn' : 'fail';
+            checks.push(makeReadinessCheck('clock_in_sync', status, {
+                detail: `drift ${Math.round(drift)}ms`,
+                checkedAt: now,
+            }));
+        }
+    }
+    else if (probe.outcome === 'geo_blocked') {
+        checks.push(makeReadinessCheck('binance_reachable', 'fail', { detail: 'HTTP 451', checkedAt: now }));
+        checks.push(makeReadinessCheck('clock_in_sync', 'unknown', { checkedAt: now }));
+    }
+    else if (probe.outcome === 'unreachable') {
+        // Network/DNS/timeout — could be transient, so warn (amber) rather than
+        // asserting a definitive failure. A persistent problem stays amber across
+        // re-checks; only the 451 geo-block is a hard red.
+        checks.push(makeReadinessCheck('binance_reachable', 'warn', { detail: 'unreachable', checkedAt: now }));
+        checks.push(makeReadinessCheck('clock_in_sync', 'unknown', { checkedAt: now }));
+    }
+    else {
+        // 'unknown' — the ban/weight gate paused the probe; don't assert anything.
+        checks.push(makeReadinessCheck('binance_reachable', 'unknown', { checkedAt: now }));
+        checks.push(makeReadinessCheck('clock_in_sync', 'unknown', { checkedAt: now }));
+    }
+    return {
+        schemaVersion: 1,
+        generatedAt: now,
+        overall: deriveOverallReadiness(checks),
+        checks,
+        agent: { pluginVersion: PLUGIN_VERSION, toolCount: opts.toolCount },
+    };
+}
+async function postReadiness(apiBaseUrl, token, report, fetchImpl, timeoutMs) {
+    const url = `${apiBaseUrl.replace(/\/+$/, '')}/api/internal/agent-readiness`;
+    const ac = new AbortController();
+    const tid = setTimeout(() => ac.abort(), timeoutMs);
+    try {
+        const res = await fetchImpl(url, {
+            method: 'POST',
+            headers: {
+                'content-type': 'application/json',
+                authorization: `Bearer ${token}`,
+            },
+            body: JSON.stringify(report),
+            signal: ac.signal,
+        });
+        if (res.status < 200 || res.status >= 300) {
+            logger.warn(TAG, `POST ${url} → ${res.status}`);
+        }
+    }
+    catch (err) {
+        logger.warn(TAG, `readiness POST failed: ${formatError(err)}`);
+    }
+    finally {
+        clearTimeout(tid);
+    }
+}
+let reporterStarted = false;
+/** Test-only — reset the singleton guard between unit tests. */
+export function __resetReadinessReporterForTests() {
+    reporterStarted = false;
+}
+/** Fire the readiness report once at boot then on an unref'd interval. */
+export function startReadinessReporter(opts) {
+    if (reporterStarted)
+        return;
+    if (!opts.token || !opts.token.trim()) {
+        logger.info(TAG, 'no connection token — readiness reporting disabled');
+        return;
+    }
+    reporterStarted = true;
+    const fetchImpl = opts.fetchImpl ?? fetch;
+    const intervalMs = resolveIntervalMs(opts.intervalMs);
+    const timeoutMs = opts.requestTimeoutMs ?? 10_000;
+    const cycle = async () => {
+        try {
+            const report = await collectReadiness({
+                binanceApi: opts.binanceApi,
+                toolCount: opts.toolCount,
+            });
+            await postReadiness(opts.apiBaseUrl, opts.token, report, fetchImpl, timeoutMs);
+            if (report.overall === 'fail') {
+                const failing = report.checks.filter((c) => c.status === 'fail').map((c) => c.id).join(', ');
+                logger.warn(TAG, `readiness FAIL: ${failing}`);
+            }
+        }
+        catch (err) {
+            logger.warn(TAG, `readiness cycle failed: ${formatError(err)}`);
+        }
+    };
+    void cycle();
+    const timer = setInterval(() => void cycle(), intervalMs);
+    timer.unref();
+    logger.info(TAG, `readiness reporter started (interval ${Math.round(intervalMs / 1000)}s)`);
+}

package/live/exchange-info-cache.d.ts

@@ -23,7 +23,9 @@ export declare class ExchangeInfoCache {
     private rules;
     /** Set of all known symbols for normalization lookups. */
     private knownSymbols;
-    /** Load market info from CCXT exchange instance. */
+    /** Load market info from CCXT exchange instance. Throws on failure (incl.
+     *  an active ban — the gate short-circuits with zero network so a boot
+     *  during a 418 can't extend it); callers treat a throw as init failure. */
     load(exchange: any): Promise<void>;
     /** Get rules for a symbol (tries both BTC/USDT and BTC/USDT:USDT formats). */
     getRules(symbol: string): SymbolRules | undefined;

package/live/exchange-info-cache.js

@@ -1,6 +1,7 @@
 // Exchange info cache — caches per-symbol trading rules (min notional, lot sizes, tick sizes).
 // Loaded once on startup from CCXT loadMarkets(), used to validate and round orders before submission.
 import { logger } from '../logger.js';
+import { assertNotBanned, noteBinanceError, noteSuccess } from '../ccxt/binance-ban-gate.js';
 const TAG = 'exchange-info';
 /**
  * Normalize symbol format for consistent lookups.
@@ -26,10 +27,24 @@ export class ExchangeInfoCache {
     rules = new Map();
     /** Set of all known symbols for normalization lookups. */
     knownSymbols = new Set();
-    /** Load market info from CCXT exchange instance. */
+    /** Load market info from CCXT exchange instance. Throws on failure (incl.
+     *  an active ban — the gate short-circuits with zero network so a boot
+     *  during a 418 can't extend it); callers treat a throw as init failure. */
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     async load(exchange) {
-        const info = await exchange.loadMarkets(true); // force refresh
+        let info;
+        try {
+            // GET /fapi/v1/exchangeInfo via ccxt loadMarkets — IP weight 1
+            // (doc-verified). Ban-gated but never weight-paced (NEVER_PACE):
+            // once-per-boot and required for order validation + emergency close.
+            assertNotBanned('loadMarkets');
+            info = await exchange.loadMarkets(true); // force refresh
+            noteSuccess();
+        }
+        catch (err) {
+            noteBinanceError(err);
+            throw err;
+        }
         for (const [symbol, market] of Object.entries(info)) {
             const m = market;
             // Only cache futures (swap) markets

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reefclaw/openclaw-plugin",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "ReefClaw trading plugin for OpenClaw \u2014 paper trading with real Binance market data, plus the ReefClaw dashboard connector (supervised by OpenClaw, no service manager needed). Install: /plugins install clawhub:@reefclaw/openclaw-plugin",
   "type": "module",
   "main": "index.js",

package/signals/strategy-adapter.d.ts

@@ -1,6 +1,39 @@
-import type { StrategyDefinition } from './types.js';
-import type { StrategyConfig } from './conditions/types.js';
+import type { StrategyDefinition, MarketContext, OhlcvBar } from './types.js';
+import type { StrategyConfig, PrimaryTimeframe } from './conditions/types.js';
 export declare function clearStrategyGatingState(): void;
+/**
+ * Live parity for higher-timeframe strategies (the tfHours-aware-stops fix,
+ * 2026-07 — see docs/STRATEGY_RESEARCH_2026-07.md §6.4 / CLAUDE.md ★).
+ *
+ * Every implicit bar read in this engine — stop rules
+ * (`findSwingPoints(ctx.ohlcv1h.slice(-48))`), entry rules
+ * (`computeEMA(ctx.ohlcv1h…)`), conditions without a `tfHours` param
+ * (ema_proximity, stoch_rsi_extreme, adx_*, …) and `ctx.atr14` — targets the
+ * `ohlcv1h` slot. The backtest engine feeds MAIN-timeframe bars into that
+ * slot (and computes atr14 from them), so a 4h/1d strategy backtests against
+ * primary-timeframe geometry. LIVE contexts put real 1h bars there, so the
+ * same strategy would compute stops/EMAs/ATR from 1h data — a 1d ATR is ~8×
+ * the 1h ATR, so live stops came out ~8× too tight. This helper gives the
+ * evaluation the exact context shape the backtest validated: primary bars in
+ * the `ohlcv1h` slot, atr14 recomputed from them (same computeATR the
+ * backtest and live context builders use).
+ *
+ * Detection, not configuration: when the `ohlcv1h` slot already carries
+ * primary-cadence bars (median spacing ≥ 90% of the primary bar duration —
+ * i.e. a backtest context), the context is returned UNTOUCHED, so backtest
+ * behaviour is byte-identical by construction (including warm-up: the
+ * backtest engine already refuses to build a context below 50 main bars).
+ * A live 1h series can only look primary-spaced through a data gap, in
+ * which case we fall back to the untouched context (pre-fix behaviour)
+ * rather than guessing.
+ *
+ * Returns null for a LIVE context whose primary-timeframe history is below
+ * the backtest's 50-bar warm-up — the caller skips evaluation, mirroring
+ * the backtest's null-context warm-up window.
+ *
+ * Exported for tests.
+ */
+export declare function resolvePrimaryContext(ctx: MarketContext, tf: PrimaryTimeframe, tfBars: OhlcvBar[]): MarketContext | null;
 /**
  * Convert a declarative StrategyConfig into a StrategyDefinition
  * that the signal engine and backtest engine can evaluate.

package/signals/strategy-adapter.js

@@ -9,6 +9,7 @@ import { evaluateConditions } from './conditions/registry.js';
 import { resolveDirection } from './direction-rules.js';
 import { computeEntry } from './entry-rules.js';
 import { computeStop } from './stop-rules.js';
+import { computeATR } from '../shared/indicators.js';
 /**
  * Higher-timeframe tick gating state, keyed by
  * `${gateNamespace}\x1f${strategyName}:${symbol}`.
@@ -41,6 +42,73 @@ function pickTimeframeBars(ctx, tf) {
         return ctx.ohlcv4h ?? [];
     return ctx.ohlcv1h;
 }
+const TF_MS = {
+    '1h': 3_600_000,
+    '4h': 4 * 3_600_000,
+    '1d': 24 * 3_600_000,
+};
+/** Median spacing of the last few bars — robust bar-cadence probe. */
+function barSpacingMs(bars) {
+    const n = bars.length;
+    if (n < 2)
+        return 0;
+    const deltas = [];
+    for (let i = Math.max(1, n - 4); i < n; i++) {
+        deltas.push(bars[i].time.getTime() - bars[i - 1].time.getTime());
+    }
+    deltas.sort((a, b) => a - b);
+    return deltas[Math.floor(deltas.length / 2)];
+}
+/**
+ * Live parity for higher-timeframe strategies (the tfHours-aware-stops fix,
+ * 2026-07 — see docs/STRATEGY_RESEARCH_2026-07.md §6.4 / CLAUDE.md ★).
+ *
+ * Every implicit bar read in this engine — stop rules
+ * (`findSwingPoints(ctx.ohlcv1h.slice(-48))`), entry rules
+ * (`computeEMA(ctx.ohlcv1h…)`), conditions without a `tfHours` param
+ * (ema_proximity, stoch_rsi_extreme, adx_*, …) and `ctx.atr14` — targets the
+ * `ohlcv1h` slot. The backtest engine feeds MAIN-timeframe bars into that
+ * slot (and computes atr14 from them), so a 4h/1d strategy backtests against
+ * primary-timeframe geometry. LIVE contexts put real 1h bars there, so the
+ * same strategy would compute stops/EMAs/ATR from 1h data — a 1d ATR is ~8×
+ * the 1h ATR, so live stops came out ~8× too tight. This helper gives the
+ * evaluation the exact context shape the backtest validated: primary bars in
+ * the `ohlcv1h` slot, atr14 recomputed from them (same computeATR the
+ * backtest and live context builders use).
+ *
+ * Detection, not configuration: when the `ohlcv1h` slot already carries
+ * primary-cadence bars (median spacing ≥ 90% of the primary bar duration —
+ * i.e. a backtest context), the context is returned UNTOUCHED, so backtest
+ * behaviour is byte-identical by construction (including warm-up: the
+ * backtest engine already refuses to build a context below 50 main bars).
+ * A live 1h series can only look primary-spaced through a data gap, in
+ * which case we fall back to the untouched context (pre-fix behaviour)
+ * rather than guessing.
+ *
+ * Returns null for a LIVE context whose primary-timeframe history is below
+ * the backtest's 50-bar warm-up — the caller skips evaluation, mirroring
+ * the backtest's null-context warm-up window.
+ *
+ * Exported for tests.
+ */
+export function resolvePrimaryContext(ctx, tf, tfBars) {
+    if (tf === '1h')
+        return ctx;
+    const spacing = barSpacingMs(ctx.ohlcv1h);
+    if (spacing === 0 || spacing >= TF_MS[tf] * 0.9)
+        return ctx; // already primary (backtest) or undecidable
+    if (tfBars.length < 50)
+        return null; // live warm-up parity with the backtest engine
+    const highs = tfBars.map(b => b.high);
+    const lows = tfBars.map(b => b.low);
+    const closes = tfBars.map(b => b.close);
+    const atr14 = computeATR(highs, lows, closes, 14);
+    return {
+        ...ctx,
+        ohlcv1h: tfBars,
+        atr14: Number.isFinite(atr14) && atr14 > 0 ? atr14 : ctx.atr14,
+    };
+}
 /** Empty no-signal evaluation — used when gating skips a strategy. */
 const SKIPPED = { direction: null, conditions: [], trade: undefined };
 /**
@@ -80,40 +148,49 @@ export function adaptStrategy(config, gateNamespace) {
                 return SKIPPED;
             }
             lastEvaluatedBarTime.set(gateKey, latestBarTime);
+            // ─── Higher-timeframe live parity ──────────────────────────────
+            // Evaluate against a context whose implicit-1h slot carries
+            // primary-timeframe bars — see resolvePrimaryContext. Backtest
+            // contexts pass through untouched; only live contexts for 4h/1d
+            // strategies are adapted, and a live context below the backtest's
+            // 50-bar warm-up resolves to null → skip.
+            const ectx = resolvePrimaryContext(ctx, tf, tfBars);
+            if (ectx === null)
+                return SKIPPED;
             // ─── SkipIf gates ──────────────────────────────────────────────
             // Portfolio-wide / cross-symbol filters. If any are met the
             // strategy is skipped this tick. Evaluated before main conditions
             // so the bulk of the work is short-circuited.
             if (config.skipIf && config.skipIf.length > 0) {
-                const { conditions: skipResults } = evaluateConditions(config.skipIf, ctx, null);
+                const { conditions: skipResults } = evaluateConditions(config.skipIf, ectx, null);
                 if (skipResults.some(c => c.met))
                     return SKIPPED;
             }
             // Pass 1: evaluate conditions with direction = null
-            const { conditions: pass1, condCtx } = evaluateConditions(config.conditions, ctx, null);
+            const { conditions: pass1, condCtx } = evaluateConditions(config.conditions, ectx, null);
             // Determine direction
-            const direction = resolveDirection(config.directionRule, ctx, condCtx);
+            const direction = resolveDirection(config.directionRule, ectx, condCtx);
             // Pass 2: re-evaluate direction-sensitive conditions now that we know direction
             // (orderbook_imbalance and funding_contrarian behave differently per direction)
             const directionSensitive = new Set(['orderbook_imbalance', 'funding_contrarian', 'funding_extreme_skip', 'funding_position_ok', 'return_momentum']);
             const hasDirSensitive = config.conditions.some(c => directionSensitive.has(c.type));
             let finalConditions = pass1;
             if (direction && hasDirSensitive) {
-                const { conditions: pass2 } = evaluateConditions(config.conditions, ctx, direction);
+                const { conditions: pass2 } = evaluateConditions(config.conditions, ectx, direction);
                 // Merge: use pass2 results for direction-sensitive, pass1 for others
                 finalConditions = pass1.map((c, i) => directionSensitive.has(config.conditions[i].type) ? pass2[i] : c);
             }
             const allMet = finalConditions.every(c => c.met);
             let trade;
             if (allMet && direction) {
-                const entryZone = computeEntry(config.entryRule, ctx, direction, condCtx);
-                const stopLevel = computeStop(config.stopRule, ctx, direction, condCtx);
+                const entryZone = computeEntry(config.entryRule, ectx, direction, condCtx);
+                const stopLevel = computeStop(config.stopRule, ectx, direction, condCtx);
                 const risk = direction === 'LONG'
-                    ? ctx.currentPrice - stopLevel
-                    : stopLevel - ctx.currentPrice;
+                    ? ectx.currentPrice - stopLevel
+                    : stopLevel - ectx.currentPrice;
                 const targets = config.targetRMultiples.map(rm => direction === 'LONG'
-                    ? ctx.currentPrice + risk * rm
-                    : ctx.currentPrice - risk * rm);
+                    ? ectx.currentPrice + risk * rm
+                    : ectx.currentPrice - risk * rm);
                 trade = { entryZone, stopLevel, targets };
             }
             return { direction, conditions: finalConditions, trade };

package/skills/reefclaw/SKILL.md

@@ -39,6 +39,12 @@ You are being connected to **ReefClaw**, a supervised trading control room. Your
 
 **Do not attempt to trade before the full instructions arrive.** If trading tools are visible but this file is still a bootstrap version (0.0.x), the connection has not completed — finish connecting first.
 
+## Host requirements (check before connecting)
+
+ReefClaw trades on Binance USD-M Futures, so **the machine running this OpenClaw must be able to reach Binance** (`fapi.binance.com`). Binance geo-restricts many locations: cheap US cloud regions — and some other jurisdictions — return **HTTP 451** ("restricted location"), and the agent then cannot fetch market data or trade. This applies even in **paper mode**, which uses live Binance prices.
+
+If your market-data calls fail with `451`, this host is geo-blocked — move the agent to a Binance-permitted region (most EU and several Asia VPS regions work). This is a hosting requirement; ReefClaw cannot configure around it.
+
 ## Connecting (first run) — saving the connect message
 
 The onboarding page at [reefclaw.com/onboarding](https://reefclaw.com/onboarding) gives the user a single **connect message** that carries THREE fields:

package/tools/create-order.js

@@ -1,5 +1,6 @@
 // Tool: create_order — order execution with real price data + pre-trade risk gate
 // Readiness gate: BLOCKED unless adapter.readiness === 'READY'.
+import { randomUUID } from 'node:crypto';
 import { formatError } from '../logger.js';
 import { getQuoteBalance, getQuoteWalletBalance } from '../balance-utils.js';
 import { fetchCurrentPrice, fetchOrderBook, isError } from './helpers.js';
@@ -293,32 +294,37 @@ export async function createOrderTool(args, deps) {
         }
     }
     try {
-        const order = await deps.adapter.createOrder(args.symbol, side, type, args.amount, args.price, metadata);
+        // Stash the metadata BEFORE submission, keyed by a pre-generated
+        // clientOrderId (fixed 2026-07-07; supersedes the 2026-07-05 post-return
+        // stash). For market orders the user-data WS fill routinely arrives
+        // BEFORE the REST ack resolves — observed on prod (FIL 2026-07-06
+        // 20:28:17: WS capture consumed nothing and journaled metadata=none while
+        // the post-return stash landed milliseconds later). The WS
+        // ORDER_TRADE_UPDATE carries the clientOrderId (`o.c`), so
+        // onWsFillObserved falls back to it when the exchange orderId lookup
+        // misses; promote() below adds the exchange-orderId alias once the REST
+        // ack returns for the normal (WS-after-REST) ordering. If the submission
+        // throws, the unused stash entry simply expires (24h TTL, pruned).
+        let stashCid;
+        if (deps.autoCapture?.pendingEntries && metadata) {
+            stashCid = randomUUID();
+            deps.autoCapture.pendingEntries.put({
+                orderId: stashCid,
+                clientOrderId: stashCid,
+                symbol: args.symbol,
+                side: side,
+                metadata,
+            });
+        }
+        const order = await deps.adapter.createOrder(args.symbol, side, type, args.amount, args.price, metadata, stashCid ? { clientOrderId: stashCid } : undefined);
         // Auto-capture entry to the Position Decision Journal — fail-open, never
         // block the trading hot path on a webapp ingest blip.
         if (deps.autoCapture) {
-            // ALWAYS stash the metadata first (fixed 2026-07-05). Binance futures
-            // market orders routinely come back filled>0 but with NO average price
-            // in the immediate REST response — the synchronous capture below then
-            // bails ("missing fill price; skipping capture") and, before this fix,
-            // the metadata was dropped on the floor because the stash only ran in
-            // the not-filled branch. The WS-driven onWsFillObserved captured those
-            // entries seconds later with metadata=none → the live journal filled
-            // with '(no thesis recorded)' / setup_type='unknown' rows (majority of
-            // 2026-07 live entries) even though the agent supplied full v2.10.0
-            // metadata every time. When the synchronous capture DOES succeed, the
-            // WS dedup (openedFromExchangeTradeId === orderId) skips the duplicate
-            // and the unused stash entry simply expires (24h TTL, pruned).
-            if (metadata &&
+            if (stashCid &&
                 deps.autoCapture.pendingEntries &&
                 typeof order.id === 'string' &&
                 order.id.length > 0) {
-                deps.autoCapture.pendingEntries.put({
-                    orderId: order.id,
-                    symbol: args.symbol,
-                    side: side,
-                    metadata,
-                });
+                deps.autoCapture.pendingEntries.promote(stashCid, order.id);
             }
             const filledNow = typeof order.filled === 'number' && order.filled > 0;
             if (filledNow) {