@reefclaw/openclaw-plugin 0.1.0

package/bridge/event-replay-buffer.js

@@ -0,0 +1,109 @@
+// Bounded per-channel ring buffer of events emitted to the relay. On a
+// reconcile request the bridge replays everything with `seq > lastSeq` per
+// channel so the browser can fill the gap left by a brief disconnect.
+//
+// Why this lives at the skill layer (not the relay)
+// --------------------------------------------------
+// The relay is intentionally stateless (PartyKit Durable Object with a 128 KB
+// value ceiling — see memory/feedback_skillmd_ota_size_limit.md). The skill
+// is a long-running Node process on the user's VPS, where ~250 KB of in-memory
+// ring storage is free. Sequence numbers are also generated skill-side
+// (bridge.ts: `seq: this.seqs[channel]++`), so the skill is the only layer
+// with the canonical seq-per-channel knowledge required to populate gapFill.
+//
+// What this protects against
+// --------------------------
+// Browser-side disconnect windows up to `maxAgeMs` (default 5 min). For longer
+// absences the in-memory ring is too short anyway — DB-backed hydration is the
+// proper recovery path (Layer 2, separate PR). Streaming chat chunks, real-time
+// signal pulses, and regime-update flickers have NO DB persistence, so the
+// ring buffer is their only replay mechanism.
+const VALID_CHANNELS = [
+    'market_data',
+    'trade_events',
+    'agent_state',
+    'chat',
+];
+/** Defaults — see top-of-file rationale.
+ *
+ *  At ~50 chat chunks/sec peak (worst case during a streaming reply) and
+ *  ~150 byte payloads, 500 events × 4 channels × 200 bytes ≈ 400 KB working
+ *  set. 5 min covers the dominant class of disconnect (network blip, tab
+ *  sleep, brief refresh). */
+const DEFAULT_PER_CHANNEL_CAPACITY = 500;
+const DEFAULT_MAX_AGE_MS = 5 * 60_000;
+export class EventReplayBuffer {
+    perChannelCapacity;
+    maxAgeMs;
+    now;
+    buffers = {
+        market_data: [],
+        trade_events: [],
+        agent_state: [],
+        chat: [],
+    };
+    constructor(opts = {}) {
+        this.perChannelCapacity = opts.perChannelCapacity ?? DEFAULT_PER_CHANNEL_CAPACITY;
+        this.maxAgeMs = opts.maxAgeMs ?? DEFAULT_MAX_AGE_MS;
+        this.now = opts.now ?? (() => Date.now());
+    }
+    /** Append a frame that was just sent to the relay. The seq must be the
+     *  same value placed on the wire so the browser's seq tracker matches. */
+    record(channel, event, payload, seq) {
+        const buf = this.buffers[channel];
+        buf.push({ channel, event, payload, seq, timestamp: this.now() });
+        this.evictExpired(channel);
+        while (buf.length > this.perChannelCapacity) {
+            buf.shift();
+        }
+    }
+    /** Return all buffered events on `channel` with seq > lastSeq, in seq order.
+     *  Lazy age-eviction keeps the buffer trim even when nothing has been
+     *  appended for a while. */
+    since(channel, lastSeq) {
+        this.evictExpired(channel);
+        return this.buffers[channel].filter((e) => e.seq > lastSeq);
+    }
+    /** Return all buffered events newer than the per-channel `lastSeq`, sorted
+     *  by timestamp so the browser replays them in roughly the order they
+     *  were originally emitted. Within a channel, seq is monotonic so the
+     *  timestamp sort still preserves per-channel ordering — frames emitted
+     *  in the same millisecond fall back to (channel, seq) for determinism. */
+    sinceMany(lastSequences) {
+        const out = [];
+        for (const ch of VALID_CHANNELS) {
+            const lastSeq = lastSequences[ch] ?? -1;
+            out.push(...this.since(ch, lastSeq));
+        }
+        out.sort((a, b) => {
+            if (a.timestamp !== b.timestamp)
+                return a.timestamp - b.timestamp;
+            if (a.channel !== b.channel)
+                return a.channel < b.channel ? -1 : 1;
+            return a.seq - b.seq;
+        });
+        return out;
+    }
+    /** Drop the buffer (e.g. on bridge shutdown). */
+    clear() {
+        for (const ch of VALID_CHANNELS) {
+            this.buffers[ch].length = 0;
+        }
+    }
+    /** Diagnostic — total events held across all channels. */
+    size() {
+        let n = 0;
+        for (const ch of VALID_CHANNELS)
+            n += this.buffers[ch].length;
+        return n;
+    }
+    evictExpired(channel) {
+        const buf = this.buffers[channel];
+        if (buf.length === 0)
+            return;
+        const cutoff = this.now() - this.maxAgeMs;
+        while (buf.length > 0 && buf[0].timestamp < cutoff) {
+            buf.shift();
+        }
+    }
+}

