@reefclaw/openclaw-plugin 0.1.0

package/live/live-balance-enricher.d.ts

@@ -0,0 +1,32 @@
+import type { CcxtBalance, CcxtPosition } from '../types.js';
+/** UTC date in YYYY-MM-DD form — same shape as `closedAt.slice(0, 10)`. */
+export declare function utcDateString(ms: number): string;
+/** Epoch ms for the most recent 00:00:00 UTC boundary at-or-before `ms`. */
+export declare function utcMidnightMs(ms?: number): number;
+export declare class LiveBalanceEnricher {
+    private sessionStartNav;
+    private fills;
+    private allTimeSeed;
+    private realizedTodaySeed;
+    private realizedTodaySeedDate;
+    setSessionStartNav(nav: number): void;
+    getSessionStartNav(): number;
+    /** Seed all-time realized PnL from Intelligence DB (pre-session history). */
+    seedAllTimeRealized(total: number): void;
+    /** Seed today's realized PnL from Binance's income endpoint. The seed
+     *  represents everything Binance has booked for the current UTC day. The
+     *  webapp dashboard now derives Realized as (totalPnl - unrealizedPnl)
+     *  for guaranteed consistency with Day P&L (see webapp trades.ts), so
+     *  this seed is used only for sessionStartNav anchoring + the
+     *  `realizedPnlToday` field that older consumers may still read. */
+    seedRealizedPnlToday(amount: number, dateUtc?: string): void;
+    /** Record a completed fill for realized PnL tracking. Currently unused in
+     *  production (the income-endpoint seed is the sole source of Realized);
+     *  retained for tests that exercise the accumulator semantics. */
+    recordFill(pnl: number, fee: number): void;
+    /**
+     * Enrich a raw CCXT balance with session PnL, equity, and sessionStartNav.
+     * Uses cached positions from the reconciler (no extra API call).
+     */
+    enrich(rawBalance: CcxtBalance, positions: CcxtPosition[]): CcxtBalance;
+}

package/live/live-balance-enricher.js

@@ -0,0 +1,104 @@
+// LiveBalanceEnricher — attaches session PnL + equity fields to raw CCXT
+// balance responses from the LiveAdapter, matching the enriched format that
+// ExchangeSimulator.getBalance() produces. This lets the skill's
+// fetchFreshBalance() process live-mode responses identically to paper mode.
+import { getQuoteWalletBalance } from '../balance-utils.js';
+import { logger } from '../logger.js';
+const TAG = 'live-balance-enricher';
+/** UTC date in YYYY-MM-DD form — same shape as `closedAt.slice(0, 10)`. */
+export function utcDateString(ms) {
+    return new Date(ms).toISOString().slice(0, 10);
+}
+/** Epoch ms for the most recent 00:00:00 UTC boundary at-or-before `ms`. */
+export function utcMidnightMs(ms = Date.now()) {
+    return new Date(new Date(ms).toISOString().slice(0, 10) + 'T00:00:00Z').getTime();
+}
+export class LiveBalanceEnricher {
+    sessionStartNav = 0;
+    fills = [];
+    allTimeSeed = 0; // seeded from Intelligence DB
+    // Today's realized P&L seeded from Binance income endpoint at boot. Lets the
+    // dashboard's Realized KPI exactly match Binance's "Today's Realized PNL"
+    // even after a plugin restart (without this, sessionStartNav resets to the
+    // current NAV at boot and the day's realized P&L appears as $0). Reset to 0
+    // when the enricher's day rolls over past midnight UTC; subsequent fills are
+    // accumulated via recordFill() exactly as before.
+    realizedTodaySeed = 0;
+    realizedTodaySeedDate = utcDateString(Date.now());
+    setSessionStartNav(nav) {
+        this.sessionStartNav = nav;
+        logger.info(TAG, `Session-start NAV set: ${nav}`);
+    }
+    getSessionStartNav() {
+        return this.sessionStartNav;
+    }
+    /** Seed all-time realized PnL from Intelligence DB (pre-session history). */
+    seedAllTimeRealized(total) {
+        this.allTimeSeed = total;
+    }
+    /** Seed today's realized PnL from Binance's income endpoint. The seed
+     *  represents everything Binance has booked for the current UTC day. The
+     *  webapp dashboard now derives Realized as (totalPnl - unrealizedPnl)
+     *  for guaranteed consistency with Day P&L (see webapp trades.ts), so
+     *  this seed is used only for sessionStartNav anchoring + the
+     *  `realizedPnlToday` field that older consumers may still read. */
+    seedRealizedPnlToday(amount, dateUtc = utcDateString(Date.now())) {
+        this.realizedTodaySeed = amount;
+        this.realizedTodaySeedDate = dateUtc;
+        logger.info(TAG, `Today's realized PnL seeded from Binance: ${amount.toFixed(4)} (date=${dateUtc})`);
+    }
+    /** Record a completed fill for realized PnL tracking. Currently unused in
+     *  production (the income-endpoint seed is the sole source of Realized);
+     *  retained for tests that exercise the accumulator semantics. */
+    recordFill(pnl, fee) {
+        this.fills.push({
+            realizedPnl: pnl,
+            fee,
+            closedAt: new Date().toISOString(),
+        });
+    }
+    /**
+     * Enrich a raw CCXT balance with session PnL, equity, and sessionStartNav.
+     * Uses cached positions from the reconciler (no extra API call).
+     */
+    enrich(rawBalance, positions) {
+        const quoteTotal = getQuoteWalletBalance(rawBalance);
+        // Compute unrealized P&L from live positions
+        let unrealizedPnl = 0;
+        for (const p of positions) {
+            unrealizedPnl += p.unrealizedPnl ?? 0;
+        }
+        // Live equity = wallet balance + unrealized P&L.
+        // Binance wallet already accounts for margin deductions.
+        const equity = quoteTotal + unrealizedPnl;
+        // Realized P&L from fills accumulated this session
+        const today = utcDateString(Date.now());
+        // UTC rollover: if the seed is from a previous day, drop it. Today's
+        // realized then comes purely from fills the WS has observed since 00:00
+        // UTC (which is correct — anything earlier belongs to yesterday).
+        if (this.realizedTodaySeedDate !== today) {
+            this.realizedTodaySeed = 0;
+            this.realizedTodaySeedDate = today;
+        }
+        let realizedPnlToday = this.realizedTodaySeed;
+        let sessionRealized = 0;
+        let totalFees = 0;
+        for (const f of this.fills) {
+            const net = f.realizedPnl - f.fee;
+            sessionRealized += net;
+            totalFees += f.fee;
+            if (f.closedAt.slice(0, 10) === today) {
+                realizedPnlToday += net;
+            }
+        }
+        const realizedPnlAllTime = this.allTimeSeed + sessionRealized;
+        const round4 = (n) => +n.toFixed(4);
+        const enriched = { ...rawBalance };
+        enriched.realizedPnlAllTime = round4(realizedPnlAllTime);
+        enriched.realizedPnlToday = round4(realizedPnlToday);
+        enriched.totalRoundtripFees = round4(totalFees);
+        enriched.equity = round4(equity);
+        enriched.sessionStartNav = round4(this.sessionStartNav);
+        return enriched;
+    }
+}

