@reefclaw/openclaw-plugin 0.1.0

package/scripts/assemble.mjs

@@ -0,0 +1,114 @@
+// Assemble the publishable @reefclaw/openclaw-plugin package tree.
+//
+// This is the npm-channel distribution of the plugin — installable with ZERO
+// terminal access via OpenClaw's owner chat command:
+//   /plugins install npm:@reefclaw/openclaw-plugin
+// (requires commands.plugins: true; the install auto-restarts the gateway).
+//
+// Layout produced IN THIS DIRECTORY (package root = plugin dist root, because
+// openclaw.extensions points at ./index.js):
+//   index.js + rest of plugin/dist   — the plugin, at package root
+//   openclaw.plugin.json             — manifest + `skills` declaration (npm
+//                                      package only — the npx-installer copy
+//                                      has no skills/ subdir)
+//   bridge/                          — the connector (skill dist); the plugin's
+//                                      connector-supervisor auto-starts it when
+//                                      bundled (see connector-supervisor.ts)
+//   skills/reefclaw/SKILL.md         — the thin bootstrap skill (full playbook
+//                                      arrives token-gated post-connect)
+// Runtime deps (ccxt/ws/json5/@reefclaw/shared) are REAL npm dependencies —
+// OpenClaw's plugin installer runs the package manager, unlike gateway boot.
+
+import { cpSync, existsSync, rmSync, mkdirSync, readdirSync, statSync, readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url)); // plugin-package/scripts
+const pkgRoot = join(here, '..');
+const repoRoot = join(pkgRoot, '..');
+
+function skip(name) {
+  return (
+    name === '__tests__' ||
+    name.endsWith('.test.js') ||
+    name.endsWith('.test.d.ts') ||
+    name.endsWith('.map') ||
+    name.endsWith('.tsbuildinfo')
+  );
+}
+
+function copyTree(from, to) {
+  mkdirSync(to, { recursive: true });
+  for (const entry of readdirSync(from)) {
+    if (skip(entry)) continue;
+    const s = join(from, entry);
+    const d = join(to, entry);
+    if (statSync(s).isDirectory()) copyTree(s, d);
+    else cpSync(s, d);
+  }
+}
+
+// Clean previous assembly output (everything except the package sources).
+const KEEP = new Set(['package.json', 'scripts', 'README.md', 'node_modules', '.gitignore']);
+for (const entry of readdirSync(pkgRoot)) {
+  if (!KEEP.has(entry)) rmSync(join(pkgRoot, entry), { recursive: true, force: true });
+}
+
+let missing = 0;
+
+// 1. Plugin dist at package root.
+const pluginDist = join(repoRoot, 'plugin', 'dist');
+if (!existsSync(pluginDist)) {
+  console.error('[assemble] missing plugin/dist — build the plugin first.');
+  missing += 1;
+} else {
+  copyTree(pluginDist, pkgRoot);
+  console.log('[assemble] plugin/dist -> package root');
+}
+
+// 2. Manifest, with the `skills` declaration injected (npm package only).
+const manifestSrc = join(repoRoot, 'plugin', 'openclaw.plugin.json');
+if (!existsSync(manifestSrc)) {
+  console.error('[assemble] missing plugin/openclaw.plugin.json.');
+  missing += 1;
+} else {
+  const manifest = JSON.parse(readFileSync(manifestSrc, 'utf-8'));
+  manifest.skills = ['./skills'];
+  writeFileSync(join(pkgRoot, 'openclaw.plugin.json'), JSON.stringify(manifest, null, 2) + '\n', 'utf-8');
+  console.log(`[assemble] manifest (+skills decl), ${manifest.contracts?.tools?.length ?? 0} contract tools`);
+}
+
+// 3. The connector, bundled — this is what flips the supervisor's auto-start.
+const skillDist = join(repoRoot, 'skill', 'dist');
+if (!existsSync(skillDist)) {
+  console.error('[assemble] missing skill/dist — build the skill first.');
+  missing += 1;
+} else {
+  copyTree(skillDist, join(pkgRoot, 'bridge'));
+  console.log('[assemble] skill/dist -> bridge/');
+}
+
+// 4. Bootstrap skill (config schema + connect instructions only — never the
+//    full trading playbook; that stays token-gated behind the webapp).
+const bootstrap = join(repoRoot, 'skill', 'SKILL-bootstrap.md');
+if (!existsSync(bootstrap)) {
+  console.error('[assemble] missing skill/SKILL-bootstrap.md.');
+  missing += 1;
+} else {
+  const size = statSync(bootstrap).size;
+  if (size > 20_000) {
+    console.error(`[assemble] bootstrap is ${size} bytes (>20KB) — is this the FULL SKILL.md? Refusing.`);
+    missing += 1;
+  } else {
+    mkdirSync(join(pkgRoot, 'skills', 'reefclaw'), { recursive: true });
+    cpSync(bootstrap, join(pkgRoot, 'skills', 'reefclaw', 'SKILL.md'));
+    console.log(`[assemble] bootstrap skill (${size} bytes) -> skills/reefclaw/SKILL.md`);
+  }
+}
+
+if (missing > 0) {
+  console.error(`[assemble] ${missing} input(s) missing — package INCOMPLETE; do not publish.`);
+  process.exitCode = 1;
+} else {
+  console.log('[assemble] package complete.');
+}

