@reefclaw/openclaw-plugin 0.1.0

package/live/slippage-tracker.js

@@ -0,0 +1,78 @@
+// Slippage tracker — records expected vs actual fill price for every live order.
+// Computes slippage in basis points and tracks statistics per symbol.
+import { logger } from '../logger.js';
+const TAG = 'slippage';
+export class SlippageTracker {
+    records = [];
+    maxRecords;
+    constructor(maxRecords = 1000) {
+        this.maxRecords = maxRecords;
+    }
+    /** Record a fill with slippage measurement. */
+    recordFill(params) {
+        // Slippage: positive means worse execution for the order side
+        // For buy: actual > expected = positive slippage (paid more)
+        // For sell: actual < expected = positive slippage (received less)
+        let slippageBps;
+        if (params.side === 'buy') {
+            slippageBps = ((params.actualPrice - params.expectedPrice) / params.expectedPrice) * 10_000;
+        }
+        else {
+            slippageBps = ((params.expectedPrice - params.actualPrice) / params.expectedPrice) * 10_000;
+        }
+        const record = {
+            ...params,
+            slippageBps,
+            timestamp: Date.now(),
+        };
+        this.records.push(record);
+        // Circular buffer
+        if (this.records.length > this.maxRecords) {
+            this.records.shift();
+        }
+        logger.info(TAG, `${params.symbol} ${params.side}: expected=${params.expectedPrice}, actual=${params.actualPrice}, slippage=${slippageBps.toFixed(2)}bps`);
+        return record;
+    }
+    /** Get average slippage in bps for a symbol. */
+    getAverageSlippage(symbol) {
+        const relevant = symbol
+            ? this.records.filter(r => r.symbol === symbol)
+            : this.records;
+        if (relevant.length === 0)
+            return 0;
+        return relevant.reduce((s, r) => s + r.slippageBps, 0) / relevant.length;
+    }
+    /** Get slippage stats summary. */
+    getStats(symbol) {
+        const relevant = symbol
+            ? this.records.filter(r => r.symbol === symbol)
+            : this.records;
+        if (relevant.length === 0) {
+            return { count: 0, avgBps: 0, maxBps: 0, minBps: 0, p95Bps: 0, totalCost: 0 };
+        }
+        const bps = relevant.map(r => r.slippageBps).sort((a, b) => a - b);
+        const p95Idx = Math.floor(bps.length * 0.95);
+        return {
+            count: relevant.length,
+            avgBps: bps.reduce((s, v) => s + v, 0) / bps.length,
+            maxBps: bps[bps.length - 1],
+            minBps: bps[0],
+            p95Bps: bps[p95Idx],
+            totalCost: relevant.reduce((s, r) => {
+                // Cost of slippage = (actualPrice - expectedPrice) * amount
+                const diff = r.side === 'buy'
+                    ? (r.actualPrice - r.expectedPrice)
+                    : (r.expectedPrice - r.actualPrice);
+                return s + diff * r.amount;
+            }, 0),
+        };
+    }
+    /** Get recent records (last N). */
+    getRecent(count = 10) {
+        return this.records.slice(-count);
+    }
+    /** Get all records for a symbol. */
+    getRecordsForSymbol(symbol) {
+        return this.records.filter(r => r.symbol === symbol);
+    }
+}

package/live/stop-watcher.d.ts

@@ -0,0 +1,34 @@
+import { EventEmitter } from 'node:events';
+import type { IExchangeAdapter } from '../exchange-adapter.js';
+import type { CcxtPosition } from '../types.js';
+export declare const DEFAULT_INTERVAL_MS = 10000;
+export interface StopTriggeredEvent {
+    symbol: string;
+    side: 'long' | 'short';
+    stopPrice: number;
+    markPrice: number;
+    quantity: number;
+}
+/** Decide whether a position has crossed its stop.
+ *  Exported for direct unit-testing without spinning up a watcher loop. */
+export declare function isStopBreached(position: CcxtPosition): boolean;
+export declare class PositionWatcher extends EventEmitter {
+    private interval;
+    private intervalMs;
+    private adapter;
+    /** Symbols currently awaiting a close RPC — second trigger in the same tick
+     *  is suppressed so the watcher cannot double-close. Cleared after the close
+     *  call resolves (success or failure). */
+    private closePending;
+    /** Symbols we've already logged a breach for this session, to avoid spamming
+     *  the log every tick while the close is in flight. */
+    private notifiedBreach;
+    constructor(adapter: IExchangeAdapter, intervalMs?: number);
+    start(): void;
+    stop(): void;
+    /** Run one check cycle. Exposed for tests (skip setInterval). */
+    tick(): Promise<void>;
+    private fireClose;
+    /** For tests. */
+    isRunning(): boolean;
+}