package/live/live-bracket-api.d.ts

@@ -0,0 +1,13 @@
+import type { BinancePrivateApi } from '../ccxt/binance-private.js';
+import type { CcxtOrder } from '../types.js';
+import type { BracketApi } from './bracket-manager.js';
+import type { BracketLegParams } from './bracket-params.js';
+export declare class LiveBracketApi implements BracketApi {
+    private readonly api;
+    constructor(api: BinancePrivateApi);
+    submitBracketLeg(leg: BracketLegParams): Promise<CcxtOrder>;
+    cancelOrderByClientId(clientOrderId: string, symbol: string): Promise<void>;
+    /** ROOT-CAUSE FIX 2026-05-16: disable the per-symbol countdownCancelAll
+     *  dead-man's-switch before bracket placement (see BinancePrivateApi). */
+    disableCountdownCancelAll(symbol: string): Promise<void>;
+}

package/live/live-bracket-api.js

@@ -0,0 +1,20 @@
+// Thin BracketApi implementation backed by BinancePrivateApi. Kept separate
+// from BracketManager so tests can mock the minimal surface without pulling
+// in CCXT.
+export class LiveBracketApi {
+    api;
+    constructor(api) {
+        this.api = api;
+    }
+    async submitBracketLeg(leg) {
+        return this.api.createBracketOrder(leg.symbol, leg.type, leg.side, leg.amount, leg.params);
+    }
+    async cancelOrderByClientId(clientOrderId, symbol) {
+        await this.api.cancelOrderByClientId(clientOrderId, symbol);
+    }
+    /** ROOT-CAUSE FIX 2026-05-16: disable the per-symbol countdownCancelAll
+     *  dead-man's-switch before bracket placement (see BinancePrivateApi). */
+    async disableCountdownCancelAll(symbol) {
+        await this.api.disableCountdownCancelAll(symbol);
+    }
+}

package/live/live-state-store.d.ts

