@reefclaw/openclaw-plugin 0.1.2 → 0.1.3

package/bridge/bridge.js

@@ -6,7 +6,7 @@ import { join } from 'path';
 import { homedir } from 'os';
 import { logger } from './logger.js';
 import { Connector } from './connector.js';
-import { readLocalSkillVersion, validateSkillContent, compareSemver } from './utils/skill-version.js';
+import { readLocalSkillVersion, readAgentVisibleSkillVersions, validateSkillContent, compareSemver } from './utils/skill-version.js';
 import { verifySkillSignature, signatureRequired, readLastAppliedSignedAtMs, recordAppliedSignedAt, } from './utils/skill-signing.js';
 import { isTradingMode, validateModeTransition, redactTokens } from '@reefclaw/shared';
 import { OPERATOR_WRITE_METHODS } from './types.js';
@@ -837,6 +837,37 @@ export class Bridge {
                     logger.warn(TAG, `Failed to update workspace skill SKILL.md: ${scanErr instanceof Error ? scanErr.message : String(scanErr)}`);
                 }
             }
+            // 2d. Also write to the plugin-extension bundled skill directory — the
+            // chat-channel install layout (`/plugins install clawhub:...`) loads the
+            // agent-visible skill from ~/.openclaw/extensions/<plugin>/skills/, and a
+            // plugin (re)install resets that copy to the bundled bootstrap while the
+            // workspace copy above (our version tracker) survives. Without this
+            // write the agent stays on the bootstrap forever while the pull reports
+            // "already up to date" (observed live 2026-07-11).
+            const extensionsDir = join(homedir(), '.openclaw', 'extensions');
+            if (existsSync(extensionsDir)) {
+                try {
+                    for (const ext of readdirSync(extensionsDir, { withFileTypes: true })) {
+                        if (!ext.isDirectory() || !ext.name.includes('reefclaw'))
+                            continue;
+                        const extSkillsDir = join(extensionsDir, ext.name, 'skills');
+                        if (!existsSync(extSkillsDir))
+                            continue;
+                        for (const skillEntry of readdirSync(extSkillsDir, { withFileTypes: true })) {
+                            if (!skillEntry.isDirectory() || !skillEntry.name.includes('reefclaw'))
+                                continue;
+                            const extSkillMd = join(extSkillsDir, skillEntry.name, 'SKILL.md');
+                            if (existsSync(extSkillMd)) {
+                                writeFileSync(extSkillMd, content, 'utf-8');
+                                logger.info(TAG, `Updated extension skill SKILL.md: ${extSkillMd}`);
+                            }
+                        }
+                    }
+                }
+                catch (scanErr) {
+                    logger.warn(TAG, `Failed to update extension skill SKILL.md: ${scanErr instanceof Error ? scanErr.message : String(scanErr)}`);
+                }
+            }
             // 3. Invalidate skillsSnapshot cache WITHOUT wiping sessions.json
             // Previously we wrote '{}' to sessions.json which destroyed OpenClaw chat history.
             // Now we surgically remove only the skillsSnapshot key from each session entry,
@@ -979,12 +1010,24 @@ export class Bridge {
                 return;
             }
             this.currentSkillVersion = readLocalSkillVersion();