package/live/stop-watcher.js

@@ -0,0 +1,158 @@
+// Stop watcher — polls open positions and auto-closes any that have crossed
+// their metadata stopPrice, independent of the LLM agent.
+//
+// Policy vs enforcement split:
+//   - The LLM owns POLICY: it sets stopPrice at entry and may update it at
+//     any time (move to breakeven, trail, widen, or remove entirely by
+//     clearing it). The watcher just reads whatever stopPrice currently is.
+//   - The watcher owns ENFORCEMENT: if mark crosses stopPrice, it fires a
+//     market close immediately rather than waiting for the agent's next
+//     15-min heartbeat. This closes the exit-latency gap the LLM-centric
+//     model would otherwise leave open.
+//
+// Scope:
+//   - Works in paper mode (PaperAdapter.getPositions returns CcxtPosition with
+//     stopPrice populated from position metadata).
+//   - In live mode LiveAdapter does NOT track per-position metadata, so
+//     getPositions returns positions without stopPrice and the watcher
+//     naturally skips them. Wiring live-mode metadata is a separate change
+//     for when live trading turns on.
+import { EventEmitter } from 'node:events';
+import { logger, formatError } from '../logger.js';
+const TAG = 'stop-watcher';
+// 2026-05-15 EFFICIENCY_QUICK_WINS Change 1: 3s → 10s. The watcher was
+// designed when it was the ONLY stop-enforcement mechanism; with exchange-
+// native brackets (live in enforce mode) it is now belt-and-suspenders, so
+// 10s latency to catch a watcher-triggered close is fine — Binance fires the
+// bracket stop in ms regardless. Saves ~70 weight/min (100→30). Operator can
+// revert with zero deploy via plugin-config.json `stopWatcher.intervalMs`.
+// See docs/EFFICIENCY_QUICK_WINS_PLAN.md + the Binance ban-gate context.
+export const DEFAULT_INTERVAL_MS = 10_000;
+/** Decide whether a position has crossed its stop.
+ *  Exported for direct unit-testing without spinning up a watcher loop. */
+export function isStopBreached(position) {
+    const stop = position.stopPrice;
+    if (stop === undefined || stop === null || !Number.isFinite(stop) || stop <= 0) {
+        return false;
+    }
+    const mark = position.markPrice;
+    if (!Number.isFinite(mark) || mark <= 0) {
+        return false;
+    }
+    return position.side === 'long' ? mark <= stop : mark >= stop;
+}
+export class PositionWatcher extends EventEmitter {
+    interval = null;
+    intervalMs;
+    adapter;
+    /** Symbols currently awaiting a close RPC — second trigger in the same tick
+     *  is suppressed so the watcher cannot double-close. Cleared after the close
+     *  call resolves (success or failure). */
+    closePending = new Set();
+    /** Symbols we've already logged a breach for this session, to avoid spamming
+     *  the log every tick while the close is in flight. */
+    notifiedBreach = new Set();
+    constructor(adapter, intervalMs = DEFAULT_INTERVAL_MS) {
+        super();
+        this.adapter = adapter;
+        this.intervalMs = intervalMs;
+    }
+    start() {
+        if (this.interval) {
+            logger.warn(TAG, 'Already running');
+            return;
+        }
+        logger.info(TAG, `Starting stop watcher (interval: ${this.intervalMs}ms)`);
+        this.interval = setInterval(() => {
+            void this.tick();
+        }, this.intervalMs);
+    }
+    stop() {
+        if (this.interval) {
+            clearInterval(this.interval);
+            this.interval = null;
+        }
+        this.closePending.clear();
+        this.notifiedBreach.clear();
+        logger.info(TAG, 'Stopped');
+    }
+    /** Run one check cycle. Exposed for tests (skip setInterval). */
+    async tick() {
+        let positions;
+        try {
+            positions = await this.adapter.getPositionsOrNull();
+        }
+        catch (err) {
+            logger.warn(TAG, `getPositions failed: ${formatError(err)}`);
+            return;
+        }
+        if (positions === null) {
+            // Fetch failed (429 / weight-paced / transient) — position state is
+            // UNKNOWN, not "flat". Skip this tick WITHOUT touching notifiedBreach /
+            // closePending: a null-collapse to [] would wipe the in-flight close
+            // guard (openSymbols below would be empty, clearing every closePending
+            // entry) and let the NEXT tick fire a SECOND close on a position whose
+            // close is already in flight. State repairs on the next successful tick.
+            logger.warn(TAG, 'getPositions unavailable (null) — skipping tick, preserving in-flight close guards');
+            return;
+        }
+        // Clear notification flags for any symbol no longer holding a position,
+        // so a re-entered position later gets a fresh log line on re-breach.
+        const openSymbols = new Set(positions.map(p => p.symbol));
+        for (const sym of this.notifiedBreach) {
+            if (!openSymbols.has(sym))
+                this.notifiedBreach.delete(sym);
+        }
+        for (const sym of this.closePending) {
+            if (!openSymbols.has(sym))
+                this.closePending.delete(sym);
+        }
+        for (const position of positions) {
+            if (!isStopBreached(position))
+                continue;
+            if (this.closePending.has(position.symbol))
+                continue;
+            if (!this.notifiedBreach.has(position.symbol)) {
+                logger.warn(TAG, `STOP BREACHED: ${position.symbol} ${position.side} mark=${position.markPrice} stop=${position.stopPrice} — auto-closing`);
+                this.notifiedBreach.add(position.symbol);
+            }
+            this.closePending.add(position.symbol);
+            // Fire-and-forget per symbol so one slow close doesn't stall the tick.
+            void this.fireClose(position);
+        }
+    }
+    async fireClose(position) {
+        const event = {
+            symbol: position.symbol,
+            side: position.side,
+            stopPrice: position.stopPrice ?? 0,
+            markPrice: position.markPrice,
+            quantity: position.contracts,
+        };
+        this.emit('stop_triggered', event);
+        try {
+            await this.adapter.closePosition(position.symbol, 'stop_watcher');
+            logger.info(TAG, `Auto-closed ${position.symbol} (reason=stop_watcher)`);
+            this.emit('stop_closed', event);
+        }
+        catch (err) {
+            const msg = formatError(err);
+            // "No open position" means the LLM or another path already closed it —
+            // that's a successful no-op, not a failure.
+            if (msg.includes('No open position')) {
+                logger.info(TAG, `${position.symbol} already closed by another path — skipping`);
+            }
+            else {
+                logger.error(TAG, `Auto-close failed for ${position.symbol}: ${msg}`);
+            }
+            this.emit('stop_failed', { ...event, error: msg });
+        }
+        finally {
+            this.closePending.delete(position.symbol);
+        }
+    }
+    /** For tests. */
+    isRunning() {
+        return this.interval !== null;
+    }
+}