package/bridge/gateway/event-parser.d.ts

@@ -0,0 +1,209 @@
+import type { TickerData, OrderData, FillData, OrderUpdatePayload } from '../types.js';
+import type { ProviderEventName, ProviderEvents } from '../provider.js';
+/** CCXT order object — raw shape from fetch_open_orders / create_order results */
+export interface CcxtOrder {
+    id: string;
+    symbol: string;
+    side: 'buy' | 'sell';
+    type: 'market' | 'limit' | string;
+    status: 'open' | 'closed' | 'canceled' | string;
+    amount: number;
+    filled: number;
+    remaining?: number;
+    average?: number | null;
+    price?: number | null;
+    cost?: number;
+    fee?: {
+        cost: number;
+        currency: string;
+        rate?: number;
+    };
+    timestamp?: number;
+    datetime?: string;
+    timeInForce?: string;
+    [key: string]: unknown;
+}
+/** CCXT ticker object — raw shape from fetch_ticker */
+export interface CcxtTicker {
+    symbol: string;
+    last: number | null;
+    bid: number | null;
+    ask: number | null;
+    baseVolume: number | null;
+    quoteVolume?: number | null;
+    change: number | null;
+    percentage: number | null;
+    timestamp?: number;
+    datetime?: string;
+    [key: string]: unknown;
+}
+/** CCXT balance object — raw shape from fetch_balance */
+export interface CcxtBalance {
+    [currency: string]: {
+        free: number;
+        used: number;
+        total: number;
+    } | unknown;
+    free?: Record<string, number>;
+    used?: Record<string, number>;
+    total?: Record<string, number>;
+}
+export declare function mapCcxtStatus(ccxtStatus: string): string;
+export declare function mapCcxtSide(ccxtSide: string): 'BUY' | 'SELL';
+export declare function mapCcxtType(ccxtType: string): 'MARKET' | 'LIMIT';
+/**
+ * Map a CCXT order to a ReefClaw OrderData.
+ * Returns null if the order has missing critical fields.
+ */
+/**
+ * True when a CCXT order can only REDUCE/CLOSE a position (a protective bracket),
+ * never open/add. Detects ALL forms a Binance Futures stop/TP can take:
+ *   - `reduceOnly` (unified or raw info)
+ *   - `closePosition` (the position-bound form ReefClaw brackets actually use —
+ *     see plugin bracket-params.ts; a `reduceOnly`-only check would MISS these
+ *     and the kill switch would cancel them, leaving a naked position)
+ *   - a STOP / TAKE_PROFIT order type (protective by nature)
+ * The kill switch uses this to preserve protection. Errs toward `true` only on
+ * real protective signals; a plain LIMIT/MARKET entry has none → false.
+ */
+export declare function isProtectiveOrder(ccxt: CcxtOrder): boolean;
+export declare function mapCcxtOrder(ccxt: CcxtOrder): OrderData | null;
+/**
+ * Build a FillData from a CCXT order (when the order has fills).
+ * expectedPrice is the limit price (or average if market order).
+ */
+export declare function buildFillFromCcxtOrder(ccxt: CcxtOrder, expectedPrice?: number): FillData | null;
+/**
+ * Map a CCXT order into a full OrderUpdatePayload.
+ * Returns null if the order has invalid critical fields.
+ */
+export declare function mapCcxtOrderToUpdate(ccxt: CcxtOrder, expectedPrice?: number): OrderUpdatePayload | null;
+/**
+ * Map a CCXT ticker to a ReefClaw TickerData.
+ * Returns null if the ticker has no valid price data.
+ */
+export declare function mapCcxtTicker(ccxt: CcxtTicker): TickerData | null;
+/**
+ * Map a CCXT balance response to ReefClaw balance shape.
+ * Extracts the balance for a given currency (default: USDT).
+ *
+ * On Binance Futures, prefer `info.assets[]` over CCXT's per-asset
+ * `free`/`used` fields. Two reasons:
+ *
+ * 1. Under cross-margin, per-asset `used` from CCXT is structurally 0 —
+ *    margin is shared across the account, not booked against any one asset.
+ *    The plugin backfills `free=total` when `used==0`, which sets
+ *    `available` to the full wallet and hides the actual locked margin.
+ *
+ * 2. Multi-asset accounts settle realized PnL into a separate `BNFCR` line —
+ *    negative when net-loss, positive when net-gain. It's independent of the
+ *    funded stablecoin (USDT/USDC) and must be folded into both wallet and
+ *    available reads so the dashboard's `Available + Locked = NAV`-style
+ *    invariant holds rather than the figures reading off the USDC line alone.
+ *
+ * `info.assets[i].availableBalance` is Binance's authoritative
+ * available-after-margin number; `walletBalance` is the wallet-only line
+ * (excludes uPnl). We sum these across {funded stablecoin, BNFCR}; the
+ * gateway derives `Locked = NAV − Available` so the invariant holds.
+ *
+ * Falls back to the legacy per-currency / top-level shape when `info.assets`
+ * is absent (paper, non-Binance exchanges, mocks).
+ */
+export declare function mapCcxtBalance(ccxt: CcxtBalance, currency?: string): {
+    currency: string;
+    total: number;
+    available: number;
+    locked: number;
+};
+/**
+ * Extract liquidation-risk fields from a CCXT position.  Reads the CCXT
+ * unified shape first (`position.liquidationPrice`, `position.leverage`,
+ * `position.maintenanceMargin`, `position.marginRatio`) and falls back to
+ * Binance's raw `info.*` shape — `info.liquidationPrice`, `info.leverage`,
+ * `info.maintMargin`, `info.marginRatio` — which arrives as stringy decimals
+ * on the futures REST endpoint.  Returns an object of optional numbers so
+ * callers can spread it directly into the outgoing position payload.
+ *
+ * Verified against:
+ *   - CCXT unified position fields (ccxt docs → "position structure")
+ *   - Binance Futures `/fapi/v2/positionRisk` response
+ *     (developers.binance.com → derivatives → positionRisk)
+ */
+export declare function extractLiquidationFields(pos: {
+    [key: string]: unknown;
+}): {
+    liquidationPrice?: number;
+    leverage?: number;
+    maintenanceMargin?: number;
+    marginRatio?: number;
+};
+/**
+ * Narrow plugin-side `pos.bracket` at the skill/snapshot boundary.
+ * The plugin attaches it via LiveAdapter.decoratePositionsWithMetadata when
+ * BracketLedger has an active/partial/attaching row for the symbol. The
+ * CcxtPosition index signature is `unknown`, so we re-validate shape here
+ * before forwarding into ReconciliationSnapshot.
+ *
+ * Returns undefined when the field is absent (paper mode, no bracket attached,
+ * terminal-state bracket) or malformed. The webapp hides bracket lines when
+ * the field is undefined.
+ */
+export declare function extractBracketField(pos: {
+    [key: string]: unknown;
+}): {
+    slPrice?: number;
+    tpPrice?: number;
+    state: string;
+} | undefined;
+/** The payload shape received from GatewayWsClient 'agent' event */
+export interface AgentEventPayload {
+    runId: string;
+    stream: 'lifecycle' | 'assistant' | 'tool' | string;
+    data: unknown;
+    seq?: number;
+}
+/** A single parsed event ready to be fired by GatewayProvider */
+export interface ParsedEvent<E extends ProviderEventName = ProviderEventName> {
+    event: E;
+    data: Parameters<ProviderEvents[E]>[0];
+}
+export declare class EventParser {
+    /** Buffered assistant text per runId, with timestamps for expiry */
+    private assistantBuffers;
+    /** Last decision timestamp (set on lifecycle 'start') */
+    private lastDecisionTs;
+    /** Error timestamps within the rolling window */
+    private errorTimestamps;
+    /** Symbol for balance currency extraction */
+    private readonly quoteCurrency;
+    /** Callback to emit events from inactivity timer (outside parseAgentEvent flow) */
+    private readonly onAsyncEvents;
+    constructor(quoteCurrency?: string, onAsyncEvents?: (events: ParsedEvent[]) => void);
+    /**
+     * Parse a raw agent event into zero or more ProviderEvents.
+     * GatewayProvider calls this on every 'agent' event from the WS client.
+     */
+    parseAgentEvent(payload: AgentEventPayload): ParsedEvent[];
+    /** Get the last decision timestamp */
+    getLastDecision(): string | null;
+    /** Get the rolling error rate (errors per hour) */
+    getErrorRate(): number;
+    private handleLifecycle;
+    private handleAssistant;
+    private handleTool;
+    private parseOrderResult;
+    private parseSingleOrder;
+    private parseTickerResult;
+    private parseBalanceResult;
+    /**
+     * Called when a tool ends — resume inactivity timers on all active buffers.
+     * If more assistant text follows the tool call, the timer will be cleared
+     * again by handleAssistant. If not, the buffer flushes after BUFFER_INACTIVITY_MS.
+     */
+    private resumeBuffersAfterTool;
+    private flushAssistantBuffer;
+    /** Prune buffers older than BUFFER_EXPIRY_MS to prevent memory leaks from abandoned runs */
+    private pruneExpiredBuffers;
+    /** In-place prune of error timestamps outside the rolling window */
+    private pruneErrorTimestamps;
+}