package/shadow/shadow-tracker.d.ts

@@ -0,0 +1,36 @@
+import { EventEmitter } from 'node:events';
+import type { BinancePrivateApi } from '../ccxt/binance-private.js';
+import type { ExchangeSimulator } from '../simulator/exchange-simulator.js';
+import type { ShadowComparison, ShadowMetrics, ShadowConfig } from './types.js';
+/**
+ * ShadowTracker hooks into the ExchangeSimulator to compute
+ * shadow estimates for every paper fill.
+ *
+ * Events emitted:
+ * - 'shadowComparison': ShadowComparison — after each fill comparison
+ */
+export declare class ShadowTracker extends EventEmitter {
+    private privateApi;
+    private simulator;
+    private metrics;
+    private config;
+    private recentComparisons;
+    private active;
+    constructor(privateApi: BinancePrivateApi, simulator: ExchangeSimulator, config?: ShadowConfig, existingMetrics?: ShadowMetrics);
+    /** Start listening for simulator fill events. */
+    start(): void;
+    /** Stop listening. */
+    stop(): void;
+    /** Get current shadow metrics. */
+    getMetrics(): ShadowMetrics;
+    /** Get recent comparisons. */
+    getRecentComparisons(): ShadowComparison[];
+    /** Check if shadow mode criteria are met for mode upgrade. */
+    isReadyForUpgrade(): {
+        ready: boolean;
+        reasons: string[];
+    };
+    private onFill;
+    private computeShadowComparison;
+    private updateMetrics;
+}

package/shadow/shadow-tracker.js