package/live/user-data-active-probe.d.ts

@@ -0,0 +1,54 @@
+import type { BinancePrivateApi } from '../ccxt/binance-private.js';
+import type { UserDataStream } from './user-data-stream.js';
+import type { LiveStateStore } from './live-state-store.js';
+export interface UserDataActiveProbeOptions {
+    api: BinancePrivateApi;
+    stream: UserDataStream;
+    store: LiveStateStore;
+    /** How often to run the probe. Default 60_000 (60s). Pass 0 to disable. */
+    intervalMs?: number;
+    /** Subtracted from `lastEventAt` when computing `since` so we don't miss
+     *  trades whose timestamp landed in the same millisecond as our last
+     *  frame. Default 1_000 (1 s). */
+    safetyBufferMs?: number;
+    /** For unit tests — injected timers + clock. */
+    timers?: {
+        setInterval?: (fn: () => void, ms: number) => ReturnType<typeof setInterval>;
+        clearInterval?: (h: ReturnType<typeof setInterval>) => void;
+    };
+    /** For unit tests — injected clock used only for log timestamps. */
+    now?: () => number;
+}
+export interface UserDataActiveProbeHealth {
+    probesRun: number;
+    reconnectsTriggered: number;
+    errorCount: number;
+    lastReconnectReason: string | null;
+    lastReconnectAt: number | null;
+}
+export declare class UserDataActiveProbe {
+    private readonly api;
+    private readonly stream;
+    private readonly store;
+    private readonly intervalMs;
+    private readonly safetyBufferMs;
+    private readonly setIntervalFn;
+    private readonly clearIntervalFn;
+    private readonly now;
+    private timer;
+    private running;
+    private inFlight;
+    private probesRun;
+    private reconnectsTriggered;
+    private errorCount;
+    private lastReconnectReason;
+    private lastReconnectAt;
+    constructor(opts: UserDataActiveProbeOptions);
+    start(): void;
+    stop(): void;
+    getHealth(): UserDataActiveProbeHealth;
+    /** Testing hook — runs one probe pass synchronously (well, async, but
+     *  awaitable). Production uses the interval-driven path; tests can drive
+     *  this directly without touching fake timers. */
+    runProbe(): Promise<void>;
+}