-            if (compareSemver(body.version, this.currentSkillVersion) <= 0) {
+            // The workspace tracker alone is NOT proof the agent has the full skill:
+            // a plugin (re)install resets the agent-visible extension copy to the
+            // bundled bootstrap while the workspace copy survives (observed live
+            // 2026-07-11 — agent stranded on 0.0.5 with the tracker at 2.20.4). If
+            // ANY agent-visible copy is behind the webapp version, re-apply anyway;
+            // applySkillUpdate is idempotent across all copies.
+            const staleAgentCopies = readAgentVisibleSkillVersions().filter((v) => compareSemver(body.version, v) > 0);
+            if (compareSemver(body.version, this.currentSkillVersion) <= 0 && staleAgentCopies.length === 0) {
                 logger.info(TAG, `SKILL.md webapp pull: local v${this.currentSkillVersion ?? 'unknown'} already >= webapp v${body.version} — nothing to do`);
                 this.skillPullInFlight = false;
                 return;
             }
-            logger.info(TAG, `SKILL.md webapp pull: local v${this.currentSkillVersion ?? 'unknown'} behind webapp v${body.version} — applying`);
+            if (staleAgentCopies.length > 0 && compareSemver(body.version, this.currentSkillVersion) <= 0) {
+                logger.info(TAG, `SKILL.md webapp pull: agent-visible skill copy at v${staleAgentCopies[0]} behind webapp v${body.version} (plugin reinstall reset it) — re-applying`);
+            }
+            else {
+                logger.info(TAG, `SKILL.md webapp pull: local v${this.currentSkillVersion ?? 'unknown'} behind webapp v${body.version} — applying`);
+            }
             const result = await this.applySkillUpdate({ version: body.version, content: body.content });
             this.emit('agent_state', 'skill_update_applied', {
                 event: 'skill_update_applied',

package/bridge/utils/skill-version.d.ts

@@ -2,6 +2,15 @@
 export declare function parseSkillVersion(content: string): string | null;
 /** Read current SKILL.md version from disk */
 export declare function readLocalSkillVersion(): string | null;
+/** Versions of the AGENT-VISIBLE reefclaw SKILL.md copies under the
+ *  plugin-extension layout (`~/.openclaw/extensions/<plugin>/skills/<skill>/`)
+ *  — what OpenClaw's skill loader actually reads on chat-channel installs.
+ *  A plugin (re)install resets these to the bundled bootstrap while the
+ *  workspace copy (the version tracker above) survives, so the tracker alone
+ *  cannot be trusted for "already up to date" (observed live 2026-07-11: agent
+ *  stranded on bootstrap 0.0.5 while the tracker read 2.20.4). Fail-soft:
+ *  unreadable dirs/files are skipped; no extensions dir → empty list. */
+export declare function readAgentVisibleSkillVersions(): string[];
 /**
  * Compare two semver strings.
  * Returns 1 if a > b, -1 if a < b, 0 if equal.

package/bridge/utils/skill-version.js

@@ -1,5 +1,5 @@
 // SKILL.md version parsing utility for OTA updates
-import { readFileSync } from 'fs';
+import { readFileSync, readdirSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 const SKILL_MD_PATH = join(homedir(), '.openclaw', 'workspace', 'SKILL.md');
@@ -18,6 +18,50 @@ export function readLocalSkillVersion() {
         return null;
     }
 }
+/** Versions of the AGENT-VISIBLE reefclaw SKILL.md copies under the
+ *  plugin-extension layout (`~/.openclaw/extensions/<plugin>/skills/<skill>/`)
+ *  — what OpenClaw's skill loader actually reads on chat-channel installs.
+ *  A plugin (re)install resets these to the bundled bootstrap while the
+ *  workspace copy (the version tracker above) survives, so the tracker alone
+ *  cannot be trusted for "already up to date" (observed live 2026-07-11: agent
+ *  stranded on bootstrap 0.0.5 while the tracker read 2.20.4). Fail-soft:
+ *  unreadable dirs/files are skipped; no extensions dir → empty list. */
+export function readAgentVisibleSkillVersions() {
+    const versions = [];
+    const extensionsDir = join(homedir(), '.openclaw', 'extensions');
+    let extEntries;
+    try {
+        extEntries = readdirSync(extensionsDir, { withFileTypes: true });
+    }
+    catch {
+        return versions;
+    }
+    for (const ext of extEntries) {
+        if (!ext.isDirectory() || !ext.name.includes('reefclaw'))
+            continue;
+        const skillsDir = join(extensionsDir, ext.name, 'skills');
+        let skillEntries;
+        try {
+            skillEntries = readdirSync(skillsDir, { withFileTypes: true });
+        }
+        catch {
+            continue;
+        }
+        for (const s of skillEntries) {
+            if (!s.isDirectory() || !s.name.includes('reefclaw'))
+                continue;
+            try {
+                const v = parseSkillVersion(readFileSync(join(skillsDir, s.name, 'SKILL.md'), 'utf-8'));
+                if (v)
+                    versions.push(v);
+            }
+            catch {
+                // unreadable/absent copy — nothing to report for this entry
+            }
+        }
+    }
+    return versions;
+}
 // 120KB — the full SKILL.md crossed 100KB at v2.20.0 (103.7KB), which silently
 // broke every OTA apply against the old 100KB cap. Keep comfortably under the
 // 128KiB Cloudflare Durable-Object per-value hard limit the relay stores into.

package/ccxt/binance-ban-gate.js

@@ -128,6 +128,8 @@ const CONTEXT_WEIGHT = {
     fetchOHLCV: 2,
     fetchFundingRate: 1,
     fetchOpenInterest: 1,
+    // Readiness gate's host→Binance reachability probe (fapiPublicGetTime, wt 1).
+    reachabilityProbe: 1,
     // ExchangeInfoCache boot load — ccxt loadMarkets() → GET /fapi/v1/exchangeInfo,
     // IP weight 1 (doc-verified developers.binance.com 2026-07-10). Was the
     // known "ungated_ip" ccxt-internal call named in the window-summary comment.
@@ -200,7 +202,7 @@ const NEVER_PACE = new Set([
 const SHED_FIRST = new Set([
     'fetchTodayIncomeBreakdown', 'fetchTransfers', 'fetchRecentTradedSymbols',
     'fetchTicker', 'fetchTickerRaw', 'fetchOHLCV', 'fetchOrderBook',
-    'fetchFundingRate', 'fetchOpenInterest',
+    'fetchFundingRate', 'fetchOpenInterest', 'reachabilityProbe',
 ]);
 let weightWindowStart = 0;
 let weightUsed = 0;

package/ccxt/binance-public.d.ts

@@ -15,4 +15,19 @@ export declare class BinancePublicApi {
     fetchOrderBook(symbol: string, limit?: number): Promise<OrderBookDepth | null>;
     /** Fetch OHLCV candles. Returns null on error. */
     fetchOHLCV(symbol: string, timeframe?: string, limit?: number): Promise<CcxtOHLCV[] | null>;
+    /** Probe Binance USD-M FUTURES reachability from this host — the readiness
+     *  gate's core signal. Calls the futures-explicit implicit method so it hits
+     *  `fapi.binance.com` (a bare `fetchTime()` on this instance resolves to spot
+     *  `api.binance.com`, since the public client doesn't set defaultType:'future').
+     *  HTTP 451 = Binance geo-restriction; the ban gate does NOT classify 451, so
+     *  we inspect the message here. Ban-gate compliant (assertNotBanned/noteSuccess/
+     *  noteBinanceError). Outcomes:
+     *   - 'reachable'   clean response (driftMs = serverTime − localTime)
+     *   - 'geo_blocked' HTTP 451 — host is in a restricted region (actionable)
+     *   - 'unknown'     the ban/weight gate paused us — NOT a host problem
+     *   - 'unreachable' network / DNS / timeout / other error */
+    probeReachability(): Promise<{
+        outcome: 'reachable' | 'geo_blocked' | 'unreachable' | 'unknown';
+        driftMs: number | null;
+    }>;
 }

package/ccxt/binance-public.js

@@ -2,7 +2,7 @@
 // No API keys required — only uses public market data.
 import { createRequire } from 'node:module';
 import { logger } from '../logger.js';
-import { assertNotBanned, noteBinanceError, noteSuccess } from './binance-ban-gate.js';
+import { assertNotBanned, noteBinanceError, noteSuccess, BinanceBannedError } from './binance-ban-gate.js';
 const TAG = 'binance-public';
 // Load ccxt via CJS require — OpenClaw's ESM loader gives wrong module shape
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
@@ -144,4 +144,37 @@ export class BinancePublicApi {
             return null;
         }
     }
+    /** Probe Binance USD-M FUTURES reachability from this host — the readiness
+     *  gate's core signal. Calls the futures-explicit implicit method so it hits
+     *  `fapi.binance.com` (a bare `fetchTime()` on this instance resolves to spot
+     *  `api.binance.com`, since the public client doesn't set defaultType:'future').
+     *  HTTP 451 = Binance geo-restriction; the ban gate does NOT classify 451, so
+     *  we inspect the message here. Ban-gate compliant (assertNotBanned/noteSuccess/
+     *  noteBinanceError). Outcomes:
+     *   - 'reachable'   clean response (driftMs = serverTime − localTime)
+     *   - 'geo_blocked' HTTP 451 — host is in a restricted region (actionable)
+     *   - 'unknown'     the ban/weight gate paused us — NOT a host problem
+     *   - 'unreachable' network / DNS / timeout / other error */
+    async probeReachability() {
+        try {
+            assertNotBanned('reachabilityProbe');
+            const r = await this.exchange.fapiPublicGetTime({});
+            noteSuccess();
+            const serverTime = Number(r?.serverTime);
+            const driftMs = Number.isFinite(serverTime) ? serverTime - Date.now() : null;
+            return { outcome: 'reachable', driftMs };
+        }
+        catch (err) {
+            noteBinanceError(err);
+            if (err instanceof BinanceBannedError) {
+                // Gate paused us (418/429 backoff or weight pacer) — we didn't actually
+                // reach the host, so the result is UNKNOWN, not a reachability failure.
+                return { outcome: 'unknown', driftMs: null };
+            }
+            const msg = err instanceof Error ? err.message : String(err);
+            const geo = msg.includes('451');
+            logger.warn(TAG, `probeReachability failed${geo ? ' (HTTP 451 geo-block)' : ''}: ${msg}`);
+            return { outcome: geo ? 'geo_blocked' : 'unreachable', driftMs: null };
+        }
+    }
 }

package/index.js

@@ -29,6 +29,7 @@ import { PositionStateStore } from './live/position-state-store.js';
 import { PendingEntryStore } from './ingest/pending-entry-metadata.js';
 import { onReconcilerObservedClose, reconcileStateStoreOnStartup } from './ingest/reconciler-cleanup.js';
 import { reconcileDbOpenVsExchange } from './ingest/reconcile-db-vs-exchange.js';
+import { startReadinessReporter } from './ingest/readiness-reporter.js';
 import { IntelMicrostructureAssembler } from './live/microstructure-assembler.js';
 import { recordPositionReviewsTool } from './tools/record-position-reviews.js';
 import { getMyRecentReviewsTool } from './tools/get-my-recent-reviews.js';
@@ -2020,6 +2021,19 @@ const paperTradingPlugin = {
         pluginToolNames = toolNames;
         pluginInitialised = true;
         logger.info(TAG, `Registered ${gatedTools.length} tools (gate mode=${toolGate.getMode()}): ${toolNames.join(', ')}. Plugin v3.8.0 (${runtime.mode} mode)`);
+        // Agent-readiness reporter (docs/AGENT_READINESS_GATE_PLAN.md Phase 1):
+        // probe host→Binance reachability (HTTP 451 geo-block) + clock drift on the
+        // host and POST a plain-English report to the webapp, so a silently-broken
+        // agent shows an actionable dashboard alert instead of a false green.
+        // Advisory + fire-and-forget; no token → no-op. Runs here once (guarded by
+        // the pluginInitialised early-return → once per process) + on an unref'd
+        // interval inside the reporter.
+        startReadinessReporter({
+            apiBaseUrl,
+            token: resolveIngestToken({ connectionToken }),
+            binanceApi,
+            toolCount: toolNames.length,
+        });
         maybeStartConnectorSupervisor();
     },
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reefclaw/openclaw-plugin",
-  "version": "0.1.2",
+  "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/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: