@reefclaw/openclaw-plugin 0.1.0

package/bridge/gateway/gateway-ws-client.js

@@ -0,0 +1,417 @@
+// WebSocket client for the OpenClaw gateway.
+// Implements the 3-step handshake, event routing, RPC methods,
+// and reconnection with exponential backoff.
+import WebSocket from 'ws';
+import { logger } from '../logger.js';
+import { computeDelay } from '../utils/reconnect.js';
+const TAG = 'gateway-ws';
+// ---- Protocol constants ----
+// Protocol range we can speak. The gateway picks its own version if it falls
+// inside [min, max]. v3 = OpenClaw ≤2026.4.x (prod); v4 = OpenClaw 2026.6+
+// (fresh installs) — the connect/hello frames and every RPC we use are
+// shape-identical across both (verified live against 2026.6.11; a v3-only pin
+// gets `1002 protocol mismatch` there and the bridge can never connect).
+const MIN_PROTOCOL_VERSION = 3;
+const MAX_PROTOCOL_VERSION = 4;
+const CLIENT_ID = 'openclaw-tui';
+const CLIENT_VERSION = '0.1.0';
+const DEFAULT_RECONNECT = {
+    baseDelayMs: 2_000,
+    maxDelayMs: 30_000,
+    maxAttempts: 20,
+    jitterFactor: 0.3,
+};
+// ---- Fatal close codes ----
+/** Auth errors — do not reconnect */
+const FATAL_CLOSE_CODES = [4001];
+const RPC_TIMEOUT_MS = 30_000;
+// ---- Client ----
+export class GatewayWsClient {
+    ws = null;
+    state = 'disconnected';
+    attempt = 0;
+    reconnectTimer = null;
+    staleWarnTimer = null;
+    staleReconnectTimer = null;
+    tickIntervalMs = 15_000; // Updated from hello-ok policy
+    pendingRpcs = new Map();
+    reconnectConfig;
+    destroyed = false;
+    /** Stored device token from hello-ok for future connects */
+    deviceToken = null;
+    /** Last hello-ok payload — contains initial snapshot */
+    lastHelloOk = null;
+    /** Event listeners */
+    listeners = new Map();
+    gatewayUrl;
+    gatewayToken;
+    constructor(config, reconnect) {
+        // Convert to WebSocket URL: http→ws, https→wss, bare host:port→ws://
+        let url = config.gatewayUrl.replace(/\/$/, '');
+        if (/^https:\/\//.test(url)) {
+            url = url.replace(/^https:\/\//, 'wss://');
+        }
+        else if (/^http:\/\//.test(url)) {
+            url = url.replace(/^http:\/\//, 'ws://');
+        }
+        else if (!/^wss?:\/\//.test(url)) {
+            url = `ws://${url}`;
+        }
+        this.gatewayUrl = url;
+        this.gatewayToken = config.gatewayToken;
+        this.reconnectConfig = { ...DEFAULT_RECONNECT, ...reconnect };
+    }
+    // ---- Public API ----
+    /** Start the WebSocket connection and handshake */
+    connect() {
+        if (this.destroyed)
+            return;
+        if (this.state === 'connected' || this.state === 'handshaking')
+            return;
+        this.setState(this.attempt === 0 ? 'connecting' : 'reconnecting');
+        const url = this.gatewayUrl;
+        logger.info(TAG, `Connecting to gateway (attempt ${this.attempt + 1}): ${url}`);
+        const ws = new WebSocket(url);
+        this.ws = ws;
+        ws.on('open', () => {
+            logger.info(TAG, 'WebSocket open, awaiting challenge');
+            this.setState('handshaking');
+        });
+        ws.on('message', (data) => {
+            this.handleMessage(data);
+        });
+        ws.on('close', (code, reason) => {
+            const reasonStr = reason.toString();
+            logger.info(TAG, `WebSocket closed: ${code} ${reasonStr}`);
+            this.ws = null;
+            this.clearStaleTimer();
+            this.rejectAllPending('Connection closed');
+            if (this.destroyed)
+                return;
+            const wasConnected = this.state === 'connected' || this.state === 'handshaking';
+            if (wasConnected) {
+                this.emit('disconnected', { code, reason: reasonStr });
+            }
+            // Fatal close codes: do not reconnect
+            if (FATAL_CLOSE_CODES.includes(code)) {
+                logger.error(TAG, `Fatal close code ${code} — authentication failed, not reconnecting`);
+                this.setState('failed');
+                this.emit('failed', { reason: `Authentication failed (code ${code})` });
+                return;
+            }
+            this.scheduleReconnect();
+        });
+        ws.on('error', (err) => {
+            logger.error(TAG, `WebSocket error: ${err.message}`);
+        });
+    }
+    /** Disconnect and clean up. Cannot reconnect after this. */
+    destroy() {
+        this.destroyed = true;
+        this.clearReconnectTimer();
+        this.clearStaleTimer();
+        this.rejectAllPending('Client destroyed');
+        if (this.ws) {
+            this.ws.close(1000, 'Client shutting down');
+            this.ws = null;
+        }
+        this.setState('disconnected');
+    }
+    /**
+     * Send an RPC request and wait for the response.
+     * Used for: agent (chat), health, status
+     */
+    async sendRpc(method, params) {
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            throw new Error(`Cannot send RPC: not connected (state=${this.state})`);
+        }
+        const id = `rpc-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        const frame = {
+            type: 'req',
+            id,
+            method,
+            ...(params && { params }),
+        };
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pendingRpcs.delete(id);
+                reject(new Error(`RPC ${method} timed out after ${RPC_TIMEOUT_MS}ms`));
+            }, RPC_TIMEOUT_MS);
+            this.pendingRpcs.set(id, { resolve, reject, timer });
+            this.ws.send(JSON.stringify(frame));
+            logger.debug(TAG, `Sent RPC: ${method} (id=${id})`);
+        });
+    }
+    /** Register an event listener */
+    on(event, listener) {
+        if (!this.listeners.has(event)) {
+            this.listeners.set(event, new Set());
+        }
+        this.listeners.get(event).add(listener);
+    }
+    /** Remove an event listener */
+    off(event, listener) {
+        this.listeners.get(event)?.delete(listener);
+    }
+    /** Get current connection state */
+    getState() {
+        return this.state;
+    }
+    /** Get the hello-ok snapshot from the last successful connection */
+    getHelloOk() {
+        return this.lastHelloOk;
+    }
+    /** Get stored device token (for future connects) */
+    getDeviceToken() {
+        return this.deviceToken;
+    }
+    // ---- Message handling ----
+    handleMessage(data) {
+        let frame;
+        try {
+            frame = JSON.parse(data.toString());
+        }
+        catch {
+            logger.warn(TAG, 'Received unparseable message');
+            return;
+        }
+        // -- Response frames (hello-ok, RPC responses) --
+        if (frame.type === 'res') {
+            this.handleResponse(frame);
+            return;
+        }
+        // -- Event frames --
+        if (frame.type === 'event') {
+            this.handleEvent(frame);
+            return;
+        }
+        // -- Request frames from gateway (unexpected for us) --
+        if (frame.type === 'req') {
+            logger.debug(TAG, `Received request from gateway (unexpected): ${frame.id}`);
+        }
+    }
+    handleResponse(frame) {
+        const id = frame.id;
+        if (!id)
+            return;
+        // Check pending RPCs
+        const pending = this.pendingRpcs.get(id);
+        if (pending) {
+            clearTimeout(pending.timer);
+            this.pendingRpcs.delete(id);
+            if (frame.ok) {
+                // Check if this is the hello-ok response to our connect request
+                if (frame.payload && typeof frame.payload === 'object') {
+                    const payload = frame.payload;
+                    if (payload.type === 'hello-ok') {
+                        this.handleHelloOk(frame.payload);
+                    }
+                }
+                pending.resolve(frame.payload);
+            }
+            else {
+                pending.reject(new Error(frame.error?.message ?? `RPC failed (code ${frame.error?.code ?? 'unknown'})`));
+            }
+            return;
+        }
+        // Unexpected response
+        if (!frame.ok) {
+            logger.warn(TAG, `Unexpected error response (id=${id}): ${frame.error?.message}`);
+        }
+    }
+    handleEvent(frame) {
+        const event = frame.event;
+        switch (event) {
+            case 'connect.challenge':
+                this.handleChallenge(frame.payload);
+                break;
+            case 'agent':
+                this.resetStaleTimer();
+                if (frame.payload && typeof frame.payload === 'object') {
+                    const p = frame.payload;
+                    this.emit('agent', {
+                        runId: p.runId,
+                        stream: p.stream,
+                        data: p.data,
+                        seq: frame.seq,
+                    });
+                }
+                break;
+            case 'presence':
+                this.resetStaleTimer();
+                this.emit('presence', { payload: frame.payload, seq: frame.seq });
+                break;
+            case 'tick':
+                this.resetStaleTimer();
+                this.emit('tick', undefined);
+                break;
+            case 'shutdown':
+                logger.warn(TAG, 'Gateway shutting down — will reconnect');
+                this.emit('shutdown', undefined);
+                // Don't immediately reconnect; the close event will trigger reconnection
+                break;
+            default:
+                logger.debug(TAG, `Unknown gateway event: ${event}`);
+        }
+    }
+    // ---- Handshake ----
+    /**
+     * Step 1: Receive connect.challenge with {nonce, ts}.
+     * Step 2: Send connect request with auth token.
+     */
+    handleChallenge(payload) {
+        logger.info(TAG, `Received challenge (nonce=${payload.nonce?.slice(0, 8)}...)`);
+        if (!this.ws || this.ws.readyState !== WebSocket.OPEN) {
+            logger.error(TAG, 'Cannot respond to challenge: WebSocket not open');
+            return;
+        }
+        const connectId = `connect-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        const connectFrame = {
+            type: 'req',
+            id: connectId,
+            method: 'connect',
+            params: {
+                minProtocol: MIN_PROTOCOL_VERSION,
+                maxProtocol: MAX_PROTOCOL_VERSION,
+                client: {
+                    id: CLIENT_ID,
+                    version: CLIENT_VERSION,
+                    platform: 'node',
+                    mode: 'backend',
+                },
+                role: 'operator',
+                scopes: ['operator.read', 'operator.write'],
+                auth: {
+                    token: this.gatewayToken,
+                    ...(this.deviceToken && { deviceToken: this.deviceToken }),
+                },
+            },
+        };
+        // Register as pending RPC so the hello-ok response routes through handleResponse
+        const timer = setTimeout(() => {
+            this.pendingRpcs.delete(connectId);
+            logger.error(TAG, 'Connect handshake timed out');
+            // Force close to trigger reconnect
+            this.ws?.close(4000, 'Handshake timeout');
+        }, RPC_TIMEOUT_MS);
+        this.pendingRpcs.set(connectId, {
+            resolve: () => { },
+            reject: (err) => {
+                logger.error(TAG, `Handshake failed: ${err.message}`);
+                this.ws?.close(4000, 'Handshake rejected');
+            },
+            timer,
+        });
+        this.ws.send(JSON.stringify(connectFrame));
+        logger.info(TAG, 'Sent connect request');
+    }
+    /**
+     * Step 3: Process hello-ok response.
+     * Extracts policy, snapshot, and device token.
+     */
+    handleHelloOk(payload) {
+        logger.info(TAG, `Connected to gateway (protocol=${payload.protocol})`);
+        this.lastHelloOk = payload;
+        this.attempt = 0; // Reset reconnect counter
+        // Parse policy
+        if (payload.policy?.tickIntervalMs) {
+            this.tickIntervalMs = payload.policy.tickIntervalMs;
+            logger.debug(TAG, `Tick interval: ${this.tickIntervalMs}ms`);
+        }
+        // Store device token for future connects
+        if (payload.auth?.deviceToken) {
+            this.deviceToken = payload.auth.deviceToken;
+            logger.debug(TAG, 'Stored device token');
+        }
+        // Log snapshot info
+        const snap = payload.snapshot;
+        if (snap) {
+            logger.info(TAG, `Gateway uptime: ${Math.round((snap.uptimeMs ?? 0) / 1000)}s, stateVersion: ${JSON.stringify(snap.stateVersion)}`);
+        }
+        this.setState('connected');
+        this.resetStaleTimer();
+        this.emit('connected', payload);
+    }
+    // ---- Stale detection ----
+    /** Reset the stale timers — called on any incoming event/tick */
+    resetStaleTimer() {
+        this.clearStaleTimer();
+        const warnMs = this.tickIntervalMs * 2;
+        const reconnectMs = this.tickIntervalMs * 3;
+        // Warn at 2x tick interval
+        this.staleWarnTimer = setTimeout(() => {
+            if (this.state === 'connected') {
+                logger.warn(TAG, `No data received for ${warnMs}ms — connection may be stale`);
+            }
+        }, warnMs);
+        // Force reconnect at 3x tick interval
+        this.staleReconnectTimer = setTimeout(() => {
+            if (this.state === 'connected') {
+                logger.error(TAG, `No data received for ${reconnectMs}ms — forcing reconnect`);
+                this.ws?.close(4000, 'Stale connection');
+            }
+        }, reconnectMs);
+    }
+    clearStaleTimer() {
+        if (this.staleWarnTimer) {
+            clearTimeout(this.staleWarnTimer);
+            this.staleWarnTimer = null;
+        }
+        if (this.staleReconnectTimer) {
+            clearTimeout(this.staleReconnectTimer);
+            this.staleReconnectTimer = null;
+        }
+    }
+    // ---- Reconnection ----
+    scheduleReconnect() {
+        this.attempt++;
+        if (this.attempt > this.reconnectConfig.maxAttempts) {
+            logger.error(TAG, `Max reconnection attempts (${this.reconnectConfig.maxAttempts}) exceeded`);
+            this.setState('failed');
+            this.emit('failed', { reason: 'Max reconnection attempts exceeded' });
+            return;
+        }
+        const delay = computeDelay(this.attempt - 1, this.reconnectConfig);
+        logger.info(TAG, `Reconnecting in ${Math.round(delay)}ms (attempt ${this.attempt}/${this.reconnectConfig.maxAttempts})`);
+        this.setState('reconnecting');
+        this.emit('reconnecting', { attempt: this.attempt, delayMs: Math.round(delay) });
+        this.reconnectTimer = setTimeout(() => {
+            this.reconnectTimer = null;
+            this.connect();
+        }, delay);
+    }
+    clearReconnectTimer() {
+        if (this.reconnectTimer) {
+            clearTimeout(this.reconnectTimer);
+            this.reconnectTimer = null;
+        }
+    }
+    // ---- Internal helpers ----
+    setState(newState) {
+        if (this.state === newState)
+            return;
+        const prev = this.state;
+        this.state = newState;
+        logger.debug(TAG, `State: ${prev} → ${newState}`);
+    }
+    emit(event, payload) {
+        const listeners = this.listeners.get(event);
+        if (!listeners)
+            return;
+        for (const listener of listeners) {
+            try {
+                listener(payload);
+            }
+            catch (err) {
+                logger.error(TAG, `Event listener error (${event}): ${err instanceof Error ? err.message : String(err)}`);
+            }
+        }
+    }
+    rejectAllPending(reason) {
+        for (const [, pending] of this.pendingRpcs) {
+            clearTimeout(pending.timer);
+            pending.reject(new Error(reason));
+        }
+        this.pendingRpcs.clear();
+    }
+}

package/bridge/gateway/poller.d.ts

@@ -0,0 +1,146 @@
+import type { GatewayHttpClient } from './gateway-http-client.js';
+import type { ToolMap } from './tool-discovery.js';
+import type { TickerData, CandleData, OrderData, MarketStructureData, CryptoMetricsData, VolumeAnalysisData } from '../types.js';
+export declare const TICKER_INTERVAL_MS = 5000;
+export declare const OHLCV_INTERVAL_MS = 15000;
+export declare const POSITIONS_INTERVAL_MS = 10000;
+export declare const MARKET_STRUCTURE_INTERVAL_MS = 60000;
+/** CCXT position — minimal shape needed by poller */
+export interface CcxtPosition {
+    symbol: string;
+    side: 'long' | 'short' | string;
+    contracts?: number;
+    contractSize?: number;
+    entryPrice?: number;
+    markPrice?: number;
+    unrealizedPnl?: number;
+    leverage?: number;
+    notional?: number;
+    [key: string]: unknown;
+}
+/** Callbacks fired by the Poller when fresh data arrives from polls. */
+export interface PollerCallbacks {
+    /** Ticker data from fetch_ticker — fires every 1s */
+    onTicker: (data: TickerData) => void;
+    /** Candle data from fetch_ohlcv — fires every 5s */
+    onCandle: (data: CandleData) => void;
+    /** Raw CCXT positions from fetch_positions — fires every 3s */
+    onPositions: (positions: CcxtPosition[]) => void;
+    /** Parsed balance from fetch_balance — fires every 10s */
+    onBalance: (balance: {
+        currency: string;
+        total: number;
+        available: number;
+        locked: number;
+    }) => void;
+    /** Parsed open orders from fetch_open_orders — fires every 3s */
+    onOpenOrders: (orders: OrderData[]) => void;
+    /** Multi-TF analysis from get_market_structure — fires every 30s */
+    onMarketStructure?: (data: MarketStructureData) => void;
+    /** Crypto metrics (funding rate + OI) — fires every 60s */
+    onCryptoMetrics?: (data: CryptoMetricsData) => void;
+    /** Volume/thrust analysis — fires every 15s */
+    onVolumeAnalysis?: (data: VolumeAnalysisData) => void;
+}
+/** True when an error message carries a Binance rate-limit / IP-ban signal
+ *  (418 ban, or 429 / -1003 "too many requests" soft limit). Poll methods that
+ *  wrap their own try/catch MUST rethrow these so guardedExec's catch can arm
+ *  the process-wide circuit-breaker (applyRateLimitBackoff). Swallowing them
+ *  internally as "supplementary/non-fatal" silently defeats the ban gate: a
+ *  fixed-cadence poller keeps hammering a banned IP, and every request during a
+ *  418 EXTENDS the ban (see docs/CLAUDE/binance-ratelimit.md). Kept in sync
+ *  with the classification branches in applyRateLimitBackoff. */
+export declare function isRateLimitShapedError(msg: string): boolean;
+export declare class Poller {
+    private readonly http;
+    private readonly toolMap;
+    private readonly symbol;
+    private readonly callbacks;
+    private readonly quoteCurrency;
+    private running;
+    private paused;
+    private timers;
+    /** Prevents concurrent polls of the same type (if HTTP is slow) */
+    private readonly inflight;
+    /** Process-wide circuit-breaker. While `Date.now() < cooldownUntilMs`,
+     *  `guardedExec` skips EVERY poll regardless of type. Set when any poll
+     *  observes a Binance 418 (IP ban) or 429 (rate-limit) error.
+     *
+     *  Why this exists: pre-2026-05-15 the poller had no ban awareness — on a
+     *  418 every one of ~8 pollers (ticker 1s, positions/orders 3s, …) kept
+     *  firing on its original cadence straight through the ban, and since
+     *  Binance EXTENDS an IP ban every time you hit it during the ban, the
+     *  system never recovered on its own (self-perpetuating lockout that
+     *  zeroed the dashboard + blinded the agent for the whole window). The
+     *  breaker makes the whole poller go quiet until Binance's stated ban
+     *  expiry (+slack), or an exponential window for soft 429s. */
+    private cooldownUntilMs;
+    /** Index into RATE_LIMIT_BACKOFF_MS for consecutive soft 429s. Reset to
+     *  -1 (→ step 0 on first hit) after any clean poll. */
+    private rateLimitStep;
+    /** Throttles the "in cooldown, skipping" log to once per cooldown window
+     *  so a 2-min ban doesn't emit hundreds of identical skip lines. */
+    private cooldownLogged;
+    /** Per-tool poll-attribution for the current 60s window (observability
+     *  only). The skill is a SEPARATE process from the plugin but shares the
+     *  Binance per-IP weight budget; the plugin's ban-gate weight summary
+     *  cannot see skill polls. This is the skill-side mirror so the IP load
+     *  split is provable, not guessed. */
+    private pollWindowStart;
+    private readonly pollCountByTool;
+    constructor(http: GatewayHttpClient, toolMap: ToolMap, symbol: string, callbacks: PollerCallbacks, quoteCurrency?: string);
+    /**
+     * Start all poll loops. Each tool is polled on its own interval.
+     * Tools not present in the ToolMap are silently skipped.
+     * Each poll fires immediately on start, then repeats on interval.
+     */
+    start(): void;
+    /** Stop all poll loops and clean up timers. */
+    stop(): void;
+    /** Pause polling (timers keep ticking but polls are skipped). */
+    pause(): void;
+    /** Resume polling after a pause. */
+    resume(): void;
+    /**
+     * Schedule a poll loop for a logical tool, only if it was discovered.
+     * Fires immediately, then repeats on interval.
+     */
+    private scheduleIfAvailable;
+    /**
+     * Execute a poll function with error handling and in-flight guard.
+     * - Skipped when paused or stopped (checked before AND after acquiring inflight slot)
+     * - Skipped if a previous poll of the same type is still in-flight
+     * - Errors are logged and swallowed (never crash the provider)
+     */
+    private guardedExec;
+    /** Inspect a failed poll's error for Binance rate-limit signals and arm
+     *  the process-wide circuit-breaker accordingly.
+     *
+     *  - **418** (IP ban): Binance returns `banned until <epoch-ms>` in the
+     *    message. We respect that exact timestamp + slack — guessing a
+     *    shorter window would just re-ban and extend it.
+     *  - **429 / -1003 "Too many requests"** (soft rate-limit, no ban yet):
+     *    exponential backoff so we stop climbing toward a 418.
+     *
+     *  Any non-rate-limit error is left alone (normal transient handling). */
+    private applyRateLimitBackoff;
+    private pollTicker;
+    private pollOhlcv;
+    private pollPositions;
+    private pollBalance;
+    private pollOpenOrders;
+    private pollMarketStructure;
+    /**
+     * Fetch funding rate and open interest via the dedicated get_crypto_metrics tool.
+     * The plugin tool handles spot→perp symbol conversion and raw CCXT ticker parsing.
+     */
+    private pollCryptoMetrics;
+    /**
+     * Fetch 25 bars of 5m OHLCV and compute volume analysis metrics:
+     * - Volume expansion ratio (current vs 20-bar avg)
+     * - Close position (where close sits in bar's range, 0=low, 1=high)
+     * - Directional thrust (volume-weighted close position, -1 to +1)
+     * - Buy volume estimate (proxy using close position)
+     */
+    private pollVolumeAnalysis;
+}