@reefclaw/openclaw-plugin 0.1.18 → 0.1.20

package/bridge/gateway/gateway-ws-client.d.ts

@@ -1,7 +1,10 @@
 import { type ReconnectConfig as BaseReconnectConfig } from '../utils/reconnect.js';
 import type { GatewayConfig } from './gateway-config.js';
 interface ReconnectConfig extends BaseReconnectConfig {
-    maxAttempts: number;
+    /** Fast-backoff attempts before falling back to the slow retry loop */
+    maxFastAttempts: number;
+    /** Slow retry interval once the fast attempts are exhausted (ms) */
+    slowRetryMs: number;
 }
 /** hello-ok response payload from gateway */
 export interface HelloOkPayload {
@@ -56,6 +59,9 @@ export declare class GatewayWsClient {
     private ws;
     private state;
     private attempt;
+    /** True once the fast burst is spent and we are in the slow retry loop
+     *  (kept so the "switching to slow retry" warning logs once, not per attempt). */
+    private slowRetryActive;
     private reconnectTimer;
     private staleWarnTimer;
     private staleReconnectTimer;

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

@@ -30,11 +30,23 @@ const MIN_PROTOCOL_VERSION = 3;
 const MAX_PROTOCOL_VERSION = 4;
 const CLIENT_ID = 'openclaw-tui';
 const CLIENT_VERSION = '0.1.0';
+// Mirrors the relay connector's proven shape (see connector.ts DEFAULT_RECONNECT):
+// a bounded fast-backoff burst, then a slow retry that NEVER gives up.
+//
+// This client used to have `maxAttempts: 20` and go terminal ('failed') when it
+// ran out — roughly 9 minutes of budget (2+4+8+16s, then 16 x 30s). On
+// 2026-07-31 an OpenClaw upgrade left the gateway crash-looping for 56 minutes;
+// the bridge burned its 20 attempts in the first 9, gave up permanently, and
+// stayed dark even AFTER the gateway recovered. The dashboard — the operator's
+// window and one of the emergency-control paths — required a manual bridge
+// restart to come back. Any gateway downtime over ~9 min (upgrade, reboot,
+// crash-loop) reproduced it, on every deployment.
 const DEFAULT_RECONNECT = {
     baseDelayMs: 2_000,
     maxDelayMs: 30_000,
-    maxAttempts: 20,
+    maxFastAttempts: 20,
     jitterFactor: 0.3,
+    slowRetryMs: 60_000,
 };
 // ---- Fatal close codes ----
 /** Auth errors — do not reconnect */
@@ -45,6 +57,9 @@ export class GatewayWsClient {
     ws = null;
     state = 'disconnected';
     attempt = 0;
+    /** True once the fast burst is spent and we are in the slow retry loop
+     *  (kept so the "switching to slow retry" warning logs once, not per attempt). */
+    slowRetryActive = false;
     reconnectTimer = null;
     staleWarnTimer = null;
     staleReconnectTimer = null;
@@ -351,6 +366,7 @@ export class GatewayWsClient {
         logger.info(TAG, `Connected to gateway (protocol=${payload.protocol})`);
         this.lastHelloOk = payload;
         this.attempt = 0; // Reset reconnect counter
+        this.slowRetryActive = false; // Back on the fast budget for the next drop
         // Parse policy
         if (payload.policy?.tickIntervalMs) {
             this.tickIntervalMs = payload.policy.tickIntervalMs;
@@ -403,14 +419,21 @@ export class GatewayWsClient {
     // ---- 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 { maxFastAttempts, slowRetryMs } = this.reconnectConfig;
+        // Exhausting the fast burst is NOT terminal — a gateway that is down for an
+        // hour (upgrade, reboot, crash-loop) must still be picked up when it
+        // returns. Only a fatal close code (4001 auth) ends the client, because a
+        // rejected token will never start working and must not be retried forever.
+        const exhausted = this.attempt > maxFastAttempts;
+        if (exhausted && !this.slowRetryActive) {
+            this.slowRetryActive = true;
+            logger.warn(TAG, `Fast reconnect budget (${maxFastAttempts} attempts) exhausted — switching to slow retry every ` +
+                `${Math.round(slowRetryMs / 1000)}s. Still trying; will reconnect on its own when the gateway returns.`);
         }
-        const delay = computeDelay(this.attempt - 1, this.reconnectConfig);
-        logger.info(TAG, `Reconnecting in ${Math.round(delay)}ms (attempt ${this.attempt}/${this.reconnectConfig.maxAttempts})`);
+        const delay = exhausted ? slowRetryMs : computeDelay(this.attempt - 1, this.reconnectConfig);
+        logger.info(TAG, exhausted
+            ? `Reconnecting in ${Math.round(delay)}ms (slow retry, attempt ${this.attempt})`
+            : `Reconnecting in ${Math.round(delay)}ms (attempt ${this.attempt}/${maxFastAttempts})`);
         this.setState('reconnecting');
         this.emit('reconnecting', { attempt: this.attempt, delayMs: Math.round(delay) });
         this.reconnectTimer = setTimeout(() => {

package/ingest/position-auto-capture.js

@@ -124,6 +124,25 @@ export async function onCreateOrderFilled(ctx, inputs, order) {
     //             scale-ins with WS-exact data; capturing here would double-post).
     const existing = ctx.stateStore.get(inputs.symbol);
     if (existing) {
+        // ★ SAME-ORDER GUARD — the twin of the dedup in onWsFillObserved (which
+        // returns when `stateEntry.openedFromExchangeTradeId === fill.exchangeOrderId`).
+        // That one covers create_order-then-WS; this covers WS-then-create_order,
+        // which is the ORDINARY ordering for a market order: the WS fill routinely
+        // beats the REST response (measured ~270-415ms on prod).
+        //
+        // Without it the stale probe below decides this case, and it CANNOT: its
+        // test is "does the exchange position equal this fill?", which is equally
+        // true of a genuinely stale mapping AND of the mapping the WS path just
+        // wrote for THIS VERY FILL. It chose 'stale', dropped the fresh mapping and
+        // journaled a second position — 38 duplicate pairs in 9 days (~11/day), each
+        // orphaning the WS row at 0 reviews while the exchange held ONE position.
+        // The twins were undedupable downstream because they key on different ids
+        // (WS = trade id, here = order id).
+        const orderId = typeof order.id === 'string' ? order.id : undefined;
+        if (orderId && existing.openedFromExchangeTradeId === orderId) {
+            logger.info(TAG, `onCreateOrderFilled ${inputs.symbol}: WS fill path already captured this order (${orderId}) — skipping duplicate capture`);
+            return;
+        }
         const probe = await probeStaleStateEntry(ctx, inputs.symbol, filledQty);
         if (probe === 'stale') {
             logger.warn(TAG, `onCreateOrderFilled ${inputs.symbol}: state-store entry (openedAt=${existing.openedAt}) is STALE — ` +

package/openclaw.plugin.json

@@ -1,8 +1,8 @@
 {
   "id": "reefclaw-paper-trading",
   "name": "ReefClaw Trading",
-  "version": "0.1.18",
-  "description": "Supervised trading plugin for the ReefClaw dashboard: paper trading with real market data (no API keys required), and optional live trading on Binance or Hyperliquid behind explicit operator opt-in, exchange API credentials, and always-on protective stop brackets. Includes the dashboard connector bridge, heartbeat automation, and remote SKILL.md instruction updates from the ReefClaw webapp.",
+  "version": "0.1.20",
+  "description": "Supervised trading plugin for the ReefClaw dashboard. It runs on YOUR machine and starts in PAPER mode with no API keys. It cannot trade real funds until you supply exchange credentials and step PAPER→MICRO_LIVE→LIVE yourself from the dashboard — the agent cannot make that change (the tool is refused without operator provenance). Exchange keys stay local, are used only to sign requests to the exchange, and are never transmitted to ReefClaw (asserted by a test in this package). Trading telemetry — positions, fills, decision journal — is sent to ReefClaw to render the dashboard. Every live position carries exchange-native protective stops. Remote updates to the agent's trading instructions are applied only after an Ed25519 signature is verified against a public key pinned in this build.",
   "author": "ReefClaw",
   "activation": {
     "onStartup": true

package/package.json

@@ -1,38 +1,38 @@
-{
-  "name": "@reefclaw/openclaw-plugin",
-  "version": "0.1.18",
-  "description": "ReefClaw supervised trading plugin for OpenClaw — paper trading with real market data, optional live trading on Binance or Hyperliquid (operator opt-in, API keys, always-on protective brackets), plus the ReefClaw dashboard connector with heartbeat automation and remote SKILL.md updates from the ReefClaw webapp. Install: /plugins install clawhub:@reefclaw/openclaw-plugin",
-  "type": "module",
-  "main": "index.js",
-  "openclaw": {
-    "extensions": [
-      "./index.js"
-    ],
-    "compat": {
-      "pluginApi": ">=2026.6.0"
-    },
-    "build": {
-      "openclawVersion": "2026.6.11"
-    }
-  },
-  "files": [
-    "**/*",
-    "!scripts/**"
-  ],
-  "engines": {
-    "node": ">=20"
-  },
-  "dependencies": {
-    "@reefclaw/shared": "0.1.4",
-    "ccxt": "4.5.37",
-    "json5": "2.2.3",
-    "ws": "8.21.1"
-  },
-  "scripts": {
-    "build": "node scripts/assemble.mjs",
-    "verify": "node scripts/verify-shared-contract.mjs",
-    "prepublishOnly": "node scripts/verify-shared-contract.mjs"
-  },
-  "license": "MIT",
-  "homepage": "https://reefclaw.com"
-}
+{
+  "name": "@reefclaw/openclaw-plugin",
+  "version": "0.1.20",
+  "description": "ReefClaw supervised trading plugin for OpenClaw. Runs entirely on YOUR machine and starts in PAPER mode \u00e2\u20ac\u201d it cannot trade real funds until you supply exchange credentials and walk the PAPER\u00e2\u2020\u2019MICRO_LIVE\u00e2\u2020\u2019LIVE ladder yourself from the ReefClaw dashboard (the agent cannot make that change; it is refused without operator provenance). Your exchange API keys stay on your machine to sign requests to the exchange and are NEVER sent to ReefClaw \u00e2\u20ac\u201d a test in the package asserts this. What does reach ReefClaw is trading telemetry for the dashboard (positions, fills, decision journal). Live trading always carries exchange-native protective stops. Trading instructions can be updated remotely, and every update must carry a valid Ed25519 signature verified against a key pinned in this build before it is applied. Install: /plugins install clawhub:@reefclaw/openclaw-plugin",
+  "type": "module",
+  "main": "index.js",
+  "openclaw": {
+    "extensions": [
+      "./index.js"
+    ],
+    "compat": {
+      "pluginApi": ">=2026.6.0"
+    },
+    "build": {
+      "openclawVersion": "2026.6.11"
+    }
+  },
+  "files": [
+    "**/*",
+    "!scripts/**"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "@reefclaw/shared": "0.1.4",
+    "ccxt": "4.5.37",
+    "json5": "2.2.3",
+    "ws": "8.21.1"
+  },
+  "scripts": {
+    "build": "node scripts/assemble.mjs",
+    "verify": "node scripts/verify-shared-contract.mjs",
+    "prepublishOnly": "node scripts/verify-shared-contract.mjs"
+  },
+  "license": "MIT",
+  "homepage": "https://reefclaw.com"
+}

package/skills/reefclaw/SKILL.md

@@ -1,10 +1,9 @@
 ---
 name: reefclaw
-version: 0.0.7
-description: ReefClaw trading control room — bootstrap (connects your agent; full trading instructions arrive automatically after first connect)
+version: 0.0.9
+description: ReefClaw trading control room — bootstrap (connects your agent; the full trading instructions arrive after first connect as a signed, signature-verified update)
 author: ReefClaw
 homepage: https://reefclaw.com
-repository: https://github.com/reefclaw/reefclaw
 license: MIT
 runtime: node
 entry: dist/index.js
@@ -28,7 +27,7 @@ config:
 
 ## About this file
 
-This is the thin BOOTSTRAP copy shipped in the `@reefclaw/connect` npm package. It covers **installing the ReefClaw plugin and connecting to the user's ReefClaw account** — nothing else. The FULL trading instructions (versioned 2.x.y) are delivered automatically by the ReefClaw connector minutes after the first successful connect, over the authenticated update channel — they replace this file in place (a 0.0.x version always loses the semver comparison). Maintainers: the "Connecting (first run)" section below MUST stay in sync with the same section in `skill/SKILL.md`.
+This is the thin BOOTSTRAP copy shipped in the `@reefclaw/connect` npm package. It covers **installing the ReefClaw plugin and connecting to the user's ReefClaw account** — nothing else. The FULL trading instructions (versioned 2.x.y) are delivered by the ReefClaw connector minutes after the first successful connect and replace this file in place (a 0.0.x version always loses the semver comparison). That replacement is **cryptographically verified before it is applied** — see "How instruction updates are verified" below. Maintainers: the "Connecting (first run)" section below MUST stay in sync with the same section in `skill/SKILL.md`.
 
 You are being connected to **ReefClaw**, a supervised trading control room. Your operator watches everything you do on the ReefClaw dashboard.
 
@@ -36,11 +35,39 @@ 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.
 
+## What this can and cannot do
+
+Worth stating exactly, because "a trading plugin" sounds like more authority than this actually has. Every line below is checkable in the installed package.
+
+| | |
+|---|---|
+| **Where it runs** | Entirely on the user's own machine, inside their OpenClaw. ReefClaw's servers host a dashboard, a relay and a market-data API — they do not execute trades. |
+| **Out of the box** | **PAPER mode**: real market data, simulated fills, no exchange account, no API keys. That is the default and it needs no credentials at all. |
+| **To trade real money** | The **user** adds exchange API credentials and then moves PAPER → MICRO_LIVE → LIVE one rung at a time from the ReefClaw dashboard. **The agent cannot do this**: the mode and credential tools are refused unless the call carries operator provenance from the dashboard, which an agent cannot mint conversationally. |
+| **Exchange API keys** | Kept **only on the user's machine** (`~/.reefclaw/plugin-config.json`, owner-only permissions) and used **only** to sign requests to the exchange. **They are never sent to ReefClaw** — a test in this package drives the real outbound clients and asserts no credential reaches the wire. On Hyperliquid the key is an *agent* key, which by design cannot withdraw or transfer funds. |
+| **What IS sent to ReefClaw** | Trading telemetry, so the dashboard can display it: positions, fills, balances and the decision journal. That is the product's purpose, and it is not optional while connected. |
+| **Protective stops** | Every live position carries exchange-native stop orders — enforced by the exchange itself, not by this software staying alive. |
+| **Kill switch** | The operator can pause, flatten or kill from the dashboard at any time. Those controls are never gated behind subscription state. |
+| **Instruction updates** | Signature-verified before they are applied — see the next section. |
+
+## How instruction updates are verified
+
+This file is replaced, in place, by the full trading instructions once you connect — so it is fair to ask what stops someone else from putting instructions on your machine. The answer is that **an update is applied only if it carries a valid Ed25519 signature made with ReefClaw's private signing key**, which exists only offline on the maintainer's machine — never on a server, in CI, or on the relay.
+
+Concretely, before any update is written:
+
+- The content is hashed and the signature is checked against a **public key pinned inside the installed build**. No signature, a signature that does not verify, content that does not match its hash, or a version that disagrees with the signed version ⇒ **the update is refused and the current instructions stay in place**.
+- A replay guard requires each accepted update to be strictly newer than the last one applied, so an old signed copy cannot be pushed back onto you.
+- The servers in the path are **carriers, not signers**: neither the ReefClaw webapp nor the relay holds the signing key, so compromising either is not enough to change what your agent is told to do.
+- Enforcement is **on by default**. The `SKILL_OTA_REQUIRE_SIGNATURE=off` escape hatch exists for local debugging only; it lets an *unsigned* update through and never accepts a *forged* one — an update whose signature fails is refused either way. Leave it unset.
+
+If an update is ever refused, that is the system working: the connector logs the reason and keeps the instructions you already have.
+
 ## 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.
+ReefClaw trades **Binance USD-M Futures or Hyperliquid perpetuals**, so the machine running this OpenClaw must be able to reach the venue you use. On Binance (`fapi.binance.com`) this matters more than people expect: 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 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.
+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), or use Hyperliquid, which does not geo-restrict this way. This is a hosting requirement; ReefClaw cannot configure around it.
 
 ## Connecting (first run) — saving the connect message
 
@@ -88,5 +115,5 @@ Whatever the install path, **save the connection settings anyway** — the conne
 ## After connecting
 
 - The ReefClaw dashboard flips to **Connected** on its own — no manual verification step.
-- Your full trading instructions (SKILL.md version 2.x) are delivered automatically over the authenticated connection and replace this file. You will be notified in chat when that happens.
+- Your full trading instructions (SKILL.md version 2.x) arrive over the authenticated connection and replace this file — **after** their signature is verified against the pinned key (see "How instruction updates are verified"). You will be notified in chat when that happens.
 - If more than ~10 minutes pass after a successful connect and this file is still a 0.0.x bootstrap version, tell the user to check the dashboard connection status.