@@ -0,0 +1,194 @@
+import { EventEmitter } from 'node:events';
+import type { CcxtPosition, CcxtBalance, CcxtOrder } from '../types.js';
+/** A single position line in an ACCOUNT_UPDATE event. */
+export interface ParsedPositionUpdate {
+    symbol: string;
+    /** 'long' | 'short' — collapsed from Binance's {LONG, SHORT, BOTH} where
+     *  BOTH is resolved from the sign of `quantity` (positive = long, negative = short).
+     *  Zero quantity → 'flat', meaning the position should be removed. */
+    side: 'long' | 'short' | 'flat';
+    quantity: number;
+    entryPrice: number;
+    unrealizedPnl: number;
+    marginType?: 'cross' | 'isolated';
+    /** Raw positionSide from Binance — used to sanity-check one-way mode.
+     *  On a one-way account, this is always 'BOTH'. */
+    positionSide?: 'LONG' | 'SHORT' | 'BOTH';
+}
+/** A single balance line in an ACCOUNT_UPDATE event. */
+export interface ParsedBalanceUpdate {
+    asset: string;
+    walletBalance: number;
+    crossWallet: number;
+    balanceChange: number;
+}
+/** The full payload of an ACCOUNT_UPDATE event (after parsing). */
+export interface ParsedAccountUpdate {
+    eventTime: number;
+    transactionTime: number;
+    reason: string;
+    positions: ParsedPositionUpdate[];
+    balances: ParsedBalanceUpdate[];
+}
+/** The payload of an ORDER_TRADE_UPDATE event (after parsing). */
+export interface ParsedOrderUpdate {
+    eventTime: number;
+    transactionTime: number;
+    symbol: string;
+    orderId: string;
+    clientOrderId?: string;
+    side: 'buy' | 'sell';
+    type: 'market' | 'limit' | 'stop_market' | 'take_profit_market' | 'other';
+    status: 'open' | 'closed' | 'canceled';
+    executionType: string;
+    origQuantity: number;
+    cumulativeFilled: number;
+    lastFilledQty: number;
+    avgPrice: number | null;
+    origPrice: number | null;
+    lastFillPrice: number | null;
+    commission: number;
+    commissionAsset: string;
+    /** Raw Binance timeInForce (GTC, IOC, etc.) — preserved for round-trip. */
+    timeInForce: string;
+    /** Stable Binance trade id from `o.t`. The idempotency key for the audit
+     *  trail. Present only on executionType='TRADE'; null on NEW/CANCELED. */
+    tradeId: string | null;
+    /** Reduce-only flag from `o.R`. True for bracket SL/TP fills + manual
+     *  reduce-only orders. */
+    reduceOnly: boolean;
+    /** Maker flag from `o.m`. True if this fill matched a resting order. */
+    maker: boolean;
+    /** Realised PnL on this specific fill, from `o.rp`. Negative on losses. */
+    realizedPnl: number;
+}
+/** A REST snapshot used to seed the store on connect + reconcile drift. */
+export interface RestSnapshot {
+    timestamp: number;
+    positions: CcxtPosition[];
+    balance: CcxtBalance | null;
+    openOrders: CcxtOrder[];
+}
+export type DriftSeverity = 'none' | 'minor' | 'major';
+export interface PositionDriftDetail {
+    symbol: string;
+    localContracts: number;
+    restContracts: number;
+    localSide: string | null;
+    restSide: string | null;
+    kind: 'new' | 'closed' | 'size_changed' | 'side_changed';
+}
+export interface BalanceDriftDetail {
+    asset: string;
+    localTotal: number;
+    restTotal: number;
+    deltaBps: number;
+}
+export interface OrderDriftDetail {
+    orderId: string;
+    symbol: string;
+    kind: 'missing_locally' | 'missing_on_rest';
+}
+export interface StateDrift {
+    severity: DriftSeverity;
+    positions: PositionDriftDetail[];
+    balance: BalanceDriftDetail[];
+    orders: OrderDriftDetail[];
+    summary: string;
+}
+/** Thresholds for drift classification. All tuned conservatively — minor
+ *  drifts are expected background noise (in-flight events); major drifts
+ *  are structural and trigger a forced resync. */
+export interface DriftThresholds {
+    /** Balance delta below this (basis points of the REST value) is minor. */
+    balanceMinorBps: number;
+    /** Position contract delta below this is minor. */
+    positionMinorContracts: number;
+}
+export type LiveStateStoreEvents = {
+    /** Emitted on every successful apply. Useful for observability / push-to-skill. */
+    stateChanged: (kind: 'snapshot' | 'account_update' | 'order_update' | 'algo_refresh' | 'mark_refresh') => void;
+    /** Emitted when apply fails (parse error, hedge-mode event, etc.). */
+    applyError: (kind: string, reason: string) => void;
+};
+export declare class LiveStateStore extends EventEmitter {
+    private positions;
+    private balances;
+    private orders;
+    private lastSnapshotAt;
+    private lastAccountUpdateAt;
+    private lastOrderUpdateAt;
+    private readonly thresholds;
+    constructor(thresholds?: Partial<DriftThresholds>);
+    /** Get positions, optionally filtered by symbol. Returns clones. */
+    getPositions(symbol?: string): CcxtPosition[];
+    /** Get the current balance view. Matches the CCXT shape. */
+    getBalance(): CcxtBalance;
+    /** Get open orders, optionally filtered by symbol. Returns clones. */
+    getOpenOrders(symbol?: string): CcxtOrder[];
+    /** Observability — last-apply timestamps for each write path. */
+    getHealth(): {
+        lastSnapshotAt: number | null;
+        lastAccountUpdateAt: number | null;
+        lastOrderUpdateAt: number | null;
+        positionCount: number;
+        orderCount: number;
+        balanceAssetCount: number;
+    };
+    /** Replace state with a REST snapshot. Called on connect + reconnect + forced resync.
+     *  Idempotent: a duplicate snapshot produces identical state. */
+    applySnapshot(snap: RestSnapshot): void;
+    /** Replace the algo-order subset of the store with a fresh REST list.
+     *
+     *  Binance's user-data WS does NOT emit ORDER_TRADE_UPDATE for algo orders
+     *  (STOP_MARKET / TAKE_PROFIT_MARKET) until they trigger — only the resulting
+     *  regular order fires the event. As a result, the store cannot observe algo
+     *  add/cancel/modify events via WS alone and diverges from REST whenever
+     *  brackets are touched.
+     *
+     *  This method closes that gap: callers (the controller's refresh loop) hand
+     *  it the current REST view of algo orders, and we swap them in wholesale
+     *  while leaving regular orders (WS-tracked) untouched. An order is classed
+     *  as "algo" iff its clientOrderId parses as a reefclaw bracket cid with
+     *  role stop or target. External algo orders (manual STOP_MARKET placed via
+     *  Binance UI with no rc- prefix) are NOT tracked by this path — the 60s
+     *  reconciler snapshot still covers them. */
+    replaceAlgoOrders(freshAlgoOrders: CcxtOrder[]): void;
+    /** Refresh ONLY the mark-derived soft fields (markPrice + unrealizedPnl) of
+     *  positions that already exist in the store, from a fresh REST snapshot.
+     *
+     *  Why this exists: Binance's user-data `ACCOUNT_UPDATE` is event-driven
+     *  (fills / funding / transfers) and carries NO per-tick mark price, so a
+     *  quiet open position's `unrealizedPnl` in this store is FROZEN at the last
+     *  event's value while the Binance app recomputes uPnl every mark tick. In
+     *  enforce/observe mode this store is the authoritative read path, so the
+     *  dashboard's Unrealized cell froze between events ("close but lags/frozen"
+     *  — 2026-05-16). The controller's 60s truth-check already fetches a fresh
+     *  REST snapshot (with live uPnl + mark) but DISCARDS it unless position
+     *  structure drifts (diffPositions ignores uPnl entirely). This method lets
+     *  the truth-check spend that already-paid REST read on a uPnl refresh
+     *  instead of throwing it away — bounding uPnl staleness to the 60s interval
+     *  rather than "until the next trade/funding event".
+     *
+     *  Strictly bounded — this is NOT applySnapshot:
+     *   - only mutates positions present in BOTH the store and the fresh REST
+     *     list with the SAME symbol AND side (structural changes are the
+     *     truth-check's job, not this method's);
+     *   - never adds, never removes, never touches balance or orders;
+     *   - so it cannot reintroduce the null≠empty / stale-as-truth collapse
+     *     class (callers only reach here with a non-null REST snapshot anyway —
+     *     buildSnapshot throws UntrustedSnapshotError on a failed fetch). */
+    refreshDerivedMarkFields(restPositions: CcxtPosition[]): void;
+    /** Apply an ACCOUNT_UPDATE event (positions + balance deltas). */
+    applyAccountUpdate(ev: ParsedAccountUpdate): void;
+    /** Apply an ORDER_TRADE_UPDATE event (single order state transition). */
+    applyOrderUpdate(ev: ParsedOrderUpdate): void;
+    /** Clear all state. Used on shutdown/reset. */
+    reset(): void;
+    /** Diff local state vs a fresh REST snapshot. Classifies drifts by severity
+     *  so the parent reconciler can decide: log-only (minor) vs forced resync (major). */
+    diffAgainstSnapshot(rest: RestSnapshot): StateDrift;
+    private diffPositions;
+    private diffBalance;
+    private diffOrders;
+}