@@ -0,0 +1,151 @@
+// Shadow Tracker — compares paper fills against live exchange estimates.
+// Listens for fill events from the simulator, fetches real order book,
+// computes what the live fill would have been, logs the comparison.
+import { EventEmitter } from 'node:events';
+import { logger } from '../logger.js';
+import { priceToBps } from '../simulator/types.js';
+import { computeBookAwareFillPrice } from '../simulator/realistic-fills.js';
+import { createEmptyShadowMetrics, DEFAULT_SHADOW_CONFIG } from './types.js';
+const TAG = 'shadow-tracker';
+/** Maximum recent comparisons to keep in memory. */
+const MAX_RECENT_COMPARISONS = 100;
+/**
+ * ShadowTracker hooks into the ExchangeSimulator to compute
+ * shadow estimates for every paper fill.
+ *
+ * Events emitted:
+ * - 'shadowComparison': ShadowComparison — after each fill comparison
+ */
+export class ShadowTracker extends EventEmitter {
+    privateApi;
+    simulator;
+    metrics;
+    config;
+    recentComparisons = [];
+    active = false;
+    constructor(privateApi, simulator, config, existingMetrics) {
+        super();
+        this.privateApi = privateApi;
+        this.simulator = simulator;
+        this.config = config ?? DEFAULT_SHADOW_CONFIG;
+        this.metrics = existingMetrics ?? createEmptyShadowMetrics();
+    }
+    /** Start listening for simulator fill events. */
+    start() {
+        if (this.active)
+            return;
+        this.active = true;
+        this.simulator.on('fill', this.onFill);
+        logger.info(TAG, `Shadow tracker started (${this.metrics.totalShadowTrades} prior comparisons)`);
+    }
+    /** Stop listening. */
+    stop() {
+        if (!this.active)
+            return;
+        this.active = false;
+        this.simulator.off('fill', this.onFill);
+        logger.info(TAG, 'Shadow tracker stopped');
+    }
+    /** Get current shadow metrics. */
+    getMetrics() {
+        return { ...this.metrics };
+    }
+    /** Get recent comparisons. */
+    getRecentComparisons() {
+        return [...this.recentComparisons];
+    }
+    /** Check if shadow mode criteria are met for mode upgrade. */
+    isReadyForUpgrade() {
+        const reasons = [];
+        if (this.metrics.totalShadowTrades < this.config.minTrades) {
+            reasons.push(`Need ${this.config.minTrades} shadow trades, have ${this.metrics.totalShadowTrades}`);
+        }
+        if (this.metrics.tradingDays < this.config.minDays) {
+            reasons.push(`Need ${this.config.minDays} trading days, have ${this.metrics.tradingDays}`);
+        }
+        if (this.metrics.avgDeltaBps > this.config.maxAvgDeltaBps) {
+            reasons.push(`Avg delta ${this.metrics.avgDeltaBps.toFixed(2)}bps exceeds max ${this.config.maxAvgDeltaBps}bps`);
+        }
+        return { ready: reasons.length === 0, reasons };
+    }
+    // Arrow function to preserve `this` binding when used as event listener
+    onFill = (fillData) => {
+        // Only compare market order fills (limit orders fill at limit price, no comparison needed)
+        if (fillData.type !== 'market')
+            return;
+        // Fire and forget — shadow comparison is async but doesn't block the fill
+        this.computeShadowComparison(fillData).catch(err => {
+            logger.warn(TAG, `Shadow comparison failed: ${err instanceof Error ? err.message : String(err)}`);
+        });
+    };
+    async computeShadowComparison(fillData) {
+        // Fetch fresh order book from the exchange (authenticated path)
+        const liveBook = await this.privateApi.fetchOrderBook(fillData.symbol, 20);
+        let shadowPrice;
+        let bookDepthUsed = 0;
+        let bookDepthAvailable = false;
+        if (liveBook && liveBook.asks.length > 0 && liveBook.bids.length > 0) {
+            // Walk the live book to compute shadow VWAP
+            const { vwap, levelsConsumed } = computeBookAwareFillPrice(fillData.side, fillData.amount, liveBook);
+            shadowPrice = vwap;
+            bookDepthUsed = levelsConsumed;
+            bookDepthAvailable = true;
+        }
+        else {
+            // No live book available — use paper fill as shadow estimate
+            shadowPrice = fillData.fillPrice;
+            logger.warn(TAG, `No live order book for ${fillData.symbol} — shadow estimate equals paper`);
+        }
+        // Compute shadow fee (same taker rate as paper for fair comparison)
+        const simConfig = this.simulator.getSimulationConfig();
+        const shadowFee = fillData.amount * shadowPrice * simConfig.fees.takerRate;
+        // Delta: positive = live would be worse (pay more for buy, receive less for sell)
+        const deltaBps = priceToBps(shadowPrice, fillData.fillPrice);
+        const comparison = {
+            orderId: fillData.orderId,
+            symbol: fillData.symbol,
+            side: fillData.side,
+            type: fillData.type,
+            amount: fillData.amount,
+            paperFillPrice: fillData.fillPrice,
+            shadowEstimatePrice: shadowPrice,
+            deltaBps,
+            paperFee: fillData.fee,
+            shadowEstimateFee: shadowFee,
+            bookDepthUsed,
+            bookDepthAvailable,
+            timestamp: new Date().toISOString(),
+        };
+        // Update metrics
+        this.updateMetrics(comparison);
+        // Store recent comparison (match webapp slice pattern — slice instead of shift)
+        this.recentComparisons = [
+            ...this.recentComparisons.slice(-(MAX_RECENT_COMPARISONS - 1)),
+            comparison,
+        ];
+        // Emit event for skill/bridge pipeline
+        this.emit('shadowComparison', comparison);
+        logger.info(TAG, `Shadow comparison: ${fillData.side} ${fillData.amount} ${fillData.symbol}` +
+            ` | Paper: ${fillData.fillPrice.toFixed(2)} | Shadow: ${shadowPrice.toFixed(2)}` +
+            ` | Delta: ${deltaBps.toFixed(2)}bps` +
+            ` | Book: ${bookDepthAvailable ? `${bookDepthUsed} levels` : 'unavailable'}`);
+    }
+    updateMetrics(comparison) {
+        const m = this.metrics;
+        m.totalShadowTrades++;
+        const absDelta = Math.abs(comparison.deltaBps);
+        m.totalDeltaBpsSum += absDelta;
+        m.avgDeltaBps = m.totalDeltaBpsSum / m.totalShadowTrades;
+        if (absDelta > m.worstDeltaBps) {
+            m.worstDeltaBps = absDelta;
+        }
+        m.paperTotalFees += comparison.paperFee;
+        m.shadowTotalFees += comparison.shadowEstimateFee;
+        // Track trading days
+        const today = comparison.timestamp.slice(0, 10);
+        if (today !== m.lastTradeDate) {
+            m.tradingDays++;
+            m.lastTradeDate = today;
+        }
+    }
+}

package/shadow/types.d.ts

@@ -0,0 +1,42 @@
+import type { TradingMode } from '../types.js';
+export type { TradingMode };
+/** A single shadow comparison record: paper fill vs live estimate. */
+export interface ShadowComparison {
+    orderId: string;
+    symbol: string;
+    side: 'buy' | 'sell';
+    type: 'market' | 'limit';
+    amount: number;
+    paperFillPrice: number;
+    shadowEstimatePrice: number;
+    deltaBps: number;
+    paperFee: number;
+    shadowEstimateFee: number;
+    bookDepthUsed: number;
+    bookDepthAvailable: boolean;
+    timestamp: string;
+}
+/** Aggregate shadow metrics across all shadow comparisons. */
+export interface ShadowMetrics {
+    totalShadowTrades: number;
+    avgDeltaBps: number;
+    worstDeltaBps: number;
+    totalDeltaBpsSum: number;
+    paperTotalFees: number;
+    shadowTotalFees: number;
+    startedAt: string;
+    tradingDays: number;
+    lastTradeDate: string;
+}
+/** Shadow mode configuration thresholds. */
+export interface ShadowConfig {
+    /** Minimum shadow trades before allowing mode upgrade (default: 50) */
+    minTrades: number;
+    /** Minimum days in shadow mode (default: 7) */
+    minDays: number;
+    /** Max acceptable average delta in bps (default: 5) */
+    maxAvgDeltaBps: number;
+}
+export declare const DEFAULT_SHADOW_CONFIG: ShadowConfig;
+/** Create empty shadow metrics. */
+export declare function createEmptyShadowMetrics(): ShadowMetrics;

package/shadow/types.js

@@ -0,0 +1,20 @@
+// Shadow mode types — tracking paper vs live fill comparison.
+export const DEFAULT_SHADOW_CONFIG = {
+    minTrades: 50,
+    minDays: 7,
+    maxAvgDeltaBps: 5,
+};
+/** Create empty shadow metrics. */
+export function createEmptyShadowMetrics() {
+    return {
+        totalShadowTrades: 0,
+        avgDeltaBps: 0,
+        worstDeltaBps: 0,
+        totalDeltaBpsSum: 0,
+        paperTotalFees: 0,
+        shadowTotalFees: 0,
+        startedAt: new Date().toISOString(),
+        tradingDays: 0,
+        lastTradeDate: '',
+    };
+}

package/shared/indicators-extended.d.ts

@@ -0,0 +1,52 @@
+export interface OhlcvInput {
+    open: number;
+    high: number;
+    low: number;
+    close: number;
+    volume: number;
+}
+export interface MACDResult {
+    line: number;
+    signal: number;
+    histogram: number;
+    crossover: 'bullish' | 'bearish' | 'none';
+}
+export interface BollingerResult {
+    upper: number;
+    middle: number;
+    lower: number;
+    bandwidth: number;
+    percentB: number;
+}
+export interface StochRSIResult {
+    k: number;
+    d: number;
+}
+export interface IchimokuResult {
+    tenkan: number;
+    kijun: number;
+    senkouA: number;
+    senkouB: number;
+    chikou: number;
+    cloudPosition: 'above' | 'below' | 'inside';
+}
+export interface SupertrendResult {
+    value: number;
+    direction: 'bullish' | 'bearish';
+}
+export declare function computeMACD(closes: number[], fast?: number, slow?: number, signal?: number): MACDResult;
+export declare function computeBollingerBands(closes: number[], period?: number, stdDev?: number): BollingerResult;
+export declare function computeVWAP(bars: OhlcvInput[]): number;
+export declare function computeStochRSI(closes: number[], rsiPeriod?: number, stochPeriod?: number, kSmooth?: number, dSmooth?: number): StochRSIResult;
+export declare function computeADX(highs: number[], lows: number[], closes: number[], period?: number): {
+    adx: number;
+    plusDI: number;
+    minusDI: number;
+};
+export declare function computeIchimoku(highs: number[], lows: number[], closes: number[], tenkanPeriod?: number, kijunPeriod?: number, senkouBPeriod?: number): IchimokuResult;
+export declare function computeOBV(closes: number[], volumes: number[]): {
+    obv: number;
+    slope: 'rising' | 'falling' | 'flat';
+};
+export declare function computeSupertrend(highs: number[], lows: number[], closes: number[], period?: number, multiplier?: number): SupertrendResult;
+export declare function computeWilliamsR(highs: number[], lows: number[], closes: number[], period?: number): number;