@reefclaw/connect 0.1.39 → 0.1.41

package/assets/plugin/plugin-version.js

@@ -0,0 +1,58 @@
+// Which ReefClaw plugin RELEASE is running, and how it was installed — the two
+// facts the dashboard needs to (a) tell the trader an update exists and (b)
+// offer the right update path (one click for npx installs, ClawHub steps for
+// ClawHub installs, silence for the operator's own source/dist deploys).
+//
+// Version source: the `openclaw.plugin.json` that ships NEXT TO index.js in
+// every installed layout. Both release channels stamp it with the package
+// release version — installer/scripts/bundle-assets.mjs for `npx
+// @reefclaw/connect`, plugin-package/scripts/assemble.mjs for ClawHub. The
+// repo's own manifest carries the unstamped 0.1.0, which is what tells a
+// source-tree / script-deployed box apart from a packaged install.
+//
+// History: the readiness report used to send a hardcoded internal constant
+// ('3.8.0') that lived in a different namespace from the release versions
+// ('0.1.x'), so the dashboard's update banner compared apples to oranges and
+// never fired (memory feedback_plugin_update_banner_inert_version_namespace).
+// The webapp still recognises that legacy value and nudges those boxes once.
+import { existsSync, readFileSync } from 'node:fs';
+import { join, resolve, sep } from 'node:path';
+import { homedir } from 'node:os';
+/** The repo manifest's placeholder version. A box reporting it was not
+ *  installed from a release package (no release will ever be 0.1.0 — the
+ *  release line passed it long ago). */
+export const UNSTAMPED_VERSION = '0.1.0';
+const RELEASE_VERSION_RE = /^\d+\.\d+\.\d+$/;
+export function resolvePluginInstallFacts(input) {
+    let version;
+    try {
+        const raw = readFileSync(join(input.pluginRoot, 'openclaw.plugin.json'), 'utf-8');
+        const v = JSON.parse(raw).version;
+        if (typeof v === 'string' && RELEASE_VERSION_RE.test(v.trim()))
+            version = v.trim();
+    }
+    catch {
+        // No (readable) manifest next to index.js — legacy deploy layout. Report
+        // nothing rather than a guess; the dashboard fails open (no banner).
+    }
+    return { version, channel: detectChannel(input, version) };
+}
+function detectChannel(input, version) {
+    // Unstamped or absent manifest → the repo's own: source tree or a dist deploy
+    // (the operator's rigs, updated by deploy scripts — never by the installer).
+    if (version === undefined || version === UNSTAMPED_VERSION)
+        return 'source';
+    // ClawHub packages carry the bootstrap skill at the package root
+    // (plugin-package/scripts/assemble.mjs); the npx layout deliberately does
+    // not. Checked FIRST: a box that once ran the npx installer and later
+    // installed from ClawHub loads the ClawHub copy.
+    if (existsSync(join(input.pluginRoot, 'skills')))
+        return 'clawhub';
+    const home = resolve(input.reefclawHome ?? join(homedir(), '.reefclaw'));
+    const root = resolve(input.pluginRoot);
+    if (input.connectorSupervisor === 'on' || root.startsWith(home + sep))
+        return 'npx';
+    // Stamped release package without an installer marker (placed by hand).
+    // The installer still updates it in place, so it gets the one-click path.
+    return 'npx';
+}

package/assets/plugin/simulator/exchange-simulator.js

@@ -9,6 +9,7 @@ import { randomUUID } from 'node:crypto';
 import { logger, formatError } from '../logger.js';
 import { MAX_TRADE_HISTORY, DEFAULT_SIMULATION_CONFIG } from './types.js';
 import { fillMarketOrder, fillLimitOrder, parseSymbol } from './fill-engine.js';
+import { MAX_BOOK_DRIFT_BPS } from './realistic-fills.js';
 import { updateMfe } from '../mfe.js';
 import { computeInvalidationHit } from '../pinned-plan.js';
 const TAG = 'simulator';