package/live/user-data-active-probe.js

@@ -0,0 +1,180 @@
+// UserDataActiveProbe — proactive REST probe that catches "WS silently
+// stopped delivering" before the staleness watchdog does.
+//
+// WHY THIS EXISTS
+// ---------------
+// On 2026-04-25 we observed the prod user-data stream go silent for 15
+// minutes at a stretch while a real bracket-stop fill happened on Binance.
+// The socket stayed "open" at the OS level (no FIN, no error), the listenKey
+// keep-alive succeeded, but no frames arrived. The 15-min staleness watchdog
+// caught it eventually, but in that window the local store still showed an
+// already-closed position as live. Either alone — adaptive watchdog OR active
+// probe — narrows the window; together they close it.
+//
+// WHAT IT DOES
+// ------------
+// Every `intervalMs` (default 60s):
+//   1. If the stream isn't connected, skip — reconnect logic owns recovery.
+//   2. Read symbols from `store.getPositions()` — only positions where a
+//      missed fill matters (a closed position is a non-event).
+//   3. For each symbol, call `api.fetchMyTrades(symbol, since=lastEventAt - 1s)`.
+//   4. If any returned trade has `timestamp > lastEventAt`, the WS missed
+//      a fill: log the trade id + symbol and call `stream.requestReconnect`.
+//   5. Stop after the first detection — reconnect will trigger snapshot +
+//      gap-fill, and another probe pass on the next tick covers anything new.
+//
+// WHAT IT DOES NOT DO
+// -------------------
+// - Does NOT ingest the trade itself. Reconnect → resyncRequired → gap-filler
+//   handles ingest with `source='rest_reconcile'`. Single-responsibility.
+// - Does NOT touch LiveStateStore. Reconnect snapshot reseeds it.
+// - Does NOT run on flat accounts. With no open positions there's nothing to
+//   protect — the watchdog's looser idle threshold is appropriate.
+//
+// COST
+// ----
+// `fetchMyTrades` is weight 5 per symbol per call on Binance Futures. With
+// ~5 open positions on a typical account, that's 25 weight/min — well below
+// the 2400/min budget.
+import { logger, formatError } from '../logger.js';
+const TAG = 'user-data-active-probe';
+/** CCXT unified symbol → API form. The reconciler stores `BTC/USDT` (no suffix);
+ *  CCXT's fetchMyTrades takes either form, but we re-attach the settle suffix
+ *  to be explicit. */
+function toApiSymbol(s) {
+    if (!s)
+        return s;
+    if (s.includes(':'))
+        return s;
+    const parts = s.split('/');
+    return parts.length === 2 ? `${s}:${parts[1]}` : s;
+}
+export class UserDataActiveProbe {
+    api;
+    stream;
+    store;
+    intervalMs;
+    safetyBufferMs;
+    setIntervalFn;
+    clearIntervalFn;
+    now;
+    timer = null;
+    running = false;
+    inFlight = false;
+    probesRun = 0;
+    reconnectsTriggered = 0;
+    errorCount = 0;
+    lastReconnectReason = null;
+    lastReconnectAt = null;
+    constructor(opts) {
+        this.api = opts.api;
+        this.stream = opts.stream;
+        this.store = opts.store;
+        this.intervalMs = opts.intervalMs ?? 60_000;
+        this.safetyBufferMs = opts.safetyBufferMs ?? 1_000;
+        this.setIntervalFn = opts.timers?.setInterval ?? ((fn, ms) => setInterval(fn, ms));
+        this.clearIntervalFn = opts.timers?.clearInterval ?? ((h) => clearInterval(h));
+        this.now = opts.now ?? (() => Date.now());
+    }
+    start() {
+        if (this.running)
+            return;
+        if (this.intervalMs <= 0) {
+            logger.info(TAG, 'disabled (intervalMs=0)');
+            return;
+        }
+        this.running = true;
+        this.timer = this.setIntervalFn(() => {
+            void this.runProbe().catch((err) => {
+                this.errorCount++;
+                logger.warn(TAG, `probe pass threw: ${formatError(err)} — continuing`);
+            });
+        }, this.intervalMs);
+        logger.info(TAG, `started (intervalMs=${this.intervalMs}, safetyBufferMs=${this.safetyBufferMs})`);
+    }
+    stop() {
+        if (!this.running)
+            return;
+        if (this.timer) {
+            this.clearIntervalFn(this.timer);
+            this.timer = null;
+        }
+        this.running = false;
+        logger.info(TAG, 'stopped');
+    }
+    getHealth() {
+        return {
+            probesRun: this.probesRun,
+            reconnectsTriggered: this.reconnectsTriggered,
+            errorCount: this.errorCount,
+            lastReconnectReason: this.lastReconnectReason,
+            lastReconnectAt: this.lastReconnectAt,
+        };
+    }
+    /** Testing hook — runs one probe pass synchronously (well, async, but
+     *  awaitable). Production uses the interval-driven path; tests can drive
+     *  this directly without touching fake timers. */
+    async runProbe() {
+        if (!this.running && this.timer === null) {
+            // Allow direct invocation in tests even when start() wasn't called.
+        }
+        if (this.inFlight)
+            return;
+        this.inFlight = true;
+        this.probesRun++;
+        try {
+            if (!this.stream.isConnected())
+                return;
+            const health = this.stream.getHealth();
+            const lastEventAt = health.lastEventAt;
+            if (lastEventAt == null)
+                return; // Never received an event; nothing to compare against.
+            const positions = this.store.getPositions().filter((p) => p && p.contracts > 0);
+            if (positions.length === 0)
+                return;
+            const symbols = Array.from(new Set(positions.map((p) => p.symbol).filter(Boolean)));
+            const since = lastEventAt - this.safetyBufferMs;
+            for (const symbol of symbols) {
+                let trades;
+                try {
+                    trades = await this.api.fetchMyTrades(toApiSymbol(symbol), since, 50);
+                }
+                catch (err) {
+                    this.errorCount++;
+                    logger.warn(TAG, `fetchMyTrades(${symbol}) threw: ${formatError(err)}`);
+                    continue;
+                }
+                if (!Array.isArray(trades) || trades.length === 0)
+                    continue;
+                let newest = null;
+                for (const t of trades) {
+                    if (!t || typeof t !== 'object')
+                        continue;
+                    const rec = t;
+                    const ts = typeof rec.timestamp === 'number' ? rec.timestamp : 0;
+                    if (ts <= lastEventAt)
+                        continue;
+                    const id = typeof rec.id === 'string' ? rec.id : String(rec.id ?? '?');
+                    if (!newest || ts > newest.timestamp) {
+                        newest = { id, timestamp: ts };
+                    }
+                }
+                if (newest) {
+                    const lagMs = this.now() - newest.timestamp;
+                    const reason = `active_probe_silent_stream`;
+                    logger.error(TAG, `silent-stream detected: ${symbol} trade id=${newest.id} t=${new Date(newest.timestamp).toISOString()} ` +
+                        `> lastEventAt=${new Date(lastEventAt).toISOString()} (lagMs=${lagMs}) — forcing reconnect`);
+                    this.reconnectsTriggered++;
+                    this.lastReconnectReason = `${reason}:${symbol}`;
+                    this.lastReconnectAt = this.now();
+                    this.stream.requestReconnect(reason);
+                    // One reconnect per pass — don't fire repeatedly across symbols.
+                    return;
+                }
+            }
+        }
+        finally {
+            this.inFlight = false;
+        }
+    }
+}