@@ -805,7 +806,10 @@ export class ExchangeSimulator extends EventEmitter {
             logger.info(TAG, `Market order filled: ${order.side} ${order.amount} ${order.symbol} @ ${result.order.average}` +
                 ` (decision: ${eq.decisionPrice.toFixed(2)}, slippage: ${eq.slippageBps.toFixed(2)}bps` +
                 `, latency: ${eq.latencyMs.toFixed(0)}ms, fee: ${eq.feeRate * 100}%` +
-                `, book: ${eq.bookDepthAvailable ? `${eq.bookLevelsConsumed} levels` : 'unavailable'})`);
+                `, book: ${eq.bookDepthAvailable ? `${eq.bookLevelsConsumed} levels` : 'unavailable'}` +
+                `${eq.bookDriftBps !== undefined && Math.abs(eq.bookDriftBps) > MAX_BOOK_DRIFT_BPS
+                    ? `, stale book ${eq.bookDriftBps.toFixed(0)}bps off the decision price: fill anchored`
+                    : ''})`);
         }
         else {
             logger.info(TAG, `Market order filled: ${order.side} ${order.amount} ${order.symbol} @ ${result.order.average}`);

package/assets/plugin/simulator/realistic-fills.d.ts

@@ -1,4 +1,18 @@
 import type { OrderBookDepth, SimulationConfig, ExecutionQuality } from './types.js';
+/**
+ * How far (bps) the cached book's mid may sit from the decision price before
+ * the fill is anchored to the decision price instead of the raw book VWAP.
+ *
+ * The book is refreshed only when a tool fetches it (tools/helpers.ts
+ * fetchOrderBook, typically at entry), so a stop or target hours later used to
+ * fill against an hours-old book: an ADA/USDT short stop with a 0.2123 breach
+ * mark filled at 0.207103, 245 bps in the trader's favour, booking a -1.04R
+ * loss as -0.02R (2026-09-16 audit). Inside the band the book is fresh enough
+ * to price the fill directly (unchanged behaviour); outside it the book only
+ * shapes the impact (VWAP vs mid), applied to the price the decision was
+ * actually made on.
+ */
+export declare const MAX_BOOK_DRIFT_BPS = 10;
 /**
  * Walk the order book to compute a volume-weighted average fill price.
  *
@@ -45,6 +59,8 @@ export declare function getFeeRate(orderType: 'market' | 'limit', config: Simula
  *
  * Combines: orderbook VWAP + latency drift + appropriate fee rate.
  * Falls back to simple random slippage if no orderbook is available.
+ * A book whose mid has drifted more than MAX_BOOK_DRIFT_BPS from the decision
+ * price is stale: its impact is kept, the level is re-anchored.
  *
  * @returns fillPrice and ExecutionQuality metrics
  */

package/assets/plugin/simulator/realistic-fills.js

@@ -1,6 +1,20 @@
 // Phase 9a: Realistic fill simulation.
 // Order book-aware VWAP fills, latency modeling, maker/taker fees.
 import { DEFAULT_SIMULATION_CONFIG, priceToBps } from './types.js';
+/**
+ * How far (bps) the cached book's mid may sit from the decision price before
+ * the fill is anchored to the decision price instead of the raw book VWAP.
+ *
+ * The book is refreshed only when a tool fetches it (tools/helpers.ts
+ * fetchOrderBook, typically at entry), so a stop or target hours later used to
+ * fill against an hours-old book: an ADA/USDT short stop with a 0.2123 breach
+ * mark filled at 0.207103, 245 bps in the trader's favour, booking a -1.04R
+ * loss as -0.02R (2026-09-16 audit). Inside the band the book is fresh enough
+ * to price the fill directly (unchanged behaviour); outside it the book only
+ * shapes the impact (VWAP vs mid), applied to the price the decision was
+ * actually made on.
+ */
+export const MAX_BOOK_DRIFT_BPS = 10;
 /**
  * Walk the order book to compute a volume-weighted average fill price.
  *
@@ -92,6 +106,8 @@ export function getFeeRate(orderType, config) {
  *
  * Combines: orderbook VWAP + latency drift + appropriate fee rate.
  * Falls back to simple random slippage if no orderbook is available.
+ * A book whose mid has drifted more than MAX_BOOK_DRIFT_BPS from the decision
+ * price is stale: its impact is kept, the level is re-anchored.
  *
  * @returns fillPrice and ExecutionQuality metrics
  */
@@ -103,6 +119,7 @@ export function computeRealisticMarketFill(side, amount, decisionPrice, orderboo
     let latencyImpactBps;
     let bookLevelsConsumed;
     let bookDepthAvailable;
+    let bookDriftBps;
     if (orderbook && orderbook.asks.length > 0 && orderbook.bids.length > 0) {
         // Book-aware VWAP fill
         const { vwap, levelsConsumed } = computeBookAwareFillPrice(side, amount, orderbook);
@@ -113,8 +130,14 @@ export function computeRealisticMarketFill(side, amount, decisionPrice, orderboo
         marketImpactBps = priceToBps(vwap, midPrice);
         // For sells, impact is negative (received less), so take absolute for the metric
         // but keep signed for the actual price
-        // Apply latency drift on top of VWAP
-        const latencyResult = applyLatencyDrift(vwap, side, latencyMs, volFactor);
+        // A book that has drifted from the decision price is stale: keep its
+        // impact, re-anchor the level (see MAX_BOOK_DRIFT_BPS).
+        bookDriftBps = priceToBps(midPrice, decisionPrice);
+        const level = Math.abs(bookDriftBps) > MAX_BOOK_DRIFT_BPS
+            ? decisionPrice * (1 + marketImpactBps / 10_000)
+            : vwap;
+        // Apply latency drift on top of the (possibly re-anchored) VWAP
+        const latencyResult = applyLatencyDrift(level, side, latencyMs, volFactor);
         fillPrice = latencyResult.adjustedPrice;
         latencyImpactBps = latencyResult.latencyImpactBps;
     }
@@ -147,6 +170,7 @@ export function computeRealisticMarketFill(side, amount, decisionPrice, orderboo
         feePaid,
         bookLevelsConsumed,
         bookDepthAvailable,
+        ...(bookDriftBps !== undefined ? { bookDriftBps } : {}),
     };
     return { fillPrice, executionQuality };
 }

package/assets/plugin/simulator/types.d.ts

@@ -39,6 +39,10 @@ export interface ExecutionQuality {
     feePaid: number;
     bookLevelsConsumed: number;
     bookDepthAvailable: boolean;
+    /** Signed bps between the cached book's mid and the decision price at fill
+     *  time. Beyond MAX_BOOK_DRIFT_BPS the fill was anchored to the decision
+     *  price (stale book). Absent when no book was available. */
+    bookDriftBps?: number;
     /** Age of the quote the fill priced against (fill time − ticker.timestamp).
      *  Surfaces feed staleness (issue #202); absent on records from before the
      *  field existed or when the ticker carried no usable timestamp. */

package/assets/shared/readiness.d.ts

@@ -48,7 +48,12 @@ export interface ReadinessReport {
     checks: ReadinessCheck[];
     /** Best-effort agent facts for display. */
     agent?: {
+        /** Release version from the shipped manifest ('0.1.27'). Legacy plugins
+         *  sent an internal '3.x' constant — the webapp treats that as "behind". */
         pluginVersion?: string;
+        /** 'npx' | 'clawhub' | 'source' — how the plugin was installed. Kept
+         *  `string` so an older webapp renders reports from a newer plugin. */
+        installChannel?: string;
         toolCount?: number;
         /** Trading venue this agent executes on ('binance' | 'hyperliquid').
          *  Kept `string` so an older webapp renders reports from a newer plugin.

package/dist/agents.js

@@ -0,0 +1,92 @@
+// Which OpenClaw agent ReefClaw attaches to, and a loud notice when the
+// gateway hosts more than one.
+//
+// The installer targets the gateway's DEFAULT agent: `openclaw skills install`
+// puts the trading skill in its workspace, the bridge's heartbeat cron runs on
+// it, and the bridge addresses chat to it and shows only its runs
+// (skill/src/gateway/agent-scope.ts applies the same rule). On a single-agent
+// box that is simply `main`. On a gateway that already runs, say, a business
+// agent as its default, a fresh "trading" agent added alongside gets NOTHING
+// and the business agent starts trading — silently, until 2026-09-16. This
+// module makes that choice visible at install time. A full "pick the agent"
+// flow (skill placed with --agent, heartbeat cron with agentId, per-agent
+// paths in the bridge) is a later feature.
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { REEFCLAW_HOME } from './paths.js';
+export const DEFAULT_AGENT_ID = 'main';
+function normalizeAgentId(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim().toLowerCase();
+    return trimmed.length > 0 ? trimmed : undefined;
+}
+function agentEntries(cfg) {
+    const list = cfg?.agents?.list;
+    if (!Array.isArray(list))
+        return [];
+    return list.filter((e) => !!e && typeof e === 'object' && !Array.isArray(e));
+}
+/** Every agent id the gateway lists; empty on a single-agent box. */
+export function listAgentIds(cfg) {
+    const ids = [];
+    for (const entry of agentEntries(cfg)) {
+        const id = normalizeAgentId(entry.id);
+        if (id && !ids.includes(id))
+            ids.push(id);
+    }
+    return ids;
+}
+/** OpenClaw's own rule (agent-scope-config.ts `resolveDefaultAgentId`): the
+ *  `agents.list` entry flagged `default: true`, else the first, else `main`. */
+export function resolveDefaultAgentId(cfg) {
+    const entries = agentEntries(cfg);
+    if (entries.length === 0)
+        return DEFAULT_AGENT_ID;
+    const chosen = entries.find((e) => e.default === true) ?? entries[0];
+    return normalizeAgentId(chosen.id) ?? DEFAULT_AGENT_ID;
+}
+/** Best-effort read of ~/.reefclaw/plugin-config.json (the bridge reads the
+ *  same file for its `agentId` override). Null when absent or unreadable. */
+export function readPluginConfig(path = join(REEFCLAW_HOME, 'plugin-config.json')) {
+    try {
+        const parsed = JSON.parse(readFileSync(path, 'utf-8'));
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function describeAgentAttachment(cfg, pluginConfig) {
+    const defaultAgentId = resolveDefaultAgentId(cfg);
+    const override = normalizeAgentId(pluginConfig?.agentId);
+    const agentId = override ?? defaultAgentId;
+    const hosted = listAgentIds(cfg);
+    return {
+        agentId,
+        source: override ? 'override' : 'default',
+        defaultAgentId,
+        hosted,
+        shared: hosted.some((id) => id !== agentId),
+    };
+}
+/** The lines the installer prints. Pure, so the copy is unit-tested. */
+export function agentAttachmentNotice(a) {
+    if (!a.shared) {
+        return { level: 'ok', lines: [`ReefClaw attaches to agent '${a.agentId}'`] };
+    }
+    const others = a.hosted.filter((id) => id !== a.agentId).join(', ');
+    const lines = [
+        `this gateway also hosts: ${others}. ReefClaw attaches to '${a.agentId}' `
+            + (a.source === 'override'
+                ? '(the agentId set in ~/.reefclaw/plugin-config.json).'
+                : '(the gateway default agent).'),
+        `The trading skill goes into that agent's workspace, the heartbeat runs on it, and the dashboard shows only its runs.`,
+        `To trade on a different agent, flag it "default": true in agents.list of openclaw.json and re-run this installer, `
+            + `or give the trading agent its own OpenClaw instance (cleanest).`,
+    ];
+    if (a.source === 'override' && a.agentId !== a.defaultAgentId) {
+        lines.push(`Note: the override only steers the bridge on this version; the skill and heartbeat still land on the default agent '${a.defaultAgentId}'.`);
+    }
+    return { level: 'warn', lines };
+}

package/dist/cli.js

@@ -14,6 +14,7 @@ import { installPlugin } from './plugin.js';
 import { installBridge } from './bridge.js';
 import { installSkill } from './skill.js';
 import { enableConnectorSupervisor } from './supervisor-config.js';
+import { describeAgentAttachment, readPluginConfig, agentAttachmentNotice } from './agents.js';
 import { tuneGatewayMemory } from './gateway-tuning.js';
 import { checkGateway, checkBinanceRegion, checkHyperliquidRegion } from './validate.js';
 import { readConfig, writeConfig, mergeReefClawConfig, gatewayAuthAlreadyRelaxed, openClawInstalled, openClawConfigPath, readGatewayPort, } from './openclaw.js';
@@ -149,6 +150,20 @@ function parseVenueArg(argv) {
     }
     return null;
 }
+/** Say which agent ReefClaw is about to attach to. On a gateway that hosts
+ *  several agents this is the difference between the trading agent trading
+ *  and the business agent trading (see agents.ts). */
+function noticeAgentAttachment(config) {
+    step('Choosing the agent ReefClaw attaches to');
+    const notice = agentAttachmentNotice(describeAgentAttachment(config, readPluginConfig()));
+    if (notice.level === 'ok') {
+        ok(notice.lines[0]);
+        return;
+    }
+    warn(notice.lines[0]);
+    for (const line of notice.lines.slice(1))
+        info(line);
+}
 async function main() {
     banner(bold(cyan('ReefClaw connect')) + dim('  — link your OpenClaw agent to ReefClaw (paper trading)'));
     preflight();
@@ -165,6 +180,7 @@ async function main() {
         binanceReachable = await checkBinanceRegion();
     }
     const pre = readConfig();
+    noticeAgentAttachment(pre);
     const plugin = installPlugin();
     const merged = wireConfig(pre);
     // After wireConfig: the config is schema-valid (flat legacy keys migrated),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reefclaw/connect",
-  "version": "0.1.39",
+  "version": "0.1.41",
   "description": "One-command installer that connects your OpenClaw agent to ReefClaw (paper trading, no exchange keys).",
   "type": "module",
   "bin": {
@@ -29,5 +29,8 @@
     "vitest": "^4.0.18"
   },
   "license": "MIT",
-  "homepage": "https://reefclaw.com"
+  "homepage": "https://reefclaw.com",
+  "bugs": {
+    "email": "support@reefclaw.com"
+  }
 }